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

[Drew Adams <drew.adams@oracle.com>]

> Emacs 25.3, Emacs 26.0.91 elisp manual.
> 
> In enough places in emacs, we find terms like "generalized variable"
> "place form", and "place" being used.  These terms are not defined in
> the Elisp manual, or any place where they are used.  This is a bug.
> 
> There is a page in elisp which purports to define "generalized
> variable", but rather than defining the term, it talks vaguely around
> it, saying it is "one of the many places in Lisp memory where values can
> be stored".  Does this mean it is different from the other such places?
> If so, how does it differ.  WHAT IS IT????
> 
> The elisp page then goes on to give examples of "generalized variables",
> never defining the term.  It gives no criterion by which the reader can
> determine whether some random object is a generalized variable or not.
> 
> I want to know whether a function is a "generalized variable".  After a
> long time trying to find out, I still don't know.  I've been trying for
> over an hour to use add-function, with forms like
> 
>     (add-function :before sit-for (lambda () (acm-backtrace 5)))
>     (add-function :before 'sit-for (....))
>     (add-function :before #'sit-for (.....))
>     (add-function :before (symbol-function 'sit-for) (....))
> 
> , and got nothing but unhelpful error messages back, such as
> 
>     Symbol's value as variable is void: sit-for
> 
> .  The documentation of add-function is likewise vague and unhelpful.
> The various inflections of "sit-for" above are at a place in the
> add-function form where a "generalized variable" is needed.  Is a
> function a generalized variable or not?

Hear, hear.

This is a more general problem, for all of our Common Lisp
emulation or Cl-inspired stuff.  (Not that the Emacs
implementation of generalized vars actually emulates what
Common Lisp has for generalized vars.)

When Emacs has something more or less borrowed or inspired
from Common Lisp, the Emacs doc explaining it (e.g. the
concepts) is sometimes somewhat paltry.  In such cases, you
it can help to (1) know that Emacs was inspired by Common
Lisp for that construct and (2) consult the Common Lisp doc.

To learn about generalized variables I think you need to
consult the Common Lisp doc, which is quite clear about it:

https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node80.html

"The concept of variables named by symbols can be generalized to
any storage location that can remember one piece of data, no
matter how that location is named. Examples of such storage
locations are the car and cdr of a cons, elements of an array,
and components of a structure."

When you hear "generalized variable" just think `setf'.

For Emacs, we could conceivably have many more generalized
vars than we have now.  We might make it possible to use
`setf' for functions like these, for instance: `point',
`selected-* (*=...), `point-min|max', `current-*', ...

Not that we need that, but it could sometimes be useful.

In most cases it just provides a uniform way to change
something.  E.g., (setf (current-local-map) my-map)
instead of (use-local-map my-map).  The old Emacs update
functions are often simpler, but using `setf' means you
don't need to know the setter/update function; you just
need to know the getter/access function.