Patch for ANSI references in manual

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

This patch updates some manuals to refer to ISO C consistently
(instead of ANSI C) and cover -std better when referring to -ansi.  It
passes "make info" and "make dvi".  OK to commit?

2001-01-12  Joseph S. Myers  <jsm28@cam.ac.uk>

	* cpp.texi, extend.texi, gcc.texi, install.texi, invoke.texi,
	tm.texi: Consistently refer to ISO C instead of ANSI C.  Refer to
	-std options alongside references to -ansi.  Update some
	documentation for C99.
	* cpp.1: Regenerate.

diff -ruN gcc.orig/cpp.texi gcc/cpp.texi
--- gcc.orig/cpp.texi	Tue Jan  9 17:41:39 2001
+++ gcc/cpp.texi	Fri Jan 12 12:06:19 2001
@@ -1156,8 +1156,9 @@

 @item __STRICT_ANSI__
 @findex __STRICT_ANSI__
-GNU C defines this macro if and only if the @samp{-ansi} switch was
-specified when GNU C was invoked.  Its definition is the null string.
+GNU C defines this macro if and only if the @option{-ansi} switch, or a
+@option{-std} switch specifying strict conformance to some version of ISO C,
+was specified when GNU C was invoked.  Its definition is the null string.
 This macro exists primarily to direct certain GNU header files not to
 define certain traditional Unix constructs which are incompatible with
 ISO C@.
diff -ruN gcc.orig/extend.texi gcc/extend.texi
--- gcc.orig/extend.texi	Mon Jan  8 18:16:17 2001
+++ gcc/extend.texi	Fri Jan 12 11:51:04 2001
@@ -7,7 +7,7 @@
 @cindex extensions, C language
 @cindex C language extensions

-GNU C provides several language features not found in ANSI standard C.
+GNU C provides several language features not found in ISO standard C.
 (The @samp{-pedantic} option directs GNU CC to print a warning message if
 any of these features is used.)  To test for the availability of these
 features in conditional compilation, check for a predefined macro
@@ -17,6 +17,13 @@
 also available in C++.  @xref{C++ Extensions,,Extensions to the
 C++ Language}, for extensions that apply @emph{only} to C++.

+@c FIXME: document clearly which features are in ISO C99, but also
+@c accepted as extensions for -std=gnu89 and possibly for C++.
+@c See PR other/930.
+
+@c FIXME: the documentation for preprocessor extensions here is out of
+@c date.  See PR other/928.
+
 @c The only difference between the two versions of this menu is that the
 @c version for clear INTERNALS has an extra node, "Constraints" (which
 @c appears in a separate chapter in the other version of the manual).
@@ -594,7 +601,7 @@
 @noindent
 Here the type described is that of pointers to @code{int}.

-If you are writing a header file that must work when included in ANSI C
+If you are writing a header file that must work when included in ISO C
 programs, write @code{__typeof__} instead of @code{typeof}.
 @xref{Alternate Keywords}.

@@ -1936,7 +1943,7 @@
 @cindex old-style function definitions
 @cindex promotion of formal parameters

-GNU C extends ANSI C to allow a function prototype to override a later
+GNU C extends ISO C to allow a function prototype to override a later
 old-style non-prototype definition.  Consider the following example:

 @example
@@ -1959,13 +1966,13 @@
 @}
 @end example

-Suppose the type @code{uid_t} happens to be @code{short}.  ANSI C does
+Suppose the type @code{uid_t} happens to be @code{short}.  ISO C does
 not allow this example, because subword arguments in old-style
 non-prototype definitions are promoted.  Therefore in this example the
 function definition's argument is really an @code{int}, which does not
 match the prototype argument type of @code{short}.

-This restriction of ANSI C makes it hard to write code that is portable
+This restriction of ISO C makes it hard to write code that is portable
 to traditional C compilers, because the programmer does not know
 whether the @code{uid_t} type is @code{short}, @code{int}, or
 @code{long}.  Therefore, in cases like these GNU C allows a prototype
@@ -1998,7 +2005,8 @@
 continue until the end of the line.  Many other C implementations allow
 such comments, and they are likely to be in a future C standard.
 However, C++ style comments are not recognized if you specify
-@w{@samp{-ansi}} or @w{@samp{-traditional}}, since they are incompatible
+@w{@samp{-ansi}}, a @option{-std} option specifying a version of ISO C
+before C99, or @w{@samp{-traditional}}, since they are incompatible
 with traditional constructs like @code{dividend//*comment*/divisor}.

 @node Dollar Signs
@@ -2340,7 +2348,7 @@
 another, thus improving run-time efficiency.

 Note that the alignment of any given @code{struct} or @code{union} type
-is required by the ANSI C standard to be at least a perfect multiple of
+is required by the ISO C standard to be at least a perfect multiple of
 the lowest common multiple of the alignments of all of the members of
 the @code{struct} or @code{union} in question.  This means that you @emph{can}
 effectively adjust the alignment of a @code{struct} or @code{union}
@@ -2516,7 +2524,7 @@
 @}
 @end example

-(If you are writing a header file to be included in ANSI C programs, write
+(If you are writing a header file to be included in ISO C programs, write
 @code{__inline__} instead of @code{inline}.  @xref{Alternate Keywords}.)
 You can also make all ``simple enough'' functions inline with the option
 @samp{-finline-functions}.
@@ -2844,7 +2852,7 @@
 an assembler instruction access to the condition code left by previous
 instructions.

-If you are writing a header file that should be includable in ANSI C
+If you are writing a header file that should be includable in ISO C
 programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
 Keywords}.

@@ -3169,15 +3177,20 @@
 @cindex alternate keywords
 @cindex keywords, alternate

-The option @samp{-traditional} disables certain keywords; @samp{-ansi}
-disables certain others.  This causes trouble when you want to use GNU C
-extensions, or ANSI C features, in a general-purpose header file that
-should be usable by all programs, including ANSI C programs and traditional
-ones.  The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
-used since they won't work in a program compiled with @samp{-ansi}, while
-the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
-and @code{inline} won't work in a program compiled with
-@samp{-traditional}.@refill
+The option @option{-traditional} disables certain keywords;
+@option{-ansi} and the various @option{-std} options disable certain
+others.  This causes trouble when you want to use GNU C extensions, or
+ISO C features, in a general-purpose header file that should be usable
+by all programs, including ISO C programs and traditional ones.  The
+keywords @code{asm}, @code{typeof} and @code{inline} cannot be used
+since they won't work in a program compiled with @option{-ansi}
+(although @code{inline} can be used in a program compiled with
+@option{-std=c99}), while the keywords @code{const}, @code{volatile},
+@code{signed}, @code{typeof} and @code{inline} won't work in a program
+compiled with @option{-traditional}.  The ISO C99 keyword
+@code{restrict} is only available when @option{-std=gnu99} (which will
+eventually be the default) or @option{-std=c99} (or the equivalent
+@option{-std=iso9899:1999}) is used.@refill

 The way to solve these problems is to put @samp{__} at the beginning and
 end of each problematical keyword.  For example, use @code{__asm__}
diff -ruN gcc.orig/gcc.texi gcc/gcc.texi
--- gcc.orig/gcc.texi	Wed Jan 10 10:50:45 2001
+++ gcc/gcc.texi	Fri Jan 12 11:53:13 2001
@@ -2192,7 +2192,8 @@
 for pragmatic reasons, not as a requirement.

 GCC normally defines @code{__STDC__} to be 1, and in addition
-defines @code{__STRICT_ANSI__} if you specify the @samp{-ansi} option.
+defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
+or a @option{-std} option for strict conformance to some version of ISO C.
 On some hosts, system include files use a different convention, where
 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
 conformance to the C Standard.  GCC follows the host convention when
diff -ruN gcc.orig/install.texi gcc/install.texi
--- gcc.orig/install.texi	Fri Jan 12 09:45:43 2001
+++ gcc/install.texi	Fri Jan 12 11:53:22 2001
@@ -2267,7 +2267,7 @@
 @code{fixincludes} on the header files in @file{$(tooldir)/include}.
 (If the cross compilation header files need to be fixed, they must be
 installed before GNU CC is built.  If the cross compilation header files
-are already suitable for ANSI C and GNU CC, nothing special need be
+are already suitable for ISO C and GNU CC, nothing special need be
 done).

 @code{GPLUSPLUS_INCLUDE_DIR} means the same thing for native and cross.  It
diff -ruN gcc.orig/invoke.texi gcc/invoke.texi
--- gcc.orig/invoke.texi	Fri Jan 12 00:27:29 2001
+++ gcc/invoke.texi	Fri Jan 12 12:02:36 2001
@@ -908,6 +908,11 @@
 previous C standards.  For example, you may use @code{__restrict__} even
 when @code{-std=c99} is not specified.

+The @option{-std} options specifying some version of ISO C have the same
+effects as @option{-ansi}, except that features that were not in ISO C89
+but are in the specified version (for example, @samp{//} comments and
+the @code{inline} keyword in ISO C99) are not disabled.
+
 @xref{Standards,,Language Standards Supported by GCC}, for details of
 these standard versions.

@@ -919,15 +924,19 @@

 In C++, this switch only affects the @code{typeof} keyword, since
 @code{asm} and @code{inline} are standard keywords.  You may want to
-use the @samp{-fno-gnu-keywords} flag instead, which has the same effect.
+use the @samp{-fno-gnu-keywords} flag instead, which has the same
+effect.  In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
+switch only affects the @code{asm} and @code{typeof} keywords, since
+@code{inline} is a standard keyword in ISO C99.

 @item -fno-builtin
 @cindex builtin functions
 Don't recognize builtin functions that do not begin with
 @samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
 functions provided by GNU CC}, for details of the functions affected,
-including those which are not builtin functions when @samp{-ansi} is
-used because they do not have an ISO standard meaning.
+including those which are not builtin functions when @option{-ansi} or
+@option{-std} options for strict ISO C conformance are used because they
+do not have an ISO standard meaning.

 GCC normally generates special code to handle certain builtin functions
 more efficiently; for instance, calls to @code{alloca} may become single
@@ -960,7 +969,8 @@

 @item -trigraphs
 Support ISO C trigraphs.  You don't want to know about this
-brain-damage.  The @samp{-ansi} option implies @samp{-trigraphs}.
+brain-damage.  The @option{-ansi} option (and @option{-std} options for
+strict ISO C conformance) implies @option{-trigraphs}.

 @cindex traditional C language
 @cindex C language, traditional
@@ -1559,7 +1569,8 @@
 version of the ISO C standard specified by any @samp{-std} option used.

 Valid ISO C and ISO C++ programs should compile properly with or without
-this option (though a rare few will require @samp{-ansi}).  However,
+this option (though a rare few will require @option{-ansi} or a
+@option{-std} option specifying the required version of ISO C).  However,
 without this option, certain GNU extensions and traditional C and C++
 features are supported as well.  With this option, they are rejected.

diff -ruN gcc.orig/tm.texi gcc/tm.texi
--- gcc.orig/tm.texi	Thu Jan 11 00:07:20 2001
+++ gcc/tm.texi	Fri Jan 12 12:04:38 2001
@@ -547,13 +547,14 @@
 @item CPP_PREDEFINES
 Define this to be a string constant containing @samp{-D} options to
 define the predefined macros that identify this machine and system.
-These macros will be predefined unless the @samp{-ansi} option is
-specified.
+These macros will be predefined unless the @option{-ansi} option (or a
+@option{-std} option for strict ISO C conformance) is specified.

 In addition, a parallel set of macros are predefined, whose names are
 made by appending @samp{__} at the beginning and at the end.  These
-@samp{__} macros are permitted by the ANSI standard, so they are
-predefined regardless of whether @samp{-ansi} is specified.
+@samp{__} macros are permitted by the ISO standard, so they are
+predefined regardless of whether @option{-ansi} or a @option{-std} option
+is specified.

 For example, on the Sun, one can use the following value:

@@ -3001,7 +3002,7 @@
 argument is also stored on the stack.

 @cindex @file{stdarg.h} and register arguments
-The usual way to make the ANSI library @file{stdarg.h} work on a machine
+The usual way to make the ISO library @file{stdarg.h} work on a machine
 where some arguments are usually passed in registers, is to cause
 nameless arguments to be passed on the stack instead.  This is done
 by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.
@@ -3900,10 +3901,10 @@
 varargs, and the two machine independent header files must have
 conditionals to include it.

-ANSI @file{stdarg.h} differs from traditional @file{varargs.h} mainly in
+ISO @file{stdarg.h} differs from traditional @file{varargs.h} mainly in
 the calling convention for @code{va_start}.  The traditional
 implementation takes just one argument, which is the variable in which
-to store the argument pointer.  The ANSI implementation of
+to store the argument pointer.  The ISO implementation of
 @code{va_start} takes an additional second argument.  The user is
 supposed to write the last named argument of the function here.

@@ -3915,7 +3916,7 @@
 @findex __builtin_saveregs
 @item __builtin_saveregs ()
 Use this built-in function to save the argument registers in memory so
-that the varargs mechanism can access them.  Both ANSI and traditional
+that the varargs mechanism can access them.  Both ISO and traditional
 versions of @code{va_start} must use @code{__builtin_saveregs}, unless
 you use @code{SETUP_INCOMING_VARARGS} (see below) instead.

@@ -4345,8 +4346,8 @@
 @cindex @code{bzero}, implicit usage
 @cindex @code{memset}, implicit usage
 @item TARGET_MEM_FUNCTIONS
-Define this macro if GCC should generate calls to the System V
-(and ANSI C) library functions @code{memcpy} and @code{memset}
+Define this macro if GCC should generate calls to the ISO C
+(and System V) library functions @code{memcpy} and @code{memset}
 rather than the BSD functions @code{bcopy} and @code{bzero}.

 @findex LIBGCC_NEEDS_DOUBLE
@@ -8159,7 +8160,7 @@
 @item NEED_ATEXIT
 @findex NEED_ATEXIT
 Define this if the target system lacks the function @code{atexit}
-from the ANSI C standard.  If this macro is defined, a default definition
+from the ISO C standard.  If this macro is defined, a default definition
 will be provided to support C++.  If @code{ON_EXIT} is not defined,
 a default @code{exit} function will also be provided.


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