doc bug in explanation of reference commands

[Bruno Haible]

Hi,

The texinfo 4.11 manual explains the arguments of references as follows:

  The five possible arguments for a cross reference are:

  1. The node or anchor name (required).  This is the location to which
     the cross reference takes you.  In a printed document, the
     location of the node provides the page reference only for
     references within the same document.

  2. The cross reference name for the Info reference, if it is to be
     different from the node name.  If you include this argument, it
     becomes the first part of the cross reference.  It is usually
     omitted.

  3. A topic description or section name.  Often, this is the title of
     the section.  This is used as the name of the reference in the
     printed manual.  If omitted, the node name is used.

  ...

This suggests that the default value for the second argument is the node
name (= first argument). But when I try this input

===================================================
@ref{Variable Size Automatic,,,libc},

@ref{Variable Size Automatic,Arg2,,libc},

@ref{Variable Size Automatic,,Arg3,libc},

@ref{Variable Size Automatic,Arg2,Arg3,libc},
===================================================

with makeinfo, the resulting .info file contains this:

===================================================
   *note Variable Size Automatic: (libc)Variable Size Automatic,

   *note Arg2: (libc)Variable Size Automatic,

   *note Arg3: (libc)Variable Size Automatic,

   *note Arg2: (libc)Variable Size Automatic,
===================================================

Note the third line. It means that the default of the second argument is the
third argument, if given, otherwise the first argument. The doc of item 2
is therefore incorrect; it will be more correct like this:

  2. The cross reference name for the Info reference, if it is to be
     different from the node name or the topic description.  If you
     include this argument, it becomes the first part of the cross reference.
     It is usually omitted; then the topic description (third argument) is
     used if it was specified; if that was omitted as well, the node name
     is used.

Bruno