The PreTeXt Guide

Some elements in PreTeXt are containers, meaning they do not stand by themselves, but are meant to be filled with other elements. Other elements are atomic, meaning they cannot be decomposed into smaller elements. A canonical example is the case of a <figure>, which is a container meant to be filled with other elements. One such element is an <image>, which is atomic. Note that the figure can be filled with other items, and that an image may appear inside other elements, including as a child of a division, perhaps as a peer within a run of paragraphs. A purpose of the container is typically to provide a number and some text (a title, caption, or similar) as identification or description, in addition to indicating to conversions the necessity for some visual formatting (such as small amounts of separating vertical space above and below). Note that an author provides the caption, while PreTeXt provides the vertical spacing.

Here we provide very brief descriptions of these four containers. Be sure to consult the in-depth topics for more details on specifics. Generally, the common thread here is that these containers contain text or graphic elements that has a two-dimensional quality to it. To different degrees the content is rigid. Unlike a paragraph, which could be unwound into a single (linear) long sequence of characters, something about the contents of these containers would be lost if stretched out in one dimension. To reflect this rigid two-dimensional flavor, we refer to these objects (and their containers) as planar.

A <figure> is the most general planar container. It can hold an <image>, a <audio>, a <video>, and more. A <caption> is authored early as metadata, but will likely render below. A <title> can be used for cross-references or in lists of figures, but may not render where authored. See Section 4.17 for full details.

A <table> is the container for a <tabular>, an atomic element which is the only allowed content of a table. A <title> is the identifying information, and renders above the rows and columns of the table. A variety of notes (to appear below the table) are possible (not implemented as of 2021-12-10). The elements we provide to describe a table are heavily influenced by the discussion in Chicago Manual of Style [1, Chapter 13], which is worth reading if your project has many important tables. See Section 4.18 for full details.

A <listing> is a container for computer code or programs, to support projects in computer science and other technical disciplines. These languages often rely on indentation (Python) or even exact column numbers of text (FORTRAN), hence a planar quality. Other languages can be written syntactically-correct as one long reflowable line (C, Pascal), but are impractical to do so as part of an exposition. So the allowed content is a <program> or <console>, which will respect indentation, use monospace fonts, and include syntax highlighting. Otherwise, a listing is very similar to a figure in how a caption and title are handled. See Section 4.19 for full details.

A <list> may not be what you think it is. An actual list (be it ordered, unordered, or description) is a common and popular device for organizing information. Start at Section 3.8 for details on lists. Since these lists are considered part of a sentence (within a paragraph), or a part of a paragraph, it is hard to create a cross-reference to them. So when you have a list that is important to mention elsewhere, you can create a named list with the <list> element, a container that has an optional <introduction>, followed by a actual list, and then an optional <conclusion>. An example might be a laboratory procedure, such as the steps necessary to dissect a frog. Like a <table> this element should have a <title>, and will be given a number. Using a new line for each new list item, and conveying nesting with indentation gives a list a planar quality. See Section 4.20 for full details.

We use a <table> to summarize these similar containers.