The PreTeXt Guide

Your source will be plain text ASCII files, which you create and edit with any number of text editors. Files can be saved with the .ptx extension, which might tell your text editor what sort of file you are editing and will provide syntax highlighting and code completion, among other features. If your editor does not recognize .ptx, then you can use the .xml extension which has wider editor support (but with fewer PreTeXt-specific features).

Popular text editors include Visual Studio Code, Sublime Text, vi, emacs, Notepad, Notepad++, Atom, TextWrangler, and BBEdit. But in particular, you should not use word processing programs like Word, LibreOffice, Google Docs, WordPerfect, AbiWord, Pages, or similar programs. 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.

Visual Studio Code has support for PreTeXt documents via a free extension, and the editor is open source and cross-platform (Windows, OS X, and Linux). The developers of PreTeXt have also had a very good experience with Sublime Text, which is cross-platform, and can be used for free, though it has a very liberal paid license if you want to avoid nagging.

There are XML editors, which might be too complex for authoring in PreTeXt. They do have some advantages and XML Copy Editor is one that you might find useful.

Some text editors (like VS Code) have spell checking extensions. More generally, recommendations for a spell checker can be found in Section D.2.

If you start to think about the structure of a document (like an article or book) you will quickly realize that components are like blocks, stacked inside or next to other blocks. From the outside to inside, a book will have a number of chapters (next to each other, but all inside the book), and each might have sections (adjacent but inside the chapter). In the section, there will be a title, paragraphs, images, examples, theorems, and so on. Examples will themselves contain paragraphs. A theorem might contain a statement, which contains some paragraphs, which might contain some displayed math, and adjacent to the statement, there could be a proof, itself containing paragraphs, etc.

The hierarchical nature of XML is perfect to capture the hierarchical nature of a scholarly document. Consider the start of a PreTeXt document shown in Listing 1.2.1.

<?xml version="1.0" encoding="UTF-8"?>
<pretext>
    <book>
        <title>Hello world!</title>
        <chapter>
            <title>Getting Started</title>
            <p>Welcome to PreTeXt!</p>
            <!-- TODO: find something more to say... -->
        </chapter>
    </book>
</pretext>

The first line is boilerplate that lets various programs know the rest of the file is XML, and the line start <!-- is an example of a comment that won’t appear in the output. Besides this, you can start to see how the structure of the book is layed out.

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.

However, it can be useful to use whitespace to indent the different levels of the XML (and document) hierarchy. Use two (or four) spaces for indentation; a good editor will visually respect this indentation, and help you with maintaining the right indentation with each new line. Line up opening and closing tags at the same level of indentation, and your editor should let you “fold” the code to visually hide blocks.

Whatever you do, use a style and stick with it. You could put titles on a new line (indented) after creating a new chapter or section; some people like them on the same line, immediately adjacent. You could 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.

In some parts of a PreTeXt document, every single whitespace character is important and will be transmitted to your output, such as in the <input> and <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 <input> (or <output>) content will be uniformly shifted left to the margin in your final output.

Never use tabs, they can only cause problems. You should 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). Most editors have a setting that will show whitespace as a small faint dots or arrows, so you can be certain there is no stray whitespace anywhere.

Because XML requires a closing tag for every opening tag, it feels like a lot of typing. The VS Code PreTeXt extension comes with many snippets (code completions) that can fill out lots of the markup for you. More generally, any editor should know what tag to close next and there should be a simple command to do that (for example, in Sublime Text on Linux, Alt-Period gives a closing tag). Not only is this quick and easy, it can help spot errors when you forget to close an earlier tag.

If your editor can predict your opening tag, all the better. VS Code can recognize what tags are allowed at a given position. Sublime Text recognizes if you already have a <section> elsewhere, so when you start a second section, you very quickly (and automatically) get a short list of choices as you type, with the one you 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 since the source is just text files. The hands-down favorite is git. To fully understand it is beyond the scope of this guide but some information is provided in Appendix H which has hints on how to best use git together with a PreTeXt project.

If you use the workflow recommended in the Chapter 2 using GitHub’s codespaces, you will get revision control via git automatically, and VS Code provides a graphical user interface for all the basic operations you need.