doc/xslt/params/index.method.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude"
   4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
   5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   6           version="5.0" xml:id="index.method">
   7 <refmeta>
   8 <refentrytitle>index.method</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">list</refmiscinfo>
  10 <refmiscinfo class="other" otherclass="value">basic</refmiscinfo>
  11 <refmiscinfo class="other" otherclass="value">kosek</refmiscinfo>
  12 <refmiscinfo class="other" otherclass="value">kimber</refmiscinfo>
  13 </refmeta>
  14 <refnamediv>
  15 <refname>index.method</refname>
  16 <refpurpose>Select method used to group index entries in an index</refpurpose>
  17 </refnamediv>
  18
  19 <refsynopsisdiv>
  20 <src:fragment xml:id="index.method.frag">
  21 <xsl:param name="index.method">basic</xsl:param>
  22 </src:fragment>
  23 </refsynopsisdiv>
  24
  25 <refsection><info><title>Description</title></info>
  26
  27 <para>This parameter lets you select which method to use for sorting and grouping
  28  index entries in an index.
  29 Indexes in Latin-based languages that have accented characters typically
  30 sort together accented words and unaccented words.
  31 Thus <quote>Á</quote> (U+00C1 LATIN CAPITAL LETTER A WITH ACUTE) would sort together
  32 with <quote>A</quote> (U+0041 LATIN CAPITAL LETTER A), so both would appear in the <quote>A</quote>
  33 section of the index.
  34 Languages using other alphabets (such as Russian,  which is written in the Cyrillic alphabet)
  35 and languages using ideographic chararacters (such as Japanese)
  36 require grouping specific to the languages and alphabets.
  37 </para>
  38
  39 <para>The default indexing method is limited.
  40 It can group accented characters in Latin-based languages only.
  41 It cannot handle non-Latin alphabets or ideographic languages.
  42 The other indexing methods require extensions of one type or
  43 another, and do not work with
  44 all XSLT processors, which is why they are not used by default.</para>
  45
  46 <para>The three choices for indexing method are:</para>
  47 <variablelist>
  48 <varlistentry>
  49 <term><literal>basic</literal></term>
  50 <listitem>
  51 <para>
  52 (default)  Sort and groups words based only on the Latin alphabet.
  53 Words with accented Latin letters will group and sort with
  54 their respective primary letter, but
  55 words in non-Latin alphabets will be
  56 put in the <quote>Symbols</quote> section of the index.
  57 </para>
  58 </listitem>
  59 </varlistentry>
  60 <varlistentry>
  61 <term><literal>kosek</literal></term>
  62 <listitem>
  63 <para>
  64 This method sorts and groups words based on letter groups configured in
  65 the DocBook locale file for the given language.
  66 See, for example, the French locale file <filename>common/fr.xml</filename>.
  67 This method requires that the XSLT processor
  68 supports the EXSLT extensions (most do).
  69 It also requires support for using
  70 user-defined functions in xsl:key (xsltproc does not).
  71 </para>
  72 <para>This method is suitable for any language for which you can
  73 list all the individual characters that should appear
  74 in each letter group in an index.
  75 It is probably not practical to use it for ideographic languages
  76 such as Chinese that have hundreds or thousands of characters.
  77 </para>
  78
  79 <para>To use the kosek method, you must:</para>
  80
  81 <orderedlist>
  82 <listitem>
  83 <para>Use a processor that supports its extensions, such as
  84 Saxon 6 or Xalan (xsltproc and Saxon 8 do not).
  85 </para>
  86 </listitem>
  87 <listitem>
  88 <para>Set the index.method parameter's value to <quote>kosek</quote>.
  89 </para>
  90 </listitem>
  91 <listitem>
  92 <para>Import the appropriate index extensions stylesheet module
  93 <filename>fo/autoidx-kosek.xsl</filename> or
  94 <filename>html/autoidx-kosek.xsl</filename> into your
  95 customization.
  96 </para>
  97 </listitem>
  98 </orderedlist>
  99
 100 </listitem>
 101 </varlistentry>
 102 <varlistentry>
 103 <term><literal>kimber</literal></term>
 104 <listitem>
 105 <para>
 106 This method uses extensions to the Saxon processor to implement
 107 sophisticated indexing processes. It uses its own
 108 configuration file, which can include information for any number of
 109 languages. Each language's configuration can group
 110 words using one of two processes. In the
 111 enumerated process similar to that used in the kosek method,
 112 you indicate the groupings character-by-character.
 113 In the between-key process, you specify the
 114 break-points in the sort order that should start a new group.
 115 The latter configuration is useful for ideographic languages
 116 such as Chinese, Japanese, and Korean.
 117 You can also define your own collation algorithms and how you
 118 want mixed Latin-alphabet words sorted.</para>
 119 <itemizedlist>
 120 <listitem>
 121 <para>For a whitepaper describing the extensions, see:
 122 <link xlink:href="http://www.innodata-isogen.com/knowledge_center/white_papers/back_of_book_for_xsl_fo.pdf">http://www.innodata-isogen.com/knowledge_center/white_papers/back_of_book_for_xsl_fo.pdf</link>.
 123 </para>
 124 </listitem>
 125 <listitem>
 126 <para>To download the extension library, see
 127 <link xlink:href="http://www.innodata-isogen.com/knowledge_center/tools_downloads/i18nsupport">http://www.innodata-isogen.com/knowledge_center/tools_downloads/i18nsupport</link>.
 128 </para>
 129 </listitem>
 130 </itemizedlist>
 131
 132 <para>To use the kimber method, you must:</para>
 133
 134 <orderedlist>
 135 <listitem>
 136 <para>Use Saxon (version 6 or 8) as your XSLT processor.
 137 </para>
 138 </listitem>
 139 <listitem>
 140 <para>Install and configure the Innodata Isogen library, using
 141 the documentation that comes with it.
 142 </para>
 143 </listitem>
 144 <listitem>
 145 <para>Set the index.method parameter's value to <quote>kimber</quote>.
 146 </para>
 147 </listitem>
 148 <listitem>
 149 <para>Import the appropriate index extensions stylesheet module
 150 <filename>fo/autoidx-kimber.xsl</filename> or
 151 <filename>html/autoidx-kimber.xsl</filename> into your
 152 customization.
 153 </para>
 154 </listitem>
 155 </orderedlist>
 156
 157 </listitem>
 158 </varlistentry>
 159 </variablelist>
 160
 161 </refsection>
 162 </refentry>