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 this 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. An index-see element expresses another entry that the reader should reference instead of that entry. For example,
<indexterm>Carassius auratus
<index-see>Goldfish</index-see>
</indexterm>
This will typically generate an entry without a page reference:
An index-see-also element expresses another entry that the reader may reference in addition to that entry. For example,
<indexterm>Carp
<index-see-also>Goldfish</index-see-also>
</indexterm>
This will typically generate a page reference to "Carp" and a redirection:
It may be desirable to express a hyperlink between the "see" entry and the entry to which it is referring to. On the other hand, if the deliverable does not need this linking, it should be straightforward to generate a "plain" index entry using just the static text in the indexterm element. In other words, it should be possible for the implementation to do the hard thing and easy to do the easy thing.
Expressing a redirection to a subentry is possible by mirroring the nesting hierarchy. For example, for the following index entries, the "see also" can be accomplished with <index-see-also>Goldfish <indexterm>feeding </indexterm> </index-see-also>.
In reusing content, there may easily arise situations where the index elements conflict. That is, a map may include a topic where a deprecated term identified by a index-see is also a generated index entry in another topic. In such a situation, the index-see shall degrade to the semantics of an index-see-also. For example, consider the following instances:
<indexterm>Carassius auratus<index-see>Goldfish</index-see></indexterm> ... <indexterm>Carassius auratus</indexterm>The result will be the following index entry, with the page reference coming from the second indexterm instance:
You can currently an indexterm in a map's metadata outside of any content (map/topicmeta/keywords/indexterm). In the absence of content context, an indexterm shall never generate page references, even if it contains an index-see-also element. An index-see element is most appropriate here, where it can declare preferred synonyms for the entire deliverable without conflicting with other contexts of reuse. An index-see-also element here can add a "see also" subentry to an index entry without modifying the topic being reused.
New child elements will 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. These will be new elements that specialize off a new common index-base element. This will allow other indexing extensions to be added as specializations of index-base. This will make it easier for index generators to handle indexing elements that they understand while filtering out those that they cannot handle.
Minimal: add two new elements.
Processors will need to handle the new elements, with varying levels of work. Processors can do something exotic like inserting hyperlinks to jump from a see-also entry to the referred-to entry. Alternatively, they can just insert the static text prepended by a "See" or "See also" label.