[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [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;
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC