DITA Proposed Feature # 45

Add See, See Also indexing elements.

Longer description

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.

  • index-see
  • index-see-also

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:

  • Carassius auratus, see Goldfish

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:

  • Carp, 56
    • see also Goldfish

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>.

  • Feeding, 348
    • see also Goldfish feeding
  • Goldfish
    • feeding, 56
    • flushing, 128, 345

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:
  • Carassius auratus, 98
    • see also Goldfish

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.

Discussion:

Scope

Small. Introducing a few new elements to the DTDs is trivial.

Use Case

Technical Requirements

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. There will be a new indexing domain indexing-p to accomodate the specializations of index-base.

The following is a sample implementation of the indexing elements in DTD:


<!-- shell DTD ----------------------------------------------------------->
<!ENTITY % indexing-d-dec     PUBLIC 
"-//OASIS//ENTITIES DITA Indexing Domain//EN" 
"indexingDomain.ent"                                                      >
%indexing-d-dec;

<!ENTITY % index-base "index-base | %indexing-d-index-base;">

<!ENTITY included-domains 
                        "&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att;
                         &ut-d-att; &indexing-d-att;"                     >

<!ENTITY % indexing-d-def     PUBLIC 
"-//OASIS//ELEMENTS DITA Indexing Domain//EN" 
"indexingDomain.mod">
%indexing-d-def;

<!-- metaDecl.mod -------------------------------------------------------->
<!ELEMENT indexterm      (%words.cnt;|%indexterm;|%index-base)*>
<!ELEMENT index-base     (%words.cnt;|%indexterm;)*>

<!ATTLIST index-base   %global-atts;  class CDATA "- topic/index-base ">

<!-- indexingDomain.ent -------------------------------------------------->
<!ENTITY % indexing-d-index-base 
     "index-see | index-see-also | index-sort-as | index-range start | index-range-end">

<!ENTITY indexing-d-att "(topic indexing-d)">

<!-- indexingDomain.mod -------------------------------------------------->
<!ELEMENT index-see        (%words.cnt;|%indexterm;)*>
<!ELEMENT index-see-also   (%words.cnt;|%indexterm;)*>
<!ELEMENT index-sort-as (%words.cnt;|%indexterm;)*>
<!ELEMENT index-range-start EMPTY>
<!ELEMENT index-range-end EMPTY>

<!ATTLIST index-see %global-atts; class CDATA 
                           "+ topic/index-base indexing-d/index-see ">
<!ATTLIST index-see-also %global-atts; class CDATA 
                           "+ topic/index-base indexing-d/index-see-also ">
<!ATTLIST index-sort-as %global-atts; class CDATA 
                           "+ topic/index-base indexing-d/index-sort-as ">
<!ATTLIST index-range-start %global-atts; class CDATA 
                           "+ topic/index-base indexing-d/index-range-start ">
<!ATTLIST index-range-end %global-atts; class CDATA 
                           "+ topic/index-base indexing-d/index-range-end ">

Costs

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.

Benefits

With these additions, DITA adopters will have a standard way to generate see and see also index entries.

Time Required

Less than a day.