Subject: Re: bug#24740: 26.0.50; Bad signature for alist-get in elisp manual

From: Eli Zaretskii <[email-masked]>
Date: Thu, 20 Oct 2016 10:49:04 +0300

> From: Stephen Berman <[email-masked]>
> Cc: [email-masked],  [email-masked]
> Date: Thu, 20 Oct 2016 01:39:15 +0200
> 
> > -@defun alist-get key value &optional default remove
> > +@defun alist-get key alist &optional default remove
> >  This function is like @code{assq}, but instead of returning the entire
> > -association for @var{key}, @code{(@var{key} . @var{value})}, it
> > -returns just the @var{value}.  If @var{key} is not found in
> > -@var{alist} it returns @var{default}.
> > +association for @var{key} in @var{alist},
> > +@w{@code{(@var{key} . @var{value})}}, it returns just the @var{value}.
>                                                              ^^^^^^^^^^^
> > +If @var{key} is not found in @var{alist}, it returns @var{default}.
> 
> Shouldn't the text be "it returns just the value", i.e. without the
> markup, since `value' is no longer a formal argument of the function
> signature?

@var is not only for formal arguments, it's for any symbol which
stands for something else.  That is why @var is also used in the cons
cell description; it is not because KEY and VALUE happen to appear in
the function argument list.

For example, we use @var in text such as this:

    A value of the form @code{(@var{num} . @var{expr})} stands for the
  product of the values of @var{num} and @var{expr}.

These NUM and EXPR are not formal arguments of any function.

The Texinfo manual says:

  Use the '@var' command to indicate metasyntactic variables.  A
  "metasyntactic variable" is something that stands for another piece of
  text.  For example, you should use a metasyntactic variable in the
  documentation of a function to describe the arguments that are passed to
  that function.

IOW, the function arguments use case is just one example of where @var
should be used.