Indexing

DITA 1.1 supports the following new indexing elements:
Note:
  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.

See and See Also indexing elements

In DITA 1.0, you cannot specify the <see> and <see also> index entries by using the current <indexterm> element. The DITA1.1 standard introduces the following new child elements for <indexterm> that support this functionality:


For example, you can add an index entry, as illustrated in the following text in the DITA source file:
<indexterm>computer
   <index-see>monitor</index-see>
   <index-see-also>Illustration</index-see-also> 
</indexterm>
Then, if you generate a PDF output with the indexing function enabled, you can see the following index entries in the PDF output:

computer 43
        See monitor
        See also Illustration
The "monitor" and "Illustration" entries after "see" and "see also" will not be links to the "monitor" and "Illustration" index entries in a PDF output.
Index entries will only be processed when you generate HTMLHelp and JavaHelp. For HTMLHelp and JavaHelp, the index contains an entry that uses the text "See xxx" or "See also xxx". The "See xxx" or "See also xxx" index entries will link to their parent index term.
Note:
  • For HTML output, indexing is ignored.
  • For PDF output, you must enable indexing using the FO plugin provided by Idiom.
For example, if you put the following content in the source file,
<indexterm>computer
   <index-see>monitor</index-see>
</indexterm>
the output is as follows:

computer
  See monitor

Sort order indexing elements

With the DITA 1.1 standard, you can specify a sort phrase and sort index entries under the sort phrase. This feature provides you with the flexibility to sort an index entry in a different way. Typically you can disregard insignificant leading text, such as punctuation or words like "the" or "a". If you want to sort <data> under the letter D rather than the character "<", you can include such an entry under both the punctuation heading and the letter D. Thus, there can be two index entry directives differentiated only by the sort order.

For example, if you put the following content in the source file,
  <indexterm>data<index-sort-as>key</index-sort-as></indexterm>
  <indexterm>indextest<index-sort-as>abc</index-sort-as></indexterm>
the output should be:

indextest
data

If you have written an XML book with many punctuation-laden entries in its index, you can use the <index-sort-as> element to specify how the sorting method of the entries if the punctuation marks are eliminated. For example, <data> is always displayed as an entry <data> in the index term under the letter D; otherwise, all the entries with punctuations will be sorted under "<".

Here is another example. In a translation project, a document needs to be translated into Japanese. Many of the index entries contain kanji, which need to be sorted in phonetic order. The translators, who can understand the language and see the entry in its context, can insert the <index-sort-as> elements into the <indexterm> elements as part of their localization work.

Page-range indexing elements

In DITA OT 1.3, you can indicate page ranges instead of individual references over consecutive pages. Page ranges indicate where the index entry links to an extended discussion that goes over a number of pages. This is typically manifested as a page range like 34-36. This is distinguished from individual references over consecutive pages (34, 35, 36). The page-range indexing function is enabled when you use the FO plugin.

For example, you can add a page spanning index entry:
<indexterm>DITA<index-range-start/></indexterm>
. Later in the same topic, you can add a range terminating marker: <indexterm>DITA<index-range-end/></indexterm>. This spans 4 pages on the paper, as illustrated in the following example.
DITA, 46-49
Note: If you generate HTMLHelp, JavaHelp, and XHTML outputs, the page-range indexing elements are ignored.

Supporting ICU in index sorting

With enabled ICU interface, DITA Open Toolkit 1.3 helps you get correctly sorted index output for different languages.

During normal transformation, the toolkit tries to find if there are ICU classes inside the classpath element. If ICU exists, the toolkit uses ICU's Collator class to do the comparing and sorting work. If no ICU is found, the toolkit will use JDK's Collator class to do the comparing and sorting work. ICU is packed in the big package in DITA OT 1.3