Skip to main content

Section 4.8 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 a single optional <shorttitle> and/or a single optional <plaintitle>. 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, when horizontal space may be at a premium, the <shortitle> will be used preferentially.

A <plaintitle> is similar, but slightly different, so you might want both. In limited situations, PreTeXt markup does not travel well in certain conversions. The best example is mathematics, which might be in a title of a division, and then in a conversion to HTML, will fail to render in the tab of a browser, or the list of open tabs for a browser window. Two examples

<title><m>q</m>-crystalline cohomology</title>
<title><m>\delta</m>-rings</title>

PreTeXt will automatically do a nice job for you with the first, but the second will retain \delta in a browser tab. However, you can add a <plaintitle> element where the \delta can be replaced by a Unicode delta (U+03B4), which will used preferentially and be fine in HTML output.

To avoid confusing your readers, use these alternate titles 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, or when markup is behaving poorly in situations such as a browser tab. Your first option should be to ask if your long title must absolutely be so long, or if the markup is strictly necessary.

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).

If a title is very long, the <line> element can be used to indicate how the title should appear on multiple lines. Note: does not apply to all output formats.

Best Practice 4.8.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.26). Constructing them on-the-fly is much easier than making a big chore out of going back and doing it later.

Bad

Example 5.10

Better

Example 5.10 A cool lizard trick.

Best

Example 5.10 Various colors and markings of a chameleon.