[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]