"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<section id="sec-index" xmlns:xi="http://www.w3.org/2001/XInclude">

<title>Creating an Index</title>

  <para>

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

  </para>

<example><title>Index Entry</title>

  <programlisting language="XML">

In this paragraph is described the function 

<function>strcpy</function><indexterm><primary>strcpy</primary></indexterm>.

</para>

]]>  </programlisting>

</example>

  <para>

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

  </para>

<section id="sec-index-locale"><title>Internationalized Indexes</title>

<section id="sec-index-tools"><title>Indexing Tools</title>

<para><command>Makeindex</command> 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.</para>

<para>Therefore dblatex gives the possibility to use

<command>xindy</command> 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.</para>

<para>A parameter is provided to use xindy instead of makeindex:

<itemizedlist>

<listitem><para><parameter>latex.index.tool</parameter>=xindy tells dblatex 

to use xindy instead of makeindex (default).</para>

</listitem>

</itemizedlist>

</para>

<para>A typical use is then:

<screen>

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

</screen>

</para>

</section>

<section><title>Index Sorting</title>

<para><command>Makeindex</command> has very few methods to change its

index sorting rules, except the <option>-g</option> and <option>-L</option> options which are not very hepfull in a DocBook context. On the contrary <command>xindy</command> can sort the index according to

a specific language.</para>

<para>When xindy is used as index tool, <command>dblatex</command> passes to

xindy through the xindy <option>-L</option> option

the language name corresponding to the <literal>lang</literal> attribute of the

document. If the document has no language or if <command>xindy</command>

does not support the document language, the default sorting is applied. In this

case you can use the following parameter:

<itemizedlist>

<listitem><para><parameter>latex.index.language</parameter> 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.</para>

</listitem>

</itemizedlist>

</para>

<para>The parameter can be used like any other like this:

<screen>

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

</screen>

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 <xref linkend="xsl-index-lang"/>.

</para>

<example id="xsl-index-lang"><title>XSL Index Language Setup</title>

<para>By default dblatex maps the <literal>de</literal> lang

code to the language named <literal>german-din</literal>, and has no

correspondance to map <literal>cy</literal> (Welsh) or <literal>eu</literal>

(Basque). The following setup provides a mapping for these cases:

</para>

<programlisting language="XML">

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>

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

]]> </programlisting>

</example>

</section>

</section>

</section>