Re: [Emacs-diffs] emacs-26 4ab4551: Firm up documentation of generalized variables

Re: [Emacs-diffs] emacs-26 4ab4551: Firm up documentation of generalized variables

[Stefan Monnier]

>     * doc/lispref/variables.texi (Generalized Variables)
>     (Setting Generalized Variables): Define a generalized variable as something
>     setf can write to.  Remove the insinuation that hackers have poor memories.
>     State explicitly that the list of GVs given is complete.  Remove the
>     suggestion that `setf' has superseded, or is in the process of superseding,

Thanks, it's indeed more clear now.
But note that the list is not "complete".


        Stefan

Re: [Emacs-diffs] emacs-26 4ab4551: Firm up documentation of generalized variables

[Alan Mackenzie]

Hello, Stefan.

On Wed, Mar 21, 2018 at 15:56:51 -0400, Stefan Monnier wrote:
> >     * doc/lispref/variables.texi (Generalized Variables)
> >     (Setting Generalized Variables): Define a generalized variable as something
> >     setf can write to.  Remove the insinuation that hackers have poor memories.
> >     State explicitly that the list of GVs given is complete.  Remove the
> >     suggestion that `setf' has superseded, or is in the process of superseding,

> Thanks, it's indeed more clear now.
> But note that the list is not "complete".

What the paragraph I modified actually says on this point is:

    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}:

I take it this isn't quite accurate.  How is it inaccurate?

Is it (i) because there are more GVs in the cl-*.el files?  Or (ii)
because users can create their own GVs?  Or (iii) <something else>?

Depending on the answer, I suggest one of the following corrections:

    The following Lisp forms are the forms in standard Emacs that will
    work as generalized variables, and so may appear in the PLACE
    argument of `setf'.  You can load more such forms from the file
    xxxx.el.

    The following Lisp forms are the forms in standard Emacs that will
    work as generalized variables, and so may appear in the PLACE
    argument of `setf'.  You can also create your own generalized
    variables (see Adding Generalized Variables).

It would be nice to fix this.  What do you think?

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [Emacs-diffs] emacs-26 4ab4551: Firm up documentation of generalized variables

[Stefan Monnier]

>     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}:
>
> I take it this isn't quite accurate.  How is it inaccurate?

While it doesn't say so explicitly it gives the impression of
being exhaustive.  I'm not sure it's a big deal, tho, since the rest of
the doc explains how to add more forms, hence clarifies the fact that
it's indeed not exhaustive.

> Is it (i) because there are more GVs in the cl-*.el files?  Or (ii)
> because users can create their own GVs?  Or (iii) <something else>?

I guess a mix of the two (e.g. cl-defstruct creates more, and some of
the preloaded files use cl-defstruct, so even the core predefines more
places than the ones listed).

Similarly, accessors defined using `defmacro` (e.g. (defmacro
mything-secondfield (x) `(cadr ,x))) will also work as places, which
makes yet more places available.

> It would be nice to fix this.  What do you think?

I have the impression it's going to be difficult to keep this list
exhaustive, so we might just add a "catch all" case which refers to
a vague notion of "accessor" maybe.

Or maybe just leave it as is.


        Stefan