Re: Documentation generation patch [Take 2]

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On Thu, 10 May 2001, Mark Mitchell wrote:

>     >> + c-tree.dvi: $(srcdir)/c-tree.texi
> 
> Theordore --
> 
>   Would you be iwlling to take on the task of merging c-tree.texi into
> gcc.texi?  It should be analagous to `rtl.texi'; it documents an
> internal representation used in GCC.

Is this the direction we want to go in - one large "Using and Porting the
GNU Compiler Collection (GCC) and Writing GNU Compiler Front Ends" manual,
rather than cleanly divided manuals for each audience "Using GCC",
"Porting GCC", "Writing GCC Front Ends", "Installing GCC", each providing
its own set of documented interfaces?

The manual has grown over the years, without I think any clear structural
direction or editing for overall cohesiveness; its overall structure may
need reconsidering - and this should include consideration of the various
front end manuals and where they fit in, both as part of the info manuals
and as printed volumes.  At present:

* Almost all users of GCC do not need to know about porting it; if they 
buy a printed manual, or print one out, the porting information is not 
useful to them.  Only the information on asm constraints probably needs to 
be in both using and porting manuals.  "Using and Porting" reflects a 
different era of GCC users.  If someone is porting, since interfaces do 
change incompatibly at present they want the current mainline manual, not 
anything in a bought volume that relates to a previous release.

* There is interest in writing front ends and manuals for that; a manual
for this, though not fully up to date with all current recommended GNU
practices, is included with GNU COBOL.  If that manual is properly
assigned, I think it should go in GCC now, so that work can be done on
bringing it up to current standards (as both a tutorial and reference
manual) in the GCC tree.  This is the manual that c-tree.texi ought to
form a part of, with duplication resolved.

* There is also miscellaneous other internals documentation such as 
cppinternals.texi.  This need not be merged into other manuals, but may as 
well stay on its own as long as it isn't relevant to the front end or back 
end interface.

-- 
Joseph S. Myers
jsm28@cam.ac.uk