unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#38601: describe-mode never says the most important thing
@ 2019-12-13 23:29 積丹尼 Dan Jacobson
  2019-12-14  7:42 ` Eli Zaretskii
  2019-12-15  2:09 ` Phil Sainty
  0 siblings, 2 replies; 9+ messages in thread
From: 積丹尼 Dan Jacobson @ 2019-12-13 23:29 UTC (permalink / raw)
  To: 38601

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"





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-04-18 16:43 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-12-13 23:29 bug#38601: describe-mode never says the most important thing 積丹尼 Dan Jacobson
2019-12-14  7:42 ` Eli Zaretskii
2019-12-15 20:58   ` 積丹尼 Dan Jacobson
2021-04-18 16:43   ` Stefan Kangas
2019-12-15  2:09 ` Phil Sainty
2019-12-15 20:28   ` 積丹尼 Dan Jacobson
2019-12-15 22:00   ` Tomas Nordin
2019-12-15 22:32     ` Phil Sainty
2019-12-16 21:36       ` Juri Linkov

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).