Chunking in DocBook 5 limits TOC depth and makes it skip numbers?

Question

I have a DocBook V5.0 document that used to be one .docbook file containing the entire book. At that point, the generated TOC looked fine. Now, I have chunked the input into 4 different .docbook files and also want chunked output.

After this change I suddenly have two problems:

1. The TOC only contains four entries (one for each .docbook) rather than the full depth it used to
2. Quite oddly, the TOC chapter numbers are 1, 2, and 4, then the glossary, which doesn't have a number.

About the latter, if I remove the second chapter, I get 1, 2, and the glossary, so I guess it's nothing about the second chapter's content that causes the misnumbering.

Anyway, my question is, how do I restore a normal-looking TOC while retaining chunked input and output? (The chunking could even be limited to single-file depth, i.e., one file in, one file out--but I want the TOC depth much higher.)

What I did

I made my main file look like this:

<!DOCTYPE book [
    <!ENTITY a SYSTEM "a.docbook">
    <!ENTITY b SYSTEM "b.docbook">
    <!ENTITY c SYSTEM "c.docbook">
    <!ENTITY glossary SYSTEM "glossary.docbook">
    <!ENTITY larr "&#x2190;">
    <!ENTITY rarr "&#x2192;">
    <!ENTITY mdash "&#x2014;">
]>
<book xmlns:xl="http://www.w3.org/1999/xlink">
<title>My Title</title>
&a;
&b;
&c;
&glossary;
</book>

My XSL is similar to before with the addition of a handful of chunking control options (but no changes to the original TOC option):

<?xml version='1.0'?>
<xsl:stylesheet  
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl"/>

<xsl:output method="html"
            encoding="UTF-8"
            indent="no"/>
<!--new--><xsl:param name="chunk.quietly" select="1"></xsl:param>
<!--new--><xsl:param name="chunker.output.encoding">UTF-8</xsl:param>
<!--new--><xsl:param name="html.extra.head.links" select="0"></xsl:param>
<xsl:param name="html.stylesheet" select="'main.css'"/>
<xsl:param name="generate.toc">
  book      toc,title
</xsl:param>
<xsl:param name="glossentry.show.acronym">yes</xsl:param>
<xsl:param name="glossary.sort" select="1"></xsl:param>
<!--new--><xsl:param name="use.id.as.filename" select="1"></xsl:param>

</xsl:stylesheet>

My .docbook files all look like this:

A ...

Except glossary.doc which is:

Glossary

Now, I realize it may be a bit strange having a chapter within a chapter. This may even be the cause. However, it validates without warning, and also, if I make the outermost tag in a given file <section> instead, then the entire file is missing from the TOC.

Answer 1

TIP: Replace the older <!ENTITY ...> with xinclude. This has the advantage that all can be nice validated by xml schema's. Also XML editors can better away with xinclude, then with the file inclusion through ENTITY.

Below is an example:

File: book.xml

<?xml version="1.0" encoding="UTF-8"?>

<book version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>This is a book</title>
  </info>

  <chapter>
    <title>This is a chapter</title>

    <section>
      <title>This is a section</title>

      <para>This is a paragraph.</para>
    </section>

    <xi:include href="included_section.xml" />
  </chapter>
</book>

File: include_section.xml

<?xml version="1.0" encoding="UTF-8"?>

<section version="5.0" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns5="http://www.w3.org/2000/svg"
         xmlns:ns4="http://www.w3.org/1998/Math/MathML"
         xmlns:ns3="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <title>This is an included section</title>
  <para>This is an included paragraph.</para>

  <mediaobject>
    <imageobject>
      <imagedata fileref="media/martin-luther-king.jpg"></imagedata>
    </imageobject>
  </mediaobject>
</section>

In this example there is also an directory media containing the file martin-luther-king.jpg.

Your example above would look like:

<book version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:db="http://docbook.org/ns/docbook">
    <title>My Title</title>
    <xi:include href="chapter-a.xml" />
    <xi:include href="chapter-b.xml" />
    <xi:include href="chapter-c.xml" />
    <xi:include href="glossary.xml" />
</book>

And each separate chapter file, could look like:

<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:db="http://docbook.org/ns/docbook">
    <title>This is a chapter</title>

    <section>
      <title>This is a section</title>

      <para>This is a paragraph.</para>
    </section>
</chapter>

And the glossary file, could look like:

<?xml version="1.0" encoding="UTF-8"?>
<glossary version="5.0" xmlns="http://docbook.org/ns/docbook" 
        xmlns:xi="http://www.w3.org/2001/XInclude" 
        xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>Example Glossary</title>

    <para>
        This is not a real glossary, it's just an example.
    </para>
</glossary>

Answer 2

Do not nest chapters within the included .docbook files. Use chapter for the outermost tag and section for everything within.

(Despite validation, I discovered that the shortest file, which I tried to restructure by changing its outermost tag to chapter and then its inner chapter tag to section, actually had a missing pair of chapter tags, so it had had a chapter with two titles and so on. Before noticing this, this had been causing it not to show up on the TOC, so I had assumed that I had proven that section-within-chapter didn't work for some reason, when actually it was these missing tags from my cut-n-paste job. Don't rely on the validator!)