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

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Mon, 19 Oct 2015 15:16:01 UTC

Severity: wishlist

Merged with 14875

Found in versions 24.3.50, 25.0.50

Fixed in version 28.1

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21709 in the body.
You can then email your comments to 21709 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#21709; Package emacs. (Mon, 19 Oct 2015 15:16:01 GMT) Full text and rfc822 format available.

Acknowledgement sent to Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Mon, 19 Oct 2015 15:16:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; doc of :variable in `define-minor-mode'
Date: Mon, 19 Oct 2015 08:14:57 -0700 (PDT)
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'




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#21709; Package emacs. (Mon, 19 Oct 2015 17:06:02 GMT) Full text and rfc822 format available.

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Random832 <random832 <at> fastmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#21709: 25.0.50; doc of :variable in `define-minor-mode'
Date: Mon, 19 Oct 2015 12:48:14 -0400
Drew Adams <drew.adams <at> 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.





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#21709; Package emacs. (Mon, 19 Oct 2015 17:53:02 GMT) Full text and rfc822 format available.

Message #11 received at 21709 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Random832 <random832 <at> fastmail.com>, 21709 <at> debbugs.gnu.org
Subject: RE: bug#21709: 25.0.50; doc of :variable in `define-minor-mode'
Date: Mon, 19 Oct 2015 10:52:10 -0700 (PDT)
> 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)




Merged 14875 21709. Request was from Glenn Morris <rgm <at> gnu.org> to control <at> debbugs.gnu.org. (Mon, 19 Oct 2015 19:52:02 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#21709; Package emacs. (Mon, 16 Aug 2021 12:24:02 GMT) Full text and rfc822 format available.

Message #16 received at 21709 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21709 <at> debbugs.gnu.org
Subject: Re: bug#21709: 25.0.50; doc of :variable in `define-minor-mode'
Date: Mon, 16 Aug 2021 14:22:58 +0200
Drew Adams <drew.adams <at> 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




bug marked as fixed in version 28.1, send any further explanations to 21709 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Mon, 16 Aug 2021 12:26:01 GMT) Full text and rfc822 format available.

bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Tue, 14 Sep 2021 11:24:04 GMT) Full text and rfc822 format available.

This bug report was last modified 2 years and 196 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.