unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
From: Eli Zaretskii <eliz@gnu.org>
To: Stephen Berman <stephen.berman@gmx.net>
Cc: a.lloyd.flanagan@gmail.com, 24740@debbugs.gnu.org
Subject: bug#24740: 26.0.50; Bad signature for alist-get in elisp manual
Date: Thu, 20 Oct 2016 10:49:04 +0300	[thread overview]
Message-ID: <83shrrtq8f.fsf@gnu.org> (raw)
In-Reply-To: <87funrq57g.fsf@gmx.net> (message from Stephen Berman on Thu, 20 Oct 2016 01:39:15 +0200)

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





  parent reply	other threads:[~2016-10-20  7:49 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-10-19 17:01 bug#24740: 26.0.50; Bad signature for alist-get in elisp manual A. Lloyd Flanagan
2016-10-19 18:12 ` Eli Zaretskii
2016-10-19 23:39   ` Stephen Berman
2016-10-20  1:00     ` A. Lloyd Flanagan
2016-10-20  7:49     ` Eli Zaretskii [this message]
2016-10-20  8:10       ` Stephen Berman

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=83shrrtq8f.fsf@gnu.org \
    --to=eliz@gnu.org \
    --cc=24740@debbugs.gnu.org \
    --cc=a.lloyd.flanagan@gmail.com \
    --cc=stephen.berman@gmx.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).