Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Chapter 12 Document Structure

Elements such as <chapter>, <section>, and <subsection> are called divisions. They are the key organizational elements of the structure of a PreTeXt document and all have (essentially) the same syntax. If a division does not contain any other divisions, then its structure looks like what we see in Listing 12.0.1. (Plenty of other things can go inside other than paragraphs, including figures, etc.)
<section>
  <title>Mandatory</title>
  <p>
    First paragraph.
  </p>

  <p>
    Second paragraph.
  </p>
</section>
Listing 12.0.1. The general outline of a section as a model division
If a division has other divisions inside it, then the structure is a bit more complicated and regimented. In particular, if you want text before your first subdivision (<subsection> in this example), that text must go inside <introduction>. If you want to start with the <subsection>, then the <introduction> is optional. In the “division with subdivisions” model, everything must be contained inside <introduction>, <subsection> (or whatever your subdivision type is), <exercises>, <references>, or <conclusion>. This is illustrated in Listing 12.0.2.
<section>
  <title>Mandatory</title>
  <introduction>
    <p>
      Introductory text.
      (Optional.)
    </p>
  </introduction>

  <subsection>
    <title>Mandatory</title>
    <p>
      Subsection content.
    </p>
  </subsection>

  <subsection>
    <title>Mandatory</title>
    <p>
      Subsection content.
    </p>
  </subsection>

  <conclusion>
    <p>
      Concluding text.
      (Optional.)
    </p>
  </conclusion>
</section>
Listing 12.0.2. A <section> with <subsection>s.

Limitations on introductions and conclusions.

There are many tags that are not allowed in introductions and conclusions. In general, avoid things that would have numbers. For instance, one should not put an <example> or an <exercise> in an introduction or conclusion.

Paragraphs: like an un-numbered (sub)section.

It can be useful to gather a few items and give them a title, but perhaps those items do not merit their own (sub)section. The <paragraphs> serves that purpose. A <title> is required.
This <paragraphs> contains two <p>s. Immediately before, and immediately after this <paragraphs> there are <paragraphs> which each contain one <p>. A <paragraphs> can contain pretty much anything except for a division.

The role of <p> tags.

One of the things you’ll need to keep an eye out for is when things must be wrapped in <p> (paragraph) tags. Notice that <title> tags do not have their content wrapped in <p>, which places some limits on the sorts of things that can be contained in a title. If you find text disappearing or displaying strangely, the culprit is likely an unnecessary or or missing <p> tag. See Chapter 6 for information on how to use some additional tools to see if your PreTeXt file is valid in terms of following the structural rules in the schema.
PrevTopNext