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.
[snip]
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. - Doug