[boost] Re: Reference documentation: one approach

From: Carl Daniel (cpdaniel_at_[hidden])
Date: 2002-10-29 22:09:58

"Peter Simons" <simons_at_[hidden]> wrote in message
news:871y683ola.fsf_at_peti.int.muc.intenga.com...
> Douglas Gregor writes:
>
>  > In your opinion, do you think it's enough to handle what we need in
>  > Boost?
>
> In the current state, DocBook does definitely not suffice to express
> complex C++ code. If you want to express every little detail, that is.
> I don't think that this is necessary, though, not even useful, because
> the results are almost completely unreadable if you're editing the
> SGML document directly. One could try to solve this by generating the
> DocBook "code" from the actual C++ code, but this would be a major
> undertaking.

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, it might even be
feasible to have the C++ -> DocBook tool able to extract specified portions
of a file (e.g. "delcaration of function x")  & convert it to SGML (DocBook
or whatever).

-cd