Boost logo

Boost :

From: David Abrahams (dave_at_[hidden])
Date: 2002-11-02 15:02:44

Douglas Gregor <gregod_at_[hidden]> writes:

> 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),

Actually, this is one point I've discussed with Steven Davies: nested
class templates typically should /not/ be represented separately from
the enclosing class template.

> 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 |-----+ +----+
> +----------+

Looks reasonable to my untrained eye. I'd like to add

 ReStructuredText | C++ XML |

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

It would be
> 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
> it.
> Doug
> _______________________________________________
> Unsubscribe & other changes:

                    David Abrahams
dave_at_[hidden] *

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