GNU bug report logs -
#38601
describe-mode never says the most important thing
Previous Next
Reported by: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Date: Sat, 14 Dec 2019 01:22:01 UTC
Severity: wishlist
Tags: notabug
Done: Stefan Kangas <stefan <at> marxist.se>
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 38601 in the body.
You can then email your comments to 38601 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sat, 14 Dec 2019 01:22:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Sat, 14 Dec 2019 01:22:01 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
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"
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sat, 14 Dec 2019 07:43:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 38601 <at> debbugs.gnu.org (full text, mbox):
> From: 積丹尼 Dan Jacobson
> <jidanni <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sun, 15 Dec 2019 02:10:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 38601 <at> debbugs.gnu.org (full text, mbox):
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
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sun, 15 Dec 2019 20:30:03 GMT)
Full text and
rfc822 format available.
Message #14 received at 38601 <at> debbugs.gnu.org (full text, mbox):
>>>>> "PS" == Phil Sainty <psainty <at> 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.)
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sun, 15 Dec 2019 20:59:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 38601 <at> debbugs.gnu.org (full text, mbox):
>>>>> "EZ" == Eli Zaretskii <eliz <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sun, 15 Dec 2019 22:01:01 GMT)
Full text and
rfc822 format available.
Message #20 received at 38601 <at> debbugs.gnu.org (full text, mbox):
Phil Sainty <psainty <at> 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
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sun, 15 Dec 2019 22:33:02 GMT)
Full text and
rfc822 format available.
Message #23 received at 38601 <at> debbugs.gnu.org (full text, mbox):
On 16/12/19 11:00 AM, Tomas Nordin wrote:
> Phil Sainty <psainty <at> 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))
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Mon, 16 Dec 2019 22:53:04 GMT)
Full text and
rfc822 format available.
Message #26 received at 38601 <at> debbugs.gnu.org (full text, mbox):
>>> (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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#38601
; Package
emacs
.
(Sun, 18 Apr 2021 16:44:01 GMT)
Full text and
rfc822 format available.
Message #29 received at 38601 <at> debbugs.gnu.org (full text, mbox):
tags 38601 notabug
close 38601
thanks
Eli Zaretskii <eliz <at> gnu.org> writes:
>> From: 積丹尼 Dan Jacobson
>> <jidanni <at> 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.
Added tag(s) notabug.
Request was from
Stefan Kangas <stefan <at> marxist.se>
to
control <at> debbugs.gnu.org
.
(Sun, 18 Apr 2021 16:44:02 GMT)
Full text and
rfc822 format available.
bug closed, send any further explanations to
38601 <at> debbugs.gnu.org and 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Request was from
Stefan Kangas <stefan <at> marxist.se>
to
control <at> debbugs.gnu.org
.
(Sun, 18 Apr 2021 16:44:03 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
.
(Mon, 17 May 2021 11:24:04 GMT)
Full text and
rfc822 format available.
This bug report was last modified 2 years and 337 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.