The PreTeXt Guide

A division (or more carefully, a structural division) is a structured component of a book or article that would be recognized by most any reader. They are essential to the organization of a PreTeXt project. Notice that we use the generic term division, since a <section> is just one example of a division.

Divisions are <book>, <article>, <part>, <chapter>, <section>, <subsection>, <subsubsection>, and <paragraphs>. Their use is fairly intuitive, though there are some restrictions, so please read on.

A <book> must contain at least one <part> or at least one <chapter>, which may contain <section>, <subsection>, and <subsubsection>. A <part> simply contains a sequence of <chapter> and functions in two user-selectable ways: structural (e.g. numbering will reset), or decorative (merely inserting a decorative page between two chapters and sectioning the Table of Contents).

An <article> is simpler and shorter than a book. It might be really simple and have no divisions at all, or it may have <section>s. It cannot have <chapter>s, as that would be a <book>. Within a <section>, <subsection>s and <subsubsection>s may follow.

Divisions must nest properly and may not be skipped. So a <section> cannot contain a <chapter> and a <subsection> may not be contained in a <chapter> without an intervening <section>.

A division must contain a <title>, and may contain one or more index entries (see Section 4.27), which should appear before anything else. Any division may be unstructured, with just a sequence of top-level content such as paragraphs, figures, lists, theorems, etc. Or a division may be structured, and in this case it must follow a prescribed pattern. There may be a single, optional <introduction>, filled with top-level content, followed by a sequence of at least one of the appropriate divisions, ending with a single, optional <conclusion>, filled with top-level content. It is an error to begin with a run of top-level content inside a division and then begin to use divisions. (The solution is to make the initial content an <introduction> and/or one or several divisions.)

A <book> may be structured into parts. After the <frontmatter> and before the <backmatter> there may be a sequence of <part>. These elements may carry a <title>, and not much else, besides a substantial sequence of <chapter>. The main effect is to get an extra level of division in the Table of Contents. For print and PDF there is an entire page devoted to the title and number of the part. The default numbering is decorative, which means that the chapters are numbered consecutively from the start of the book and do not reset to one at the start of each part. It is as if the parts were not even there. The alternative is that parts are structural. Now each part begins with Chapter 1. There are other more subtle differences, such as cross-references use a part number if, and only if, the trip from the cross-reference to its target crosses a boundary of two parts. The two approaches to part structure may be set via the publication file, see Section 44.2.

There are exceptions to the above. For one, <paragraphs> is an anomalous division, as a sort of lightweight sectioning command. It may appear in any division, at any location within a division, it may not be divided further (it is a leaf of the document tree), it never gets a number, and its title is formatted in a subsidiary way. I especially like to use this in a two- or three-page <article> that has no other divisions at all. It is also very useful as a way to subdivide portions of the front matter (Section 4.25), such as a <preface>. Typical presentation has the title in bold, without much change in font size (if at all), inline with the first paragraph, and perhaps a bit of vertical space as it begins and ends. Despite the name, it may contain more than just paragraphs, so may contain any top-level-content that would go in any other division.