Re: [docbook] alternative topic proposal

["Chris Chiasson" <chris@chiasson.name>]

What exacly would this topic ref attribute allow one to do? Include
the element with that ref in another piece of content, but without
bringing along xml:ids?

What would be the difference between <topic> and <section topicref="something">?

On 10/27/06, Bob Stayton <bobs@sagehill.net> wrote:
> 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
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
>
>


-- 
http://chris.chiasson.name/