<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="sec-footnote">
<title>Footnotes</title>
<section id="sec-footnote-basic">
<title>Footnote Numbering Scope</title>
<para>The foonotes are well handled by latex. Dblatex just takes care about
special cases like footnotes in headings or in tables. Therefore the default
latex behaviour is applied for footnote numbering.</para>
<para>By default the footnote numbers are reset for each new chapter. If you
want to change the numbering scope, you can use the latex package <package>chngcntr</package> either in a customized latex style (see <xref linkend="sec-custom"/>) or in the parameter <parameter>latex.begindocument</parameter>. The following example makes the footnote numbers document wide.</para>
<programlisting language="XML"><![CDATA[
<xsl:param name="latex.begindocument">
<xsl:text>
% Want document wide footnotes
\usepackage{chngcntr}
\counterwithout{footnote}{chapter}
\begin{document}
</xsl:text>
</xsl:param>]]>
</programlisting>
</section>
<section id="sec-footnote-endnote">
<title>End Notes</title>
<para>You can configure <command>dblatex</command> to manage the footnotes as
endnotes. In this case the notes are expected to be displayed in a dedicated
section. The following sections tell how to do this.</para>
<section>
<title>Writing a document with endnotes</title>
<para>To have footnotes behaving as endnotes, you just need to set the
<parameter>footnote.as.endnote</parameter> to 1, and to put in your document an
empty <sgmltag>index</sgmltag> element with the attribute
<sgmltag>type</sgmltag> set to 'endnotes'. This index is supposed to be included
in a section dedicated to contain the notes, and therefore it does not display
any heading by itself. The section containing the endnotes index can also
contain any other materials.</para>
<example><title>Writing a document with endnotes</title>
<para>The following document contains some footnotes and a section for
the End Notes:
<programlisting language="XML"><![CDATA[
<book>
<chapter><title>A Chapter</title>
<para>Bla bla]]><emphasis role="bold"><![CDATA[<footnote id="fn1">First note</footnote>]]></emphasis><![CDATA[ bla
bla]]><emphasis role="bold"><![CDATA[<footnote id="fn2">Second note</footnote>]]></emphasis><![CDATA[ ...</para>
</chapter>
<chapter><title>Another Chapter</title>
<para>Bla bla]]><emphasis role="bold"><![CDATA[<footnote id="fn3">Third note</footnote>]]></emphasis><![CDATA[ bla
bla]]><emphasis role="bold"><![CDATA[<footnote id="fn4">Fourth note</footnote>]]></emphasis><![CDATA[ ...</para>
</chapter>
<chapter><title>End Notes</title>
<para>This chapter contains all the notes of the book.</para>
]]><emphasis role="bold"><![CDATA[<index type="endnotes"/>]]></emphasis><![CDATA[
</chapter>
</book>]]>
</programlisting>
</para>
<para><command>dblatex</command> is called with:</para>
<screen>$ dblatex -P <emphasis role="bold">footnote.as.endnote=1</emphasis> file.xml</screen>
</example>
</section>
<section>
<title>Setup Properties</title>
<para>Currently the endnotes are handled by the latex package
<package>endnotes</package>. You can customize its use with
the <parameter>endnotes.properties</parameter> attribute set. This attribute set
is filled by default with the values given by the internal attribute set
<parameter>endnotes.properties.default</parameter>, and you can override the
following attributes:</para>
<variablelist>
<varlistentry>
<term><sgmltag>package</sgmltag></term>
<listitem><simpara>Recall the latex package in charge to handle the
endnotes. Attribute provided for provision since currently there is
no real alternative with well established packages.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>heading</sgmltag></term>
<listitem><simpara>Macros to render the heading of the endnotes
to display.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>font-size</sgmltag></term>
<listitem><simpara>Macro specifying the font size to apply for each endnote.
The package default is <literal>\footnotesize</literal>. The dblatex default
is <literal>\normalsize</literal>.</simpara></listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>note-format</sgmltag></term>
<listitem><simpara>Macros specifying how the render a end note. The
package default is the same formatting that footnotes. The dblatex
default is to print out endnotes like a numbered list.</simpara></listitem>
</varlistentry>
</variablelist>
<para>The default setup:</para>
<programlisting language="XML">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="params/syn/endnotes.properties.xml"/></programlisting>
</section>
<section>
<title>Endnotes Setup from scratch</title>
<para>If you want to fully control the endnotes setup, add some other macros,
you can directly override the
template <literal>endnotes.setup</literal>, as shown by the example below.
If the endnote setup is already defined in your latex style you can override
the template to make it empty in order to avoid some conflict between the latex style
definition and the default one done by dblatex.</para>
<programlisting language="XML"><![CDATA[
<!-- Use the default endnotes package setup and change the heading -->
<xsl:template name="endnotes.setup">
<xsl:text>\usepackage{endnotes} </xsl:text>
<xsl:text>\def\enoteheading{\paragraph*{List Of Notes}%
\mbox{}\par\vskip-\baselineskip} </xsl:text>
</xsl:template>
]]></programlisting>
</section>
<section id="sec-endnotes-group">
<title>Grouping Endnotes</title>
<para>By default the endnotes are displayed for the whole document as a global
list. You can configure dblatex to show the endnotes grouped per part or per chapter. A heading is put before each group of notes to recall the component (part, chapter, or another section) that contains these notes. The purpose is to make the research of the notes at the end of the document easier for the reader.</para>
<para>To group the endnotes according to the granularity you wish,
you just need to
set the <parameter>endnotes.heading.groups</parameter> with the expected section
types separated by a space. For example, the following setup displays
notes per part and per chapter:</para>
<programlisting language="XML"><![CDATA[
<xsl:param name="footnote.as.endnote" select="1"/>
<xsl:param name="endnotes.heading.groups" select="'part chapter'"/>
]]></programlisting>
<section>
<title>Adding new Groups</title>
<para>By default dblatex can group the notes per chapter and/or per part,
provided that the section type is declared in <parameter>endnotes.heading.groups</parameter> as explained previously. If you want to add another section type you need to override the template called in mode <literal>endnotes</literal>, and to add this type to the declared groups. Usually the <literal>endnotes</literal> mode template only calls the <function>endnotes.add.header</function> template. The example below makes a new group for <sgmltag>preface</sgmltag>.</para>
<programlisting language="XML"><![CDATA[
<xsl:param name="endnotes.heading.groups" select="'part chapter preface'"/>
<xsl:template match="preface" mode="endnotes">
<xsl:call-template name="endnotes.add.header">
<xsl:with-param name="reset-counter" select="1"/>
</xsl:call-template>
</xsl:template>
]]></programlisting>
</section>
<section>
<title>Formatting the Headings text</title>
<para>You can use the parameter
<parameter>endnotes.heading.style</parameter> to format the headings of the groups with the same syntax than <sgmltag>xrefstyle</sgmltag> does. The example below gives a template where the title and the page of the chapter containing
the notes are displayed.</para>
<programlisting language="XML"><![CDATA[
<xsl:param name="endnotes.heading.style">
<xsl:text>template:Notes of the chapter "%t", page %p</xsl:text>
</xsl:param>
]]></programlisting>
</section>
<section>
<title>LaTeX Command to make the Headings</title>
<para>By default <command>dblatex</command> creates the headings of the groups
with a section command whose level is just below the level of the endnotes
section. For example, if the endnotes section is a chapter, the headings are
created by using a <literal>\section*</literal> latex command. If the endnotes
section is a section, the headings are done by using
<literal>\subsection*</literal>, and so on.</para>
<para>If this behaviour does not fit your needs you can specify the command to use with the parameter <parameter>endnotes.heading.command</parameter>. It can be usefull if you want to format these heading in a specific way. The heading markup produced following the <parameter>endnotes.heading.style</parameter> template is passed as an argument of
the specified command. The example below uses the command
<literal>\enoteheader*</literal> to create the headings. It assumes that this
macro is defined somewhere else (e.g. in a user latex style).</para>
<programlisting language="XML"><![CDATA[
<xsl:param name="endnotes.heading.command" select="'\enoteheader*'"/>
]]></programlisting>
</section>
<section>
<title>Endnotes Counter Scope</title>
<para>By default the endnotes counter restarts from one in each chapter or
part when they are grouped. You can change this behaviour by overriding
the <parameter>endnotes.counter.resetby</parameter> parameter that lists
the section types where the counter is reset. If you want a global
counter running for the whole document, just set the parameter empty.</para>
</section>
</section>
</section>
</section>