Re: [docbook] Table of Contents structure

[Michael Smith <smith@xml-doc.org>]

Hi Dee,

You wrote:

> Hi,
> New to the list, and this is my first question.
> I've been doing XML work for the last several years now, using my own structure
> designs for each job. This is the first time though I've tried marking up a doc
> using Docbook (customer requires it). My problem is in the TOC Preface section.
> There does not seem to be enough depth there to do what I need. I have a preface
> with multiple levels (sections). The Tocfront elements don't allow sublevels
> (children), and I don't want to use the Tocchap elements until I get into the
> main body (chapters) of the TOC. Tocpart seems to be limited to just Tocentry
> too...

What you say about Tocfront is true.
The Tocfront content model doesn't allow child Tocentry elements because
it is apparently based on the assumption (too-restrictive, it seems)
that users are dealing with documents that follow the convention of not
having the TOC list subsections (if any) that a Preface might have. Most
existing TOCs in printed documents do follow that convention, but I'm
sure there are many exceptions -- like the documents you're working with.

As far as Tocpart goes, it actually isn't limited to just Tocentry. It
can include Tocchap as well, though that doesn't do you any good,
because you say you don't want to use Tocchap.

But, unfortunately, as far as I can see, if your preface has subsections
and you want them listed in the TOC, using Tocchap to mark up your
preface TOC along with the chapter TOCs is the only solution the current
DTD provides.

What's the reason you don't want to use Tocchap for the preface? If it's
just that it doesn't allow you to distinguish the preface from the
chapters, you can use a role attribute on Tocchap.

> So may Preface would look something like this normally (by my own design..):
> <toc>
>   <title>Contents</title>
>   <preface>
>     <tocA>A-title</tocA>
>     <tocA>A-title
>        <tocB>B-title</tocB>
>        <tocB>B-title</tocB>
>     </tocA>
>     <tocA>A-title
>        <tocB>B-title</tocB>
>        <tocB>B-title</tocB>
>     </tocA>
>    </preface>
>    <chapter value="1">
>        ... and so on.

Here's how I would mark that up using the current DTD. 

  <!DOCTYPE toc
    PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   >
  <toc>
    <title>Contents</title>
    <tocchap label="Preface" role="TOCpreface">
      <tocentry
        linkend="id_of_preface_element_in_your_source"
        pagenum="page_where_preface_starts_in_your_legacy_doc"
      />
      <toclevel1>
        <tocentry linkend="A1-titleID" pagenum="xx" />
        <toclevel2>
          <tocentry linkend="A1-B1-titleID" pagenum="xx" />
        </toclevel2>
        <toclevel2>
          <tocentry linkend="A1-B2-titleID" pagenum="xx" />
        </toclevel2>
      </toclevel1>
      <toclevel1>
        <tocentry linkend="A2-titleID" pagenum="xx" />
        <toclevel2>
          <tocentry linkend="A2-B1-titleID" pagenum="xx" />
        </toclevel2>
        <toclevel2>
          <tocentry linkend="A2-B2-titleID" pagenum="xx" />
        </toclevel2>
      </toclevel1>
    </tocchap>
    <tocchap label="Chapter 1">
      <tocentry
        linkend="id_of_first_chapter_element_in_your_source"
        pagenum="xx"
      />
      <toclevel1>
        <tocentry>etc</tocentry>
      </toclevel1>
    </tocchap>
  </toc>

Note that there is an open proposal to greatly simplify the current TOC
content model. See here:

  http://lists.oasis-open.org/archives/docbook/200202/msg00109.html

If that proposal passes, we would eventually have a DTD that would allow
you to use nested Tocentries in place of Tocfront, Tocpart, Tocchap, and
all the Toclevel* elements. So in my example about, you could just
substitute Tocentry for all the Tocchap, Toclevel1 and Toclevel2 stuff.

以上。よろしくお願いします。

PGP signature