Re: treelang patch part 1 of 6

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

On Tue, 7 May 2002, Toon Moene wrote:

> > Front end documentation goes in the front end directory (except for the C
> > family front ends where it's in the main manual).  There are however other
> > problems with the documentation; the gcc and gccint manuals should be used
> > as models, not the g77 one.
> 
> Why ?
> 
> [ So that we can solve this problem for g95 ... ]

The USING and INTERNALS conditionals that aren't actually used; there
should either be a combined manual, or separate manuals, but not
conditionals purporting the support multiple variants most of which are
never tested.

It should use gcc-common.texi to get common macros and version
definitions.

The DEVELOPMENT conditional isn't intrisically bad.  However, that sort of 
thing belongs in gcc-common.texi, and should have three states (release, 
prerelease, development), and should just make the manual indicate it 
corresponds to a development etc. version, not the release with that 
number, not claim that the manual is out-of-date with respect to the code.  
(Manuals should never be out-of-date with respect to the code.)

Some of the manual is generally written from a perspective carrying 
historical baggage, where g77 involved a large patch against core GCC code 
and was a modification of GCC, rather than the perspective of being one of 
several front ends, all integrated in the one GCC.  (Any references to 
"GNU CC" in the Fortran manual are obsolete; see the terminology guide 
about that, and the differences between "GCC" and "gcc", in 
codingconventions.html.)

There's a lot of duplication of what is or should be or was in general GCC
manuals, e.g. much of the overview of the components of G77, the bug
reporting instructions and projects list (which belong on the web site
only[1]).

[1] If it makes sense to branch docs for a release, they should be in the
distribution - for example, the user and install manuals.  If someone
should only ever refer to the latest version of docs, they should be on
the web site - for example, the bug reporting instructions (which can then
get updated for new bug tracking systems, etc.), projects lists (people
should only implement new projects against the mainline).

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