doc/xslt/params/index.links.to.section.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.links.to.section">
   7 <refmeta>
   8 <refentrytitle>index.links.to.section</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>index.links.to.section</refname>
  13 <refpurpose>HTML index entries link to container section title</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17 <src:fragment xml:id="index.links.to.section.frag">
  18 <xsl:param name="index.links.to.section" select="1"/>
  19 </src:fragment>
  20 </refsynopsisdiv>
  21
  22 <refsection><info><title>Description</title></info>
  23
  24 <para>If zero, then an index entry in an index links
  25 directly to the location of the
  26 generated <tag>anchor</tag> that is output
  27 for the indexterm. If two identical indexterm elements
  28 exist in the same section, then both entries appear
  29 in the index with the same title but link to different
  30 locations.</para>
  31
  32 <para>If non-zero, then an index entry in an index links to the
  33 section title containing the <tag>indexterm</tag>, rather than
  34 directly to the <tag>anchor</tag> output for the indexterm.
  35 Duplicate indexterm entries in the same section are dropped.
  36 </para>
  37
  38 <para>The default value is 1, so index entries link to
  39 section titles by default.</para>
  40
  41 <para>In both cases, the link text in an index entry is the
  42 title of the section containing the indexterm.
  43 That is because HTML does not have numbered pages.
  44 It also provides the reader with context information
  45 for each link.</para>
  46
  47 <para>This parameter lets you choose which style of
  48 index linking you want. </para>
  49
  50 <itemizedlist>
  51 <listitem>
  52 <para>When set to 0, an index entry takes you
  53 to the precise location of its corresponding indexterm.
  54 However, if you have a lot of duplicate
  55 entries in sections, then you have a lot of duplicate
  56 titles in the index, which makes it more cluttered.
  57 The reader may not recognize why duplicate titles
  58 appear until they follow the links. Also, the links
  59 may land the reader in the middle of a section where the
  60 section title is not visible, which may also be
  61 confusing to the reader.</para>
  62 </listitem>
  63 <listitem>
  64 <para>When set to 1, an index entry link is
  65 less precise, but duplicate titles in the
  66 index entries are eliminated.
  67 Landing on the section title location may confirm the reader's
  68 expectation that a link that
  69 shows a section title will take them to that section title,
  70 not a location within the section.
  71 </para>
  72 </listitem>
  73 </itemizedlist>
  74
  75 </refsection>
  76 </refentry>