From: Douglas Gregor (dgregor_at_[hidden])
Date: 2007-06-25 15:36:48
Stefan Seefeld wrote:
> DocBook is designed for extensibility. That's becoming even more true
> with the new DocBook 5. It is possible to refine the document type (e.g.
> add custom vocabulary), as well as add custom (xslt) templates to be
> used in the processing pipeline when generating html, pdf, etc.
> I had some discussions with Norman Walsh over the years, when I realized
> that DocBook was a bit inconsistent in its support for language-specific
> artifacts. The tricky thing is that DocBook is a documentation language,
> not a modeling language. I do believe it would be good to be able to represent
> more language artifacts (I have a hard time deciding what kind of DocBook to
> generate with my Synopsis reference manual generator), but I understand
> the concern about language bloat that may incur, at least if these changes
> got into the core vocabulary.
I started BoostBook precisely because of this problem. DocBook was (is)
a decent, well-supported standard format for documentation, but it's
support for C++ was non-existent. BoostBook was meant to be DocBook
extended to support the description of C++ interfaces/declarations so
that we could build good reference documentation manually and merge that
with documentation extracted from source code (currently, via Doxygen).
You mentioned that DocBook 5 is meant to be more extensible... might it
possible for our C++ markup to be introduced into DocBook 5 as some kind
of custom vocabulary? I'd love to minimize the distance between
BoostBook and DocBook, but the need for Boost- and C++-specific features
pushed them apart further than one would like. Perhaps with a more
extensible DocBook 5, and Matias et. al.'s new work on the
BoostBook/Quickbook toolchain, we can simplify things and move back
closer to DocBook. But make no mistake: DocBook alone is insufficient
for Boost, and standards are only useful when they solve your problems.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk