Add topic element to DocBook?

[Norman Walsh <ndw@nwalsh.com>]

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 |

PGP signature