Document va_copy in preference to __va_copy

["Joseph S. Myers" <joseph at codesourcery dot com>]

The glibc manual documents __va_copy, a GNU extension, rather than
va_copy, a standard C99 feature.  I propose this patch to prefer
va_copy in the documentation and only refer to __va_copy as a
secondary matter, since I don't think compatibility with compilers
before GCC 3.0 is particularly relevant to most readers of this manual
now.  (Note that nowadays the GNU Coding Standards allow relying on
C99 features.)

Tested with "make info" and "make pdf".

2012-07-20  Joseph Myers  <joseph@codesourcery.com>

	* manual/lang.texi (__va_copy): Document primarily as ISO C99
	va_copy.  Document allowing for unavailable va_copy only as
	pre-C99 compatibility.
	* manual/string.texi (Copying and Concatenation): Use va_copy
	instead of __va_copy in concat example.

diff --git a/manual/lang.texi b/manual/lang.texi
index baaccaa..8244786 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -463,28 +463,34 @@ assign the value of one variable of type @code{va_list} to another variable
 of the same type.
 
 @comment stdarg.h
+@comment ISO
+@deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
 @comment GNU
-@deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
-The @code{__va_copy} macro allows copying of objects of type
+@deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
+The @code{va_copy} macro allows copying of objects of type
 @code{va_list} even if this is not an integral type.  The argument pointer
 in @var{dest} is initialized to point to the same argument as the
 pointer in @var{src}.
 
-This macro is a GNU extension but it will hopefully also be available in
-the next update of the ISO C standard.
+This macro was added in ISO C99.  When building for strict conformance
+to ISO C90 (@samp{gcc -ansi}), it is not available.  The macro
+@code{__va_copy} is available as a GNU extension in any standards
+mode; before GCC 3.0, it was the only macro for this functionality.
 @end deftypefn
 
-If you want to use @code{__va_copy} you should always be prepared for the
+If you want to use @code{va_copy} and be portable to pre-C99 systems,
+you should always be prepared for the
 possibility that this macro will not be available.  On architectures where a
-simple assignment is invalid, hopefully @code{__va_copy} @emph{will} be available,
-so one should always write something like this:
+simple assignment is invalid, hopefully @code{va_copy} @emph{will} be available,
+so one should always write something like this if concerned about
+pre-C99 portability:
 
 @smallexample
 @{
   va_list ap, save;
   @dots{}
-#ifdef __va_copy
-  __va_copy (save, ap);
+#ifdef va_copy
+  va_copy (save, ap);
 #else
   save = ap;
 #endif
diff --git a/manual/string.texi b/manual/string.texi
index 831873b..2844bc6 100644
--- a/manual/string.texi
+++ b/manual/string.texi
@@ -824,7 +824,6 @@ to use @code{strcat}/@code{wcscat}.  A lot of time is wasted finding the
 end of the destination string so that the actual copying can start.
 This is a common example:
 
-@cindex __va_copy
 @cindex va_copy
 @smallexample
 /* @r{This function concatenates arbitrarily many strings.  The last}
@@ -838,9 +837,7 @@ concat (const char *str, @dots{})
   char *result;
 
   va_start (ap, str);
-  /* @r{Actually @code{va_copy}, but this is the name more gcc versions}
-     @r{understand.}  */
-  __va_copy (ap2, ap);
+  va_copy (ap2, ap);
 
   /* @r{Determine how much space we need.}  */
   for (s = str; s != NULL; s = va_arg (ap, const char *))

-- 
Joseph S. Myers
joseph@codesourcery.com