[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-tc] proposal: add topic element to DocBook
"Bob Stayton" <bobs@sagehill.net> writes: > appropriate for a topic. Also, article currently cannot > be a child of chapter or appendix. I wonder if that's a bug. > a. To provide a designated element for authoring > modular content, each instance of which "stands alone", but > which also has relationships to other modules. Do you want to make an attempt to describe these relationships from within the topic, or leave that to the assembly layer? > 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 class attribute value. > For example, "task", "reference", "concept", etc. Do you really want an enumerated list of class values, or does it make more sense to allow a type attribute, which is open-ended by default? > 3. A topic cannot include topic children. Allowing a topic > to contain other topic elements breaks the semantic of > "standalone unit of information". The assembly layer can construct nested topics, can't it? > 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. I've long suspected we would eventually need a topic element. The strongest arguments aren't technical, in my mind, they're about user expectations and perception. This proposal seems like the right thing to me. Be seeing you, norm -- Norman Walsh <ndw@nwalsh.com> | Convictions are more dangerous http://www.oasis-open.org/docbook/ | enemies of truth than lies.-- Chair, DocBook Technical Committee | Nietzsche
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]