The PreTeXt Guide

Sometimes it is useful to have an automatic list of various elements of one kind in a book, other than the ones already available in a PreTeXt document. The predefined ones include an index (see Section 4.27) and a list of notation (see Section 4.28). Examples of lists one might wish to create could include lists figures, computational listings, or theorems.

There is a very flexible way to make a list of various blocks (or perhaps other items) in your text. Use an empty <list-of/> element as a child of a division. A very natural use would be to create an <appendix> for the sole purpose of holding one such list. This is why this feature is frequently used in the back matter. But you could place an automatic list many other places.

We will illustrate with an example. Suppose you know your book has theoretical results only in <theorem> and <lemma> elements. So, for example, you never use <corollary> elements. Then you could author

<appendix xml:id="appendix-list-results">
  <title>List of Results</title>

  <list-of elements="theorem lemma" divisions="chapter" empty="yes"/>
</appendix>

The result will be a link to every <theorem> and <lemma> in the entire book, using a clickable with its type, number and title. See Appendix B for an example. In HTML output the clickables will usually be knowls, which is especially handy. The list will be organized with the titles of the chapters as headings. The @divisions attribute can have several types of divisions listed, such as both <chapter> and <section>. The @empty attribute set to yes indicates that a division heading should be used even if there is nothing on the list contained within. The default for @empty is no.

This feature is best used when the items in the list have been authored with titles, which greatly increases the utility of the list for your reader. Review Best Practice 4.8.1 if this advice is new to you.

There is a @scope attribute, which should be the name of an element which is a division containing the location of the <list-of> element. Then the list is restricted to items within the specified division. For example, if you have the <list-of> inside a <subsection> built for this purpose, and you use @scope="section" then the list will have all the items from throughout the section containing the list.

There are four types of exercises, based on their location: inline, divisional, worksheet, and reading questions. These may be specified inside @elements by the pseudo-elements: 'inlineexercise', 'divisionexercise', 'worksheetexercise', 'readingquestion'. (These are just strings meant for this purpose, and are not real PreTeXt elements.)

There may be an argument for a @ref attribute that would behave similar to @scope. Make a feature request if you need it?