]> git.stg.codes - stg.git/blob - doc/xslt/params/generate.toc.xml
Ticket 26. The if (newSettings.GetLogFileName() != "") construction
[stg.git] / 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>