RE: [docbook] DocBook topic element

["David Cramer" <dcramer@motive.com>]

This does look very intersting. I gather this portion only relates to
the new topic element and the assembly structure will come later? 

I second Bergfrid's request that there be some mechanism(s) for avoiding
the intertopic dependencies created by crossreferences (i.e. the problem
that dita reltables are supposed to solve). 

Thanks,
David 

> -----Original Message-----
> From: Bob Stayton [mailto:bobs@sagehill.net] 
> Sent: Saturday, July 25, 2009 12:00 PM
> To: DocBook Apps; docbook@lists.oasis-open.org
> Subject: [docbook] DocBook topic element
> 
> The DocBook Technical Committee is considering adding 
> features to DocBook to better support modular authoring and 
> assembly of documents.  The Committee is developing an 
> assembly structure that lets you point to DocBook files and 
> elements, similar in function (but not form) to DITA maps.  A 
> process would be run on an assembly to pull the various 
> elements together for further processing as a document.
> 
> While it would be possible to assemble a document from 
> existing DocBook elements, I submitted an additional proposal 
> to add a new <topic> element. 
> Such a topic element would be a natural candidate for 
> assembly of modular units into larger documents.
> 
> A new topic element is needed because no other DocBook 
> element meets the needs for authoring standalone units of 
> information.  A section element is not appropriate, because 
> it implies a "section of something" with a larger context.
> The article element comes closest, but it allows appendix, 
> acknowledgements, and colophon children, which are not 
> appropriate for a topic.  Also, article currently cannot be a 
> child of chapter or appendix.
> 
> The design goals of this proposal are:
> 
> a. To provide a designated element for authoring modular 
> content, each instance of which "stands alone", but which 
> also has relationships to other modules.
> 
> b. Design the topic element to be very general, so that it 
> can be adapted for many types of topics.
> 
> c. Make the addition of topic backwards compatible with DocBook 5.0.
> 
> d. Clearly distinguish topics and sections.
> 
> 
> Here are is the proposed design for topic:
> 
> 1. The content model for topic is identical to that of section.
> 
> 2. A topic type is indicated by a CDATA "type" attribute value.
> For example, "task", "reference", "concept", etc.
> 
> 3. A topic cannot include topic children.  Allowing a topic 
> to contain other topic elements breaks the semantic of 
> "standalone unit of information".
> 
> 4. A topic can contain section children to subdivide its 
> content for clarity and ease of reference.
> 
> 5.  A section element cannot contain a topic element.
> Placing a topic inside a section implies the topic depends on 
> the section parent for its context.
> It also hopelessly muddles the distinction between topic and section.
> 
> 6.  Allow topic as a child of book or part. This allows you 
> to author groups of topics in a convenient container.
> Such topics could be siblings of chapters and other component 
> elements, the way article can be such a sibling.
> 
> 7. Allow topic as a child of chapter or appendix, but not as 
> a sibling of section.  This also allows you to author groups 
> of topics in a convenient container, this time grouped into a 
> chapter or appendix.  There is an additional constraint, 
> though.  A chapter can contain either section children or 
> topic children, but not both.  This is to maintain a clear 
> distinction between topics and sections.
> 
> 
> The Committee would like to allow some experimentation and 
> comment before adopting the new element.  I include here a 
> customization of DocBook 5.0 RelaxNG (compact syntax) to add 
> a topic element as described above.  The Committee looks 
> forward to users trying it out and commenting on their 
> experiences and ideas.
> 
> ------------------ topic customization 
> ------------------------------- default namespace = 
> "http://docbook.org/ns/docbook";
> namespace db = "http://docbook.org/ns/docbook";
> namespace xlink = "http://www.w3.org/1999/xlink";
> namespace s = "http://www.ascc.net/xml/schematron";
> namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0";
> 
> 
> include "docbook.rnc" inherit = db {
> 
> db.toplevel.sections =
>   ((db.section+, db.simplesect*) | db.simplesect+)
>   | (db.sect1+, db.simplesect*)
>   | db.refentry+
>   | dbx.topic+
> 
> }
> dbx.topic =
>     element topic {
>       dbx.topic.attlist,
>       dbx.topic.info,
>       db.recursive.blocks.or.sections,
>       db.navigation.components*
>     }
> 
> dbx.topic.type.attribute =
>   attribute type { text }
> 
> dbx.topic.attlist = db.section.attlist  & dbx.topic.type.attribute?
> dbx.topic.info = db._info.title.req
> 
> --------------------------------------------------------------
> ---------
> 
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
> 
>