When the stylesheet parameter index.method is set to basic, the default indexing processing is used. Since this is the default value, all you need to do is add an empty index element to your document in the location where you want an index to be generated. The stylesheet will do the rest.

If you are wondering how the basic method operates, here is a summary of the steps:

When the stylesheet parameter index.method is set to kosek, a different indexing process is used. This method adds the ability to define indexing groups and their members, and the order of the groups within the index.

However, setting the parameter is not sufficient. You must use a customization layer in order to import a supplemental stylesheet module that contains some additional templates that are needed by this method. For example:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version="1.0">
<xsl:param name="index.method">kosek</xsl:param>
<xsl:import href="docbook-xsl/fo/docbook.xsl"/>
<xsl:import href="docbook-xsl/fo/autoidx-kosek.xsl"/>
...

For an HTML customization layer, you would import the corresponding autoidx-kosek.xsl file from the html or xhtml stylesheet directory.

The definitions of the groups used by this method are in the gentext locale files, such as common/fr.xml for French.

<l:letters>
      <l:l i="-1"/>
      <l:l i="0">Symboles</l:l>
      <l:l i="1">A</l:l>
      <l:l i="1">a</l:l>
      <l:l i="1">&#224;</l:l>
      <l:l i="1">&#192;</l:l>
      <l:l i="1">&#226;</l:l>
      <l:l i="1">&#194;</l:l>
      <l:l i="1">&#198;</l:l>
      <l:l i="1">&#230;</l:l>
      <l:l i="2">B</l:l>
      <l:l i="2">b</l:l>
      ...

Note these features of the configuration:

All of the gentext files in the common directory of the stylesheet distribution have a set of groups defined. But many have not yet been actually prepared for the specific language, and are just a copy of the groups from the English file (which has many accented characters in its groups anyway). You can identify such groups by the lang="en" attribute on the l:letters element in the gentext file. If your language has not been properly prepared, you can create a further customization of the gentext elements. That process is described in the section “Customizing generated text”. If you are confident that it is correct, you could submit it back to the DocBook development team for inclusion in future releases.

The sorting of entries within each group is handled in the stylesheet by an xsl:sort element, with a lang attribute whose value is taken from the document being processed. So you must have an appropriate lang attribute on the root element of your document.

XSLT processors hand off the actual sorting process to the operating system. So the results will depend on how well your operating system can sort the language specified. If it does not have the proper collation rules for your language, then the results will likely be unsatisfactory.

For the customization to work, the XSLT processor must be able to use EXSLT extension functions, and it must be able to use them in xsl:key elements. Saxon is known to work with the customization. But xsltproc does not support using the EXSLT extensions in xsl:key, and so will not work.

When the stylesheet parameter index.method is set to kimber, Java extension functions are used in building the index. The Java classes used in this method were written by Eliot Kimber of Innodata Isogen, Inc. and donated to the open source community. A white paper describing the package is available at:

This index method is the most flexible and powerful, but also the most difficult to set up. Currently the Saxon 6 and 8 processors work with the extensions. Here is what you need to do.

If all the pieces are in place, you should get an index that is generated using the Java extensions. If you had not set a lang attribute on your document's root element, or if the value did not match those in the configuration file, then you will see a message like the following:

 - Failed to find index configuration for language 'xy', trying English.

This tells you that the code is working, but the configuration is not quite right. In the location where you unpacked the library, you will find the indexing configuration file config/botb_index_rules/botb_index_rules.xml (here botb means “back-of-the-book”). That configuration file has an index_config element for each locale, containing all the configuration elements for that language. See the white paper mentioned above for details on the configuration elements.

In order for the configuration to work for your language, the lang attribute on your document root element must match the value of a national_language element in the configuration file. For example, here is the start of the configuration for Czech:

<index_config>
  <national_language>cs-CZ</national_language>
  <description> <p>Czech index configuration</p> </description>
  <collation_spec></collation_spec>
  <sort_method>
    <sort_by_members/>
  </sort_method>
  <group_definitions>
    <term_group>
      <group_key>A</group_key>
      <group_members>
        <char_or_seq>a</char_or_seq>
        <char_or_seq>A</char_or_seq>
        <char_or_seq>Á</char_or_seq>
        <char_or_seq>á</char_or_seq>
      </group_members>
    </term_group>
    <term_group>
      <group_key>B</group_key>
      <group_members>
        <char_or_seq>b</char_or_seq>
        <char_or_seq>B</char_or_seq>
        ...

A document element should have a lang="cs-CZ" in order for this index configuration to be used. Otherwise edit the configuration file's national_language element to match your document's lang value.

For ideographic languages such as Chinese and Korean, the configuration file can use the sort_between_keys sort method, and specify an optional collation rules file, as shown in the following example:

<index_config>
  <national_language>ko-KR</national_language>
  <description>
    <p>Index configuration for Korean</p>
  </description>
  <collation_spec>
    <java_collation_spec>
      <include_collation_spec>ko-sort-rules.txt</include_collation_spec>
    </java_collation_spec>
  </collation_spec>
  <sort_method>
    <sort_between_keys/>
  </sort_method>
  <group_definitions>
  <term_group>
    <group_key>&#x3131;</group_key>
    <group_members></group_members>
  </term_group>

When sort_between_keys is used, all of the index terms are sorted into a stream for processing. As each term is processed, if its first character matches a group_key value, that triggers the start of a new index group. All characters in the stream up to the next match are in that group. This method is most suitable for alphabets that have thousands of characters that make group lists impractical. You can also specify your own sort order for the characters by specifying a file containing a Java collation specification. See the white paper described above for more information.