[Bug ada/15479] New: Ada manual problems

[jsm28 at gcc dot gnu dot org]

The Ada manuals have the following previously noted problems:

All cross-references between the user and reference manuals (both
to the manuals as a whole or to individual sections) should be proper
Texinfo links.

In addition, the following problems with the user manual, previously
noted in <http://gcc.gnu.org/ml/gcc-patches/2002-03/msg01018.html>
when it was first added, still seem to be present: (cut-and-pasted from
that message; I've tried to remove things that have been fixed)

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

This notice is true, but misleading as comments on a FDL manual.

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

Should be "Free Software Foundation, Inc.".

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.

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.

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

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

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

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

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

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

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

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

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

@file in the second place.

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

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

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

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

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

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

-- 
           Summary: Ada manual problems
           Product: gcc
           Version: 3.5.0
            Status: UNCONFIRMED
          Severity: normal
          Priority: P2
         Component: ada
        AssignedTo: unassigned at gcc dot gnu dot org
        ReportedBy: jsm28 at gcc dot gnu dot org
                CC: gcc-bugs at gcc dot gnu dot org


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=15479