Blob Blame History Raw
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<section id="sec-section-num">
<title>Chapter and Section numbering</title>

<title>Depth of Section numbering and Table Of Content</title>

<para><command>Dblatex</command> relies on latex to automatically compute the
chapter and section numbers. It also relies on latex to produce the headings
with these numbers, and to produce the Table Of Content containing these

<para>Some specific sections like <sgmltag>preface</sgmltag>,
<sgmltag>colophon</sgmltag>, or <sgmltag>dedication</sgmltag> are not numbered
because they are displayed in front and back matters, but they can be listed in
the TOC if the related parameters are set
(<parameter>dedication.tocdepth</parameter>, <parameter>preface.tocdepth</parameter>, <parameter>colophon.tocdepth</parameter>).</para>

<para>More generally you can configure the depth of the chapter and section
numbering with the parameter <parameter>doc.section.depth</parameter>, and the
depth of the entries in the TOC with the parameter

<para>Note however that an unumbered section
becomes an informal component, and therefore you can only link to such a section
by using a specific xrefstyle because their label built with the
automatic number does not exist anymore. The other drawback is that
all the sections included in an unnumbered section or chapter are

<title>Using the latex style for section numbering</title>

<para>A well customized latex style can be a powerfull yet versatile 
alternative to the use of section and/or TOC depth parameter. With some latex
packages you can easily format the headings to remove the numbers, or transform them. See <xref linkend="sec-custom-latex"/> to know how to use your own latex
style with <command>dblatex</command>.</para>

<para>The benefit of this method is that you can fully control how the titles
must be displayed, you do not have to play with latex counters to have the right
depth, and the sections do not lost their formal number label.</para>

<para>The following example shows how you can customize the chapter title by
using the latex package titlesec, and shows how to remove the chapter label in
the Table Of Content with the package titletoc. Look in particular in the
listing where text is emphasized.</para>

<para><programlisting language="tex">

%% Example 1: Redefines the heading to remove the chapter label
%% The 2nd parameter only contains \filcenter without any label
{\filcenter\huge}{]]><emphasis role="bold"><![CDATA[\filcenter]]></emphasis><![CDATA[}{20pt}{\Huge}

%% Example 2: Put the chapter number in word
%% The title of the first chapter is then displayed like this:
%% "Chapter One <chapter title>"

{]]><emphasis role="bold"><![CDATA[\filcenter\MakeUppercase{\chaptertitlename} \makeletterof{\thechapter}]]></emphasis><![CDATA[}{20pt}{\Huge}

%% Make TOC entries for chapters without label

\titlecontents{chapter} %
[1.5em] % 
{\addvspace{1em plus 0pt}\bfseries} %
{]]><emphasis role="bold"><![CDATA[\hspace{-1.3em}]]></emphasis><![CDATA[} % no number, remove room reserved for it 
{\hspace{-1.3em}} %
{\hfill \contentspage} %
[\addvspace {0pt}]

<title>Using the <sgmltag>label</sgmltag> attribute</title>

<para>If you need to mix numbered and not numbered chapters, the numbering depth
parameters will not help. The latex style will not easily detect that for
some chapters the number should be displayed and for others it should not.

<para>To mix numbered and unnumbered chapters you can use a label with an 
empty string for the chapters that must not be numbered, as shown by the example

<para><programlisting language="XML">
<![CDATA[<chapter id="intro" ]]><emphasis role="bold">label=""</emphasis><![CDATA[><title>Introduction</title>
  <!-- This chapter must be displayed with no number, like a preface -->
<chapter id="before" ]]><emphasis role="bold">label=""</emphasis><![CDATA[><title>Pre-requisite</title>
  <!-- This chapter must be displayed with no number, like a preface -->
<chapter id="chap1"><title>First chapter</title>
  <!-- First numbered chapter -->
<chapter id="after" ]]><emphasis role="bold">label=""</emphasis><![CDATA[><title>Conclusion</title>
  <!-- This chapter must be displayed with no number, like a colophon -->

<para>You can also set a label to a specific integer to force a section
counter. In this case there is no more automatic numbering. The automatic
numbering then applies to the following sections that increment the counter
set for this section if there is no label.</para>

<para><programlisting language="XML">
<![CDATA[<chapter id="intro" ]]><emphasis role="bold">label="2"</emphasis><![CDATA[><title>Introduction</title>
  <!-- This chapter is forced to have number 2 (it should be 1) -->
  <section id="s1" ]]><emphasis
  role="bold">label="3"</emphasis><![CDATA[><title>Section 2.3</title>
    <!-- This section is forced to have number 3 (it should be 1) -->
    <section id="s11" ]]><emphasis
    role="bold">label="4"</emphasis><![CDATA[><title>Section 2.3.4</title>
      <!-- This section is forced to have number 4 (it should be 1) -->