GNU bug report logs - #34073
26.1; Missing documentation for minor mode hook behavior

Previous Next

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

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

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

From: Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; Missing documentation for minor mode hook behavior
Date: Mon, 14 Jan 2019 10:13:08 +0100

--text follows this line--

I couldn't find essential information about minor mode hooks behavior, namely that "The minor mode's hook is called both when activating and deactivating the minor mode" (as stated here: https://emacs.stackexchange.com/a/47092/17425).

It isn't mentioned in the manual (sections "Minor Modes" and "Hooks"), nor in the docstring for `add-hook' function.

Please consider adding this information in the relevant sections of the docs.
Thank you.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
Cc: 34073 <at> debbugs.gnu.org
Subject: Re: bug#34073: 26.1;
 Missing documentation for minor mode hook behavior
Date: Wed, 10 Jul 2019 00:20:00 +0200

Piotr Kaznowski <piotr.kaznowski <at> gmail.com> writes:

> I couldn't find essential information about minor mode hooks behavior,
> namely that "The minor mode's hook is called both when activating and
> deactivating the minor mode" (as stated here:
> https://emacs.stackexchange.com/a/47092/17425).
>
> It isn't mentioned in the manual (sections "Minor Modes" and "Hooks"),
> nor in the docstring for `add-hook' function.

Mentioning it `add-hook' is perhaps not natural, and I don't think it's
100% adhered to, anyway?  Only by minor modes that are defined by
define-minor-mode?  Other minor modes may or may not call the hook.

It is mentioned in the "Defining Minor Modes" node of the Lisp
manual...  but is probably not where people would be looking for this
information.

Hm.  Perhaps `add-hook' is the right place to mention this anyway?  But
with caveats about, well, everything?

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

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 34073 <at> debbugs.gnu.org, Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
Subject: Re: bug#34073: 26.1;
 Missing documentation for minor mode hook behavior
Date: Tue, 09 Jul 2019 18:35:57 -0400

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

> Piotr Kaznowski <piotr.kaznowski <at> gmail.com> writes:
>
>> I couldn't find essential information about minor mode hooks behavior,
>> namely that "The minor mode's hook is called both when activating and
>> deactivating the minor mode" (as stated here:
>> https://emacs.stackexchange.com/a/47092/17425).
>>
>> It isn't mentioned in the manual (sections "Minor Modes" and "Hooks"),
>> nor in the docstring for `add-hook' function.
>
> Mentioning it `add-hook' is perhaps not natural, and I don't think it's
> 100% adhered to, anyway?  Only by minor modes that are defined by
> define-minor-mode?  Other minor modes may or may not call the hook.
>
> It is mentioned in the "Defining Minor Modes" node of the Lisp
> manual...  but is probably not where people would be looking for this
> information.
>
> Hm.  Perhaps `add-hook' is the right place to mention this anyway?  But
> with caveats about, well, everything?

Maybe define-minor-mode could mention this in the mode's docstring, like
it does for the ARG?

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 34073 <at> debbugs.gnu.org, Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
Subject: Re: bug#34073: 26.1;
 Missing documentation for minor mode hook behavior
Date: Wed, 10 Jul 2019 00:43:21 +0200

Noam Postavsky <npostavs <at> gmail.com> writes:

> Maybe define-minor-mode could mention this in the mode's docstring, like
> it does for the ARG?

It subtly alludes to this in this bit:

--
BODY contains code to execute each time the mode is enabled or disabled.
  It is executed after toggling the mode, and before running MODE-hook.
--

But that's not the documentation somebody who wonders when hooks are run
would look -- that macro is for people who implement modes, not people
who just wants to run some hooks...

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

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 34073 <at> debbugs.gnu.org, Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
Subject: Re: bug#34073: 26.1;
 Missing documentation for minor mode hook behavior
Date: Tue, 09 Jul 2019 18:44:56 -0400

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

> Noam Postavsky <npostavs <at> gmail.com> writes:
>
>> Maybe define-minor-mode could mention this in the mode's docstring, like
>> it does for the ARG?
>
> It subtly alludes to this in this bit:
>
> --
> BODY contains code to execute each time the mode is enabled or disabled.
>   It is executed after toggling the mode, and before running MODE-hook.
> --

I didn't mean the docstring of define-minor-mode, I meant the docstring
of the mode it defines.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 34073 <at> debbugs.gnu.org, Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
Subject: Re: bug#34073: 26.1;
 Missing documentation for minor mode hook behavior
Date: Wed, 10 Jul 2019 00:57:53 +0200

Noam Postavsky <npostavs <at> gmail.com> writes:

> I didn't mean the docstring of define-minor-mode, I meant the docstring
> of the mode it defines.

Yes, that makes sense.  I just had a look at a random one of these:

---

auto-image-file-mode is an autoloaded interactive Lisp function in
‘image-file.el’.

(auto-image-file-mode &optional ARG)

  Probably introduced at or before Emacs version 21.1.

Toggle visiting of image files as images (Auto Image File mode).

If called interactively, enable Auto-Image-File mode if ARG is positive, and
disable it if ARG is zero or negative.  If called from Lisp,
also enable the mode if ARG is omitted or nil, and toggle it
if ARG is ‘toggle’; disable the mode otherwise.

An image file is one whose name has an extension in
‘image-file-name-extensions’, or matches a regexp in
‘image-file-name-regexps’.

---

It doesn't mention the hook at all...  which I guess it could do?

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 34073 <at> debbugs.gnu.org, Piotr Kaznowski <piotr.kaznowski <at> gmail.com>
Subject: Re: bug#34073: 26.1; Missing documentation for minor mode hook
 behavior
Date: Fri, 21 Aug 2020 17:15:56 +0200

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

> Noam Postavsky <npostavs <at> gmail.com> writes:
>
>> I didn't mean the docstring of define-minor-mode, I meant the docstring
>> of the mode it defines.
>
> Yes, that makes sense.  I just had a look at a random one of these:

[...]

> It doesn't mention the hook at all...  which I guess it could do?

I've now added a sentence to easy-mmode--arg-docstring.

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

Previous Next

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