bug#38601: describe-mode never says the most important thing

bug#38601: describe-mode never says the most important thing

[積丹尼 Dan Jacobson]

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"

bug#38601: describe-mode never says the most important thing

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson
>  <jidanni@jidanni.org>
> Date: Sat, 14 Dec 2019 07:29:31 +0800
> 
>   ^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!

Actually, it does: that's the last sentence above.

> 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 not a user command, that's a Lisp way of doing this stuff, and
therefore doesn't have to be anywhere near the beginning of the help
text.

So I think we should close this as a non-b ug.

bug#38601: describe-mode never says the most important thing

[Phil Sainty]

On 14/12/19 12:29 PM, 積丹尼 Dan Jacobson wrote:
> P.S., some of the entries are followed by a mysterious
> (fn &optional ARG)
> and some of them aren't.

It appears that this bug has been fixed for Emacs 27.


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

Surely the most important thing is telling you what each mode does.

Knowing how to turn them off is important, but once you know how to
turn one minor mode on or off, then you know how to turn *any* minor
mode on or off -- it's the same in all cases.

(I do think there's an argument for showing the mode symbol rather
than a capitalised variant of the name in the `describe-mode' help;
but that's a different conversation.)


> 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.")

But even if you follow the link, it still won't tell you how to
*interactively* enable or disable the mode (e.g. with M-x MODENAME);
so if a person is so new to Emacs that they don't already know how to
do all these things, I'm not sure that your suggestion is sufficient
to resolve that situation.  And once they do have that very basic
understanding of modes, the information is pretty redundant.

I don't think I'd be bothered by the information being added, but I'm
not sure that its absence is really a significant problem?  I suspect
you'll need more people to add their agreement to the bug report to
convince people otherwise.


-Phil

bug#38601: describe-mode never says the most important thing

[積丹尼 Dan Jacobson]

>>>>> "PS" == Phil Sainty <psainty@orcon.net.nz> writes:
PS> Knowing how to turn them off is important, but once you know how to
PS> turn one minor mode on or off, then you know how to turn *any* minor
PS> mode on or off -- it's the same in all cases.

Well OK but the cautious user knows to first check the docs before
executing things. (E.g., Unix sort vs. uniq arguments.)

bug#38601: describe-mode never says the most important thing

[積丹尼 Dan Jacobson]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
>> The problem is, it doesn't mention how to turn it on and off!

EZ> Actually, it does: that's the last sentence above.

OK, but e.g., the next one doesn't:
^L
File-Name-Shadow minor mode (no indicator):
Toggle file-name shadowing in minibuffers (File-Name Shadow mode).
With a prefix argument ARG, enable File-Name Shadow mode if ARG
is positive, and disable it otherwise.  If called from Lisp,
enable the mode if ARG is omitted or nil.

File-Name Shadow mode is a global minor mode.  When enabled, any
part of a filename being read in the minibuffer that would be
ignored (because the result is passed through
‘substitute-in-file-name’) is given the properties in
‘file-name-shadow-properties’, which can be used to make that
portion dim, invisible, or otherwise less visually noticeable.
^L

It talks about a prefix argument but doesn't show one how to invoke it.

bug#38601: describe-mode never says the most important thing

[Tomas Nordin]

Phil Sainty <psainty@orcon.net.nz> writes:

> (I do think there's an argument for showing the mode symbol rather
> than a capitalised variant of the name in the `describe-mode' help;
> but that's a different conversation.)

A different conversation but I didn't see that so I take the opportunity
to agree here. The capitalized variants of the command name was always
confusing to me -- is it the command name, only with a big letter in the
beginning, or is it some sort of doxy description that is not the same
as the command name. Easy to check, but anyway.

The help for a specific function has a different approach, not
capitalized.

Best regards
--
Tomas

bug#38601: describe-mode never says the most important thing

[Phil Sainty]

On 16/12/19 11:00 AM, Tomas Nordin wrote:
> Phil Sainty <psainty@orcon.net.nz> writes:
>> (I do think there's an argument for showing the mode symbol rather
>> than a capitalised variant of the name in the `describe-mode' help;
>> but that's a different conversation.)
>
> A different conversation but I didn't see that so I take the
> opportunity to agree here. The capitalized variants of the command
> name was always confusing to me -- is it the command name, only
> with a big letter in the beginning, or is it some sort of doxy
> description that is not the same as the command name. Easy to check,
> but anyway.

For the major mode it's just the `mode-name' value.

For the minor modes it's the symbol name, sans "-minor-mode"/"-mode",
passed through `capitalize': "foo-bar-mode" becomes "Foo-Bar".

This is hard-coded in `describe-mode', which produces the following:

(pp-eval-expression
 '(let (minor-modes)
    ;; Older packages do not register in minor-mode-list but only in
    ;; minor-mode-alist.
    (dolist (x minor-mode-alist)
      (setq x (car x))
      (unless (memq x minor-mode-list)
        (push x minor-mode-list)))
    ;; Find enabled minor mode we will want to mention.
    (dolist (mode minor-mode-list)
      ;; Document a minor mode if it is listed in minor-mode-alist,
      ;; non-nil, and has a function definition.
      (let ((fmode (or (get mode :minor-mode-function) mode)))
        (and (boundp mode) (symbol-value mode)
             (fboundp fmode)
             (let ((pretty-minor-mode
                    (if (string-match "\\(\\(-minor\\)?-mode\\)?\\'"
                                      (symbol-name fmode))
                        (capitalize
                         (substring (symbol-name fmode)
                                    0 (match-beginning 0)))
                      fmode)))
               (push (list fmode pretty-minor-mode
                           (format-mode-line
                             (assq mode minor-mode-alist)))
                     minor-modes)))))
    minor-modes))

bug#38601: describe-mode never says the most important thing

[Juri Linkov]

>>> (I do think there's an argument for showing the mode symbol rather
>>> than a capitalised variant of the name in the `describe-mode' help;
>>> but that's a different conversation.)
>>
>> A different conversation but I didn't see that so I take the
>> opportunity to agree here. The capitalized variants of the command
>> name was always confusing to me -- is it the command name, only
>> with a big letter in the beginning, or is it some sort of doxy
>> description that is not the same as the command name. Easy to check,
>> but anyway.
>
> For the major mode it's just the `mode-name' value.
>
> For the minor modes it's the symbol name, sans "-minor-mode"/"-mode",
> passed through `capitalize': "foo-bar-mode" becomes "Foo-Bar".

At least, minor modes have links to their Help buffers
where the symbol name is displayed and available for
e.g. copying etc, but the major mode has no such link
in the `describe-mode' help, that's the problem that
should be fixed.

bug#38601: describe-mode never says the most important thing

[Stefan Kangas]

tags 38601 notabug
close 38601
thanks

Eli Zaretskii <eliz@gnu.org> writes:

>> From: 積丹尼 Dan Jacobson
>>  <jidanni@jidanni.org>
>> Date: Sat, 14 Dec 2019 07:29:31 +0800
>>
>>   ^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!
>
> Actually, it does: that's the last sentence above.
>
>> 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 not a user command, that's a Lisp way of doing this stuff, and
> therefore doesn't have to be anywhere near the beginning of the help
> text.
>
> So I think we should close this as a non-b ug.

OK, closing.