`define-minor-mode' makes erroneous docstrings.

`define-minor-mode' makes erroneous docstrings.

[Luc Teirlinck]

The docstrings provided by `define-minor-mode' are wrong for many
minor-mode variables.  They _automatically_ say that setting the
variable directly has no effect.  I believe that this is wrong for the
majority of minor modes.

For global minor modes, setting the variable buffer locally is often
useful, like for column-number-mode.  For local minor modes, you can
enable them globally by setting the default-value of the variable.

As an example here is what you get from `C-h v column-number-mode'.
It is definitely wrong, you can set it directly and buffer locally.
It works.

  column-number-mode's value is t
  Local in buffer *info*; global value is nil

  Non-nil if Column-Number mode is enabled.
  See the command `column-number-mode' for a description of this minor-mode.
  Setting this variable directly does not take effect;
  use either M-x customize or the function `column-number-mode'.

  You can customize this variable.

  Defined in `simple'.

Re: `define-minor-mode' makes erroneous docstrings.

[Luc Teirlinck]

>From my previous message:

   As an example here is what you get from `C-h v column-number-mode'.
   It is definitely wrong, you can set it directly and buffer locally.
   It works.

Well, setting the variable definitely will run no mode hooks, but who
cares.  Maybe basic minor modes such as column-number-mode that work
by just setting the variable should not be defined using
`define-minor-mode' and should not have any useless hooks associated
with them.

Sincerely,

Luc.

Re: `define-minor-mode' makes erroneous docstrings.

[Luc Teirlinck]

>From my previous message:

   Well, setting the variable definitely will run no mode hooks, but who
   cares.  Maybe basic minor modes such as column-number-mode that work
   by just setting the variable should not be defined using
   `define-minor-mode' and should not have any useless hooks associated
   with them.

Or maybe they can have hooks associated with them, just to have hooks
associated with them.  But basically, very few people will use these
hooks, so the fact that setting the variable does not run them is
irrelevant.

Sincerely,

Luc.

Re: `define-minor-mode' makes erroneous docstrings.

[Stefan Monnier]

> useful, like for column-number-mode.  For local minor modes, you can
> enable them globally by setting the default-value of the variable.

The comment about not setting the variable locally should not be added if
the mode is not declared to be global.


        Stefan

Re: `define-minor-mode' makes erroneous docstrings.

[Luc Teirlinck]

Stefan Monnier wrote:

   The comment about not setting the variable locally should not be added if
   the mode is not declared to be global.

If the mode is not global, the comment is less explicit, but still says:

   Use the command `visible-mode' to change this variable.

In the case of Visible mode, this is actually correct: just setting
the variable does not work.

Whether or not setting the variable works does not depend on whether
the mode is global or local.  The only difference is that for local
modes, setting through Custom does not work.

Maybe if the minor mode defined using `define-minor-mode', local or
global, has an empty explicitly specified function definition, the
docstring could explicitly say that setting the variable has the same
effect as calling the function, except for some side stuff, like
running the mode hooks.

Examples include line-number-mode, column-number-mode, size-indication-mode
and transient-mark-mode.  I guess that there must be many others.

There is the problem of reconciling stuff in `(emacs)Minor Modes' with
the behavior of `define-minor-mode'.  Part of that might be updating
the node, but part of it might be correcting misfeatures of
`define-minor-mode'.

Sincerely,

Luc.

Re: `define-minor-mode' makes erroneous docstrings.

[Richard Stallman]

    The docstrings provided by `define-minor-mode' are wrong for many
    minor-mode variables.  They _automatically_ say that setting the
    variable directly has no effect.  I believe that this is wrong for the
    majority of minor modes.

Would it work to try to distinguish by whether the "body" of
the define-minor-mode form is empty?  If it is non-empty,
then it contains forms that will be executed by the function.
Just setting the variable won't execute those forms, which means
just setting the variable probably isn't right.

If the body is empty, then I think just setting the variable will
work.


As regards mode hooks, I agree it is a mistake to associate
mode hooks with the modes that, aside from their hooks, are
fully controlled by variables.  Maybe this means we should
give define-minor-mode a new option to control whether to
make a hook.

Re: `define-minor-mode' makes erroneous docstrings.

[Luc Teirlinck]

Richerd Stallman wrote:

   Would it work to try to distinguish by whether the "body" of
   the define-minor-mode form is empty?

I believe that would work.

Sincerely,

Luc.