Add See, See Also indexing elements.
The current indexterm element cannot express the full range of indexing semantics needed for production book indexes. The inability to express "see" and "see also" index entries is one glaring example. This proposal introduces new child elements of indexterm that address the missing functionality.
The redirection elements' content will be the text of the referred-to entry. They will redirect the reader to the appropriate index entry.
Sort order will be specified by an element whose content will be the text to sort by. This controls how the index entry would be sorted relative to its peers, where the default would be to sort it by the entry's text. This allows a sort that ignores common words like "the" and "a," or leading punctuation characters such as "@href". This feature is important for some languages. For example, Japanese index entries would typically be sorted by their phonetic equivalent which cannot be reliably derived from the index entry text. Typically, correct sorting would require the presence of both the index entry text and the phonetic text.
Page range will be marked by start and end range markers. Within a topic, these markers will only span within that topic. Cross-topic spanning can be achieved by coalescing adjacent ranges ("DITA page 12-14, 14-15" becomes "DITA page 12-15"), or by spanning at the map level. If there is a start range marker but no end range marker, the index entry containing the start range marker will degrade into a simple single-page entry. The presence of an unmatched end range marker will cause a processing error. Note: Scott Prentice on the dita-users list suggested topic spanning by using an attribute to indicate that the indexterm spans the entire topic, which is another alternative.
All new indexterm child elements will have an "index-" prefix. So an index entry might look like:
<indexterm>Art
<indexterm>The Drawing
<index-sort-as>Drawing</index-sort-as>
<index-see-also>Illustration</index-see-also>
<index-range-start/>
</indexterm>
</indexterm>
The linking behavior of the redirection elements presents some difficulty, because it is not simply a matter of linking directly to another indexterm element. For example, consider the following extract from the index of a hypothetical book, "The Complete Aquarium Book":
In this example, there isn't a specific indexterm element for "Goldfish."It is only implicit in a multi-level indexterm such as <indexterm>Goldfish <indexterm>feeding </indexterm> </indexterm>. Any redirection to "Goldfish" remains valid even if individual entries like "selection" disappear depending on the DITA map's topic selection. In the case of "Carp," there are multiple indexterm instances that created the main entry: any redirection to "Carp" should remain valid even if one or more of these indexterms disappear. A third difficulty is that the reference to "Goldfish feeding" points to a nested indexterm. We need to define an identifier that a redirection element such as index-see can use to point to something yet to be generated. Some definitions might be useful:
If we adopt the textual content of an indexterm as its identifier, we can make links from an indexterm to an index entry or a combined indexed entry that is yet to be generated. For example, <index-see>Goldfish </index-see> will link to "Goldfish" because its content is the combined index entry's common prefix identifier. Similarly, a link to "Goldfish feeding" is possible with <index-see>Goldfish <indexterm>feeding </indexterm> </index-see> which mirrors the hierarchy of the indexterm that generates "Goldfish feeding": <indexterm>Goldfish <indexterm>feeding </indexterm> </indexterm>.
New child elements should be introduced to the indexterm element. They will not be specializations of indexterm itself: a domain specialization of indexterm will be available anywhere that indexterm is available, but these new elements are only meaningful as children of an indexterm element.
While the actual DTD changes are minor, the new semantics may require substantial work for processors that generate indexes.
With these additions, DITA adopters will have a standard way to generate production quality book indexes.