Section 1.2 Formatting Your Source
There are a lot of details related to how you prepare your source: the actual files that you, and you alone, will create. At least skim through the following, come back here often, and also consult <<exhaustive-chapter-on-source-files>>.
Your source should be plain ASCII files which you will create with a text editor. In other words, do not create your source with Word, LibreOffice, WordPerfect, AbiWord, Pages or similar programs. Popular text editors include vi, emacs, Notepad, Notepad++, Atom, TextWrangler, and BBEdit. I have had a very good experience with Sublime Text, which is cross-platform (Windows, OS X, Linux), and can be used for free, though it has a very liberal license and is well worth the cost. Sometimes these editors are known as a programmer's editor (though we will be doing no programming). Support for writing HTML sometimes translates directly to good support for XML.
There are XML editors, which I have generally found too complex for authoring in PreTeXt. They do have some advantages and XML Copy Editor is one that I have found that is possibly useful.
Learn to Use Your Editor
Because XML requires a closing tag for every opening tag, it feels like a lot of typing. Your editor should know what tag to close next and there should be a simple command to do that. Discover this first and consider switching editors if it is not available. For me, in Sublime Text on Linux, I just press
Alt-Period and get a closing tag. Not only is this quick and easy, I often recognize that I am not getting the tag I expected since I forgot to close one earlier. This one shortcut can pretty much cut your authoring overhead in half.
If your editor can predict your opening tag, all the better. Sublime Text recognizes that I already have a
<section> elsewhere, so when I start my second section, I very quickly (and automatically) get a short list of choices as I type, with the one I want at the top of the list, or close to it.
Invest a little time early on to learn, and configure, your editor and you can be even more efficient about capturing your ideas with a minimum of overhead and interference.
If you are writing a book, or if you are collaborating with co-authors, then you owe it to yourself and your co-authors to learn how to use revision control, which works well with PreTeXt. The hands-down favorite is
git which has a steep learning curve, and so is beyond the scope of this guide. But see <<topic-git-coexistence>> which has hints on how to best use
git together with a PreTeXt project and look for Beezer and Farmer's Git For Authors.
The term whitespace refers to characters you type but typically do not see. For us they are space, non-breaking space, tab and newline (also known as a “carriage return” and/or “line feed”). Unlike some other markup languages, PreTeXt does not ever use whitespace to convey formatting information.
In some parts of a PreTeXt document, every single whitespace character is important and will be transmitted to your output, such as in the
<output> portions of a
<sage> element. Since Sage code mostly follows Python syntax, indentation is important and leading spaces must be preserved. But you can indent all of your code to match your XML indentation and the entire
<output>) content will be uniformly shifted left to the margin in your final output.
In other parts of a PreTeXt document, every single whitespace character is ignored, and you have the freedom to use indentation and blank lines to help you understand the logical structure of your document. An example is that you can add as much whitespace as you like between the paragraphs of a section, such as a preceding blank line and indentation, and none of it will affect your output in any way.
Never use tabs, they can only cause problems. You may be able to set your editor to translate the tab key to a certain number of spaces, or to translate tabs to spaces when you save a file (and these behaviors are useful). I have Sublime Text configured to show me every single space as a small faint dot, since I like to be certain I have no stray whitespace anywhere.
Structure of your Source
XML is hierarchical, like a family tree. Books contain chapters, chapters contain sections, sections contain paragraphs, etc. I like to reflect each new level of containment by consistently indenting four spaces (you might prefer two spaces). A good editor will visually respect this indentation, and help you with maintaining the right indentation with each new line, so much so, that you will forget how much assistance it is providing.
Develop a style and stick with it. I put titles on a new line (indented) after I create a new chapter or section, some people like them on the same line, immediately adjacent. I put a single blank line before each new paragraph, but not after the last. And so on. The choice is yours, but consistency will pay off when you inevitably come back to edit something. You have put a lot of work and effort into your source. You will be rewarded with fewer problems if you keep it neat and tidy, and you will also get very clean output.