Re: [docbook] alternative topic proposal

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

Yes, they could be siblings.  Article can appear in book or part, and the 
book and part content models (after the title stuff) consist of a 
collection of components in any order.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net


----- Original Message ----- 
From: "Johnson, Eric" <Eric.Johnson@iona.com>
To: <docbook@lists.oasis-open.org>
Sent: Saturday, October 28, 2006 1:58 PM
Subject: RE: [docbook] alternative topic proposal



This is a good definition. What is the relationship between <topic> and
<article>? Will they also be allowed as siblings?


> -----Original Message-----
> From: Bob Stayton [mailto:bobs@sagehill.net] 
> Sent: Friday, October 27, 2006 3:30 PM
> To: docbook@lists.oasis-open.org
> Subject: [docbook] alternative topic proposal
> 
> 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
> 
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org