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