RE: [boost] Re: Reference documentation: one approach

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

I agree.  Version management and make tools aren't simple either, but
they are essential...

Jeff