Section 3.5 Titles
Divisions always need titles, you accomplish this with a
<title> tag first thing. Almost everything that you can use in a paragraph can be used in a title, but a few constructions are banned, such as a displayed mathematical equation (for good reason). Try to avoid using footnotes in titles, even if we have tried to make them possible.
A division will also support an optional
<shortitle>. The full
<title> will be used where the division is born, but in other places where the title is used for navigation, such as a Table of Contents, print page header, or HTML summary page, the
<shortitle> will be used preferentially. To avoid confusing your readers, use this feature sparingly, and ideally only when you have a really, really, really long title and then use a short title that is easily recognizable as a variant of the long title. Your first option should be to ask if your long title must absolutely be so long.
Many, many other structures admit titles. Experiment, or look at specific descriptions of the structure you are interested in. Titles are very integral to PreTeXt, much like cross-references. Titles migrate to the Table of Contents, get used in page headers for print output, can be used in lists (such as a List of Figures), and can be used as the text of a cross-reference, instead of a number. You might not be inclined to give a
<remark> a title, but it would be good practice to do so. If you use knowls in your HTML output for structures such as
<example> (or if somebody else may someday choose to), then your readers will be spared a lot of confusion if you supply informative titles for each. Your electronic outputs will be much more useful to your readers if you routinely title every structure that allows it (perhaps excepting
<exercise> which can be known by their number).
Best Practice 3.5.1. Provide Informative Titles Liberally.
Provisions for titles in many situations is a key PreTeXt feature. And then they are used for various purposes to benefit readers. A good example is when the HTML conversion is used to place content in a knowl, a unit of content that begins hidden, but can be revealed (and hidden again) with one click of a mouse. Since a reader cannot see the content originally, we will migrate a title into the clickable text. But we cannot read your mind—it is your job as the author to provide a title, and to provide a good one.
Even if you are not yet sure what a knowl is, and even if you think you do not want to use them, there are other good reasons to have a title (such as automatic lists, see Section 4.22). Constructing them on-the-fly is much easier than making a big chore out of going back and doing it later.
Example 5.10 A cool lizard trick.
Example 5.10 Various colors and markings of a chameleon.