Re: [Ada] GNAT User Guide

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

On Tue, 12 Mar 2002, Florian Weimer wrote:

> Below is a compressed version of the GNAT User Guide Ben Brosgol sent
> to me a couple of hours ago.

Here is a list of Texinfo issues with this file.

> \input texinfo   @c -*-texinfo-*-
> @input texiplus

As for reference manual, texiplus is not a part of a standard GNU Texinfo
distribution and should not be used.

> @c          Copyright (C) 1992-2002 Ada Core Technologies, Inc.               o

Should be assigned to FSF?

> @c  GNAT is free software;  you can  redistribute it  and/or modify it under  o
> @c  terms of the  GNU General Public License as published  by the Free Soft-  o
> @c  ware  Foundation;  either version 2,  or (at your option) any later ver-  o

As for reference manual (please go through all the comments I gave on
that, and check whether they apply to this manual as well), this notice is
true, but misleading as comments on a FDL manual.  (Of course the actual
text of the manual can explain somewhere the program licence, and include
it as a section, taking it from doc/include/gpl.texi.)

> @author Ada Core Technologies, Inc.

The GNU Coding Standards say that companies are not manual authors.

> Copyright @copyright{} 1995-2002, Free Software Foundation

Different dates and copyright holders in the two notices.  Should be "Free
Software Foundation, Inc.".

> Permission is granted to copy, distribute and/or modify this document
> under the terms of the GNU Free Documentation License, Version 1.1
> or any later version published by the Free Software Foundation;
> with the Invariant Sections being ``GNU Free Documentation License'', with the

http://www.gnu.org/licenses/fdl-howto-opt.html
says that

#  You do not have to list the GNU
#  FDL itself as an invariant section, because the FDL explicitly says
#  that the FDL itself may not be changed.

> Front-Cover Texts being 
> @ifset vms
> ``GNAT User's Guide for OpenVMS Alpha'', 

This isn't how Front-Cover Texts and Back-Cover Texts are generally used 
in GNU manuals.  The FDL already says that

# The front cover must present the full title with all words of the title
# equally prominent and visible.

so the manual title shouldn't be listed as a Front-Cover Text.  Instead, I 
think the standard GNU texts, as in the GCC manual, should be used.

> Copyright @copyright{} 1995-2002, Free Software Foundation

Again, "Free Software Foundation, Inc.".

The Information For Maintainers of GNU Software says that copyright 
notices don't give years as a range - but if you must, then use "--" to 
get a proper en dash rather than a hyphen.

> @ref{Preliminary Note for Cross Platform Users}, describes the basic
> differences between the cross and native versions of GNAT.

@. for full stop at end of sentence preceded by capital letter (further
cases not mentioned below).

> Ada programs with @code{gcc}, the Ada compiler.

@command for commands (further cases not mentioned below).

> @cite{GNAT Reference Manual}, which contains all reference
> material for the GNAT implementation of Ada 95.

This should be a proper Texinfo link.

> @itemize @bullet
> @item
> @code{Functions}, @code{utility program names}, @code{standard names},
> and @code{classes}.

@command{utility program names}

> @item
> @samp{Option flags}

@option{Option flags}

> @item
> @file{File Names}, @file{button names}, and @file{field names}.

Only file names should be @file; others maybe @samp (which looks the
same).

> @item
> @var{Variables}.

@var is specific for metasyntactic variables, not programming language
variables which are @code.

> Commands that are entered by the user are preceded in this manual by the
> characters @w{"@code{$ }"} (dollar sign followed by space). If your system

Never use neutral double quotes outside examples, only TeX quotes.  @samp 
adds quotes, so the correct use here is @samp{$ }.

Two spaces after full stops at end of sentences (further cases not
mentioned below).

> which the cross compiler is configured. For instance, the cross @command{gnatmake}
> tool is called @command{@i{target}-gnatmake} where @code{@i{target}} stands for the name of

@var{target}.  Further cases not mentioned below.

> file corresponding to your Ada program. It also generates an "Ada Library Information" file

Use proper TeX quotes.  Further cases not mentioned below.

> @smallexample
> $ hello
> @end smallexample
> 
> @noindent
> assuming that the current directory is on the search path for executable programs.

Non-Texinfo comment: in general users should be discouraged from having
such an environment, and even if they do then the current directory should
be at the end of the search path and GNU hello might be installed earlier
on the path.  Write examples so as not to assume the current directory is
on the path.

> @code{-C} option.  The third command loads the module, which is the file 

@option not @code for options.

> In a character cell terminal, Emacs help is invoked with "Ctrl-h" (also written
> as "C-h"), and the tutorial by "C-h t".

Use @kbd.  Further cases not mentioned below.

> Documentation on Emacs and other tools is available in Emacs under the
> pull-down menu button: Help - Info. After selecting Info, use the middle

I think this should be an em dash (--- with no spaces around it).

> mouse button to select a topic (e.g. Emacs).

e.g. or i.e. must be followed by comma or @:.  Further cases not mentioned
below.

> Although it is possible to develop programs using only the command line interface (@command{gnatmake}, etc.) a graphical Interactive Development Environment can make it easier for you to compose, navigate, and debug programs.  This section describes the main features of Glide, the GNAT graphical IDE, and also shows how to use the basic commands in GVD, the GNU Visual Debugger.  Additional information may be found in the on-line help for these tools.

Excessively long source lines.  Also in other places, not mentioned above
and below.

Glide doesn't seem to be part of GCC at present, so I doubt its 
documentation should be; such a tutorial belongs in the Glide manual, and 
the GNAT one can have a link to it.  Likewise GVD.

> The basic character set is Latin-1. This character set is defined by ISO
> standard 8859, part 1. The lower half (character codes @code{16#00#}
> ... @code{16#7F#)} is identical to standard ASCII coding, but the upper half is

... should be @dots{} except where it's literal programming language text.

> Any character in the range 80-FF allowed in identifiers, and all are

- (for a range) should be -- (en dash).  Further cases not mentioned.

> The default file name is determined by the name of the unit that the
> file contains. The name is formed by taking the full expanded name of
> the unit and replacing the separating dots with hyphens and using
> ^lowercase^uppercase^ for all letters.

What does "^lowercase^uppercase^" mean?

> An exception arises if the file name generated by the above rules starts
> with one of the characters
> @ifset vms
> A,G,I, or S,
> @end ifset
> @ifclear vms
> a,g,i, or s,
> @end ifclear

There should be spaces after the commas.  Probably the individual letters
should be quoted by putting them in @samp.

> Interfaces, and GNAT, which use the prefixes
> @ifset vms
> S- A- I- and G-
> @end ifset
> @ifclear vms
> s- a- i- and g-
> @end ifclear

These should definitely be in @samp or @file.

> If an object file O  depends on the proper body of a subunit through inlining

That should be @var{O}.

> Using GNAT and G++ (GNU C++ compiler) from the same GCC
> installation. The c++ linker can simply be called by using the c++

C++, C++.

> specific driver called @code{c++}. Note that this setup is not
> very common because it may request recompiling the whole GCC
> tree from sources and it does not allow to upgrade easily to a new
> version of one compiler for one of the two languages without taking the
> risk of destabilizing the other.

I doubt this paragraph is relevant to FSF releases with all languages
included.

> GNAT offers the capability to derive Ada 95 tagged types directly from
> preexisting C++ classes and . See "Interfacing with C++" in the GNAT

Sentence doesn't seem to end properly.  Cross-reference should be a proper
link.

> @code{Interfaces.CPP}. The default version of this file is adapted to
> the GNU c++ compiler. Internal knowledge of the virtual

"GNU C++ compiler" or "G++".

> If you attempt to compile any of these files, you will get one of the
> following error messages (where fff is the name of the file you compiled):

@var{fff}.

> @smallexample
> $ gcc -c [@var{switches}] @file{file name}

@file{@var{file-name}}.

> from @var{dir} instead of the default location. Only use this switch
> when multiple versions of the GNAT compiler are available. See the
> @code{gcc} manual page for further details. You would normally use the
> @code{-b} or @code{-V} switch instead.

Don't cross-reference the man page.  Link to the info manual instead.  
Don't advocate use of -V - we'd like to get rid of it.

> @ifclear vms
> @item -V @var{ver}
> @cindex @code{-V} (@code{gcc})
> Execute @var{ver} version of the compiler. This is the @code{gcc}
> version, not the GNAT version.
> @end ifclear

At the very least, include a similar warning to that in the GCC manual
that -V won't work except with very similar compiler versions.

> Avoid processing @file{gnat.adc}. If a gnat.adc file is present, it will be ignored.

@file in the second place.

> also suppress generation of cross-reference information (see -gnatx).

@option.

> @ifclear VMS
> @item -fstack-check
> Activates stack checking. See separate section on stack checking for
> details of the use of this option.

"See separate section" should be a proper link.

> @item -gnato
> Enable numeric overflow checking (which is not normally enabled by
> default). Not that division by zero is a separate check that is not
> controlled by this switch (division by zero checking is on by default).

I think you mean "Note that" rather than "Not that".

> @item -gnatR[0/1/2/3][s]

The square brackets should be in @r{} unless they're a literal part of the
option name.

> values. If @option{-gnatVf} is specified, then validity checking also applies
> for floating-point values, and NaN's and infinities are considered invalid,

The plural should be "NaNs" without apostrophe.

> as well as out of range values for constrained types. Note that this means
> that standard @code{IEEE} infinity mode is not allowed. The exact contexts

IEEE doesn't go in @code.

> overflow, set the environment variable
> @code{GNAT_STACK_LIMIT} to indicate the maximum

Environment variables are @env.

> brackets and @code{UTF-8} encodings will be recognized. The units that are

UTF-8 shouldn't go in @code.

> The GNAT Ada aware version of GDB understands these encoded prefixes, so if this

What does "The GNAT Ada aware version of GDB" mean?  It would be better to
refer to specific versions, e.g. "GDB x.y or later", depending on what
version it's been merged in or will be merged in.

> @code{gnatlink} accepts the following types of extra files on the command
> line: objects (.OBJ), libraries (.OLB), shareable images (.EXE), and
> options files (.OPT). These are recognized and handled according to their
> extension.

@file for file extensions.  Further cases not mentioned below.

> You have defined an environment variable @code{ADA_PROJECT_PATH} that

@env for environment variables.  Further cases not mentioned below.

> Here is an example of a string type declaration:
> 
> @smallexample
>    type OS is ("NT, "nt", "Unix", "Linux", "other OS");
> @end smallexample

I suspect the FSF might rather this example said "GNU/Linux".

> On non VMS platforms, the @command{gnat} driver accepts the following commands

I don't think "non" should be used as a separate word; it should be used
either with a hyphen (as here) or with no hyphen or space.  (Further cases
not mentioned above or below.)

> Here is a more formal grammar :
> @smallexample
> @group
> @iftex
> @leftskip=.5cm
> @end iftex
> regexp ::= term
> term   ::= elmt            -- matches elmt
> term   ::= elmt elmt       -- concatenation (elmt then elmt)

One thing noticable here, and elsewhere, is the lack of any standard
Texinfo facilities for representing formal grammars.  Is there anyone
interested in implementing such a facility?

> will match any of the two strings 'abcde' and 'fghi'.

Single quotes become right quotes in TeX - you must use matched ` and ',
or (perhaps better here) @samp.

> @code{gnatxref} can generate a tags file output, which can be used
> directly from @file{vi}. Note that the standard version of @file{vi}
> will not work properly with overloaded symbols. Consider using another
> free implementation of @file{vi}, such as @file{vim}.

@command{vi} rather than @file{vi}.  What do you mean by "the standard
version" of vi - there are many competing free versions, no one clear
standard?

> ^a, g, s, or i^A, G, S, or I^ then replace the dot by the character
> ^~ (tilde)^$ (dollar sign)^

@samp for file name characters.  Further cases not mentioned below.

> option -shared in the GCC manual).

@option.

> problems. It does not explain how to write a makefile (see the GNU make
> documentation), nor does it try to replace the @code{gnatmake} utility

This should be a proper link to the GNU Make manual.

>     cd $@{dir $@@ @}; gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
>     cd $@{dir $@@ @}; cp -f ../*.ali .

These commands are not good makefile style.  When multiple commands or
shell loops are used in a Makefile (or indeed any shell script), either
"set -e" should be used or (perhaps better in this case) they should be
linked with "&&" rather than ";", so that errors in earlier commands are
detected.

> @node Converting Ada Files to html with gnathtml
> @section Converting Ada Files to html with @code{gnathtml}
> 
> @noindent
> This @code{Perl} script allows Ada source files to be browsed using
> standard Web browsers. For installation procedure, see the section
> @xref{Installing gnathtml}.

This script does not seem to be included with GCC, so its documentation
shouldn't be in this manual.

> @node Installing gnathtml
> @section Installing @code{gnathtml}
> 
> @noindent
> @code{Perl} needs to be installed on your machine to run this script.
> @code{Perl} is freely available for almost every architecture and
> Operating System via the Internet.
> 
> On Unix systems, you  may want to modify  the  first line of  the script
> @code{gnathtml},  to explicitly  tell  the Operating  system  where Perl
> is. The syntax of this line is :
> @smallexample
> #!full_path_name_to_perl
> @end smallexample

Of course, if it were included in GCC, the configure script should be used
to substitute the correct path.

> The manual @cite{Debugging with GDB}
> @ifset vms
> , located in the GNU:[DOCS] directory,
> @end ifset

Proper link.

> will run exactly as it would have if @code{GDB} were not present. This

@code{GDB} is not the correct form of reference.  GDB (no special markup)  
to refer to the debugger in general, @command{gdb} for specific reference
to the command.  Other uses not mentioned above and below.

> ???????????? WE NEED TO DECIDE WHETHER TO DISTRIBUTE IT ??????????????????????

As long as the tool in question isn't part of the FSF tree, neither should
this manual section for it be.

> @include gfdl.texi

The file is called fdl.texi, not gfdl.texi.

> @contents
> 
> @bye

Contents lists should go at the front of the manual in their right place,
not at the back, so that the printed output doesn't need to be rearranged.
(texi2dvi will handle rerunning what's needed as many times as necessary,
so any reason for putting contents lists at the end is obsolete.)

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