Overview of using the grouped and sorted index entries in the collected data to do index generation.

The collected data includes grouped-and-sorted index entries. This data can then be used to generate output-specific indexes, such as back-of-the-book indexes for print, navigation trees in online outputs, and so on.

The DITA for Publishers HTML2 and EPUB/Kindle transformation types provide examples of using the collected index entries to generate various output forms of the index. The HTML2 transformation type can include the index as part of the left-nav dynamic table of contents. The EPUB/Kindle transformation type can include the index as a HTML file with links back to the entries in content.

<mapdriven:collected-data xmlns:mapdriven="http://dita4publishers.org/mapdriven"
                          xmlns:index-terms="http://dita4publishers.org/index-terms"
                          xmlns:enum="http://dita4publishers.org/enumerables">
   <index-terms:index-terms>
      <index-terms:ungrouped>
        ...
      </index-terms:ungrouped>
      <index-terms:grouped-and-sorted>
          ...
          <index-terms:index-group grouping-key="g" sorting-key="g">
            <index-terms:label>G</index-terms:label>
            <index-terms:sub-terms>
               <index-terms:index-term grouping-key="g" sorting-key="general task">
                  <index-terms:label>general task</index-terms:label>
                  <index-terms:original-markup>
                     <indexterm xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
                                class="- topic/indexterm "
                                xtrf="/Users/ekimber/workspace/dita-for-practitioners/doc_src/body/part-arch-overview/conref-facility.xml"
                                xtrc="indexterm:69">general task</indexterm>
                  </index-terms:original-markup>
                  <index-terms:targets>
                     <index-terms:target source-uri="file:/Users/ekimber/workspace/dita-for-practitioners/doc_src/temp/epub/body/part-arch-overview/conref-facility.xml#subsection_gsu_mxu_hb">
                        <indexterm xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
                                   class="- topic/indexterm "
                                   xtrf="/Users/ekimber/workspace/dita-for-practitioners/doc_src/body/part-arch-overview/conref-facility.xml"
                                   xtrc="indexterm:69">general task</indexterm>
                     </index-terms:target>
                  </index-terms:targets>
                  <index-terms:sub-terms/>
               </index-terms:index-term>
               ...
            </index-terms:sub-terms>
            ...
         </index-terms:index-group>
         ...
      </index-terms:grouped-and-sorted>
    </index-terms:index-terms>
    ...
</mapdriven:collected-data>

The <index-terms:ungrouped> element contains the raw index entries in the order they occur in the source. You can normally ignore it.

The <index-terms:grouped-and-sorted> structure contains the grouped-and-sorted index entries. The structure is pretty self-explanatory. Each group and term has a grouping key and a sorting key. For groups the two will usually be the same, but for entries, they will usually be different. Each <index-terms:index-term> element contains the term's label, the original DITA <indexterm> markup, the targets to which the entry links (meaning all the places the original term occurred in the source), and any subordinate terms.

The index grouping and sorting is implemented in the file org.dita4publishers.common.mapdriven/xsl/indexProcessing.xsl. You can modify the default grouping and sorting behavior by overriding or extending the mode group-and-sort-index. You can modify the default grouping and sorting key construction by overriding the template for "topic/indexterm" in mode gather-index-terms. This template uses the functions local:construct-index-group-key() and local:construct-index-term-grouping-key() to construct the grouping and sort keys. You can implement your own functions if you need different grouping and sort keys, which is likely if you are working with non-English documents.