Creating an Index

Internationalized Indexes

An index is automatically generated if some index entries (indexterm), telling the terms to put in the index, are written in the document. The keyword elements are not printed but are also added to the index.

Example 3.11. Index Entry

<para>In this paragraph is described the function 
<function>strcpy</function><indexterm><primary>strcpy</primary></indexterm>.
</para>
  

The index is put at the end of the document. It is not possible to put it somewhere else.

Internationalized Indexes

Indexing Tools

Makeindex is used by default to build the index. It works fine for latin charset but it is not suited for other charsets and UTF-8 encoding. Moreover its sorting rule is not suited for many languages.

Therefore dblatex gives the possibility to use xindy that allows internationalized indexing. When xindy is used, the sorting language used is deduced from the Docbook document lang. If the document lang has no correspondance for xindy, or if you want to force the use of a specific sorting language, you can specify the sorting language to use. With Xindy you can also provide your own sort rules, but see the official Xindy documentation for more details.

A parameter is provided to use xindy instead of makeindex:

  • latex.index.tool=xindy tells dblatex to use xindy instead of makeindex (default).

A typical use is then:

dblatex -P latex.index.tool=xindy file.xml

Index Sorting

Makeindex has very few methods to change its index sorting rules, except the -g and -L options which are not very hepfull in a DocBook context. On the contrary xindy can sort the index according to a specific language.

When xindy is used as index tool, dblatex passes to xindy through the xindy -L option the language name corresponding to the lang attribute of the document. If the document has no language or if xindy does not support the document language, the default sorting is applied. In this case you can use the following parameter:

  • latex.index.language specifies the language used to sort the indexes. Currently this parameter is relevant only for xindy. The language set must be known by xindy (see the xindy documentation). When not set (or empty) the sorting language to apply is deduced from the document lang.

The parameter can be used like any other like this:

dblatex -P latex.index.language=german-din file.xml

But it can also be used through an XSL configuration file to provide new mapping rules between ISO lang codes and known xindy languages, or override the current mapping done by dblatex as shown in Example 3.12, “XSL Index Language Setup”.

Example 3.12. XSL Index Language Setup

By default dblatex maps the de lang code to the language named german-din, and has no correspondance to map cy (Welsh) or eu (Basque). The following setup provides a mapping for these cases:

<xsl:param name="latex.index.tool">xindy</xsl:param>

<xsl:param name="latex.index.language">
  <xsl:variable name="lang">
    <xsl:call-template name="l10n.language">
      <xsl:with-param name="target" select="(/set|/book|/article)[1]"/>
      <xsl:with-param name="xref-context" select="true()"/>
    </xsl:call-template>
  </xsl:variable>

  <!-- Define Xindy lang to use in specific cases -->
  <xsl:choose>
  <xsl:when test="$lang='de'">german-duden</xsl:when>
  <xsl:when test="$lang='cy'">english</xsl:when>
  <xsl:when test="$lang='eu'">french</xsl:when>
  </xsl:choose>
</xsl:param>