* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
@ 2015-04-29 17:29 Drew Adams
2015-04-30 7:12 ` Glenn Morris
2016-04-30 19:03 ` Lars Ingebrigtsen
0 siblings, 2 replies; 7+ messages in thread
From: Drew Adams @ 2015-04-29 17:29 UTC (permalink / raw
To: 20462
A minor mode created conventionally, i.e., using `define-minor-mode' or
`define-globalized-minor-mode', should automatically have its doc string
say explicitly that it is a minor mode and whether it is local or
global.
That helps users know what to expect, because all such minor modes have
some things in common, which are well documented.
In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
of 2015-04-05 on LEG570
Bzr revision: 16eec6fc55dcc05d1d819f18998e84a9580b2521
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
2015-04-29 17:29 bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode Drew Adams
@ 2015-04-30 7:12 ` Glenn Morris
2015-04-30 13:47 ` Drew Adams
2016-04-30 19:03 ` Lars Ingebrigtsen
1 sibling, 1 reply; 7+ messages in thread
From: Glenn Morris @ 2015-04-30 7:12 UTC (permalink / raw
To: 20462
(define-globalized-minor-mode foo auto-fill-mode 'ignore)
C-h foo
Toggle Auto-Fill mode in all buffers.
1) It's a minor mode (you can't toggle a major mode, nor sensibly apply
it to all buffers).
2) It's global ("all buffers").
(define-minor-mode blah nil)
C-f blah
Toggle Blah mode on or off.
1) It's a minor mode (you can't toggle a major mode)
2) Since it does not say it affects all buffers, don't assume it does.
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
2015-04-30 7:12 ` Glenn Morris
@ 2015-04-30 13:47 ` Drew Adams
2015-04-30 13:55 ` Drew Adams
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Drew Adams @ 2015-04-30 13:47 UTC (permalink / raw
To: Glenn Morris, 20462
> (define-globalized-minor-mode foo auto-fill-mode 'ignore)
> C-h foo
> Toggle Auto-Fill mode in all buffers.
>
> 1) It's a minor mode (you can't toggle a major mode, nor sensibly
> apply it to all buffers).
> 2) It's global ("all buffers").
> (define-minor-mode blah nil)
> C-f blah
> Toggle Blah mode on or off.
> 1) It's a minor mode (you can't toggle a major mode)
> 2) Since it does not say it affects all buffers, don't assume it
> does.
Irrelevant to this bug report. A command that toggles something,
including toggling a mode, is not necessarily a minor-mode command.
See, for example, the misnamed `use-hard-newlines' command of
bug #20464. It happens to be a minor-mode command. But with
that name it might just as well not have been. And there is
no way to tell from its doc string that it has anything to do
with a minor mode. `define-globalized-minor-mode' and
`define-minor-mode' should explicitly add something to the
doc string to make clear that the command is not just some
command that toggles. They should explicitly mention "minor mode".
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
2015-04-30 13:47 ` Drew Adams
@ 2015-04-30 13:55 ` Drew Adams
2015-04-30 15:36 ` Artur Malabarba
2017-01-02 21:59 ` Drew Adams
2 siblings, 0 replies; 7+ messages in thread
From: Drew Adams @ 2015-04-30 13:55 UTC (permalink / raw
To: Glenn Morris, 20462
> See, for example, the misnamed `use-hard-newlines' command of
> bug #20464.
I meant bug #20461, which is about the name.
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
2015-04-30 13:47 ` Drew Adams
2015-04-30 13:55 ` Drew Adams
@ 2015-04-30 15:36 ` Artur Malabarba
2017-01-02 21:59 ` Drew Adams
2 siblings, 0 replies; 7+ messages in thread
From: Artur Malabarba @ 2015-04-30 15:36 UTC (permalink / raw
To: Drew Adams; +Cc: 20462
2015-04-30 14:47 GMT+01:00 Drew Adams
>> (define-globalized-minor-mode foo auto-fill-mode 'ignore)
>> C-h foo
>> Toggle Auto-Fill mode in all buffers.
>>
>> 1) It's a minor mode (you can't toggle a major mode, nor sensibly
>> apply it to all buffers).
>> 2) It's global ("all buffers").
>> (define-minor-mode blah nil)
>> C-f blah
>> Toggle Blah mode on or off.
>> 1) It's a minor mode (you can't toggle a major mode)
>> 2) Since it does not say it affects all buffers, don't assume it
>> does.
>
> Irrelevant to this bug report. A command that toggles something,
> including toggling a mode, is not necessarily a minor-mode command.
I agree with Drew here. The fact that this information can be inferred
(deciphered, perhaps) from the docstring doesn't mean that it
shouldn't be included explicitly. Even more so where it comes minor
modes, which are commands that even the most basic users will interact
with (and probably read).
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
2015-04-30 13:47 ` Drew Adams
2015-04-30 13:55 ` Drew Adams
2015-04-30 15:36 ` Artur Malabarba
@ 2017-01-02 21:59 ` Drew Adams
2 siblings, 0 replies; 7+ messages in thread
From: Drew Adams @ 2017-01-02 21:59 UTC (permalink / raw
To: 20462
In addition, I think it would be good if the doc for the mode
either mentioned whether the mode is currently on or (at least)
mentioned the associated variable, letting users know that the
value of that variable will tell them whether it is currently
on or off. (They might also need to be told that they need to
examine the variable value in the appropriate buffer. Or else
clicking the variable link in the doc for the function should
evaluate it in the proper buffer (same buffer that the function
doc was invoked from).
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode
2015-04-29 17:29 bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode Drew Adams
2015-04-30 7:12 ` Glenn Morris
@ 2016-04-30 19:03 ` Lars Ingebrigtsen
1 sibling, 0 replies; 7+ messages in thread
From: Lars Ingebrigtsen @ 2016-04-30 19:03 UTC (permalink / raw
To: Drew Adams; +Cc: 20462
Drew Adams <drew.adams@oracle.com> writes:
> A minor mode created conventionally, i.e., using `define-minor-mode' or
> `define-globalized-minor-mode', should automatically have its doc string
> say explicitly that it is a minor mode and whether it is local or
> global.
>
> That helps users know what to expect, because all such minor modes have
> some things in common, which are well documented.
Yeah, I kinda think that `define-minor-mode' should include the toggle
verbiage by default at the start of all doc strings, even if there is a
doc string given. That would mean going through all the usages in the
tree and remove the leading incantations, but that's no big deal.
We could have a keyword :no-introduction t for the few modes that really
don't want the standard verbiage at the start.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2017-01-02 21:59 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-04-29 17:29 bug#20462: 25.0.50; A minor mode's doc string should say it is [local/global] a minor mode Drew Adams
2015-04-30 7:12 ` Glenn Morris
2015-04-30 13:47 ` Drew Adams
2015-04-30 13:55 ` Drew Adams
2015-04-30 15:36 ` Artur Malabarba
2017-01-02 21:59 ` Drew Adams
2016-04-30 19:03 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.