This is the mail archive of the
mailing list for the GCC project.
Re: Documentation generation patch [Take 2]
- To: Geoff Keating <geoffk at geoffk dot org>
- Subject: Re: Documentation generation patch [Take 2]
- From: "Joseph S. Myers" <jsm28 at cam dot ac dot uk>
- Date: Fri, 11 May 2001 00:59:07 +0100 (BST)
- cc: <gcc at gcc dot gnu dot org>
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