Re: treelang patch part 3 of 6

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

On Sun, 5 May 2002, Tim Josling wrote:

> + @setfilename treelang.info

Info files generated in source directory need to be listed in .cvsignore.

> + @set last-update 2001-07-30

This date is wrong.

> + @c DEVELOPMENT is set to indicate an in-development version,
> + @c as compared to a release version.  When making a release
> + @c (e.g. a release branch in the CVS repository for GCC),
> + @c clear this and set the version information correctly.
> + @clear DEVELOPMENT

Though the Fortran front end manual uses this, I don't think it's
particularly useful.  The manual should be up to date with the code at all
times.  Note that for the mainline, if doing this, you must @set
DEVELOPMENT.  If such a flag is wanted (to identify manuals for
development versions rather than releases), it should be three-way
(development / prerelease / release) and go in
doc/include/gcc-common.texi, not individual manuals.

> + @set version-treelang 1.0

Front ends should not have their own versions like this.

> + @set version-GCC 3.0

This is the wrong version.  You should be using
doc/include/gcc-common.texi for the version anyway.

> + @set email-bugs gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org

Refer to the URL for bug reporting instead.

> + @set which-treelang GCC-@value{version-GCC}
> + @set which-GCC GCC

These made sense in a historical context for the Fortran front end that
might be used with FSF GCC, or with EGCS.  They don't make sense now, for
a new front end.

> + @c @setfilename usetreelang.info
> + @c @setfilename maintaintreelang.info
> + @c To produce the full manual, use the "treelang.info" setfilename,
> and
> + @c make sure the following do NOT begin with '@c' (and the @clear
> lines DO)
> + @set INTERNALS
> + @set USING

We got rid of this nonsense in the GCC manual, with a clean separation of
the two manuals.  There's no use in having options for manual variants
that no-one uses.  Either have separate manuals, or have one manual, but
don't pretend both versions are supported.  (Another option is for the
internals information to go in the main GCC internals manual, with the
user information separate in a front end manual.)

> + @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. (from
> gcc.texi)
> + @c @smallbook
> +
> + @c i also commented out the finalout command, so if there *are* any
> + @c overfulls, you'll (hopefully) see the rectangle in the right hand
> + @c margin. -- burley 1999-03-13 (from mew's comment in GCC.texi).
> + @c @finalout

Again, no need to copy ancient comments.  doc/include/gcc-common.texi has
an FSFPRINT conditional; there should be nothing like this in individual
manuals.

> + @ifset INTERNALS
> + @ifset USING

Get rid of these conditionals; decide which sort of manuals are wanted.

This front end is supposed to be a good example; these sorts of unused
conditionals aren't.

> + Copyright (C) @value{copyrights-treelang} Free Software Foundation,

That should be @copyright{}, not (C).

> + @c Last printed ??ber, 19??.@*

Don't add Y2K problems in new manuals.

> + @ifinfo

Have you made sure that this manual builds with makeinfo --html?  @ifinfo
is often incorrect (should be @ifnottex).

> + This manual documents how to run, install and maintain
> @code{treelang},
> + as well as its new features and incompatibilities,
> + and how to report bugs.

It shouldn't document how to install (install manual) or how to report
bugs (just point to online bug reporting docs).

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