Subsection 4.27.1 Syntax and Placement of Index Entries
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.
Subsection 4.27.2 Advice on Indexing
An index is a navigational aid for your readers (and you). We do not assume that a reader remembers where anything is, nor that the Table of Contents is a replacement for part of the index. Some readers of the index may not have even read your book yet, and are looking to get a feel for the range of topics as part of the decision of whether or not to read your book at all, or if it will be useful to have. It should be comprehensive, including everything substantive.
Indexing is a job for a skilled professional, and most authors produce poor indexes. The tips in this section will help you avoid the most common pitfalls. We follow recommendations from the
Chicago Manual of Style [1, Chapter 18],
Indexing for Editors and Authors: A Practical Guide to Understanding Indexes [3], and Pilar Wyman of
Wyman Indexing.
Terminology.
The basic element of an index is an entry, which consists of a piece of information and its locator. For example:
normal subgroup, 37
is an entry indicating that information about “normal subgroup” can be found on page 37. Indexes are (usually) organized alphabetically, with a main heading aligned with the left margin, and progressively indented subheadings below the main heading.
Often it is desirable to place the same locator under more than one heading, known as double posting. For example, a desirable addition to the sample entry above is
subgroup, 28
normal, 37 .
An alternative to double posting is cross referencing, using see and see also. Typically cross references are used to avoid repeating a large number of entries, or to direct the reader to related topics.
An index may start with a headnote giving advice about using the index. Typically a headnote is not necessary unless the index has some unusual features.
Basic principles.
The purpose of an index is to point the reader to information. Point to, not repeat. For example, acronyms should be indexed at the location where they are defined, not at every place they appear, and it is not necessary to define the acronym within the index. People and places should be indexed when information is given about them, not every time they are mentioned.
A good index has multiple ways to find the same information. Being redundant is desirable, because it increases the chance the reader finds what they seek in the first place they look.
Indexing is best done after the text has been written. Adding index entries while writing the text may seem to be a labor-saving device, but if you are not an experienced indexer, those entries will only be a small fraction of the final index.
Topics should be indexed in multiple ways. If a term is defined, you should also think of other words the reader might search for. For example, you may define “limit point” and consistently use only that term, but an index entry for “accumulation point” with a “see limit point” locator would be appropriate.
Use disambiguation to distinguish identical terms with different meanings. For example
isomorphism (of groups), 55
isomorphism (of rings), 123
Both of those entries should also be double posted under the main headings of “group” and “ring”, respectively. No disambiguation is needed for those entries.
Singular or plural forms of nouns should reflect the language in the text. So if a chapter is titled “Mammals”, then use a heading mammals. And if the chapter is titled “The Mammal Class”, then use a heading mammal.
An index is typically as long as 5% of the main text. With many figures, or other structures creating additional whitespace, the percentage may be lower. If your primary output is online, length may not be an issue. For print, there are strategies for pruning an index.
Once you have finished the text, and then finished the index, it is time for a thorough review of the index. There will be places for consolidation, often due to using variants of particular words. You may wish to remove subheadings which all appear within the range given in the heading. For example,
fish, 204-212
bass, 208-209
salmon, 210
trout, 207
could have all of its subheadings removed, especially if space is an issue.
Common pitfalls.
Sometimes it takes less than one second to determine that an index is poor. If a quick glance reveals that the index consists mostly of main headings with very few subheadings, then few readers will find it to be useful. Double posting, which may mean more than literally two entries with the same locator, will help readers find what they are looking for. Most of those entries will be in subheadings.
Another instantly recognizable problem is too many locators in one entry. This entry
asymptote, 37, 48
is probably fine. But once you have three or more locators in an entry, then your index may be improved by adding some subheadings. If the locators in the above example refer separately to “horizontal” and “vertical”, then probably two subheadings would be more useful than two undifferentiated locators in one entry.
An additional problem which can be seen at a glance if you know what to look for, is the absence of any main headings with a large number of subheadings. On almost any subject there are topics which are addressed repeatedly. This should be reflected in the structure of the index. For example, in a group theory textbook there should be several entries under “group, examples”. In an introductory calculus book the index should help the reader locate the derivative of many different elementary functions.
Index headings should be nouns, not adjectives. An adjective may be important, and you should use it, but it should not be the entire content of a heading since it is not an idea by itself. But it may be a subheading. For example, suppose you have a paragraph on “highland sheep.” Then both of the following should appear in your index, since a reader might consult both locations.
highland sheep, 45
sheep
highland, 45
