From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#30241: Emacs 26.0.91: "Generalized variables" are not defined. Date: Tue, 20 Mar 2018 20:51:31 +0000 Message-ID: <20180320205131.GB16673@ACM> References: <20180124200652.GA4493@ACM> <83h8r8ln7u.fsf@gnu.org> <41654c7c-2d8d-44ec-a5c4-dd12014b7a9e@default> <83o9lfk2sy.fsf@gnu.org> <20180210215841.GB4537@ACM> <83inb31pp0.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1521580098 22669 195.159.176.226 (20 Mar 2018 21:08:18 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 20 Mar 2018 21:08:18 +0000 (UTC) User-Agent: Mutt/1.7.2 (2016-11-26) Cc: 30241@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Mar 20 22:08:14 2018 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 1eyOUP-0005mw-0Q for geb-bug-gnu-emacs@m.gmane.org; Tue, 20 Mar 2018 22:08:13 +0100 Original-Received: from localhost ([::1]:51757 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eyOWP-0001Sx-Ra for geb-bug-gnu-emacs@m.gmane.org; Tue, 20 Mar 2018 17:10:17 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50763) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eyOWE-0001Qx-AQ for bug-gnu-emacs@gnu.org; Tue, 20 Mar 2018 17:10:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eyOWA-000472-61 for bug-gnu-emacs@gnu.org; Tue, 20 Mar 2018 17:10:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:36404) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eyOWA-00046q-1X for bug-gnu-emacs@gnu.org; Tue, 20 Mar 2018 17:10:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eyOW9-0006UR-RR for bug-gnu-emacs@gnu.org; Tue, 20 Mar 2018 17:10:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 20 Mar 2018 21:10:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30241 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 30241-submit@debbugs.gnu.org id=B30241.152158018724922 (code B ref 30241); Tue, 20 Mar 2018 21:10:01 +0000 Original-Received: (at 30241) by debbugs.gnu.org; 20 Mar 2018 21:09:47 +0000 Original-Received: from localhost ([127.0.0.1]:44301 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eyOVu-0006Tu-Hf for submit@debbugs.gnu.org; Tue, 20 Mar 2018 17:09:46 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:64308 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1eyOVt-0006Tm-08 for 30241@debbugs.gnu.org; Tue, 20 Mar 2018 17:09:45 -0400 Original-Received: (qmail 19339 invoked by uid 3782); 20 Mar 2018 21:09:44 -0000 Original-Received: from acm.muc.de (p548C7B48.dip0.t-ipconnect.de [84.140.123.72]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 20 Mar 2018 22:09:43 +0100 Original-Received: (qmail 23331 invoked by uid 1000); 20 Mar 2018 20:51:31 -0000 Content-Disposition: inline In-Reply-To: <83inb31pp0.fsf@gnu.org> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de 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:144468 Archived-At: Hello, Eli. Maybe there's still a chance to get this doc fix into Emacs 26. What do you say? On Sun, Feb 11, 2018 at 18:00:43 +0200, Eli Zaretskii wrote: > > Date: Sat, 10 Feb 2018 21:58:41 +0000 > > Cc: Drew Adams , 30241@debbugs.gnu.org > > From: Alan Mackenzie > > I've read https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node80.html, > > and found it clear indeed. However it was also long. After reading it, > > the Elisp sections on generalised variables make much more sense. > > This suggests that these Elisp sections contain the material, but are > > not suitable for readers who don't already understand generalised > > variables. > > In that CL page, a generalised variable is effectively defined as > > something you can use `setf' on within the first three paragraphs. In > > the elisp sections, that identification is not present in the opening > > paragraphs - there is no definition on that opening page. The first > > sub-page does not define a generalised variable as something you can use > > setf on - it merely says setf is a way to access one. But that > > definition needs to be in the top level page, and it needs to be clear > > that it _is_ a definition. > It seems strange to me to define something in terms of its uses, but > if people think this is better than the other way around, I don't > mind. > Can you propose how to change what we have now to include what you > think should be there? A proposed patch is below. > > The CL page gives a complete list of forms setf will work with. The > > elisp page merely gives a list, without it being clear whether that list > > is complete or not. > It's supposed to be a complete list, but if someone knows of other > forms, let them speak up. OK, I've made this clear in the patch. A quick summary of what I've changed: (i) a GV is defined as something `setf' can be used to store into. (ii) I've removed the insinuation that hackers would have difficulty remembering two functions (a get and a set) rather than just one. (iii) I've made clear that the list of GVs in the page is complete. (iv) I've removed the suggestion that setf has superseded, or is in the process of superseding, setq. (v) I've made minor corrections to the English. diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index e025d3fd10..355cf5a09a 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -2316,11 +2316,12 @@ Generalized Variables @cindex generalized variable @cindex place form -A @dfn{generalized variable} or @dfn{place form} is one of the many places -in Lisp memory where values can be stored. The simplest place form is -a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements -of arrays, properties of symbols, and many other locations are also -places where Lisp values are stored. +A @dfn{generalized variable} or @dfn{place form} is one of the many +places in Lisp memory where values can be stored using the @code{setf} +macro (@pxref{Setting Generalized Variables}). The simplest place +form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of +lists, elements of arrays, properties of symbols, and many other +locations are also places where Lisp values get stored. Generalized variables are analogous to lvalues in the C language, where @samp{x = a[i]} gets an element from an array @@ -2341,8 +2342,8 @@ Setting Generalized Variables accepts arbitrary place forms on the left side rather than just symbols. For example, @code{(setf (car a) b)} sets the car of @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}, -but without having to remember two separate functions for setting and -accessing every type of place. +but without you having to use two separate functions for setting and +accessing this type of place. @defmac setf [place form]@dots{} This macro evaluates @var{form} and stores it in @var{place}, which @@ -2352,18 +2353,19 @@ Setting Generalized Variables @var{form}. @end defmac -The following Lisp forms will work as generalized variables, and -so may appear in the @var{place} argument of @code{setf}: +The following Lisp forms are the forms in Emacs that will work as +generalized variables, and so may appear in the @var{place} argument +of @code{setf}: @itemize @item -A symbol naming a variable. In other words, @code{(setf x y)} is -exactly equivalent to @code{(setq x y)}, and @code{setq} itself is -strictly speaking redundant given that @code{setf} exists. Many -programmers continue to prefer @code{setq} for setting simple -variables, though, purely for stylistic or historical reasons. -The macro @code{(setf x y)} actually expands to @code{(setq x y)}, -so there is no performance penalty for using it in compiled code. +A symbol. In other words, @code{(setf x y)} is exactly equivalent to +@code{(setq x y)}, and @code{setq} itself is strictly speaking +redundant given that @code{setf} exists. Most programmers will +continue to prefer @code{setq} for setting simple variables, though, +for stylistic and historical reasons. The macro @code{(setf x y)} +actually expands to @code{(setq x y)}, so there is no performance +penalty for using it in compiled code. @item A call to any of the following standard Lisp functions: > Thanks. -- Alan Mackenzie (Nuremberg, Germany).