From: David Bergman (davidb_at_[hidden])
Date: 2002-11-02 01:10:30
A very nice graph (I am not as good at ASCII graphing...)!
I agree with your CPPXML layer. For cross-referencing, though, it would
be beneficial to then operate on that CPPXML level, since we there have
the semantics preserved (i.e, a template is still a template, and a
specialization a specialization). That way we could list all
specializations for a template, for instance.
I do believe that this CPPXML of yours should be a proper extension of
DocBook, in the sense of super-language, so all DocBook documents are
valid CPPXML documents. This to enable developers writing the high-level
specifications, which cannot/should not be extractable from the source
code in DocBook, and use the CPPXML extensions to express C++-specific
constructions and still use the same transformer XSL (the arch between
your "C++ XML" and "DocBook XML" nodes) as the generated documentation.
So, we should extend DocBook, *but* with your preprocessing XSLs, so we
can still enjoy the DocBook stylesheets and tools from the next node.
A concrete rendering note: from my experience with XSL-FO, using Apache
FOP, it is still better to go the TeX route to create PDF (or PS) from
the DocBook document.
[mailto:boost-bounces_at_[hidden]] On Behalf Of Douglas Gregor
Sent: Saturday, November 02, 2002 12:41 AM
To: Boost mailing list
Subject: Re: [boost] Re: Reference documentation: one approach
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
code is very Java/C-centric, and not nearly rich enough to deal with
templates, specialization, or metafunctions. We could extend it, of
but it would be a massive effort to introduce changes of this magnitude
DocBook... I'm not sure we're up to that.
What I'm proposing is a layer of XML to represent C++, with a
into DocBook. So, for instance, the example "function.xml" that I've
working with is not actually a DocBook document -- it's just raw XML
expresses C++ declarations. The XSLT stylesheet transforms that XML into
DocBook reference section, and uses as many DocBook features as can
reasonably be used. For instance, it'll use <refentry> for class
that each class template is considered one entity (e.g., one page in
HTML output or one man page), and will identify the synopsis sections,
page title, etc. But it won't use <funcprototype>, <classsynopsis>, or
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 |--->|
+---------+ +-------------+ | +-----+
^ | +----+ |
+----------+ | +----->| FO |---------+
| Synopsis |-----+ +----+
I've got a good start on the C++ XML -> DocBook XML conversion (that's
in the sandbox). I've been testing with DocBook XML->HTML (works fine,
don't have to change anything to do it), but I've also toyed with
XML->FO->PDF (not perfect yet, but getting better).
There's not really anything in this toolchain we could take out. Going
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,
the prototype supports), but then we have to have backends for all
format we need, and we have to have some other way of introducing
non-reference documentation. As I see it now, tutorials, design
etc. could be written directly in DocBook (or transformed into DocBook
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
use with a little work. The consistency and cross-referencing will be
Unsubscribe & other changes:
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk