Ellipsis in varadic macro definitions

[Jonathan Wakely]

On Mon, 3 Aug 2020 at 11:28, Florian Weimer wrote:
>
> * Jonathan Wakely via Gcc:
>
> > On Sun, 2 Aug 2020 at 15:49, Philip R Brenan via Gcc <gcc@gcc.gnu.org> wrote:
> >>
> >> Hi *GCC*:
> >>
> >> On page:
> >>
> >> https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html#Variadic-Macros
> >>
> >> you say:
> >>
> >> #define eprintf(args…) fprintf (stderr, args)
> >>
> >> but do you in fact mean:
> >>
> >> #define eprintf(args...) fprintf (stderr, args)
> >>
> >> The first variant produces:
> >>
> >> error: expected ',' or ')', found "…"
> >>
> >>  the second variant works well using GCC10.2 on Kubuntu 18.04.
> >
> > Yes, the texinfo source uses @dots which gets turned into … in
> > the HTML, which isn't necessarily displayed as three separate dots in
> > the browser. I don't know why @dots is used rather than ...
>
> It was introduced with:
>
> commit 1c5dd43ff7c78bbdba5e89a6cb16a3e50e1abff9
> Author: Zack Weinberg <zackw@stanford.edu>
> Date:   Fri Jun 15 17:57:48 2001 +0000
>
>     cpp.texi: Formatting corrections.
>
>     * doc/cpp.texi: Formatting corrections.
>     Correct buggy example of use of __GNUC__ etc.
>     Clarify $ in identifiers.
>     * doc/cpp.1: Regenerate.
>
>     From-SVN: r43404
>
> Some of these changes were clearly correct, but the ... C token should
> have not been changed.  Looks like a simple oversight to me.

Thanks for the archaeology, Florian.

Here's a patch to replace those inappropriate @dots macros with the
literal ... token.

Tested by building the docs and inspecting the .info and .html output.

OK for trunk?
-------------- next part --------------
commit 81034f739112019f29c62a704d0920e9894add6f
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Mon Aug 3 12:47:58 2020

    cpp: Do not use @dots for ... tokens in code examples
    
    This prevents a ... token in code examples from being turned into a
    single HORIZONTAL ELLIPSIS glyph (e.g. via the HTML … entity).
    
    gcc/ChangeLog:
    
            * doc/cpp.texi (Variadic Macros): Use the exact ... token in
            code examples.

diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi
index 8c3dfcc708a..33f876ab706 100644
--- a/gcc/doc/cpp.texi
+++ b/gcc/doc/cpp.texi
@@ -1631,7 +1631,7 @@ a function can.  The syntax for defining the macro is similar to that of
 a function.  Here is an example:
 
 @smallexample
-#define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__)
+#define eprintf(...) fprintf (stderr, __VA_ARGS__)
 @end smallexample
 
 This kind of macro is called @dfn{variadic}.  When the macro is invoked,
@@ -1655,11 +1655,11 @@ below for an important special case for @samp{##}.)
 If your macro is complicated, you may want a more descriptive name for
 the variable argument than @code{@w{__VA_ARGS__}}.  CPP permits
 this, as an extension.  You may write an argument name immediately
-before the @samp{@dots{}}; that name is used for the variable argument.
+before the @samp{...}; that name is used for the variable argument.
 The @code{eprintf} macro above could be written
 
 @smallexample
-#define eprintf(args@dots{}) fprintf (stderr, args)
+#define eprintf(args...) fprintf (stderr, args)
 @end smallexample
 
 @noindent
@@ -1670,7 +1670,7 @@ You can have named arguments as well as variable arguments in a variadic
 macro.  We could define @code{eprintf} like this, instead:
 
 @smallexample
-#define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__)
+#define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
 @end smallexample
 
 @noindent
@@ -1709,7 +1709,7 @@ invocation expands to its argument; but if the variable argument does
 not have any tokens, the @code{@w{__VA_OPT__}} expands to nothing:
 
 @smallexample
-#define eprintf(format, @dots{}) \
+#define eprintf(format, ...) \
   fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__)
 @end smallexample
 
@@ -1722,7 +1722,7 @@ the introduction of @code{@w{__VA_OPT__}}, this extension remains
 supported in GNU CPP, for backward compatibility.  If you write
 
 @smallexample
-#define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__)
+#define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
 @end smallexample
 
 @noindent
@@ -1758,7 +1758,7 @@ replacement list of a variadic macro.
 Variadic macros became a standard part of the C language with C99.  
 GNU CPP previously supported them
 with a named variable argument
-(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}), which
+(@samp{args...}, not @samp{...} and @code{@w{__VA_ARGS__}}), which
 is still supported for backward compatibility.
 
 @node Predefined Macros