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

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: http://lists.boost.org/mailman/listinfo.cgi/boost
> 

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com