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

From: David Abrahams (dave_at_[hidden])
Date: 2002-10-29 23:11:06

"Carl Daniel" <cpdaniel_at_[hidden]> writes:

> I think this is quite doable.  Joel's simple "cpptohtml" example (included
> in the Spirit distribution) is halfway there already.  For a documentation
> project of my own, I took that sample and modified it to produce XML (not
> DocBook, but similar) in only a few minutes of hacking.  If JCAB's C++
> parser (also implemented with Spirit) gets finished up, 

*Please* do not underestimate the difficulty of getting this right and
finished. Even if we do get a complete C++ parser written in Spirit,
there are a huge number of issues to deal with before you have a
system you can use to generate documentation... several I can think of off
the top of my head:

    * Preprocessing
    * hiding information you don't want to present
    * "linking" together the result of processing many files
    * emulating compilers (e.g. system #includes, built-in #defines)
    * Back-ends for generating HTML, DocBook, TeX, ...
    * Configurability
    ...

Synopsis has a huge head-start in all of these areas. The C++ parser
is just one small component. A preliminary look at what it was doing
with Boost.Python a couple of weeks ago is available at
http://www.boost-consulting.com/BoostPython. However, as I said that
was a couple of weeks ago, and things have progressed considerably
since then. I wanted to post a link to a more-recent version but the
conversation is so hot I just thought I'd better show it now.

Stephen Davies (the main Synopsis guy) is using Boost.Python as his
primary testbed and has been extremely responsive to my feedback. We
got it working under Cygwin and have corrected many non-C++
colloquiallisms over the past few weeks (you won't see this reflected
in the link above). I think pouring our energies into getting this tool
working suitably for Boost is the best use of our effort.

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