stylesheets/styleguide/docbook-xsl-1.75.2/params/make.index.markup.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"\r
   2           xmlns:xlink="http://www.w3.org/1999/xlink"\r
   3           xmlns:xi="http://www.w3.org/2001/XInclude"\r
   4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"\r
   5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"\r
   6           version="5.0" xml:id="make.index.markup">\r
   7 <refmeta>\r
   8 <refentrytitle>make.index.markup</refentrytitle>\r
   9 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>\r
  10 </refmeta>\r
  11 <refnamediv>\r
  12 <refname>make.index.markup</refname>\r
  13 <refpurpose>Generate XML index markup in the index?</refpurpose>\r
  14 </refnamediv>\r
  15 \r
  16 <refsynopsisdiv>\r
  17 <src:fragment xml:id="make.index.markup.frag">\r
  18 <xsl:param name="make.index.markup" select="0"/>\r
  19 </src:fragment>\r
  20 </refsynopsisdiv>\r
  21 \r
  22 <refsection><info><title>Description</title></info>\r
  23 \r
  24 <para>This parameter enables a very neat trick for getting properly\r
  25 merged, collated back-of-the-book indexes. G. Ken Holman suggested\r
  26 this trick at Extreme Markup Languages 2002 and I'm indebted to him\r
  27 for it.</para>\r
  28 \r
  29 <para>Jeni Tennison's excellent code in\r
  30 <filename>autoidx.xsl</filename> does a great job of merging and\r
  31 sorting <tag>indexterm</tag>s in the document and building a\r
  32 back-of-the-book index. However, there's one thing that it cannot\r
  33 reasonably be expected to do: merge page numbers into ranges. (I would\r
  34 not have thought that it could collate and suppress duplicate page\r
  35 numbers, but in fact it appears to manage that task somehow.)</para>\r
  36 \r
  37 <para>Ken's trick is to produce a document in which the index at the\r
  38 back of the book is <quote>displayed</quote> in XML. Because the index\r
  39 is generated by the FO processor, all of the page numbers have been resolved.\r
  40 It's a bit hard to explain, but what it boils down to is that instead of having\r
  41 an index at the back of the book that looks like this:</para>\r
  42 \r
  43 <blockquote>\r
  44 <formalpara><info><title>A</title></info>\r
  45 <para>ap1, 1, 2, 3</para>\r
  46 </formalpara>\r
  47 </blockquote>\r
  48 \r
  49 <para>you get one that looks like this:</para>\r
  50 \r
  51 <blockquote>\r
  52 <programlisting>&lt;indexdiv&gt;A&lt;/indexdiv&gt;\r
  53 &lt;indexentry&gt;\r
  54 &lt;primaryie&gt;ap1&lt;/primaryie&gt;,\r
  55 &lt;phrase role="pageno"&gt;1&lt;/phrase&gt;,\r
  56 &lt;phrase role="pageno"&gt;2&lt;/phrase&gt;,\r
  57 &lt;phrase role="pageno"&gt;3&lt;/phrase&gt;\r
  58 &lt;/indexentry&gt;</programlisting>\r
  59 </blockquote>\r
  60 \r
  61 <para>After building a PDF file with this sort of odd-looking index, you can\r
  62 extract the text from the PDF file and the result is a proper index expressed in\r
  63 XML.</para>\r
  64 \r
  65 <para>Now you have data that's amenable to processing and a simple Perl script\r
  66 (such as <filename>fo/pdf2index</filename>) can\r
  67 merge page ranges and generate a proper index.</para>\r
  68 \r
  69 <para>Finally, reformat your original document using this literal index instead of\r
  70 an automatically generated one and <quote>bingo</quote>!</para>\r
  71 \r
  72 </refsection>\r
  73 </refentry>\r