GNU bug report logs - #38601
describe-mode never says the most important thing

Previous Next

Full log

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: bug-gnu-emacs <at> gnu.org
Subject: describe-mode never says the most important thing
Date: Sat, 14 Dec 2019 07:29:31 +0800

C-h m runs the command describe-mode

And it has problems. Let's take a look at a typical section of the
describe-mode output:

  ^L
  Electric-Indent minor mode (no indicator):
  Toggle on-the-fly reindentation (Electric Indent mode).
  With a prefix argument ARG, enable Electric Indent mode if ARG is
  positive, and disable it otherwise.  If called from Lisp, enable
  the mode if ARG is omitted or nil.

  When enabled, this reindents whenever the hook ‘electric-indent-functions’
  returns non-nil, or if you insert a character from ‘electric-indent-chars’.

  This is a global minor mode.  To toggle the mode in a single buffer,
  use ‘electric-indent-local-mode’.
  ^L

The problem is, it doesn't mention how to turn it on and off!

The user has to click on each line right after an ^L, to learn that he
simply needs to do e.g.,

  (electric-indent-mode &optional ARG)

That's right, each section between the ^L's could go on for miles and
miles, never revealing the most important thing: how to turn it on and
off.

Well OK, at the top say "to avoid cluttering the page, please click each
item to learn how to turn it on and off". (Or "how to invoke.")

P.S., some of the entries are followed by a mysterious
  (fn &optional ARG)
and some of them aren't.

  ^L
  Auto-Compression minor mode (no indicator):
  Toggle Auto Compression mode.
  With a prefix argument ARG, enable Auto Compression mode if ARG
  is positive, and disable it otherwise.  If called from Lisp,
  enable the mode if ARG is omitted or nil.

  Auto Compression mode is a global minor mode.  When enabled,
  compressed files are automatically uncompressed for reading, and
  compressed when writing.
  ^L
  Auto-Encryption minor mode (no indicator):
  Toggle automatic file encryption/decryption (Auto Encryption mode).
  With a prefix argument ARG, enable Auto Encryption mode if ARG is
  positive, and disable it otherwise.  If called from Lisp, enable
  the mode if ARG is omitted or nil.

  (fn &optional ARG)
  ^L

Perhaps fn stands for the function name, but the page never says what
the exact function name is. So we end up having to look it up anyway.
Also there is no rhyme or reason why we only see it on some entries.

emacs-version "26.3"

Previous Next

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