Write your first document

Section 3 Write your first document

Now it is time to start thinking about your first document.

Subsection 3.1 Use a template

Writing XML is tedious. There are many things to do to make it easier, including having an awesome text editor (which I do not). But the most important one is not to start from scratch!

For your first article, I recommend using the PTX minimal example, but for some even that one might be too maximal. If you want to make a really minimal example, please go directly to the most minimal document possible at the author's guide. I will do something in between here. See Example 3.2 for a little of the output. (To begin in PTX, I recommend using the <article> document type and not the <book> type.)

Remark 3.1.

It's not bad practice to try to type this, or a similar template, verbatim without cut and paste. You'll want to exercise your typing chops in any case if you want to take on an PTX text. (Many people use configured text editors for exactly this reason.)

<?xml version="1.0" encoding="UTF-8" ?>

<pretext>

  <article xml:id="minimal">
    <title>A Minimal Article</title>

    <frontmatter>

      <titlepage>
        <author>
          <personname>Your Name</personname>
          <institution>Your Place</institution>
        </author>
      </titlepage>

      <abstract>
        <p>An abstract.</p>
      </abstract>

    </frontmatter>

    <section xml:id="section-first">
      <title>A first (and only) section</title>

      <p>This paragraph has some inline math, 
      the Diophantine equation, <m>x^2 + y^2 = z^2</m>.
      And some display math about infinite series: 
      <me>\sum_{n=1}^\infty\,\frac{1}{n^2} = \frac{\pi^2}{6}.</me></p>
    </section>

  </article>

</pretext>

Example 3.2.

Here is the output of the mathematics paragraph in my nearly-minimal example.

This paragraph has some inline math, a Diophantine equation, \(x^2 + y^2 = z^2\text{.}\) And some display math about infinite series:

\begin{equation*} \sum_{n=1}^\infty\,\frac{1}{n^2} = \frac{\pi^2}{6}. \end{equation*}

Subsection 3.2 Things you must do

There are several main things to say about what is required when writing PreTeXt documents.

You must start with the line including ?xml.
You must use ‘tags’ like <proof> or <subsection> to structure content. All actual text goes ‘inside’ of such tags.
You must use the tags in ‘nested’ form. It is completely illegal to do something like <theorem><title>My Theorem</theorem>, even if you put </title afterwards.
You must have <pretext> as the first (and last, in closed form) tag, and then either <article> or the equivalent for book, slides, etc. as the next level tag.

Running xsltproc on your project reasonably often will help catch these before they become menaces. The error messages are a lot better than those for LaTeX!

Subsection 3.3 Keys to success

Naturally, the keys to success for you will depend a lot upon your previous experience. But here are some tips I can't live without. You may wish to add to them!

List 3.3. Tips for PTX authoring success

Always pair your tags first!

Put <theorem> with </theorem as soon as you can, and similarly with tags like <xref /> which are ‘self-closing’.
Make it a habit to do at least some structure first, before content. Don't start writing (unless you have pre-existent content); instead, put in a few <section>s (and close tags) with roughly the structure you want first. You can always add or combine sections later. Your goal is for your article to compile right now, not later. Fixing problems is very challenging without this!
Along these lines, you may wish to familiarize yourself with the most important structures from the Author's Guide, or even the somewhat more forbidding official schema.
Use xml:id identifications for xml elements on your biggest things now, and come up with a system for labeling them. If you want to do cross-references of various kinds, this is a must. I highly recommend using some convention like <theorem xml:id="theorem-antiderivs-exist"> for a theorem about antiderivatives existing, because it will make the references manageable. As an example, I put the chapter name in each exercise I cross-reference, so I don't forget where the exercises live!
Finally, don't feel bad about putting in comments. You can put in lots, and I recommend putting them in separate lines. The syntax is , as it is in html.