<refentry xmlns="http://docbook.org/ns/docbook"
	  xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
	  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	  xmlns:xlink="http://www.w3.org/1999/xlink"
	  version="5.0" xml:id="generate.toc">
<refmeta>
<refentrytitle>generate.toc</refentrytitle>
<refmiscinfo role="type">table</refmiscinfo>
</refmeta>
<refnamediv>
<refname>generate.toc</refname>
<refpurpose>Control generation of ToCs and LoTs</refpurpose>
</refnamediv>

<refsynopsisdiv>
<src:fragment xml:id='generate.toc.frag'>
<xsl:param name="generate.toc" as="element()*">
<tocparam path="appendix"         toc="1" title="1"/>
<tocparam path="article/appendix" toc="1" title="1"/>
<tocparam path="article"          toc="1" title="1"/>
<tocparam path="book"             toc="1" title="1"
	                          figure="1" table="1"
				  example="1" equation="1"/>
<tocparam path="chapter"          toc="1" title="1"/>
<tocparam path="part"             toc="1" title="1"/>
<tocparam path="preface"          toc="1" title="1"/>
<tocparam path="qandadiv"         toc="1"/>
<tocparam path="qandaset"         toc="1"/>
<tocparam path="reference"        toc="1" title="1"/>
<tocparam path="sect1"            toc="1"/>
<tocparam path="sect2"            toc="1"/>
<tocparam path="sect3"            toc="1"/>
<tocparam path="sect4"            toc="1"/>
<tocparam path="sect5"            toc="1"/>
<tocparam path="section"          toc="1"/>
<tocparam path="set"              toc="1" title="1"/>
</xsl:param>
</src:fragment>
</refsynopsisdiv>

<refsect1><title>Description</title>

<para>FIXME:</para>

<para>This parameter has a structured value. It is a table of
space-delimited path/value pairs. Each path identifies some element in
the source document using a restricted subset of XPath (only the
implicit child axis, no wildcards, no predicates). Paths can be either
relative or absolute.</para>

<para>When processing a particular element, the stylesheets consult
this table to determine if a ToC (or LoT(s)) should be
generated.</para>

<para>For example, consider the entry:</para>

<screen>book toc,figure</screen>

<para>This indicates that whenever a <sgmltag>book</sgmltag> is
formatted, a Table Of Contents and a List of Figures should be
generated. Similarly,</para>

<screen>/chapter toc</screen>

<para>indicates that whenever a document <emphasis>that has a root
of</emphasis> <sgmltag>chapter</sgmltag> is formatted, a Table of
Contents should be generated. The entry <literal>chapter</literal>
would match all chapters, but <literal>/chapter</literal> matches only
<sgmltag>chapter</sgmltag> document elements.</para>

<para>Generally, the longest match wins. So, for example, if you want
to distinguish articles in books from articles in parts, you could use
these two entries:</para>

<screen>book/article toc,figure
part/article toc</screen>

<para>Note that an article in a part can never match a
<literal>book/article</literal>, so if you want nothing to be
generated for articles in parts, you can simply leave that rule
out.</para>

<para>If you want to leave the rule in, to make it explicit that
you're turning something off, use the value <quote>nop</quote>. For
example, the following entry disables ToCs and LoTs for
articles:</para>

<screen>article nop</screen>

<para>Do not simply leave the word <quote>article</quote> in the file
without a matching value. That'd be just begging the silly little
path/value parser to get confused.</para>

<para>Section ToCs are further controlled by the
<parameter>generate.section.toc.level</parameter> parameter. For a
given section level to have a ToC, it must have both an entry in
<parameter>generate.toc</parameter> and be within the range enabled by
<parameter>generate.section.toc.level</parameter>.</para>
</refsect1>
</refentry>
