[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: alternative topic proposal
I'm pretty strongly opposed to mixing topic and section elements as siblings. I think that will produce such a hash that neither authors nor stylesheets will understand it. I would suggest a different model for modular Docbook, similar to Norm's, but different in a few aspects. My goals here are to designate a topic as a standalone unit, but permit it to be used within one or more larger contexts that include hierarchy, and remain comaptibile with DocBook. 1. Add a <topic> element with the same content model as <section>. Because I believe a topic is intended to be a standalone unit, I would not allow a topic to contain other topics, but I would allow a topic to contain sections. Nesting topics greatly confuses a topic's status as a standalone unit. However, a topic may need to divide its content into sections for clarity and ease of reference. 2. Sections do not contain topics. 3. Give topic a class attribute to differentiate topic types (same as Norm's proposal). If someone wants different element names or customized content models, then they can customize the DocBook schema. 4. Allow topic in book and part as a sibling to chapter|appendix|preface. That makes it like article if you need a flat collection of topics. I'm not sure if Norm's proposal meant topic as a sibling to chapter or as a mutually exclusive alternative. I mean as a sibling. If you mix them, then it is up to the application to determine how to present them. 5. Define chapter (and any other element that contains section) to contain *either* sections or topics, but not both. If you use section, you can go to arbitrary depth. But it makes for a single level of topics within a chapter, with sections within topics providing further hierarchy if needed. 6. To accomodate a more extensive hierarchy of topics, allow book|chapter|appendix to contain topicref as well as topic. A topicref has an href attribute that points to a separate topic element stored elsewhere. This is the mapping feature of DITA. As in DITA, a topicref can contain other topicref elements. When processed, these can form a deeper hierarchy in the presentation of the output. So the content model of chapter and other elements that currently contain section would look like: chapter front matter (title, info, etc.) intro material (para, list, etc.) section* or (topic|topicref)* I believe this design has these advantages: 1. It keeps topic as a standalone unit. 2. It avoids mixing section and topic as siblings. 3. It permits arbitrary depth of a topic (using sections), if you need it. 4. It permits easy authoring of books or other units with inline topic elements. 5. It permits creating more extensive topic hierarchies using topicref, without sacrificing topic as a standalone unit. 6. It is very flexible and not overly prescriptive, in keeping with DocBook's design. Bob Stayton Sagehill Enterprises DocBook Consulting bobs@sagehill.net
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]