Re: treelang patch part 4 of 6

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

On Sun, 5 May 2002, Tim Josling wrote:

> + @xref{Contributors,,Contributors to GCC,GCC,Using and Maintaining
> GCC},

No such manual.  The manuals are called "Using the GNU Compiler Collection
(GCC)" and "GNU Compiler Collection (GCC) Internals".  Their file names
for links are gcc and gccint (lowercase).  Please check all external links
in this manual.

> + page @uref{http://GCC.gnu.org}.

The web page is always referenced with lowercase URL.

> + to implement a new language front end to GCC. It is not a useful

Please read the list of Texinfo style issues in codingconventions.html, 
and apply them to the whole manual.  Here, you've failed to use @. after a 
capital letter at the end of a sentence, and haven't used two spaces after 
the full stop.

> + it and by reading the manual @samp{Using and Porting GCC}.

Wrong manual name.  Should be a link.

> + replacement for, or alternative to, the 'toy' language, but which is

TeX quotes.  Read the printed manual with a typographer's eye on it.

> + // set aaa to the value returned from aaa, when passed arg7 and arg7
> as the two parameters

Comments are in @r{} within examples.  Have you made sure this example has
no overfull hboxes?

> + of the line. C style comments (/* */) are not supported. For example,

@samp{/* */}.

> + @smallexample
> + @{ - used to start the statements in a function

For a list like this, use something like @table @samp, not @smallexample.

> + Names consist of any letter or "_" followed by any number of letters
> or
> + numbers or "_". "$" is not allowed in a name. All names must be

@samp{_}, @samp{$}.  The neutral double quote should in general not get 
used in Texinfo.

> + unique - the same name may not be used twice in any context - and must

TeX dashes.

> + @cindex @code{gcc}, command
> + @cindex commands, @code{gcc}

@command{gcc}.

> + A modified version of the @code{gcc} command, which also might be
> + installed as the system's @code{cc} command.

It's not a modified version in any meaningful sense; it's a standard 
version, built with treelang support.  "Modified" made sense for g77 as a 
patch for GCC 2.7.x or 2.8.x, not now.

> + of @code{GCC} considered more stable or that is

@code{GCC} is never correct markup.  See codingconventions.html.

> + The @code{treelang} command itself.

@command.

> + @code{GCC} is often thought of as ``the C compiler'' only,
> + but it does more than that.
> + Based on command-line options and the names given for files
> + on the command line, @code{gcc} determines which actions to perform,

Fix the markup of GCC.  "GCC" is the Collection, @command{gcc} is the
command.

> + For example, the command @samp{gcc foo.c} @dfn{drives} the file
> + @file{foo.c} through the preprocessor @code{cpp}, then
> + the C compiler (internally named
> + @code{cc1}), then the assembler (usually @code{as}), then the linker
> + (@code{ld}), producing an executable program named @file{a.out} (on
> + UNIX systems).

In general, this sort of generic language-independent description belongs
somewhere in the main manual - not in front end manuals.

> + One chunk is the so-called @dfn{GNU Back End}, or GBE,
> + which knows how to generate fast code for a wide variety of
> processors.

Likewise.  Add some such overview to the main manual, get rid of it from
other manuals.

> + A GNU Treelang installation includes a modified version of the
> @code{gcc}
> + command.
> +
> + In a non-Treelang installation, @code{gcc} recognizes C, C++,
> + and Objective-C source files.

Not modified.  Lots of other languages.  Don't list the languages here.

> + @xref{G++ and GCC,,Compile C; C++; or Objective-C,GCC,Using and
> Porting GCC},
> + for information on the way different languages are handled
> + by the GCC compiler (@code{gcc}).

Out of date link.  (Though that section of the GCC manual should be
renamed not to list the languages explicitly, so that the Fortran etc.  
manuals don't need updating every time a new language is added and that
section's title changes.)

> + You can use this, combined with the output of the @samp{GCC -v x.tree}

No such command as "GCC".  Have you read this manual critically for both 
technical correctness and typography?

> + C promotes small integer types to 'int' when used as function

@samp{int} or @code{int}.

> + To create a compiler that integrates into GCC, you need create many
> + files. Some of the files are integrated into the main GCC makefile, to

There is absolutely no place for such information as this in any front end
manual.  The front end build interface is documented in sourcebuild.texi.  
Work to improve that documentation, not to duplicate it.  I provided the
framework in the internals manual (with plenty of gaps to fill in) for
people to work on improving that manual, not arbitrarily duplicating and
fragmenting documentation.

> + Typically a program's language will be identified from its suffix (eg
> + .tree) for treelang programs.

"eg" should be "e.g.@:" or "e.g.,".  Use @file for file suffixes, as well 
as file names.  The printed manual should be aesthetically pleasing, not 
ugly and inconsistent.

> + @node treelang main compiler,  , treelang driver, treelang compiler
> interfaces

In general, please try to avoid the long form of @node, and just give the
node name instead.  Manuals where just the node name, not manual
specification of the nodes related to it, is given, are a lot easier to
maintain.

> + The main compiler for treelang consists of toplev.c from the main GCC

@file{toplev.c}, and in general above and below.  As noted, put such docs 
in sourcebuild.texi (or a new file in the main manual) instead.

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