doc/xslt/params/generate.toc.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="generate.toc">
   7 <refmeta>
   8 <refentrytitle>generate.toc</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">table</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>generate.toc</refname>
  13 <refpurpose>Control generation of ToCs and LoTs</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17 <src:fragment xml:id="generate.toc.frag">
  18 <xsl:param condition="html" name="generate.toc">
  19 appendix  toc,title
  20 article/appendix  nop
  21 article   toc,title
  22 book      toc,title,figure,table,example,equation
  23 chapter   toc,title
  24 part      toc,title
  25 preface   toc,title
  26 qandadiv  toc
  27 qandaset  toc
  28 reference toc,title
  29 sect1     toc
  30 sect2     toc
  31 sect3     toc
  32 sect4     toc
  33 sect5     toc
  34 section   toc
  35 set       toc,title
  36 </xsl:param>
  37 <xsl:param condition="fo" name="generate.toc">
  38 /appendix toc,title
  39 article/appendix  nop
  40 /article  toc,title
  41 book      toc,title,figure,table,example,equation
  42 /chapter  toc,title
  43 part      toc,title
  44 /preface  toc,title
  45 reference toc,title
  46 /sect1    toc
  47 /sect2    toc
  48 /sect3    toc
  49 /sect4    toc
  50 /sect5    toc
  51 /section  toc
  52 set       toc,title
  53 </xsl:param>
  54 </src:fragment>
  55 </refsynopsisdiv>
  56
  57 <refsection><info><title>Description</title></info>
  58
  59 <para>This parameter has a structured value. It is a table of space-delimited
  60 path/value pairs. Each path identifies some element in the source document
  61 using a restricted subset of XPath (only the implicit child axis, no wildcards,
  62 no predicates). Paths can be either relative or absolute.</para>
  63
  64 <para>When processing a particular element, the stylesheets consult this table to
  65 determine if a ToC (or LoT(s)) should be generated.</para>
  66
  67 <para>For example, consider the entry:</para>
  68
  69 <screen>book toc,figure</screen>
  70
  71 <para>This indicates that whenever a <tag>book</tag> is formatted, a
  72 Table Of Contents and a List of Figures should be generated. Similarly,</para>
  73
  74 <screen>/chapter toc</screen>
  75
  76 <para>indicates that whenever a document <emphasis>that has a root
  77 of</emphasis> <tag>chapter</tag> is formatted, a Table of
  78 Contents should be generated. The entry <literal>chapter</literal> would match
  79 all chapters, but <literal>/chapter</literal> matches only <tag>chapter</tag>
  80 document elements.</para>
  81
  82 <para>Generally, the longest match wins. So, for example, if you want to distinguish
  83 articles in books from articles in parts, you could use these two entries:</para>
  84
  85 <screen>book/article toc,figure
  86 part/article toc</screen>
  87
  88 <para>Note that an article in a part can never match a <literal>book/article</literal>,
  89 so if you want nothing to be generated for articles in parts, you can simply leave
  90 that rule out.</para>
  91
  92 <para>If you want to leave the rule in, to make it explicit that you're turning
  93 something off, use the value <quote>nop</quote>. For example, the following
  94 entry disables ToCs and LoTs for articles:</para>
  95
  96 <screen>article nop</screen>
  97
  98 <para>Do not simply leave the word <quote>article</quote> in the file
  99 without a matching value. That'd be just begging the silly little
 100 path/value parser to get confused.</para>
 101
 102 <para>Section ToCs are further controlled by the
 103 <parameter>generate.section.toc.level</parameter> parameter.
 104 For a given section level to have a ToC, it must have both an entry in
 105 <parameter>generate.toc</parameter> and be within the range enabled by
 106 <parameter>generate.section.toc.level</parameter>.</para>
 107 </refsection>
 108 </refentry>