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

Previous Next

Full log

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''

Previous Next

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