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

From: David Bergman (davidb_at_[hidden])
Date: 2002-11-02 01:10:30

Doug,

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.

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[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
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
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost