[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] Add topic element to DocBook?
I think I missed something. What does <topic> better allow the author to express semantically than <section> or <chapter>? On 10/26/06, Norman Walsh <ndw@nwalsh.com> wrote: > We've talked about adding some sort of topic element to DocBook for > almost a decade, off and on. (Back at least as far as the days when > Novell was an active participant in the Davenport Group.) > > The DITA folks make a lot of marketing hay out of their conceptual use > of topics. I don't think there's a single, solitary technical > advantage to DITA, but marketing doesn't depend on technical accuracy. > It's also possible to argue that task-based authoring is not a good > idea in general. It's ideal in some circumstances, but results in less > useful and less usable documentation in other circumstances. > > However, DocBook has never been principally about imposing a > particular documentation style on authors. For the most part, we leave > stylistic choices to authors. > > With this in mind, I think we should consider, perhaps once and for > all, whether we want to add a <topic> element to DocBook. > > If we decide to do so, I think something along the following lines > fits into the design of DocBook: > > 1. Add a <topic> element with the same content model as <section> > except that where section allows (sect1|section|simplesect), we > allow <topic>. So a topic contains subtopics analagous to the way a > section contains subsections. > > 2. Give topic a class attribute so that authors can have different > kinds of topics. DITA has all this funky weirdness about the > content models of various kinds of topics; I don't think we should > go there. > > 3. Allow topic as an alternative to (chapter|appendix|preface) in books. > This allows one to have a book of topics. > > 4. Allow topic as an alternative to (sect1|section|simplesect) in > chapters and appendixes. This allows one to have a chapter of > topics. > > As a slight extension of this model, we could also add a <tasktopic> > element. This would address the feature request[1] for "task" as a > peer to "section". If we did this, then I'd expect "topic" or > "tasktopic" to be allowed anywhere I've mentioned topic above. > > Given that topics are often composed in a fairly arbitrary order for > publishing in print, we might want to consider adding a "contentmap" > element as well for describing the order of topics. But we might be > able to get "toc" to serve this purpose. > > Be seeing you, > norm > > -- > Norman Walsh <ndw@nwalsh.com> | No victor believes in chance.-- > http://www.oasis-open.org/docbook/ | Nietzsche > Chair, DocBook Technical Committee | > > > -- http://chris.chiasson.name/
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]