Re: Documentation generation patch [Take 2]

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

On 10 May 2001, Geoff Keating wrote:

> I believe there is a switch that you can pass (to texinfo?) that will
> cut out all the 'porting' stuff and produce a manual titled 'Using GCC'.

Yes.  This is bitrotten, given that it isn't used.  (Though the parts in
@ifset INTERNALS aren't included in the generated manpages.)  Also, some
information, in @ifset INTERNALS inside parts relating to using GCC, is
missing in such a manual pair at present; it should be present but tagged
as relating to internals.

> I think it's better to have one manual for writing front-ends and back-ends,
> but with a clear separation (for instance, separate chapters).

I considered the notion of a general "GCC Internals" manual, but don't
think the topics are (or should be) significantly related.  A front end
shouldn't be dealing with RTL; it should pass language-independent trees
for whole functions down to the middle end to convert to RTL (as per the
long term vision at http://gcc.gnu.org/ml/gcc/2000-12/msg00727.html).  A
back end shouldn't be dealing with trees.  However, there may be enough
other miscellaneous internals issues that ought to be documented for such
a manual to make sense.

In any case, a clear logic behind what should go in a single manual, or in 
separate manuals, would be desirable.  (E.g. to provide some logic for the 
main manual including C++ documentation, but Fortran documentation being 
in a separate manual.  The reasons may be historical, but the GNU coding 
standards say manuals should be structured for users rather than according 
to the implementation, and I think similarly they should be structured in 
the most useful and coherent way rather than according to history.)

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