OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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]