[9602-004] Re: [Ada] GNAT User Guide

[Ben Brosgol]

Joseph,

Thanks for your comments.  I was preempted over the past few weeks by some
other activities but I will be returning shortly to the GNAT documentation
tasks.  I recognize that the GNAT User's Guide has the same Texinfo issues
as the GNAT Reference Manual (indeed, some additional ones as have been
noted in earlier discussions), and I plan to ensure that we adhere to the
GNU documentation style conventions.

Ben Brosgol

Ada Core Technologies
79 Tobey Road; Belmont, MA 02478; USA
+1-617-489-4027 (voice);  +1-617-489-4009 (FAX)
brosgol@gnat.com
----- Original Message -----
From: "Joseph S. Myers" <jsm28@cam.ac.uk>
To: <gcc-patches@gcc.gnu.org>
Cc: <brosgol@gnat.com>
Sent: Saturday, March 16, 2002 8:42 PM
Subject: Re: [Ada] GNAT User Guide


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