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

[Alan Mackenzie]

Hello, Eli.

Sorry about the long delay.

On Sat, Jan 27, 2018 at 12:34:53 +0200, Eli Zaretskii wrote:
> > Date: Fri, 26 Jan 2018 08:15:32 -0800 (PST)
> > From: Drew Adams <drew.adams@oracle.com>
> > Cc: acm@muc.de, 30241@debbugs.gnu.org

[ .... ]

> > I think you'll see a difference - it is, IMO, "significantly
> > different".

> Actually, no, I didn't.  I do see some additional explanations that
> might have helped Alan understand the issue, but nothing
> "significant".  So much so that I doubt Alan will find the CL docs
> helpful after disliking our docs of the same subject, as he did, based
> on his original bug report.  Of course, it's possible that I'm missing
> something here.

> Therefore, I invite Alan (and anyone else who'd like to chime in) to
> please compare the CL docs on this matter with ours, and tell what
> parts of the former made the issue "fall into place" (pun intended)
> wrt this topic, where our docs don't.  Bonus points for proposing
> patches for the relevant parts of the ELisp manual, to make this
> subject's documentation "significantly" better.

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.

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.

> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).