This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Phil Edwards <phil at codesourcery dot com>
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Cc: gcc at gcc dot gnu dot org
- Date: Tue, 27 Jan 2004 15:09:50 -0500
- Subject: Re: "Documentation by paper"
- References: <10401272001.AA00920@vlsi1.ultra.nyu.edu>
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.