[Bug-gnupress] [DOCPATCH] Review of GCC Manual, segment 011

[Simon Law]

On Thu, Apr 24, 2003 at 11:20:09PM -0400, D F wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> I've attached a file containing the results of my review of section 
> 011. I'm now working on section 018. I hope to have it completed in 
> a couple of days.

        Thanks for your review, it was most helpful.  There is a patch
attached, with a few changes.

PowerPc changes are ignored.

> Page 193--line 45
>       more information on when long calls are and are not necessary
>       should be
>       more information on when long calls are or are not necessary

        This should probably use a "whether" construct.

> Page 193--line 47
>       This attribute allows to specify how to call a particular function on
>       should be
>       This attribute allows one to specify how to call a particular function 
> on
>       or
>       This attribute specifies how a particular function is called on

        The latter is best, I think.

> Page 194--lines 8 and 9
>       the compiler to call the function via a global pointer to the function
>       pointer that is set up by the Windows NT dll library. The pointer
>       should be
>       the compiler to reference the function via a global pointer. This global
>       pointer refers directly to the pointer to the function that is set up by
>       the Windows dll. The pointer

        I'm pretty sure that "function pointer" is a standard term, and
can be used to reduce verbiage.

> Page 195--line 32
>       Use this attributeon the M32R/D to set the addressability of an object,
>       should be
>       Use this attribute on the M32R/D to set the addressability of an object,

        I think this is merely an artifact of your anti-aliasing.  I saw
no error here.

> Page 197--paragraph 4
>       I have absolutely no idea what any of this paragraph is supposed to 
> mean.
>       Certainly, the first sentence is excessively long and needs to be 
> broken up.
>       I suggest someone who is more technically astute than am I look at this
>       paragraph.

        I have split this to the best of my ability.  It's "standards
document" style wording, and I don't think I can get it any clearer.

> Page 209--lines 46 and 47
>       For future compatability with when GCC implements ISO C99 semantics for
>       inline functions, it is best to use static inline only. (The existing 
> semantics will
>       should be
>       Since GCC is moving toward the increasing implementation of ISO C99
>       semantics in the future for inline functions, it is best to use static
>       inline only to guarantee compatability. (The existing semantics will

        I reworked this one.

Simon

Index: extend.texi
===================================================================
RCS file: /cvsroot/gcc/gcc/gcc/doc/extend.texi,v
retrieving revision 1.109.2.13
diff -u -r1.109.2.13 extend.texi
--- extend.texi 30 Apr 2003 14:16:58 -0000      1.109.2.13
+++ extend.texi 4 May 2003 18:21:13 -0000
@@ -2300,7 +2300,7 @@
 @cindex @code{malloc} attribute
 The @code{malloc} attribute is used to tell the compiler that a function
 may be treated as if it were the malloc function.  The compiler assumes
-that calls to malloc result in a pointers that cannot alias anything.
+that calls to malloc result in pointers that cannot alias anything.
 This will often improve optimization.
 
 @item alias ("@var{target}")
@@ -2352,7 +2352,7 @@
 Internal visibility is like hidden visibility, but with additional
 processor specific semantics.  Unless otherwise specified by the psABI,
 gcc defines internal visibility to mean that the function is @emph{never}
-called from another module.  Note that hidden symbols, while then cannot
+called from another module.  Note that hidden symbols, while they cannot
 be referenced directly by other modules, can be referenced indirectly via
 function pointers.  By indicating that a symbol cannot be called from
 outside the module, gcc may for instance omit the load of a PIC register
@@ -2407,12 +2407,12 @@
 both the @option{-mlongcall} switch and the @code{#pragma longcall}
 setting.
 
address@hidden/6000 and PowerPC Options}, for more information on when long
-calls are and are not necessary.
address@hidden/6000 and PowerPC Options}, for more information on whether long
+calls are necessary.
 
 @item long_call/short_call
 @cindex indirect calls on ARM
-This attribute allows to specify how to call a particular function on
+This attribute allows specifies how a particular function is called on
 address@hidden  Both attributes override the @option{-mlong-calls} (@pxref{ARM 
Options})
 command line switch and @code{#pragma long_calls} settings.  The
 @code{long_call} attribute causes the compiler to always call the
@@ -2424,7 +2424,8 @@
 @item dllimport
 @cindex functions which are imported from a dll on PowerPC Windows NT
 On the PowerPC running Windows NT, the @code{dllimport} attribute causes
-the compiler to call the function via a global pointer to the function
+the compiler to reference the function via a global pointer.  This global
+pointer refers directly to the function
 pointer that is set up by the Windows NT dll library.  The pointer name
 is formed by combining @code{__imp_} and the function name.
 
@@ -2467,9 +2468,9 @@
 Note, interrupt handlers for the H8/300, H8/300H and SH processors can
 be specified via the @code{interrupt_handler} attribute.
 
-Note, on the AVR interrupts will be enabled inside the function.
+Note, on the AVR, interrupts will be enabled inside the function.
 
-Note, for the ARM you can specify the kind of interrupt to be handled by
+Note, for the ARM, you can specify the kind of interrupt to be handled by
 adding an optional parameter to the interrupt attribute like this:
 
 @smallexample
@@ -2524,20 +2525,20 @@
 @item signal
 @cindex signal handler functions on the AVR processors
 Use this attribute on the AVR to indicate that the specified
-function is an signal handler.  The compiler will generate function
-entry and exit sequences suitable for use in an signal handler when this
-attribute is present.  Interrupts will be disabled inside function.
+function is a signal handler.  The compiler will generate function
+entry and exit sequences suitable for use in a signal handler when this
+attribute is present.  Interrupts will be disabled inside the function.
 
 @item naked
 @cindex function without a prologue/epilogue code
 Use this attribute on the ARM, AVR and IP2K ports to indicate that the
-specified function do not need prologue/epilogue sequences generated by
+specified function does not need prologue/epilogue sequences generated by
 the compiler.  It is up to the programmer to provide these sequences.
 
 @item model (@var{model-name})
 @cindex function addressability on the M32R/D
 Use this attribute on the M32R/D to set the addressability of an object,
-and the code generated for a function.
+and of the code generated for a function.
 The identifier @var{model-name} is one of @code{small}, @code{medium},
 or @code{large}, representing each of the code models.
 
@@ -2700,9 +2701,9 @@
 @c changed later by "packed" attributes.
 
 Otherwise, an attribute specifier appears as part of a declaration,
-counting declarations of unnamed parameters and type names, and relates
+counting declarations of unnamed parameters and type names.  It relates
 to that declaration (which may be nested in another declaration, for
-example in the case of a parameter declaration), or to a particular declarator
+example, parameter declarations), or to a particular declarator
 within a declaration.  Where an
 attribute specifier is applied to a parameter declared as a function or
 an array, it should apply to the function or array rather than the
@@ -2949,7 +2950,7 @@
 designs, @code{__alignof__ (double)} is 4 or even 2.
 
 Some machines never actually require alignment; they allow reference to any
-data type even at an odd addresses.  For these machines, @code{__alignof__}
+data type even at an odd address.  For these machines, @code{__alignof__}
 reports the @emph{recommended} alignment of a type.
 
 If the operand of @code{__alignof__} is an lvalue rather than a type,
@@ -3187,7 +3188,7 @@
 program.  The warning also includes the location of the declaration
 of the deprecated variable, to enable users to easily find further
 information about why the variable is deprecated, or what they should
-do instead.  Note that the warnings only occurs for uses:
+do instead.  Note that the warning only occurs for uses:
 
 @smallexample
 extern int old_var __attribute__ ((deprecated));
@@ -3365,7 +3366,7 @@
 
 @item packed
 This attribute, attached to an @code{enum}, @code{struct}, or
address@hidden type definition, specified that the minimum required memory
address@hidden type definition, specifies that the minimum required memory
 be used to represent the type.
 
 @opindex fshort-enums
@@ -3394,7 +3395,7 @@
 conversions.
 
 Second, the argument is passed to the function using the calling
-conventions of first member of the transparent union, not the calling
+conventions of the first member of the transparent union, not the calling
 conventions of the union itself.  All members of the union must have the
 same machine representation; this is necessary for this argument passing
 to work properly.
@@ -3606,8 +3607,9 @@
 to be inlined.  If any uses of the function remain, they will refer to
 the single copy in the library.
 
-For future compatibility with when GCC implements ISO C99 semantics for
-inline functions, it is best to use @code{static inline} only.  (The
+Since GCC eventually will implement ISO C99 semantics for
+inline functions, it is best to use @code{static inline} only
+to guarentee compatibility.  (The
 existing semantics will remain available when @option{-std=gnu89} is
 specified, but eventually the default will be @option{-std=gnu99} and
 that will implement the C99 semantics, though it does not do so yet.)
@@ -3679,7 +3681,7 @@
 @noindent
 Note that the symbolic operand names have no relation whatsoever to
 other C identifiers.  You may use any name you like, even those of
-existing C symbols, but must ensure that no two operands within the same
+existing C symbols, but you must ensure that no two operands within the same
 assembler construct use the same symbolic name.
 
 Output operand expressions must be lvalues; the compiler can check this.