[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook] Add topic element to DocBook?
It sounds like adding an element to the schema for purely marketing reasons. Essentially <topic> and <section> are the same, but not interchangeable correct? Or is the idea to make it easier for DITA authors to migrate to DocBook and DocBook authors to migrate to DITA? > -----Original Message----- > From: chris.chiasson@gmail.com > [mailto:chris.chiasson@gmail.com] On Behalf Of Chris Chiasson > Sent: Thursday, October 26, 2006 2:26 PM > To: Norman Walsh > Cc: docbook@lists.oasis-open.org > 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/ > > --------------------------------------------------------------------- > To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org > For additional commands, e-mail: docbook-help@lists.oasis-open.org > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]