Boost logo

Boost :

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-11-02 00:41:12

On Friday 01 November 2002 09:50 pm, Jeff Garland wrote:
> As I said before, we don't really need to choose one extraction tool
> or another. We can use one or both. I think the point that is being
> missed here is that Doug has a proposal on the table, but to my eye
> it looks like mostly an extension of DocBook. What I see in Doug's
> stuff looks like solid XML, but I don't understand how DocBook
> extends so I'm just a little worried that the standard DocBook
> tools will be less useful than we think...

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.

The "whole" system might look something like this:

| Doxygen |------+ +---------+
+---------+ | +----->| (X)HTML |
                 v | +---------+
             +---------+ +-------------+ | +-----+ +--------+
             | C++ XML |---->| DocBook XML |----+----->| TeX |--->| PS/PDF |
             +---------+ +-------------+ | +-----+ +--------+
                 ^ | +----+ |
+----------+ | +----->| FO |---------+
| Synopsis |-----+ +----+

I've got a good start on the C++ XML -> DocBook XML conversion (that's what's
in the sandbox). I've been testing with DocBook XML->HTML (works fine, and we
don't have to change anything to do it), but I've also toyed with DocBook
XML->FO->PDF (not perfect yet, but getting better).

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 could go from the C++ XML directly to some other format (e.g., HTML, which
the prototype supports), but then we have to have backends for all output
format we need, and we have to have some other way of introducing
non-reference documentation. As I see it now, tutorials, design documents,
etc. could be written directly in DocBook (or transformed into DocBook from a
tool like reST), whereas reference documents would be transformed into
DocBook via the above flow-chart soup.

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


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