Re: [boost] Reference documentation: one approach

From: David Abrahams (dave_at_[hidden])
Date: 2002-10-29 18:35:50

Douglas Gregor <gregod_at_[hidden]> writes:

> On Tuesday 29 October 2002 08:46 am, Maciej Sobczak wrote:
> > AFAIK, the well-established way to write anything is to use LaTeX. It
> > has all the characteristics you write, from "omnipresence" to
> > possibility to convert to any format I've heard of.
> [...]
> > - XML is more trendy in this season.
> >
> > I'm really sorry if you find the second point offensive, but I just do
> > not understand the motivation for the additional effort with XSLT. Note
> > also that the description of the logical structure of the text is much
> > more concise in LaTeX than in XML. At least I think so.
> 
> I'm not concerned at all with normal text. DocBook, LaTeX, Doxygen, or 
> reStructuredText will all do a fine job at formatting text for tutorials, 
> descriptions of classes, etc.
> 
> I'm concerned with the code part of reference documentation. If you take a 
> look at the C++ standard documentation style, there is a lot of repetition:

I've been working with Synopsis (http://synopsis.sf.net). I think it
stands a good chance of being able to handle parsing and documentation
extraction for Boost code. It's currently doing a pretty astounding
job on the Boost.Python sources. I'll post the results next week when
I get home to a faster internet connection.

The Synopsis developers are interested in integrating with ReST.

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