Re: "Documentation by paper"

[Phil Edwards <phil at codesourcery dot com>]

Richard Kenner wrote:
>     Do you have a suggested syntax which allows us to extract nicely formatted
>     HTML, LaTeX, and troff documentation?
>
> No, because you can't "extract" documentation in a mechanical fashion.
> High-level documentation is not a collection of low-level details.

I've said many times on the libstdc++ list, and I'll say it here:  the goal of
extracting comments is to get a /reference/, not a textbook, not a tutorial.
Look at the libstdc++ web pages -- actually go /look/ at them -- and note that
the HOWTOs and writeups are separate from the API extractions.  They reference
each other, but neither replaces the other.

If you want high-level documentation, then look at the internals manual -- the
TeXinfo one, the badly outdated and incomplete one -- and improve it.  If you
want API documentation, then extract comments.

We can even combine them.  We can even write the high-level stuff in such a
way as to have doxygen "extract" it verbatim, formatting intact.  I don't
believe anybody's suggesting that we stop trying to write an internals manual.