Re: gcc/gcc/ada ChangeLog gnat_rm.texi

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

On 26 Oct 2001 bosch@gcc.gnu.org wrote:

> 	* gnat_rm.texi: Add GNAT Reference Manual.

Here is a probably non-exhaustive list of problems with this manual,
mostly but not entirely relating to formatting and Texinfo style.

Note: from time to time I will make full passes over some or all of the
manuals (as I did before GCC 3.0 with the main GCC manual) and fix various
classes of problems, both manually found and found through grep.
However, any such pass will probably miss a certain proportion of the
problems, so it is best for people to write good Texinfo in the first
place, and to fix the problems I point out on initial passes such as this
over new documentation (using where appropriate their knowledge of the
subject matter of the patch), and related problems they find elsewhere in
the manual (for example, in a great many places in this manual @code
should be used but I didn't note this in each individual place).

Could people contributing documentation also please read the long lists of
problems such as this I send and remember them and try to avoid repeating
the same problems?

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

What's texiplus?  Why is it needed?  It isn't in CVS.  What test procedure
did you use for this commit?

(In fact, removing this line seems to leave a manual that works.)

> @c          Copyright (C) 1992-2001 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
> @c  sion.  GNAT is distributed in the hope that it will be useful, but WITH-  o
> @c  OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY  o
> @c  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License  o
> @c  for  more details.  You should have  received  a copy of the GNU General  o
> @c  Public License  distributed with GNAT;  see file COPYING.  If not, write  o
> @c  to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston,  o
> @c  MA 02111-1307, USA.                                                       o

While accurate, including such a notice in an FDL manual is a bit
confusing.

> @setfilename gnat_rm.info
> @settitle GNAT Reference Manual

Also include @dircategory and @direntry.

> Copyright @copyright{} 1995-2001, Ada Core Technologies
> 
> 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
> Front-Cover Texts being ``GNAT Reference Manual'', and with no Back-Cover Texts.
> A copy of the license is included in the section entitled ``GNU
> Free Documentation License''.

The standard FSF Front-Cover and Back-Cover texts (as in the GCC manual)  
should probably be included.

> Silicon Graphics and IRIS are registered trademarks
> and IRIX is a trademark of Silicon Graphics, Inc.
> 
> IBM PC is a trademark of International
> Business Machines Corporation.
> 
> UNIX is a registered trademark of AT&T
> Bell Laboratories. 
> DIGITAL 
> 
> VADS is a registered trademark of Rational Software Inc.
> 
> The following are trademarks of Digital Equipment Corporation:
> DEC, DEC Ada, DECthreads, Digital, OpenVMS, and VAX.

These trademark acknowledgements should not be here; the GNU Coding 
Standards say:

   Please do not include any trademark acknowledgements in GNU software
   packages or documentation.

   Trademark acknowledgements are the statements that such-and-such is a
   trademark of so-and-so. The GNU Project has no objection to the basic
   idea of trademarks, but these acknowledgements feel like kowtowing, so
   we don't use them. There is no legal requirement for them.

> Version 3.14a

The version number was 3.15w earlier in the file.  Be consistent.

> Silicon Graphics and IRIS are registered trademarks
> and IRIX is a trademark of Silicon Graphics, Inc.

Again, no trademark acknowledgements.

> GNAT compiler. It includes information on implementation dependent

Two spaces after full stops ending sentences.  (Not noted further below.)

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

Utility program names should be in @command (though they are formatted the
same).

> @samp{Option flags}

Should be @option (formatted the same).

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

Only file names (and parts of file names) should be in @file.  Use @samp
(formatted the same) for the others.

> @var{Variables}.

@var is only for metasyntactic variables.  For literal names of 
programming language variables, use @code.

> characters "$ " (dollar sign followed by space). If your system uses this

@samp{$ }.

> appear with the $ replaced by whatever prompt character you are using.

@samp{$}.

> See the following documents for further information on GNAT

Something - either a full stop or a colon - should terminate this
sentence.

> @cite{GNAT User's Guide}, which provides information on how to use
> the GNAT compiler system.

Assuming this is a Texinfo manual, link to it in the proper manner.

> and generics may name types with unknown discriminants without using
> the (<>) notation. In addition, some but not all of the additional

Use @samp or @code for literal examples of programming language notation.

> @smallexample
> pragma Annotate (IDENTIFIER @{, ARG@});
> 
> ARG ::= NAME | EXPRESSION
> @end smallexample

@var{identifier}, @var{arg}, @var{name}, @var{expression} (as below).  In
Info output these will be in capitals, in printed output they will be in
italics.

> @smallexample
> pragma Assert (
>   boolean_EXPRESSION
>   [, static_string_EXPRESSION])
> @end smallexample

Likewise, @var.

> @smallexample
> if assertions-enabled then
>    if not boolean_EXPRESSION then
>       System.Assertions.Raise_Assert_Failure
>         (string_EXPRESSION); 

@var.

> @smallexample
> ...

@dots.

> type of the expression is either Standard.Boolean, or any type derived

@code{Standard.Boolean}.

> If assertions are disabled (switch @code{-gnata} not used), then there

@option for command-line options, not @code.

> If assertions are enabled, then the given expression is tested, and if
> it is @code{False} then System.Assertions.Raise_Assert_Failure is called

@code{System.Assertions.Raise_Assert_Failure}.

> which results in the raising of Assert_Failure with the given message.

@code{Assert_Failure}.

> @smallexample
> pragma AST_Entry (entry_IDENTIFIER);

@var.  (Further such instances where @var should be used not noted below.)

> This is almost identical in effect to pragma Ident. It allows the

@code{Ident} or @code{pragma Ident}.

> difference is that Comment, unlike Ident, has no limit on the

@code{Comment} and @code{Ident}.

> Pragma @code{CPP_Class} is intended primarily for automatic generation
> using an automatic binding generator tool. Ada Core Technologies does
> not currently supply such a
> tool; See @ref{Interfacing to C++} for more details.

Discussing what Ada Core Technologies does or does not supply is probably
inappropriate in a GNU manual.  You should however discuss what the FSF
provides, and what is available as non-GNU Free Software.

> with pragma Import) as corresponding to a C++

@code{Import} or @code{pragma Import}.

> constructor. The argument is a name that must have been
> previously mentioned in a pragma
> Import with @var{Convention CPP}, and must be of one of the following

Likewise, and @var is inappropriate here.  (In general, the argument of
@var should not contain any spaces.)

> Pragma @code{CPP_Constructor} is intended primarily for automatic generation
> using an automatic binding generator tool. Ada Core Technologies does
> not currently supply such a
> tool; See @ref{Interfacing to C++} for more details.

Again, what Ada Core Technologies supplies is inappropriate to this
manual.

> The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
> there is one Vtable_Ptr present (single inheritance case) and all

@code{Vtable_Ptr}.

> Pragma @code{CPP_Virtual} is intended primarily for automatic generation
> using an automatic binding generator tool. Ada Core Technologies does
> not currently supply such a
> tool; See @ref{Interfacing to C++} for more details.

Again, don't discuss what ACT supplies.  The appropriate place for
advertising services that may be used with free software is the GNU
Service Directory rather than the text of GNU manuals.

> Pragma @code{CPP_Vtable} is intended primarily for automatic generation
> using an automatic binding generator tool. Ada Core Technologies does
> not currently supply such a
> tool; See @ref{Interfacing to C++} for more details.

Ditto.

> the @code{-gnatE} switch had been specified on the command

@option.

> used by the GNAT compiler, see section "Elaboration Order
> Handling in GNAT" in the GNAT Users Guide.

Use a normal @xref link.  If this isn't a Texinfo document, then use TeX
quotes ``'' rather than neutral double quotes.

> The intention of pragma Eliminate is to allow a program to be compiled

@code.  More similar cases not noted below.

> This pragma may appear anywhere that a pragma is valid. in particular, it
> can be used as a configuration pragma in the @code{gnat.adc} file, in which

@file for file names.

> It is primarily intended for use with @code{OpenVMS} systems, where many

No @code around OpenVMS.

> in @code{GNAT}, which checks for invalid values under more conditions.

No @code around GNAT.

> Using this feature (see description of the @code{-gnatv} flag in the

@option for options.

> Similar to pragma  @code{Inline} except that inlining is not subject to
                   ^^ two spaces, should be one

> the use of option @code{-gnatn} for inter-unit inlining.

@option.

> If the string "GNU General Public License" is found, then the unit is assumed
> to have GPL license, unless the string "As a special exception" follows, in

TeX quotes ``...'' rather than neutral double quotes.

> "This specification is adapated from the Ada Semantic Interface" or
> "This specification is derived from the Ada Reference Manual" is found

TeX quotes.

> results in passing the strings @code{-labc} and @code{-ldef} as two

@option (or @samp, if you want to consider them as meaningless strings 
rather than options).

> This is a configuration pragma that makes sure the user code does not
> use nor need anything from the GNAT run time. This is mostly useful in
> context where code certification is required. Please consult the High
> Integrity product documentation for additional information.

What is "the High Integrity product documentation"?  Give a full
reference.

> Objects of an enumeration type are initialized to all one-bits, i.e. to
> the value 2 ** typ'Size - 1. This will be out of range of the enumeration

@code{2 ** typ'Size - 1}, and similarly for all the literal programming
language code above.  (Note that minus signs in free text - not in @code
etc. - must be @minus{}, but using @code seems more appropriate here.)

> 2**8, 2**16, or 2**32.

Similarly.

> @code{digits} specified in the range 7 .. 15.

@code{7 .. 15} if this is literal code, 7--15 to represent a range in TeX
form.

> pragma is semantically equivalent to @code{__attribute__((
> @var{string_expression}))} in GNU C, where @code{string_expression}> is

Inconsistency between @code and @var.  The second should be
@code{@var{string_expression}}, properly.

> recognized by the GNU C macros @code{VALID_MACHINE_TYPE_ATTRIBUTE} and
> @code{VALID_MACHINE_DECL_ATTRIBUTE} which are defined in the

With table-driven attributes and the target structure, this is an
out-of-date description.

> runtime library, and can be found in file a-excpol.adb.

@file.

> placed in the gnat.adc file) to enable polling globally, or it can be used

@file.

> in files a-except.ads/adb.

@file.

> A standard alternative unit (called 4wexcpol.adb in the standard GNAT

@file.

> Note that polling can also be enabled by use of the -gnatP switch. See

@option.

> the alternative longjmp/setjmp implementation of exceptions is used

@code{longjmp}, @code{setjmp}.

> For the longjmp/setjmp implementation of exceptions, the answer is

Likewise.

> to ensure that this promise is met, so @var{Pure_Function} can be used

@code, not @var.

> This set of restrictions corresponds to the definition of the "Ravenscar
> Profile" for limited tasking, devised and published by the International
> Workshop On Real Time Ada", 1997. 

TeX quotes, and you seem to have just three double quotes there, so are
missing one somewhere.

> For more details on the use of the @code{Source_File_Name} pragma,
> see the sections "Using Other File Names", and "Alternative File
> Naming Schemes" in the GNAT User's Guide.

Proper @xref links, or failing that TeX quotes.

> information. This is most notably used for the output of @code{gnatchop}
> with the @samp{-r} switch, to make sure that the original unchopped

@command, @option.

> used in the @code{-gnaty} switch on the @code{gcc} or @code{gnatmake}

@option, @command, @command.

> @smallexample
> @iftex
> @leftskip=0cm
> @end iftex
> pragma Style_Checks ("k"); -- requires keywords in lower case
> pragma Style_Checks (Off); -- turn off style checks
> NULL;                      -- this will not generate an error message
> pragma Style_Checks (On);  -- turn style checks back on
> NULL;                      -- this will generate an error message
> @end smallexample

Comments in examples should be inside @r.

> @smallexample
> @iftex
> @leftskip=0cm
> @end iftex
> pragma Style_Checks ("r"); -- require consistency of identifier casing
> Arg : Integer;
> Rf1 : Integer := ARG;      -- incorrect, wrong case
> pragma Style_Checks (Off, Arg);
> Rf2 : Integer := ARG;      -- OK, no error
> @end smallexample

Likewise.

> @smallexample
> --  Example of the use of pragma Task_Name

Likewise.

> many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is
> reserved to the implementation, so that @code{Ctrl-C} can be used to

@kbd{Ctrl-C}.

> @code{Ctrl-C} will not automatically interrupt execution. However,

Likewise.

> file a-intnam.ads. This is a target dependent file that contains the

@file.

> is exactly as described for the @code{-gnatVx} compiler switch (see the

@option.

> to the use of the @code{gnatva} switch.

@option{-gnatva}, I guess.

> pragma Validity_Checks ("c"); -- validity checks for copies
> pragma Validity_Checks (Off); -- turn off validity checks
> A := B;                       -- B will not be validity checked
> pragma Validity_Checks (On);  -- turn validity checks back on
> A := C;                       -- C will be validity checked

@r.

> @smallexample
> procedure K is ...

@dots{}.

> A call to L is then expected to result in a call to K. In Ada 83, where

@code{L}, @code{K} (or you could use @var).

> it to be used for (<>) discrete formal arguments in a generic unit that

@code or @samp.

> @cindex OpenVMS
> Values from 3-10 are only relevant to Digital OpenVMS implementations.

3--10 (TeX en dash).

> @code{Ada.Exceptions} in files @file{a-except.ads,a-except.adb}

Put each file name in a separate @file.

> (@code{Fortran}, ...) applies to a multidimensional array type, then

@dots{}.

> Followed. (@code{Duration'Small} = 10**(-9)).

Either surround the expression in @code, or at least use @minus{}.  
Preferably use @math{10^{-9}} - but Texinfo bugs mean that may not work
properly.

> @code{Exception_Message}, the compiler generates one containing the location
> of the raise statement. This location has the form "file:line", where

TeX quotes.

> environment semantics as closely as is reasonable. For example, on most
> machines, it makes sense for address arithmetic to ``wrap around.''

Logical quoting - i.e., the trailing punctuation should be outside the
quotes since it is not logically part of what is quoted.

> A default (implementation-provided) storage pool for an access-to-
> constant type should not have overhead to support de-allocation of

access-to-constant (no space and split over lines).

> @cartouche
> An Ada access @var{T} parameter is passed as a ``BY REFERENCE'' data item of

If ``BY REFERENCE'' is a literal piece of COBOL code, then using @samp
would be more appropriate.

> An Ada in scalar parameter is passed as a ``BY CONTENT'' data item of

Likewise.

> Any other Ada parameter is passed as a ``BY REFERENCE'' data item of the

Likewise.

> Atomic read-modify-write operations -- e.g., test and set, compare and

TeX em dash - that is, "---" with no spaces around it.

> Standard numeric functions -- e.g., sin, log.

Likewise.

> String manipulation operations -- e.g., translate and test.

Likewise.

> Vector operations -- e.g., compare vector against thresholds.

Likewise.

> Followed by GLADE, a separately supplied PCS that can be used with
> GNAT. For information on GLADE, contact Ada Core Technologies.

The message to contact ACT is inappropriate here.  If GLADE is free
software, it can be mentioned without this reference.

> Followed by GLADE, a separately supplied PCS that can be used with
> GNAT. For information on GLADE, contact Ada Core Technologies.

Likewise.

> @code{Fine_Delta} is 2**(-63) 

As discussed above, such expressions should use @code or @math, or at
least @minus{}.

> A compilation is represented by a sequence of files presented to the
> compiler in a single invocation of the @file{gcc} command.

@command.

> provides the binder options -z and -n respectively, and in this case a

@option, @option.

> automatically). For full details on the use of these options, refer to
> the User Guide sections on Binding and Linking.

Proper @xref link.

> corresponding ali file as the input parameter to the binder.

I don't know what an ali file is, but if it is of the form "foo.ali" then
@file{.ali} may be more appropriate.

> causes two separate arguments "-labc" and "-ldef" to be passed to the

@option or @samp.

> This declaration would permit "mixed mode" arithmetic on items

TeX quotes.

> The largest Size value permitted in GNAT is 2**32-1. Since this is a

Comments above about such expressions.

>       --  Above access type intended only for interfacing purposes

@r.

>       --  ...
>    
>    begin
>       --  ...

@dots{}.

> value, and in such cases, @code{GNAT} uses an unsigned biased representation,

No @code around GNAT.

> @code{Object_Size} attribute. The phrase "is used" here means that it is

TeX quotes.

> size in bits (run the utility gnatpsta to find those values for numeric types). 

@command{gnatpsta}.

> Enumeration types and fixed-point base subtypes have 8. 16. 32 or 64

Commas rather than full stops between these numbers.

> consequence of RM 13.1(14) ("if two subtypes statically match,
> then their subtype-specific aspects are the same".)

TeX quotes.

> is allowed are for component size values in the range 1-63. The value

1--63 (TeX en dash).

> vernacular as "big endian") means that the first bit of a

TeX quotes.

> "little endian") means the opposite: the first bit is the

TeX quotes.

> The left most (most significant bit is called Control for each byte, and
> the remaing 7 bits are called V1, V2 .. V7, where V7 is the right most

If .. is a programming language literal then @code, otherwise @dots{}.

> machines, but it is indeed implemented in @code{GNAT}.

No @code around GNAT.

> independent of whether the code is compiled on a big-endial or little-endian

Typo: "big-endial" should be "big-endian".

> Packed arrays with a size up to and including 64-bits are represented

"64 bits" rather than "64-bits".  The hyphen is appropriate for the
adjective "64-bit".

> For non-primitive types, including packed arrays with a size greater than
> 64-bits, component clauses must respect the alignment requirement of the

Likewise.

> A "confirming" representation clause is one in which the values range

TeX quotes.

> positional values, (i.e. the value delivered by the  @code{Pos} attribute).
                                                     ^^ two spaces, should
                                                        be one

> convention is to use 32-bits for all enum values in C, since enum values

No hyphen.

> @cindex -gnatR switch

@option.

> For this purpose, GNAT provides the option @code{-gnatR}. If you compile

@option.

> using the switch @code{-gnatR} we obtain the following output:

@option.

> This package provides access to the command line parameters and the name
> of the current program (analogous to the use of argc and argv in C), and

@code{argc}, @code{argv}.

> This is a generic package that provides the implementation of standard
> elementary functions (such as log an trigonometric functions) for an

s/log an/log and/

> The following predefined instantiations of this package exist

Terminate sentence with colon or full stop.

> 4-bytes, so the record at index @var{K} starts at offset (@var{K} -
> 1)*4.

@minus{}.

> pressing the @code{EOT} key,

@key for keys.

> files @code{a-swuwti.ads/adb} provides similar extended @code{Wide_Text_IO}

@file.

> (The full UTF-8 scheme allows for encoding 31-bit characters as
> 6-byte sequences, but in this implementation, all UTF-8 sequences
> of four or more bytes length will raise a Constraint_Error, as
> will all illegal UTF-8 sequences.)

This should be "invalid", not "illegal"; the GNU Coding Standards reserve
"illegal" for violations of law.

Does this include over-long UTF-8 sequences (i.e., encoding a character in
more bytes than necessary), or those that would decode to the values
reserved for UTF-16 surrogates?  For security reasons it ought to - and
the manual ought to clarify this.

> @smallexample
> package Interfaces.C_Streams is
>   -- Note: the reason we do not use the types that are in
>   -- Interfaces.C is that we want to avoid dragging in the
>   -- code in this unit if possible.

@r for English text in comments in examples, here and below.  (But @code
will need using inside @r in places here.)

> extensive examples, look in the g-spipat.ads file in the library.

@file.

> @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
> @section Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
> @cindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads)

@file for file names in section headers and index entries, here and below;  
@code for literal code.

> "Computation of Cyclic Redundancy Checks via Table Look-Up", Communications

TeX quotes.

> This is a package to interface a GNAT program with a Web server via the
> Common Gateway Interface (CGI). It exports services to deal with Web

@. here (Florian Weimer's patch missed this, but the symbols "'", ")" and
"]" are transparent for the purposes of TeX's determination of the end of
a sentence).

> problems. See section "Finding memory problems with GNAT Debug Pool" in
> the GNAT User's guide.

Proper link or TeX quotes.

> encoding method. Uses definitions in
> package @code{System.Wch_Con}

Terminate sentence properly with a full stop.

> 8, 16, or 32 bits (i.e. C types signed char, short, int respectively)

@code{signed char}, etc..

> multi- dimensional array causes the array to be stored in column-major
        ^ remove this space

> instruction as described in @cite{Using and Porting GNU CC} by Richard

The manual is now called "Using and Porting the GNU Compiler Collection 
(GCC)" and should be linked to with @xref.

> The first example given in the GNU CC documentation is the C @code{asm}

Change "GNU CC" to "GCC".

> identical to what is used in GNU CC. This string must be a static

Likewise (or "GNU C" if you refer to the language rather than the
implementation).

> Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the
> key point is that each Ada task is mapped on a thread in the underlying 
> kernel. For example, in the case of VxWorks
> 
>      1 Ada task = 1 VxWorks task

I don't think you can just indent stuff like that in Texinfo - use proper
Texinfo constructs.

> useful to examine the output produced by the -gnatG flag to see the expanded

@option.

> None : constant ar1b := (others => false);      --  fully static
> None2 : constant ar_ar := (1..3 => None);       --  fully static

@r.

> with "others" cannot be used. GNAT determines the bounds for the actual

TeX quotes.

> Stub generation is fully implemented in the @code{GNAT} compiler. In addition,
> a complete compatible PCS is available as part of the @code{GLADE} system,
> a separate product available from Ada Core Technologies. When the two
> products are used in conjunction, this annex is fully implemented.

No @code around GNAT or GLADE.  Refer to free software, but not to
commercial availability.

> value of the access type to another), the default is to use a "fat pointer",

TeX quotes.

> To get around this problem, GNAT also permits the use of "thin pointers" for

Likewise.

> see appendix E of the Digital publication entitled "DEC Ada, Technical
> Overview and Comparison on DIGITAL Platforms".

Likewise.

> @include gfdl.texi

The file is called fdl.texi and is found in gcc/doc/include - which should
be included in the -I arguments to makeinfo and texi2dvi when the support
for building the manual is added to Make-lang.in.

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