From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-11-04 11:29:15
Douglas Gregor said:
> 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.
No, but letting the DocBook folks know about this effort would be a good
idea. They could take where we left off and incorporate a solution into
DocBook, which would be a good thing for everyone.
Also, I've not had a chance to dig deeply yet, but I hope you're using
DocBook tag names when they do exist. Even if we don't have any hopes for
this ever becomming part of the official DocBook, it would help the
learning curve for anyone who knows DocBook.
> 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.
Sounds very reasonable to me.
> 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).
I really need to find the time to look at this stuff in depth ;).
> 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
I agree totally, and the use of tools like reST is what could make writing
documentation simple! But we need to figure out how to get all of this
stuff to work together the way we want with little effort on the
developers... and then document the heck out of how to use the various
> 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 it.
Amen. And my thanks to you for heading up the effort so far.
And it would still be interesting if someone could provide the same (or at
least a portion of the same) using LaTeX, so that we can actually compare
the two intelligently.
-- William E. Kempf
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk