GNU bug report logs - #24740
26.0.50; Bad signature for alist-get in elisp manual

Previous Next

Full log

Message #19 received at 24740 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: a.lloyd.flanagan <at> gmail.com, 24740 <at> debbugs.gnu.org
Subject: Re: bug#24740: 26.0.50; Bad signature for alist-get in elisp manual
Date: Thu, 20 Oct 2016 10:49:04 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: eliz <at> gnu.org,  a.lloyd.flanagan <at> gmail.com
> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.