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?

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 |


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]