public inbox for gcc-bugs@sourceware.org
help / color / mirror / Atom feed
* [Bug ada/15479] New: Ada manual problems
@ 2004-05-17 4:39 jsm28 at gcc dot gnu dot org
2004-05-17 4:47 ` [Bug ada/15479] " pinskia at gcc dot gnu dot org
0 siblings, 1 reply; 2+ messages in thread
From: jsm28 at gcc dot gnu dot org @ 2004-05-17 4:39 UTC (permalink / raw)
To: gcc-bugs
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
^ permalink raw reply [flat|nested] 2+ messages in thread
* [Bug ada/15479] Ada manual problems
2004-05-17 4:39 [Bug ada/15479] New: Ada manual problems jsm28 at gcc dot gnu dot org
@ 2004-05-17 4:47 ` pinskia at gcc dot gnu dot org
0 siblings, 0 replies; 2+ messages in thread
From: pinskia at gcc dot gnu dot org @ 2004-05-17 4:47 UTC (permalink / raw)
To: gcc-bugs
------- Additional Comments From pinskia at gcc dot gnu dot org 2004-05-16 19:48 -------
Confirmed.
--
What |Removed |Added
----------------------------------------------------------------------------
Status|UNCONFIRMED |NEW
Ever Confirmed| |1
Keywords| |documentation
Last reconfirmed|0000-00-00 00:00:00 |2004-05-16 19:48:48
date| |
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=15479
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2004-05-16 19:48 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2004-05-17 4:39 [Bug ada/15479] New: Ada manual problems jsm28 at gcc dot gnu dot org
2004-05-17 4:47 ` [Bug ada/15479] " pinskia at gcc dot gnu dot org
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).