bug#30241: Emacs 26.0.91: "Generalized variables" are not defined.

[Alan Mackenzie]

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 <drew.adams@oracle.com>, 30241@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

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