Boost logo

Boost :

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.

    - Doug

Boost list run by bdawes at, gregod at, cpdaniel at, john at