Re: emacs-30 73c1252bb6b: Fix link to major mode variable in docstring

[Michael Heerdegen]

Thierry Volpiatto <thievol@posteo.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
> > Eshel Yaron <me@eshelyaron.com> writes:
> >
> >> I think it's not always correct to say "the variable" here, because that
> >> "%s" may be replaced with a form that's not just a variable.  E.g. now
> >> C-h f global-auto-revert-mode RET says:
> >>
> >>   To check whether the minor mode is enabled in the current buffer,
> >>   evaluate the variable ‘(default-value 'global-auto-revert-mode)’.
> >
> > Thanks, you're right.  Now reverted.
>
> No, this is not right, reverting fix nothing, we are just back to previous
> bug, this is unrelated, the bug is in `easy-mmode--mode-docstring` which
> have a misleading arg called 'getter' and naturally `define-minor-mode`
> pass 'getter' to it instead of passing 'mode'.

No, this is what we want: in some cases what the user should eval to
check whether a mode is enabled is _not_ the mode variable, but some
other expression.  This is why we have that sentence!  To inform the
user about what to eval exactly.

The code receives that expression via the argument named GETTER.

Also not that in your original recipe (I just tried it), you do _not_
just get to the very same page.  Instead I get to a new help page
listing _all_ things named `...-mode' - the mode variable has been
added.

And I think this is the best behavior our current heuristic can come up
with, and in this case a minor issue.

What we could do is maybe: generate different text in the two cases
(expression is the mode variable vs. it is different), or even better,
add the text only in the "special" case where the mode variable is not
the thing to eval.


Michael.