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

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

        Doug