Re: [docbook-apps] DocBook topic element

[Ron Catterall <ron@catterall.net>]

Sounds not only very interesting, but very usefull. I'll give it a try.

Bob Stayton wrote:
> 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-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
> 
> 
> 

-- 
Ron Catterall Ph.D. D.Sc.
ron@catterall.net
http://catterall.net

S/MIME Cryptographic Signature