From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#24740: 26.0.50; Bad signature for alist-get in elisp manual Date: Thu, 20 Oct 2016 10:49:04 +0300 Message-ID: <83shrrtq8f.fsf@gnu.org> References: <87k2d4xog0.fsf@wme03370.wme.owhc.net> <83d1iwus27.fsf@gnu.org> <87funrq57g.fsf@gmx.net> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1476949949 26982 195.159.176.226 (20 Oct 2016 07:52:29 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 20 Oct 2016 07:52:29 +0000 (UTC) Cc: a.lloyd.flanagan@gmail.com, 24740@debbugs.gnu.org To: Stephen Berman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 20 09:52:24 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bx88w-0003jt-M8 for geb-bug-gnu-emacs@m.gmane.org; Thu, 20 Oct 2016 09:52:02 +0200 Original-Received: from localhost ([::1]:52987 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bx88y-0000jT-Td for geb-bug-gnu-emacs@m.gmane.org; Thu, 20 Oct 2016 03:52:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52204) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bx875-0007nE-JG for bug-gnu-emacs@gnu.org; Thu, 20 Oct 2016 03:50:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bx870-0002EI-K3 for bug-gnu-emacs@gnu.org; Thu, 20 Oct 2016 03:50:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:34111) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1bx870-0002E5-Gr for bug-gnu-emacs@gnu.org; Thu, 20 Oct 2016 03:50:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bx870-0001S0-8Q for bug-gnu-emacs@gnu.org; Thu, 20 Oct 2016 03:50:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 20 Oct 2016 07:50:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24740 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24740-submit@debbugs.gnu.org id=B24740.14769497695532 (code B ref 24740); Thu, 20 Oct 2016 07:50:02 +0000 Original-Received: (at 24740) by debbugs.gnu.org; 20 Oct 2016 07:49:29 +0000 Original-Received: from localhost ([127.0.0.1]:40301 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bx86S-0001R9-GX for submit@debbugs.gnu.org; Thu, 20 Oct 2016 03:49:29 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:60927) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bx86Q-0001Qt-NE for 24740@debbugs.gnu.org; Thu, 20 Oct 2016 03:49:27 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bx86K-0001vo-PQ for 24740@debbugs.gnu.org; Thu, 20 Oct 2016 03:49:21 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:40112) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bx86H-0001sf-1a; Thu, 20 Oct 2016 03:49:17 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4714 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bx86G-0001l3-5t; Thu, 20 Oct 2016 03:49:16 -0400 In-reply-to: <87funrq57g.fsf@gmx.net> (message from Stephen Berman on Thu, 20 Oct 2016 01:39:15 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:124716 Archived-At: > From: Stephen Berman > 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.