Skip to main content
\( \newcommand{\lt}{<} \newcommand{\gt}{>} \newcommand{\amp}{&} \)

Section8Back to Work

Subsection8.1Things you must do

Since we will assume here that you will start by writing a short course supplement, we will assume you are using the <article> type and not the <book> type. Before showing this, there are three main things to say about what is required.

  1. You must start with the line including ?xml.

  2. You must use ‘tags’ like <proof> or <subsection> to structure content. All text goes ‘inside’ of such tags.

  3. 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.

Running xsltproc on your project reasonably often will help catch these before they become menaces. If something from your source file does not appear in your output file, it's almost certain that you are missing a required tag. Look carefully at the examples provided.

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*}

Subsection8.2Keys to success

Naturally, the keys to success for you will depend a lot upon your previous experience. But here are some tips:

  • Always pair your tags!

    Put <theorem> with </theorem as soon as you can, and similarly with tags like xref and image which are ‘self-closing’. An XML-aware editor can be used to give you a nice keyboard shortcut to close an open tag or to insert a pair of tags. With the right configuration, you can even get tab-completion of tags and highlighting that tells you of (some) code that's got a bug in it. (Unlike in more forgiving HTML, an opening li tag always requires a closing one.)

  • 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!

  • Use xml:id identifications for xml elements on your biggest things now, and come up with a system for labeling them. We have not talked much about this, but using some convention like <theorem xml:id="theorem-antiderivs-exist"> for a theorem about antiderivatives existing is very useful. As an example, you might put the chapter name (not number!) in each exercise you cross-reference, so you don't forget where the exercises live!

  • Don't feel bad about putting in comments. These look like this: <!-- comment goes here -->.

List8.2Tips for PTX authoring success

Overwhelmingly, people wanted to know just how to do stuff in PTX. So we will get to that shortly.

But I'd be remiss if I didn't tell you two things now, before we get in.

First, what are some good things to keep in mind for keeping it all straight?

  1. Have the author guide open. (I tried to get a handout of this today.)

  2. Have the cheatsheet open.

  3. Arrange your own source and html windows in a way that maximizes productivity. (Search for “mbx tip arrange windows” and a post by David Farmer should be the first hit.)

Second, especially if you have collaborators, you may want to think about revision control. This is too big of a topic to delve further into now, but do check out Rob and Dave's Git for Authors at http://mathbook.pugetsound.edu/gfa/html/. This will explain why you might care about revision control, even as a solo author. (One or two of you may be interested in talking with MTK about this today. He's happy to do so one-on-one.)