Re: GFDL/GPL issues

[kenner@vlsi1.ultra.nyu.edu (Richard Kenner)]

> That is true, but very often the documentation is needed in two
> places: in the code and in the manual. Especially for things like
> machine constraints, flags and options. 

Yes, but the audiences are different between users who read the manual and
developers who read the code.  For the best quality, the two descriptions
may well be quite different, in emphasis, tone and other areas.  If the
emphasis is on finding text that's acceptable for BOTH purposes, you create
documentation that's not ideal for EITHER.

> And even if the documentation isn't needed in two places to, well,
> document something, it may still be useful to automatically generate
> parts of manual to avoid divergence between the manual and the compiler.

That's indeed a worthwhile goal, but doing it at the expense of the quality
of the documentation is a very bad idea, in my opinion.

The quality of documentation in the industry, and even in the Free Software
community is pretty poor.  GCC is known for a very high standard of
documentation.  Let's not lower it by substiting automated tools for
quality handwritten documentation.

I believe that tools have their purpose for such things as functions
lists and detailed ABI documentation, but not in things like user
manuals.