bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

[Drew Adams]

Apologies if this enhancement request has been proposed before.
It seems like it might have been, as it's a pretty obvious
possibility.

Suggestion:

Have the automatically provided part of a minor-mode doc string, from
`define-minor-mode' do the following (or at least some of it):

1. Mention the mode variable (typically the same name as the mode,
   but in any case the name is known to `define-minor-mode').
   (The doc string currently mentions the keymap, but not the var.)

2. Show the current value of the variable, just as we do for the keymap.
   If undefined so far then say so, just as we do for the keymap.

3. Say whether the variable is global (an option, customizable), or
   buffer-local.

4. Maybe mention that the variable is set/reset automatically when you
   toggle the mode.  If the var is global mention that you can set/reset
   it manually using Customize.

5. Any particularities, e.g. from using `:variable' should be taken into
   account, so the doc string is correct for all cases.



In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

[Lars Ingebrigtsen]

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

> Have the automatically provided part of a minor-mode doc string, from
> `define-minor-mode' do the following (or at least some of it):
>
> 1. Mention the mode variable (typically the same name as the mode,
>    but in any case the name is known to `define-minor-mode').
>    (The doc string currently mentions the keymap, but not the var.)
>
> 2. Show the current value of the variable, just as we do for the keymap.
>    If undefined so far then say so, just as we do for the keymap.

Here's the current output from a random minor mode defined by that
function:

---

epa-mail-mode is an autoloaded interactive compiled Lisp function in
‘epa-mail.el’.

(epa-mail-mode &optional ARG)

A minor-mode for composing encrypted/clearsigned mails.

If called interactively, enable epa-mail 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.

---

No mention of a keymap?

> 3. Say whether the variable is global (an option, customizable), or
>    buffer-local.

Yes, that makes sense.  Currently a number of these modes say so
themselves, so that should also be adjusted:

---

auto-insert-mode is an autoloaded interactive compiled Lisp function
in ‘autoinsert.el’.

(auto-insert-mode &optional ARG)

Toggle Auto-insert mode, a global minor mode.

[...]

---

> 4. Maybe mention that the variable is set/reset automatically when you
>    toggle the mode.  If the var is global mention that you can set/reset
>    it manually using Customize.

Yup.

> 5. Any particularities, e.g. from using `:variable' should be taken into
>    account, so the doc string is correct for all cases.

Makes sense.

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

bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

[Drew Adams]

> > Have the automatically provided part of a minor-mode doc string, from
> > `define-minor-mode' do the following (or at least some of it):
> >
> > 1. Mention the mode variable (typically the same name as the mode,
> >    but in any case the name is known to `define-minor-mode').
> >    (The doc string currently mentions the keymap, but not the var.)
> >
> > 2. Show the current value of the variable, just as we do for the keymap.
> >    If undefined so far then say so, just as we do for the keymap.
> 
> Here's the current output from a random minor mode defined by that
> function:...
> No mention of a keymap?

Sorry, but I don't recall which minor-mode help I was
looking at the day I filed that bug (shoulda noted the
function name).  But the mode was defined by
`define-minor-mode', and the help had a sentence saying
that (minor-map) keymap such-and-such was not yet
defined. The map variable was mentioned and its value
was described, at least that far.

In any case, #1 and #2 here are about the mode variable,
not the keymap variable.

> > 3. Say whether the variable is global (an option, customizable), or
> >    buffer-local.
> 
> Yes, that makes sense.  Currently a number of these modes say so
> themselves, so that should also be adjusted:

Right.  Many mode doc strings provide info that is
not provided, or was not provided at one point, by
`define-minor-mode'.

bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

[Lars Ingebrigtsen]

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

> `define-minor-mode' do the following (or at least some of it):
>
> 1. Mention the mode variable (typically the same name as the mode,
>    but in any case the name is known to `define-minor-mode').
>    (The doc string currently mentions the keymap, but not the var.)

I've now done this in Emacs 28.

> 2. Show the current value of the variable, just as we do for the keymap.
>    If undefined so far then say so, just as we do for the keymap.

I think that would be pretty odd -- it's just a function doc string,
and the value of these variables in the *Help* buffer is usually nil.

> 3. Say whether the variable is global (an option, customizable), or
>    buffer-local.

For minor modes?  No, I think that would be counter-productive -- minor
modes should be toggled with the minor mode command.

And besides -- the "mode variable" isn't necessarily a variable: You can
use a general setf-able thing for it.  And the getter and the setter
aren't the same.  The useful thing, I think, is to have the doc string
document the getter "variable", so that you know how to check whether
the mode is off or on.  (Which I've now done, so I'm closing this bug
report.)

> 4. Maybe mention that the variable is set/reset automatically when you
>    toggle the mode.  If the var is global mention that you can set/reset
>    it manually using Customize.

Ditto.

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

bug#36500: [External] : Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

[Drew Adams]

> > `define-minor-mode' do the following (or at least some of it):
> >
> > 1. Mention the mode variable (typically the same name as the mode,
> >    but in any case the name is known to `define-minor-mode').
> >    (The doc string currently mentions the keymap, but not the var.)
> 
> I've now done this in Emacs 28.
> 
> > 2. Show the current value of the variable, just as we do for the keymap.
> >    If undefined so far then say so, just as we do for the keymap.
> 
> I think that would be pretty odd -- it's just a function doc string,
> and the value of these variables in the *Help* buffer is usually nil.

Why do you think it would be odd?  It would be helpful.
The value reported would of course be for the buffer
where help was invoked - not for `*Help*' (unless it
was invoked there).

That's the way `*Help*' works and has always worked.
`C-h k <whatever>' doesn't tell you the binding in
`*Help*'.  I'm surprised to see this kind of argument
for not documenting something.

> > 3. Say whether the variable is global (an option, customizable), or
> >    buffer-local.
> 
> For minor modes?  No, I think that would be counter-productive -- minor
> modes should be toggled with the minor mode command.

Regardless of your last phrase, which is true in general
(but not always), a globalized minor mode DOES create
a user option - customizable.  Ask yourself why.  Help
should tell users about it when that's the case.

Users shouldn't have to consult the doc for
`define-minor-mode' and `define-globalized-minor-mode'
each time they ask for help on a minor mode.  That's
been the problem from the outset, and it's still a
problem to some extent.

> And besides -- the "mode variable" isn't necessarily a variable:

No, not necessarily.  All the more reason for Help to
tell you what it is.  It should tell you when it's a
user option, a normal defvar, and a generalized var.

> The useful thing, I think, is to have the doc string
> document the getter "variable", 

There is no one "useful thing".  Certainly documenting
the variable (generalized or not) is important, and
it's only one of the things that's important.

> so that you know how to check whether the mode is
> off or on.

Help on the mode should also do that - see the first
thing, above.  Knowing what the variable is is good.
Knowing what the current state is is good.  Help on
a minor mode should tell you all such things.

> so I'm closing this bug report.)

Too bad.  But at least you presumably made some of
the suggested improvements.

> > 4. Maybe mention that the variable is set/reset automatically when you
> >    toggle the mode.  If the var is global mention that you can set/reset
> >    it manually using Customize.
> 
> Ditto.

Dunno what "ditto" means here.  There was some that
you did and much that you didn't do.  Whether you
did #4 isn't clear (without digging out the new code).