<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"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">
<![CDATA[<para>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">
<![CDATA[<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>
]]> </programlisting>
</example>

</section>
</section>
</section>