[docbook-tc] RFE 482818: Simplify ToC content model (long)

Regarding the proposal for RFE 482818 (former RFE 97)[1], I figured it
might be useful to compare the proposed content models to examples
from other DTDs. But after looking around, I couldn't find anything
useful at all. The ISO 12083 and TEI DTDs don't have any TOC content
models, and the ones I could find in other DTDs just weren't relevant.

Anyway, about the proposed content models themselves, here are a bunch
of questions and points it seems like we might need to consider before
deciding to make the changes.

 1. The current content model for Tocentry is not recursive, but the
    proposed content model for Tocentry is. Why? Is it because part of
    the simplification plan is to drop the numbered Toclevel* hierarchy?

 2. The proposal drops Tocfront, Tocback, and Tocpart from the content
    model for Toc, and so I guess from the DTD completely, since Toc
    is their only parent.

 3. The proposal also drops Tocchap from the content model for Toc. But
    Tocchap will remain as a child of Appendix, Article, and Chapter
    (its intended use there, I guess, is for creating embedded
    mini-tocs for those components, the way the stylesheets do).

 4. In place of Tocfront/Tocback/Tocpart/Tocchap, the proposal allows
    Tocentry as a direct child of Toc, along with a new element,
    Tocdiv. Dropping the old stuff and replacing it with Tocdiv/
    Tocentry seems like the main intended simplification in the proposal.

 5. Tocdiv seems to be intended as a new TOC-sectioning element or
    formal (titled) object:

      <!ELEMENT ToCDiv - O ((%sect.title.content;)?,
                             ((%tocdivcomponent.mix;)*,
                            ToCEntry+))>

    The current children of Toc are not formal objects. Their content
    models are actually simpler:

      <!ELEMENT tocfront (%para.char.mix;)*>
      <!ELEMENT tocback  (%para.char.mix;)*>
      <!ELEMENT tocpart  (tocentry+, tocchap*>
      <!ELEMENT tocchap  (tocentry+, toclevel1*)>

    Why add a formal object to the Toc hierarchy? Is it so that users
    can do something like the following?

      <tocdiv>
        <title>Chapter 5: Deploying the Application</title>
        <tocentry pagenum="120">Section 1: Installation</tocentry
        <tocentry pagenum="131">Section 2: Configuration</tocentry
        ...
      </tocdiv>

 6. If Tocdiv is to be used in the Toc as a sectioning element, should
    it be recursive -- so users could do something like the following?

      <tocdiv>
        <title>Part II</title>
        <tocdiv>
          <title>Chapter 5</title>
          <tocentry pagenum="120">Section 1: Installation</tocentry
          ...
        </tocdiv>
        <tocdiv>
          <title>Chapter 6</title>
          <tocentry pagenum="150">Section 1: Troubleshooting</tocentry
          ...
        </tocdiv>
      </tocdiv>

    Or will we expect users to just nest Tocentries to get the
    structure and presentation they want? If we do that, it seems like
    Tocentry will need a "label" attribute, as Tocpart/Tocchap do now,
    so they could do something like this:

      <tocdiv>
        <title>Part II</title>
        <tocentry label="Chapter 5">
          <tocentry pagenum="120">Section 1: Installation</tocentry
          ...
        </tocentry>
      </tocdiv>

 7. With Tocdiv, what do users do about the case where they want to
    indicate a division, but don't want to include any Tocentries
    beneath it? That is, all they want is for the title of the division
    to appear in the Toc -- like the case of an index for example?

    Should the Tocdiv content model allow Tocdiv to contain just a
    Title, but no Tocentries, so something like this would be valid:

      <tocdiv pagenum="300">
        <title>Index</title>
      </tocdiv>

    Or is it simpler to just say that users should do the following
    instead?

      <tocentry pagenum="300">Index</tocentry>

 8. Aren't TOC entries for the different top-level stuff -- the ones
    for Part and the components (Preface, Chapter, Appendix, Glossary,
    Index, etc.) -- sometimes styled differently from one another? It
    seems like that was part of the rationale behind the Tocfront/
    Tocback/Tocchap/Tocpart distinction. So if that distinction is
    removed, it seems like we need to provide a way for users to style
    top-level component entries differently from one another.

    Maybe we could do that with a "class" attribute on Tocdiv and/or
    Tocentry, with an enumerated list of values that correspond to the
    component names, like this:

      <!ATTLIST Tocdiv  class (dedication|preface|toc|lot
                               |part|chapter|article|reference
                               |bibliography|appendix|glossary
                               |index|colophon)  #IMPLIED
                        ... >
   
 9. Tocdiv adds a new parameter entity, %tocdivcomponent.mix. What's
    the proposed content model for %tocdivcomponent.mix?

10. The Toclevel* hieararchy now has as its only parent the Tocchap
    element. If we drop Tocchap from Toc, where (if anywhere) will the
    Toclevel* hierarchy fit in the Toc hierarchy?

    I'm assuming if it's included at all, it'll be by putting Toclevel1
    in %tocdivcomponent.mix. Right? Or is part of the plan to drop the
    Toclevel* hierarchy -- because we're making Tocentry recursive?

I guess that's plenty of questions for now. Text of the RFE below.

  --Mike

-----------------------------------------------------------------------

[1] RFE 482818: Simplify ToC content model

    - ToC content model will be simplified.

    - The semantic of a ToC is that it only contains entries for the
      elements that are it's peers and descendants of its peers.

    - The semantic of an empty ToC is that it is a location where an
      automatically generated ToC is to appear.

    Proposed new content models:

    <!ELEMENT ToC - O ((%bookcomponent.title.content;)?,
            (%component.mix;)*, (ToCDiv* | ToCEntry*))
            %ndxterm.exclusion;>
    <!ATTLIST ToC
            %pagenum.attrib;
            %common.attrib;
            %toc.role.attrib;
            %local.toc.attrib;
    >

    <!ELEMENT ToCDiv - O ((%sect.title.content;)?, ((%
    tocdivcomponent.mix;)*,
            ToCEntry+))>
    <!ATTLIST ToCDiv
            %linkend.attrib; --to element that this entry represents--
            %pagenum.attrib;
            %common.attrib;
            %toc.role.attrib;
            %local.toc.attrib;
    >

    <!ELEMENT ToCEntry - - ((%para.char.mix;)+,ToCEntry*)>
    <!ATTLIST ToCEntry
            %linkend.attrib; --to element that this entry represents--
            %pagenum.attrib;
            %common.attrib;
            %tocentry.role.attrib;
            %local.tocentry.attrib;
    >