From: Jeff Garland (jeff_at_[hidden])
Date: 2002-11-02 11:30:10
> Actually, I'm not extending DocBook at all. DocBook's support for documenting
> code is very Java/C-centric, and not nearly rich enough to deal with
> templates, specialization, or metafunctions. We could extend it, of course,
> but it would be a massive effort to introduce changes of this magnitude into
> DocBook... I'm not sure we're up to that.
> What I'm proposing is a layer of XML to represent C++, with a transformation
> into DocBook. So, for instance, the example "function.xml" that I've been
> working with is not actually a DocBook document -- it's just raw XML that
> expresses C++ declarations. The XSLT stylesheet transforms that XML into a
> DocBook reference section, and uses as many DocBook features as can
> reasonably be used. For instance, it'll use <refentry> for class templates so
> that each class template is considered one entity (e.g., one page in chunked
> HTML output or one man page), and will identify the synopsis sections, man
> page title, etc. But it won't use <funcprototype>, <classsynopsis>, or any of
> the other code documentation features because they won't give us the C++
> Standard-like output that many Boost libraries seem to use.
Ok, thx for making all this clearer (and I agree with David -- nice diagram!)
My only thought on this, however, is that we should use docbook elements
whereever that is reasonable and extend where it isn't. My worry/desire
is that at some point in the future it would be nice to be able to
extend the docbook DTD so that C++ XML would actually validate within
a docbook doc.
> There's not really anything in this toolchain we could take out. Going from
> Doxygen/Synopsis->DocBook directly would make things tougher, because we
> would have to keep the formatting consistent between the two DocBook
> generators and with authors not using either generator.
We can take out the generators and replace them with a human, but
I agree that to do everything we want requires a fairly large
set of tools.
> We could go from the C++ XML directly to some other format (e.g., HTML, which
> the prototype supports),
Yes and I think this one is useful because for standard boost docs
the toolchain can be as simple as:
| Author |------+ +----------------+
+---------+ | | XSL Stylesheet |
+---------+ v +------+
| C++ XML |----------------->| HTML |
> It sounds complicated, and it probably is, but I think we can make it easy to
> use with a little work. The consistency and cross-referencing will be worth
I agree. Version management and make tools aren't simple either, but
they are essential...
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk