[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook] DocBook topic element
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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]