GNU bug report logs - #33912
27.0.50; Mention in minor-mode doc strings that the mode is a minor mode

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Sat, 29 Dec 2018 16:29:01 UTC

Severity: wishlist

Merged with 20462, 29497, 41884

Found in versions 25.0.50, 26.0.90, 27.0.50, 27.0.91

Fixed in version 28.1

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

Bug is archived. No further changes may be made.

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

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

View this report as an mbox folder, status mbox, maintainer mbox

Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#33912; Package emacs. (Sat, 29 Dec 2018 16:29:02 GMT) Full text and rfc822 format available.
Acknowledgement sent to Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sat, 29 Dec 2018 16:29:02 GMT) Full text and rfc822 format available.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.50; Mention in minor-mode doc strings that the mode is a minor
 mode
Date: Sat, 29 Dec 2018 08:13:54 -0800 (PST)

Please consider mentioning explicitly in the doc string of all minor
modes (at least those defined using `define-minor-mode') that the mode
is a minor mode.

I thought there was already a bug, and agreement that it should be
fixed, saying that more of the full info that the doc string of
`define-minor-mode' provides should also be provided in the doc string
of each mode.  But maybe that never happened or was agreed upon.

In any case, it can help a mode's doc to have it state that the mode is
a minor mode.  Even more helpful would be a link to either (1) the doc
of `define-minor-mode' or (2) the manual.

Users are often confused about how to turn a minor mode on/off,
including in their init files (i.e., using Lisp).  If a mode's doc
doesn't make clear whether it is a major or a minor mode then this lack
adds to confusion about how to enable/disable it, because the two kinds
of mode are handled very differently (and a major mode is disabled only
by enabled a different one, and major modes cannot be combined).

The doc string of a major usually (always?) does say that it is a major
mode.  It is even more important that the doc of a minor say that the
mode is minor - minor modes can be disabled and combined.


In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''
Forcibly Merged 20462 33912. Request was from Glenn Morris <rgm <at> gnu.org> to control <at> debbugs.gnu.org. (Mon, 31 Dec 2018 06:05:01 GMT) Full text and rfc822 format available.
Merged 20462 29497 33912. Request was from Glenn Morris <rgm <at> gnu.org> to control <at> debbugs.gnu.org. (Thu, 10 Jan 2019 23:36:01 GMT) Full text and rfc822 format available.
Forcibly Merged 20462 29497 33912 41884. Request was from Glenn Morris <rgm <at> gnu.org> to control <at> debbugs.gnu.org. (Mon, 15 Jun 2020 23:07:02 GMT) Full text and rfc822 format available.
bug marked as fixed in version 28.1, send any further explanations to 29497 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Wed, 30 Jun 2021 13:33:04 GMT) Full text and rfc822 format available.
bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Thu, 29 Jul 2021 11:24:04 GMT) Full text and rfc822 format available.
This bug report was last modified 2 years and 266 days ago.

Previous Next

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