This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Documentation generation patch [Take 2]


"Joseph S. Myers" wrote:
> 
> 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.

The GDB manual used to have a bunch of conditionals, for instance to
make a Hitachi-embedded-processor-only manual, but they didn't work
very well, nobody knew they were there, and the elided manual would
have been very misleading as to GDB's full capabilities.  So I whacked
them all.  GDB already has a separate internals manual, so that wasn't
an issue.

> > 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.

I always thought the all-in-one GCC manual was a subtle way to get
more people to work on GCC; start by reading about options and extensions,
then it was just a turn of the page to get seduced into learning the
mysteries of porting.  But if that's not the goal, then it would
make more sense to separate the user manual from the internals manual.
The separation also changes weightiness concerns, so if you document
the unique features of all the frontends in the user manual, and the
workings of frontends and trees in addition to porting info in the
internals manuals, you end up with two manuals that are both of about
the "right" size.

Stan


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]