The PreTeXt Guide

PreTeXt targets the production of “structured scholarly documents”—not novels, not magazine articles, not menus, and not travel brochures. (Though a novel could work well?) A research monograph might only be consulted for a portion of its content. A good textbook should be useful to a reader after a course is over, and it should be easy to locate certain portions of the material. A good textbook will foreshadow later material, and reinforce earlier material. So we provide tools that lead to a quality index, reduce the overhead of making an accurate cross-reference, and make an automatic Table of Contents. Page numbers can be a useful way to locate information for print output, but are less useful in an electronic PDF with hyperlinks, and are totally useless for online HTML and reflowable EPUB. So we rely on copious hierarchical numbering to assist with locating discrete pieces of content.

A PreTeXt document, like most any scholarly document has a hierarchy of divisions. These are always numbered to reflect that hierarchy. So Subsection 4.7.2 of a <book> is the second sub-section of the seventh section of the fourth chapter of the book. It is possible to specify that the numbering stops at some level, but that will limit how you can number smaller units of content.

Blocks are units of content held in a division. An <example> is a good example. These are always numbered, so that cross-references are as useful as possible in all output formats. The number begins with a structure number that is the number of a division. The division will contain the block, but does not need to be the closest containing division. For example, Example 5.2.65 of a book has structure number 5.2, indicating it is in Section 2 of Chapter 5. But this section might be structured as a sequence of sub-sections and Example 5.2.65 would be contained in one of these sub-sections. But if we started counting all the examples in this section we would find Example 5.2.65 as the sixty-fifth numbered block of the whole section, even if it might only be the twenty-second example of its sub-section. This final number is known as the serial number. The granularity of the structure number may be configured. This is a good place to suggest the complementary Section 26.2 on the meaning of the term level.

Numbering of equations and footnotes may be configured in a manner entirely similar to that of blocks. See Section 44.2 for details on how to control this.

As mentioned above, a number is a kind of locator—it should help a reader locate content, via a cross-reference, an index entry (a specialized cross-reference), or a Table of Contents. It should also help a reader (teacher) tell another reader (student) where to find content, perhaps as part of a citation to a smaller item within a larger work. How would you locate Example 5.2.65? A Table of Contents, in any output format should get you to Section 5.2 quite easily. We claim that the <remark> immediately preceding Example 5.2.65 should be Remark 5.2.64. In other words, it will easier to scan the section and quickly home in on the example if the serial numbers count all the numbered blocks, rather than having one sequence of serial numbers counting examples, and a second sequence counting remarks. Not convinced? Suppose there were two such sequences of serial numbers. When you see Remark 5.2.23, should you move forward or backward in your search for Example 5.2.65?

If it is so important to not have separate sequences of serial numbers, then why do equations and footnotes get their own sequences? These items are substantially different visually, and even their numbers are formatted quite differently, so scanning for blocks or equations or footnotes should be very distinct visually. Notice that it is their distinctive appearance that is the criteria for an independent sequence of serial numbers.

We have implemented some flexibility for figures and tables, and for projects. This work is in flux, so we have not yet documented the possibilities. Our view is that figures and tables can be considered visually different enough to merit a separate sequence of serial numbers.

Divisions that are <chapter>s, and only <chapter>s, may begin with a number other than one. Primarily this is to accommodate books that need to be printed in multiple physical volumes, so numbering in a second (or subsequent) volume can be correct. We also understand the instructive value of a computer science text that wants to start counting from zero. We do not mean to encourage a Chapter 0 that is an introduction (go ahead and title Chapter 1 “Introduction”) or background preparatory material (make that an appendix). Understand that a <preface>, or multiple <preface>s, is the place to talk about how, or why, you wrote your book, and/or a place to instruct a reader or instructor about the best ways to use your book. See Section 44.2 for details on how to accomplish this.