Re: [boost] Boost documentation

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.
>   
[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