Re: [docbook] Add topic element to DocBook?

[Dan Sanderson <lists@dansanderson.com>]

In our DocBook system, we have implemented a notion of topic, as a 
sub-class of section (role="topic").  Topics are allowed in chapters, and 
in other topics.

We use topics for automatic generation of the ToC, and subsequently for 
HTML chunking.  Every chapter and every topic makes it into the ToC, and 
has its own HTML file in the output.  (In our system, IDs are required on 
chapters and topics, and are used for the HTML filenames.)

Topics also allow us to re-use topics via XInclude without having to 
manage the ToC generation any further: The generated ToC can be of 
arbitrary depth, so you can include a topic (with its set of sub-topics) 
anywhere in a document and it'll all work as intended.

It looks like there are a bunch of concerns in this thread that have 
nothing to do with our own definition of "topic", especially if we're 
targetting a DITA use case of some kind (though I also see little added 
value in DITA over DocBook at this point; I've had to resist internal 
pressures to adopt DITA because it's "newer").  But I like our definition, 
and I've always thought it'd be useful for DocBook in general.

-- Dan

On Thu, 26 Oct 2006, Norman Walsh 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 |
>