bug#21709: 25.0.50; doc of :variable in `define-minor-mode'

bug#21709: 25.0.50; doc of :variable in `define-minor-mode'

[Drew Adams]

The doc is unclear - both the doc string and (elisp) `Defining Minor
Modes'.  Specifically, the part about PLACE being (GET . SET).

 PLACE can also be of the form (GET . SET), where GET is
 an expression that returns the current state, and SET is
 a function that takes one argument, the new state, and
 sets it.

 PLACE can also be a cons '(GET . SET)', where GET is an expression that
 returns the current state, and SET is a function of one argument (a
 state) that sets it.

Surely the function does not "set" a "state".  It might set the
variable to a new value (but it does not "set" the value).

What is the function argument?  A "state"?  What does that mean?
State of what?  What form does this "state" take?  What does it do?

My guess is that the doc should says something like this:

 The argument is the new variable value, which is assigned to PLACE.

Presumably, "state" should be replaced by "value" everywhere, here.
But that's just a guess.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-10-09
Bzr revision: af45926d66d303fdc4c2c3ebbc820b4a54d9e4a0
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

bug#21709: 25.0.50; doc of :variable in `define-minor-mode'

[Random832]

Drew Adams <drew.adams@oracle.com> writes:
> Surely the function does not "set" a "state".  It might set the
> variable to a new value (but it does not "set" the value).

A state could be a single variable, it could be a dozen variables, it
could be a file on the disk [which GET reads and SET writes] - the point
is to have an abstraction that doesn't care what it is.

Seems like what it really is is a "hackish" way to define a generalized
variable without actually defining one. A sort of "generalized variable
lambda" except for the fact that setf doesn't actually support it.

bug#21709: 25.0.50; doc of :variable in `define-minor-mode'

[Drew Adams]

> A state could be a single variable, it could be a dozen variables, it
> could be a file on the disk [which GET reads and SET writes] - the point
> is to have an abstraction that doesn't care what it is.

OK; right.  In that case there is still no reason to speak of a "state".
In that case, the GET sexp can do *anything* and so can the SET function.

> Seems like what it really is is a "hackish" way to define a generalized
> variable without actually defining one. A sort of "generalized variable
> lambda" except for the fact that setf doesn't actually support it.

Yup, and not made clear by the doc.

(FWIW, grepping the Emacs Lisp sources, it seems that a non-variable
PLACE is used only a few times.)

And perhaps this should be mentioned in the doc:  Using :variable prevents
`d-m-m' from defining the variable again, if it was already defined by
C code.  This idiom is used several times in the Emacs Lisp source code.
E.g.: (define-minor-mode abbrev-mode "..." :variable abbrev-mode)

bug#21709: 25.0.50; doc of :variable in `define-minor-mode'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The doc is unclear - both the doc string and (elisp) `Defining Minor
> Modes'.  Specifically, the part about PLACE being (GET . SET).
>
>  PLACE can also be of the form (GET . SET), where GET is
>  an expression that returns the current state, and SET is
>  a function that takes one argument, the new state, and
>  sets it.
>
>  PLACE can also be a cons '(GET . SET)', where GET is an expression that
>  returns the current state, and SET is a function of one argument (a
>  state) that sets it.
>
> Surely the function does not "set" a "state".  It might set the
> variable to a new value (but it does not "set" the value).
>
> What is the function argument?  A "state"?  What does that mean?
> State of what?  What form does this "state" take?  What does it do?
>
> My guess is that the doc should says something like this:
>
>  The argument is the new variable value, which is assigned to PLACE.
>
> Presumably, "state" should be replaced by "value" everywhere, here.
> But that's just a guess.

I think "state" is fine in this context, but you're right that this can
be improved.  I've altered both the doc string and the manual so be more
along your suggested "which is assigned to PLACE".

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no