Bug 15479 - Ada manual problems
Summary: Ada manual problems
Status: RESOLVED FIXED
Alias: None
Product: gcc
Classification: Unclassified
Component: ada (show other bugs)
Version: 4.0.0
: P2 normal
Target Milestone: 4.4.0
Assignee: Not yet assigned to anyone
URL:
Keywords: documentation
Depends on:
Blocks:
 
Reported: 2004-05-16 19:42 UTC by Joseph S. Myers
Modified: 2008-05-12 23:11 UTC (History)
2 users (show)

See Also:
Host:
Target:
Build:
Known to work:
Known to fail:
Last reconfirmed: 2006-02-02 13:42:25


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Joseph S. Myers 2004-05-16 19:42:23 UTC
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.
Comment 1 Andrew Pinski 2004-05-16 19:48:47 UTC
Confirmed.
Comment 2 Ralf Wildenhues 2008-02-03 14:57:13 UTC
patch set posted at <http://gcc.gnu.org/ml/gcc-patches/2008-02/msg00058.html>.
Comment 3 Ralf Wildenhues 2008-02-17 21:20:46 UTC
Subject: Bug 15479

Author: rwild
Date: Sun Feb 17 21:20:01 2008
New Revision: 132382

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132382
Log:
gcc/ada/:
PR documentation/15479
* gnat_ugn.texi: In non-code, avoid space before colon.
(Regular Expressions in gnatfind and gnatxref): Fix indentation.
(Examples of gnatxref Usage): Use @command{vi} instead of
@file{vi}.
(Character Set Control): Do not use @code for UTF-8.
(Validity Checking): Fix typo "NaNs" instead of "NaN's".  Do not
use @code for IEEE.
* gnat_rm.texi (Aggregates with static bounds): Fix typo in code
sample.
* gnat_rm.texi, gnat_ugn.texi: Fix typos.  Bump copyright years.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat_rm.texi
    trunk/gcc/ada/gnat_ugn.texi

Comment 4 Ralf Wildenhues 2008-02-20 19:49:42 UTC
Subject: Bug 15479

Author: rwild
Date: Wed Feb 20 19:48:55 2008
New Revision: 132493

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132493
Log:
gcc/ada/:
PR documentation/15479
* gnat_ugn.texi: In non-code, avoid space before colon.
(Regular Expressions in gnatfind and gnatxref): Fix indentation.
(Examples of gnatxref Usage): Use @command{vi} instead of
@file{vi}.
(Character Set Control): Do not use @code for UTF-8.
(Validity Checking): Fix typo "NaNs" instead of "NaN's".  Do not
use @code for IEEE.
* gnat_rm.texi (Aggregates with static bounds): Fix typo in code
sample.
* gnat_rm.texi, gnat_ugn.texi: Fix typos.  Bump copyright years.

Modified:
    branches/gcc-4_2-branch/gcc/ada/ChangeLog
    branches/gcc-4_2-branch/gcc/ada/gnat_rm.texi
    branches/gcc-4_2-branch/gcc/ada/gnat_ugn.texi

Comment 5 Ralf Wildenhues 2008-02-20 19:51:24 UTC
Subject: Bug 15479

Author: rwild
Date: Wed Feb 20 19:50:39 2008
New Revision: 132494

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132494
Log:
gcc/ada/:
PR documentation/15479
* gnat_ugn.texi: In non-code, avoid space before colon.
(Regular Expressions in gnatfind and gnatxref): Fix indentation.
(Examples of gnatxref Usage): Use @command{vi} instead of
@file{vi}.
(Character Set Control): Do not use @code for UTF-8.
(Validity Checking): Fix typo "NaNs" instead of "NaN's".  Do not
use @code for IEEE.
* gnat_rm.texi (Aggregates with static bounds): Fix typo in code
sample.
* gnat_rm.texi, gnat_ugn.texi: Fix typos.  Bump copyright years.

Modified:
    branches/gcc-4_1-branch/gcc/ada/ChangeLog
    branches/gcc-4_1-branch/gcc/ada/gnat_rm.texi
    branches/gcc-4_1-branch/gcc/ada/gnat_ugn.texi

Comment 6 Ralf Wildenhues 2008-02-24 22:38:36 UTC
Subject: Bug 15479

Author: rwild
Date: Sun Feb 24 22:37:52 2008
New Revision: 132601

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132601
Log:
PR documentation/15479
* gnat_ugn.texi (Using gnatmake in a Makefile): Do not ignore errors
in Makefile rules, by using `&&' rather than `;'.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat_ugn.texi

Comment 7 Ralf Wildenhues 2008-02-24 22:41:15 UTC
Subject: Bug 15479

Author: rwild
Date: Sun Feb 24 22:40:31 2008
New Revision: 132602

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132602
Log:
PR documentation/15479
* gnat_rm.texi, gnat_ugn.texi: Where appropriate, add @command,
use @command instead of @code, @option instead of @samp or @code,
@code instead of @var, @samp instead of @file.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat_rm.texi
    trunk/gcc/ada/gnat_ugn.texi

Comment 8 Ralf Wildenhues 2008-02-24 22:44:45 UTC
Subject: Bug 15479

Author: rwild
Date: Sun Feb 24 22:44:01 2008
New Revision: 132603

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132603
Log:
PR documentation/15479
* gnat_rm.texi, gnat_ugn.texi: Where appropriate, replace `..'
and `...' with `@dots{}' or `@enddots{}'.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat_rm.texi
    trunk/gcc/ada/gnat_ugn.texi

Comment 9 Ralf Wildenhues 2008-03-02 22:37:19 UTC
Subject: Bug 15479

Author: rwild
Date: Sun Mar  2 22:36:35 2008
New Revision: 132821

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=132821
Log:
gcc/ada

	PR documentation/15479
	* gnat_rm.texi, gnat_ugn.texi: Avoid standalone `non' word.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat_rm.texi
    trunk/gcc/ada/gnat_ugn.texi

Comment 10 Ralf Wildenhues 2008-03-23 23:19:58 UTC
Subject: Bug 15479

Author: rwild
Date: Sun Mar 23 23:19:25 2008
New Revision: 133470

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=133470
Log:
gcc/ada/
2008-03-24  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	PR documentation/15479
	* Make-lang.in (doc/gnat_ugn.texi) Renamed from ...
	(doc/gnat_ugn_unw.texi): ... this, and adjusted.
	(doc/gnat_ugn.info): Renamed from ...
	(doc/gnat_ugn_unw.info): ... this.
	(doc/gnat_ugn.dvi): Renamed from ...
	(doc/gnat_ugn_unw.dvi): ... this.
	(doc/gnat_ugn.pdf): Renamed from ...
	(doc/gnat_ugn_unw.pdf): ... this.
	(ADA_INFOFILES, ADA_PDFFILES, ada.install-info, ada.dvi):
	Adjusted.
	* gnat_ugn.texi (FILE): Hard-code gnat_ugn; set filename
	unconditionally to gnat_ugn.info.  Fix cross references to the
	GNAT Reference Manual.  Convert links to the GCC, GDB, Emacs,
	and GNU make manuals to be proper texinfo links.
	* gnat_rm.texi: Fix cross references to the GNAT User's Guide.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/Make-lang.in
    trunk/gcc/ada/gnat_rm.texi
    trunk/gcc/ada/gnat_ugn.texi

Comment 11 Arnaud Charlet 2008-05-12 23:11:26 UTC
This PR seems to be addressed at this point.
Comment 12 Ralf Wildenhues 2008-07-14 18:50:21 UTC
Subject: Bug 15479

Author: rwild
Date: Mon Jul 14 18:49:37 2008
New Revision: 137793

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=137793
Log:
gcc/ada/
	PR documentation/15479
	* gnat_ugn.texi (@ovar): New macro, from autoconf.texi.
	Replace backets around optional parameters with @ovar
	where possible, use @r{[}, @r{]} otherwise.
	Replace some @r, @i, and @emph with @var where appropriate.

Modified:
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat_ugn.texi

Comment 13 Ralf Wildenhues 2008-07-30 05:30:14 UTC
Subject: Bug 15479

Author: rwild
Date: Wed Jul 30 05:28:53 2008
New Revision: 138293

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=138293
Log:
gcc/ada/
	PR documentation/15479
	* gnat-style.texi: Remove AdaCore copyright statement and GPL
	statement for GNAT.  Add @copying stanza, use it.  Update to
	GFDL 1.2.  Do not list GFDL as Invariant Section, do not list
	title as Front-Cover Text.
	* gnat_rm.texi: Likewise.
	* gnat_ugn.texi: Likewise.

gcc/
	* doc/cpp.texi: Update to GFDL 1.2.
	* doc/gcc.texi: Do not list GPL as Invariant Section.
	* doc/gccint.texi: Likewise.  Update copyright years.
	* doc/install.texi: Update copyright years.

gcc/fortran/
	* gfc-internals.texi: Update to GFDL 1.2.  Do not list GPL as
	Invariant Section.
	* gfortran.texi: Likewise.
	* intrinsic.texi: Do not list GPL as Invariant Section.
	* invoke.texi: Likewise.  Update copyright years.

gcc/java/
	* gcj.texi: Update copyright years.  Do not list GPL as
	Invariant Section.

libgomp/
	* libgomp.texi: Update to GFDL 1.2.  Update copyright years.
	Do not list GPL as Invariant Section.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/ada/ChangeLog
    trunk/gcc/ada/gnat-style.texi
    trunk/gcc/ada/gnat_rm.texi
    trunk/gcc/ada/gnat_ugn.texi
    trunk/gcc/config.in
    trunk/gcc/doc/cpp.texi
    trunk/gcc/doc/gcc.texi
    trunk/gcc/doc/gccint.texi
    trunk/gcc/doc/install.texi
    trunk/gcc/fortran/ChangeLog
    trunk/gcc/fortran/gfc-internals.texi
    trunk/gcc/fortran/gfortran.texi
    trunk/gcc/fortran/intrinsic.texi
    trunk/gcc/fortran/invoke.texi
    trunk/gcc/java/ChangeLog
    trunk/gcc/java/gcj.texi
    trunk/libgomp/ChangeLog
    trunk/libgomp/libgomp.texi
    trunk/libiberty/functions.texi