alternative topic proposal

["Bob Stayton" <bobs@sagehill.net>]

I'm pretty strongly opposed to mixing topic and section 
elements as siblings.  I think that will produce such a
hash that neither authors nor stylesheets will understand it.

I would suggest a different model for modular Docbook, similar
to Norm's, but different in a few aspects.  My goals here
are to designate a topic as a standalone unit, but permit
it to be used within one or more larger contexts that
include hierarchy, and remain comaptibile with DocBook.

1.  Add a <topic> element with the same content model as
<section>.  Because I believe a topic is intended to be a
standalone unit, I would not allow a topic to contain other
topics, but I would allow a topic to contain sections.
Nesting topics greatly confuses a topic's status as a
standalone unit.  However, a topic may need to divide its
content into sections for clarity and ease of reference.

2.  Sections do not contain topics.

3.  Give topic a class attribute to differentiate
topic types (same as Norm's proposal).
If someone wants different element names or customized
content models, then they can customize the DocBook schema.

4.  Allow topic in book and part
as a sibling to chapter|appendix|preface.
That makes it like article if you need a flat
collection of topics.  I'm not sure if Norm's proposal 
meant topic as a sibling
to chapter or as a mutually exclusive alternative.  I
mean as a sibling.   If you mix them, then it is
up to the application to determine how to present them.

5.  Define chapter (and any other element that contains
section) to contain *either* sections or topics, but
not both.  If you use section, you can go to
arbitrary depth.  But it makes for a single level of topics within
a chapter, with sections within topics providing further
hierarchy if needed.

6.  To accomodate a more extensive hierarchy of topics,
allow book|chapter|appendix to contain topicref as well
as topic.  A topicref has an href attribute that points to
a separate topic element stored elsewhere.  This is the
mapping feature of DITA.  As in DITA,
a topicref can contain other topicref elements.
When processed, these can form a deeper hierarchy in
the presentation of the output.

So the content model of chapter and other elements
that currently contain section would look like:

  chapter front matter (title, info, etc.)
  intro material (para, list, etc.)
  section*  or  (topic|topicref)*


I believe this design has these advantages:

1.  It keeps topic as a standalone unit.

2.  It avoids mixing section and topic as siblings.

3.  It permits arbitrary depth of a topic (using
sections), if you need it.

4.  It permits easy authoring of books or other units
with inline topic elements.

5.  It permits creating more extensive topic hierarchies
using topicref, without sacrificing topic as a 
standalone unit.

6.  It is very flexible and not overly prescriptive, in keeping
with DocBook's design.


Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net