Subsection4.25.1Syntax and Placement of Index Entries
Best Practice4.25.1.1.Capitalization of Index Entries.
The headings (entries) of an index are authored entirely in lower-case, unless it is a proper noun (name, place, etc.) which would normally be capitalized in the middle of a sentence. We are not able to provide any enforcement of this advice, nor any assistance. It is the author’s responsibility to provide quality source material in this regard. We do sort entries so that an entry with an initial capital letter arrives at the right location in the index.
Where you place an <idx> entry is critical. With LaTeX output, you will get the traditional page number as a locator in your index. With HTML output we can be more careful. We will look to see which sort of structure contains the <idx>. Maybe it is an <example> or a <subsection>. If so, the index will contain a locator that is a knowl of the example, or a link to the subsection. The distinction is the size of the object, we do not knowl divisions. The exception is a paragraph (<p>) that is a child of a division, and then the locator is a knowl of the entire paragraph. Remember that a knowl contains an “in-context” link which can take the reader to the original location of the content in the knowl.
A lot happens in a PreTeXt paragraph, especially when producing HTML. Sometimes an <idx> can get in the way. Our recommendation is to put <idx> entries between sentences, and not at the start or end of the paragraph. They can be authored with each on their own line. If you do not need the specificity of a paragraph, then locate the appropriate structure and author the <idx> right after the <title> (or where one would be).
A cross-reference in an index is a pointer to another index entry. These are rendered as “See” and “See also.” You can add <see> and <seealso> elements within an <idx>, so long as it is structured with <h>. Then it is placed after the last <h>. A “see” cross-reference is a direct pointer to another entry in the index. It cannot have a locator as well. When you build the HTML output, we will recognize this situation and produce a warning. A “see also” cross-reference is an additional pointer, and so it must have a locator to go with it (you will author two <idx> with identical headings, the first without a <seealso> to create the locator, the second with the <seealso> to create the cross-reference. Again, when you build the HTML output, we will recognize a <seealso> without a locator and produce a warning.
Follow these directions and PreTeXt will format cross-references for you, in the style suggested by the Chicago Manual of Style[1] for HTML output, and according to LaTeX’s style for print and PDF.
(2019-03-04) We have consciously not said anything specific about what to place inside a <see> or <seealso> element. At this writing, you need to supply the text. Of course, this is error-prone and you will need to consult CMOS for formatting guidance. But we have plans to do this the PreTeXt way. First, the ref/xml:id mechanism will be used to automatically create the correct text for the cross-reference, both content and format. Second, these will become live links in electronic formats.
Certain index entries do not sort very well, especially entries that begin with mathematical notation. Our first advice is to avoid this situation, but sometimes it is necessary. The @sortby attribute on an <h> element can contain simple text that will be used to override the content shown to the reader during the sorting of the index.
