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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24740 in the body.
You can then email your comments to 24740 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: a.lloyd.flanagan <at> gmail.com (A. Lloyd Flanagan)
To: bug-gnu-emacs <at> gnu.org
Subject: 26.0.50; Bad signature for alist-get in elisp manual
Date: Wed, 19 Oct 2016 13:01:51 -0400

In the elisp manual, section "Association Lists", the function alist-get
is shown with the signature:

Function: alist-get key value &optional default remove

but it should be

Function: alist-get key alist &optional default remove

index e7a739f..bacf036 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,7 +1556,7 @@ Association Lists
 @end smallexample
 @end defun
 
-@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



In GNU Emacs 26.0.50.2 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.31, cairo version 1.14.6)
 of 2016-10-17 built on wme03370.wme.owhc.net
Repository revision: 1a99d5dda2460946b1035827bd2407b5f0d8336c
Windowing system distributor 'Fedora Project', version 11.0.11804000
System Description:	Fedora release 24 (Twenty Four)

Recent messages:
Entering debugger...
Back to top level
(nil 1 . 2)
invert-alist
(2 . 1)
invert-alist
(2 . 1)
Mark set
Type C-x 1 to delete the help window.
Making completion list... [3 times]

Configured using:
 'configure --with-file-notification=gfile --with-cairo
 --with-x-toolkit=gtk2'

Configured features:
XPM JPEG TIFF GIF PNG RSVG CAIRO IMAGEMAGICK SOUND GPM DBUS GCONF
GSETTINGS NOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF
XFT ZLIB TOOLKIT_SCROLL_BARS GTK2 X11 LIBSYSTEMD

Important settings:
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  show-paren-mode: t
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  yas-global-mode: t
  yas-minor-mode: t
  form-feed-mode: t
  smartparens-global-mode: t
  smartparens-mode: t
  undo-tree-mode: t
  override-global-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  auto-fill-function: do-auto-fill
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug sendmail eieio-opt speedbar sb-image
ezimage dframe help-fns radix-tree debug misearch multi-isearch
mm-archive message rfc822 mml mml-sec epa mailabbrev gmm-utils
mailheader mm-decode mm-bodies mm-encode server paren image-file tabify
vc-git diff-mode org-element ob-sql ob-sh shell ob-scheme ob-sass
ob-ruby ob-R ob-python ob-org ob-lisp ob-js ob-css ob-clojure ob-C
cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs less-css-mode css-mode smie sgml-mode dom derived
yasnippet form-feed slime apropos hideshow pp cl flycheck-pyflakes
flycheck json map rx flx-ido flx ido smartparens undo-tree
shrink-whitespace paradox paradox-menu paradox-commit-list hydra lv
paradox-execute paradox-github paradox-core spinner org-rmail org-mhe
org-irc org-info org-gnus gnus-util rmail rmail-loaddefs mail-utils
org-docview doc-view jka-compr image-mode dired dired-loaddefs
org-bibtex bibtex org-bbdb org-w3m async projectile advice grep compile
ibuf-ext ibuffer ibuffer-loaddefs dash thingatpt edmacro kmacro
use-package diminish bind-key secret-data org org-macro org-footnote
org-pcomplete pcomplete org-list org-faces org-entities noutline outline
easy-mmode org-version ob-emacs-lisp ob ob-tangle ob-ref ob-lob ob-table
ob-exp org-src ob-keys ob-comint comint ansi-color ring ob-core ob-eval
org-compat org-macs org-loaddefs format-spec find-func cal-menu calendar
cal-loaddefs network-stream starttls url-http tls gnutls mail-parse
rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr url-gw nsm subr-x
puny url-cache url-auth url url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util mailcap epg finder-inf
kotl-loaddefs info package epg-config url-handlers url-parse auth-source
cl-seq eieio eieio-core cl-macs eieio-loaddefs password-cache url-vars
seq byte-opt gv bytecomp byte-compile cl-extra help-mode easymenu cconv
cl-loaddefs pcase cl-lib time-date mule-util tooltip eldoc electric
uniquify ediff-hook vc-hooks lisp-float-type mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list newcomment elisp-mode lisp-mode prog-mode register page
menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock
syntax facemenu font-core term/tty-colors frame cl-generic cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese charscript case-table epa-hook
jka-cmpr-hook help simple abbrev obarray minibuffer cl-preloaded nadvice
loaddefs button faces cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote dbusbind gfilenotify dynamic-setting
system-font-setting font-render-setting cairo move-toolbar gtk x-toolkit
x multi-tty make-network-process emacs)

Memory information:
((conses 16 376549 58838)
 (symbols 48 46677 0)
 (miscs 40 227 467)
 (strings 32 112733 29030)
 (string-bytes 1 4389236)
 (vectors 16 52314)
 (vector-slots 8 1656624 204295)
 (floats 8 851 557)
 (intervals 56 928 401)
 (buffers 976 22)
 (heap 1024 54005 5448))

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: a.lloyd.flanagan <at> gmail.com (A. Lloyd Flanagan)
Cc: 24740-done <at> debbugs.gnu.org
Subject: Re: bug#24740: 26.0.50; Bad signature for alist-get in elisp manual
Date: Wed, 19 Oct 2016 21:12:00 +0300

> From: a.lloyd.flanagan <at> gmail.com (A. Lloyd Flanagan)
> Date: Wed, 19 Oct 2016 13:01:51 -0400
> 
> In the elisp manual, section "Association Lists", the function alist-get
> is shown with the signature:
> 
> Function: alist-get key value &optional default remove
> 
> but it should be
> 
> Function: alist-get key alist &optional default remove

Thanks, fixed on the emacs-25 branch.

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

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

On Wed, 19 Oct 2016 21:12:00 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: a.lloyd.flanagan <at> gmail.com (A. Lloyd Flanagan)
>> Date: Wed, 19 Oct 2016 13:01:51 -0400
>> 
>> In the elisp manual, section "Association Lists", the function alist-get
>> is shown with the signature:
>> 
>> Function: alist-get key value &optional default remove
>> 
>> but it should be
>> 
>> Function: alist-get key alist &optional default remove
>
> Thanks, fixed on the emacs-25 branch.


> -@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?

Steve Berman

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

From: "A. Lloyd Flanagan" <a.lloyd.flanagan <at> gmail.com>
To: Stephen Berman <stephen.berman <at> gmx.net>, 24740 <at> debbugs.gnu.org
Cc: eliz <at> gnu.org
Subject: Re: bug#24740: 26.0.50; Bad signature for alist-get in elisp manual
Date: Thu, 20 Oct 2016 01:00:15 +0000

[Message part 1 (text/plain, inline)]

Yes, good catch.

On Wed, Oct 19, 2016, 7:39 PM Stephen Berman <stephen.berman <at> gmx.net> wrote:

> On Wed, 19 Oct 2016 21:12:00 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:
>
> >> From: a.lloyd.flanagan <at> gmail.com (A. Lloyd Flanagan)
> >> Date: Wed, 19 Oct 2016 13:01:51 -0400
> >>
> >> In the elisp manual, section "Association Lists", the function alist-get
> >> is shown with the signature:
> >>
> >> Function: alist-get key value &optional default remove
> >>
> >> but it should be
> >>
> >> Function: alist-get key alist &optional default remove
> >
> > Thanks, fixed on the emacs-25 branch.
>
>
> > -@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?
>
> Steve Berman
>
-- 
"They have computers, and they may have other weapons of mass destruction."
-- Janet Reno

[Message part 2 (text/html, inline)]

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.

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

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

On Thu, 20 Oct 2016 10:49:04 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> 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.

Ok, thanks for the clarification.  I think the distinction would be made
clearer if the definite article were omitted: "it returns just VALUE",
as it is in the subsequent sentence; the definite article makes it sound
to me more like a use than a mention.

Steve Berman

Previous Next

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