* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
@ 2018-07-19 15:10 Drew Adams
2018-07-20 0:58 ` Noam Postavsky
0 siblings, 1 reply; 11+ messages in thread
From: Drew Adams @ 2018-07-19 15:10 UTC (permalink / raw)
To: 32212
emacs -Q
C-h f subword-mode
You see this at the end of buffer *Help*:
key binding
--- -------
It's not just about this appearing before the library is loaded.
Loading the library does not populate the list of keys and their
bindings. You always get such a heading, with no keys shown.
In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --without-dbus --host=x86_64-w64-mingw32
--without-compress-install 'CFLAGS=-O2 -static -g3''
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-19 15:10 bug#32212: 26; `subword-mode' doc string shows empty key-binding list Drew Adams
@ 2018-07-20 0:58 ` Noam Postavsky
2018-07-20 7:01 ` Eli Zaretskii
0 siblings, 1 reply; 11+ messages in thread
From: Noam Postavsky @ 2018-07-20 0:58 UTC (permalink / raw)
To: Drew Adams; +Cc: 32212
found 32212 25.1
severity 32212 minor
tags 32212 + confirmed
quit
Drew Adams <drew.adams@oracle.com> writes:
> emacs -Q
>
> C-h f subword-mode
>
> You see this at the end of buffer *Help*:
>
> key binding
> --- -------
>
>
> It's not just about this appearing before the library is loaded.
> Loading the library does not populate the list of keys and their
> bindings. You always get such a heading, with no keys shown.
Seems to be a regression in 25.1, in 24.5 I see
key binding
--- -------
<remap> Prefix Command
<remap> <backward-kill-word> subword-backward-kill
<remap> <backward-word> subword-backward
<remap> <capitalize-word> subword-capitalize
<remap> <downcase-word> subword-downcase
<remap> <forward-word> subword-forward
<remap> <kill-word> subword-kill
<remap> <left-word> subword-left
<remap> <mark-word> subword-mark
<remap> <right-word> subword-right
<remap> <transpose-words> subword-transpose
<remap> <upcase-word> subword-upcase
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-20 0:58 ` Noam Postavsky
@ 2018-07-20 7:01 ` Eli Zaretskii
2018-07-20 8:38 ` Stephen Berman
0 siblings, 1 reply; 11+ messages in thread
From: Eli Zaretskii @ 2018-07-20 7:01 UTC (permalink / raw)
To: Noam Postavsky; +Cc: 32212
> From: Noam Postavsky <npostavs@gmail.com>
> Date: Thu, 19 Jul 2018 20:58:52 -0400
> Cc: 32212@debbugs.gnu.org
>
> > emacs -Q
> >
> > C-h f subword-mode
> >
> > You see this at the end of buffer *Help*:
> >
> > key binding
> > --- -------
> >
> >
> > It's not just about this appearing before the library is loaded.
> > Loading the library does not populate the list of keys and their
> > bindings. You always get such a heading, with no keys shown.
>
>
> Seems to be a regression in 25.1, in 24.5 I see
>
> key binding
> --- -------
>
> <remap> Prefix Command
>
> <remap> <backward-kill-word> subword-backward-kill
ISTR that the implementation changed radically, so perhaps this is the
(unintended) consequence.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-20 7:01 ` Eli Zaretskii
@ 2018-07-20 8:38 ` Stephen Berman
2018-07-22 20:22 ` Noam Postavsky
0 siblings, 1 reply; 11+ messages in thread
From: Stephen Berman @ 2018-07-20 8:38 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Noam Postavsky, 32212
On Fri, 20 Jul 2018 10:01:04 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Noam Postavsky <npostavs@gmail.com>
>> Date: Thu, 19 Jul 2018 20:58:52 -0400
>> Cc: 32212@debbugs.gnu.org
>>
>> > emacs -Q
>> >
>> > C-h f subword-mode
>> >
>> > You see this at the end of buffer *Help*:
>> >
>> > key binding
>> > --- -------
>> >
>> >
>> > It's not just about this appearing before the library is loaded.
>> > Loading the library does not populate the list of keys and their
>> > bindings. You always get such a heading, with no keys shown.
>>
>>
>> Seems to be a regression in 25.1, in 24.5 I see
>>
>> key binding
>> --- -------
>>
>> <remap> Prefix Command
>>
>> <remap> <backward-kill-word> subword-backward-kill
>
> ISTR that the implementation changed radically, so perhaps this is the
> (unintended) consequence.
Maybe due to this change:
commit 6ddc44225e743e2b2a0d5c192f50aefd7a4a915b
Author: Daniel Colascione <dancol@dancol.org>
Date: Sun Mar 23 00:36:26 2014 -0700
Merge capitalized-words-mode and subword-mode
diff --git a/lisp/progmodes/subword.el b/lisp/progmodes/subword.el
--- a/lisp/progmodes/subword.el
+++ b/lisp/progmodes/subword.el
@@ -104,12 +82,6 @@
(defvar subword-mode-map
- (let ((map (make-sparse-keymap)))
- (dolist (cmd '(forward-word backward-word mark-word kill-word
- backward-kill-word transpose-words
- capitalize-word upcase-word downcase-word
- left-word right-word))
- (let ((othercmd (let ((name (symbol-name cmd)))
- (string-match "\\([[:alpha:]-]+\\)-word[s]?" name)
- (intern (concat "subword-" (match-string 1 name))))))
- (define-key map (vector 'remap cmd) othercmd)))
- map)
+ ;; We originally remapped motion keys here, but now use Emacs core
+ ;; hooks. Leave this keymap around so that user additions to it
+ ;; keep working.
+ (make-sparse-keymap)
"Keymap used in `subword-mode' minor mode.")
Steve Berman
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-20 8:38 ` Stephen Berman
@ 2018-07-22 20:22 ` Noam Postavsky
2018-07-22 22:36 ` Phil Sainty
2018-07-23 2:26 ` Eli Zaretskii
0 siblings, 2 replies; 11+ messages in thread
From: Noam Postavsky @ 2018-07-22 20:22 UTC (permalink / raw)
To: Stephen Berman; +Cc: 32212
[-- Attachment #1: Type: text/plain, Size: 957 bytes --]
tags 32212 + patch
quit
Stephen Berman <stephen.berman@gmx.net> writes:
> Maybe due to this change:
> (defvar subword-mode-map
> - (let ((map (make-sparse-keymap)))
> - (dolist (cmd '(forward-word backward-word mark-word kill-word
> - backward-kill-word transpose-words
> - capitalize-word upcase-word downcase-word
> - left-word right-word))
> - (let ((othercmd (let ((name (symbol-name cmd)))
> - (string-match "\\([[:alpha:]-]+\\)-word[s]?" name)
> - (intern (concat "subword-" (match-string 1 name))))))
> - (define-key map (vector 'remap cmd) othercmd)))
> - map)
> + ;; We originally remapped motion keys here, but now use Emacs core
> + ;; hooks. Leave this keymap around so that user additions to it
> + ;; keep working.
> + (make-sparse-keymap)
Aha, then we should just remove it from the docstring, right?
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 1047 bytes --]
From 6fd80dcf0fc6261de80c130fb535ad334858cbf3 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sun, 22 Jul 2018 16:15:43 -0400
Subject: [PATCH] Omit keymap from subword-mode docstring (Bug#32212)
* lisp/progmodes/subword.el (subword-mode): Remove listing of
subword-mode-map bindings, since it is empty as of 2014-03-23 "Merge
capitalized-words-mode and subword-mode".
---
lisp/progmodes/subword.el | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
diff --git a/lisp/progmodes/subword.el b/lisp/progmodes/subword.el
index cbaa273a7a..c09ba37c85 100644
--- a/lisp/progmodes/subword.el
+++ b/lisp/progmodes/subword.el
@@ -113,9 +113,7 @@ subword-mode
NSGraphicsContext => \"NS\", \"Graphics\" and \"Context\"
This mode changes the definition of a word so that word commands
-treat nomenclature boundaries as word boundaries.
-
-\\{subword-mode-map}"
+treat nomenclature boundaries as word boundaries."
:lighter " ,"
(when subword-mode (superword-mode -1))
(subword-setup-buffer))
--
2.11.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-22 20:22 ` Noam Postavsky
@ 2018-07-22 22:36 ` Phil Sainty
2018-07-23 1:01 ` Drew Adams
2018-07-23 2:26 ` Eli Zaretskii
1 sibling, 1 reply; 11+ messages in thread
From: Phil Sainty @ 2018-07-22 22:36 UTC (permalink / raw)
To: Noam Postavsky; +Cc: Stephen Berman, 32212, bug-gnu-emacs
On 2018-07-23 08:22, Noam Postavsky wrote:
> Aha, then we should just remove it from the docstring, right?
Would it be better if the \\{some-keymap} substitution handled the
case where there were no bindings, and printed nothing?
That would then account for edge-cases where users add custom
bindings to a previously-empty keymap, or clobber a populated keymap
entirely.
-Phil
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-22 22:36 ` Phil Sainty
@ 2018-07-23 1:01 ` Drew Adams
2018-07-23 4:15 ` Phil Sainty
0 siblings, 1 reply; 11+ messages in thread
From: Drew Adams @ 2018-07-23 1:01 UTC (permalink / raw)
To: Phil Sainty, Noam Postavsky; +Cc: Stephen Berman, 32212, bug-gnu-emacs
> > Aha, then we should just remove it from the docstring, right?
>
> Would it be better if the \\{some-keymap} substitution handled the
> case where there were no bindings, and printed nothing?
No. A doc string can introduce the list of bindings any
way its author wants. We cannot predict what text might
precede or follow the text \\{some-keymap}.
We already handle the case where the keymap is not
defined at all, by substituting this particular text:
Uses keymap 'foo-map', which is not currently defined.
And that's not ideal either, because it, like your
suggestion (but in a different way) assumes something
about the surrounding context.
(defvar foo-map (make-keymap) "...")
(defun foo ()
"The key bindings are:
\\{foo-map}
For more info..."
42)
`C-h f foo'
,----
| foo is a Lisp function in `...'.
|
| (foo)
|
| The key bindings are:
|
| key binding
| --- -------
|
|
| For more info...
`----
(makunbound 'foo-map)
`C-h f foo'
,----
| foo is a Lisp function in `...'.
|
| (foo)
|
| The key bindings are:
|
|
| Uses keymap 'foo-map', which is not currently defined.
|
| For more info...
`----
With your suggestion:
,----
| foo is a Lisp function in `...'.
|
| (foo)
|
| The key bindings are:
|
|
| For more info...
`----
> That would then account for edge-cases where users add custom
> bindings to a previously-empty keymap, or clobber a populated keymap
> entirely.
I think what we have now is clearest for such cases.
It indicates that (1) the keymap is defined and (2) it
is empty - it has no defined bindings.
Printing nothing is much less clear, I think.
Arguably, the no-keymap case could be handled a bit
better. It might not be clear to users just what "not
currently defined" is supposed to mean. It might be
more accurate to say that the function uses `foo-map',
which is not a variable whose value is a keymap.
(Although the "currently" in the message now presumably
hints that it might become defined when a file is loaded
or some other initialization is done. That's useful.)
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-22 20:22 ` Noam Postavsky
2018-07-22 22:36 ` Phil Sainty
@ 2018-07-23 2:26 ` Eli Zaretskii
2018-07-23 12:22 ` Noam Postavsky
1 sibling, 1 reply; 11+ messages in thread
From: Eli Zaretskii @ 2018-07-23 2:26 UTC (permalink / raw)
To: Noam Postavsky; +Cc: stephen.berman, 32212
> From: Noam Postavsky <npostavs@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, 32212@debbugs.gnu.org
> Date: Sun, 22 Jul 2018 16:22:51 -0400
>
> Aha, then we should just remove it from the docstring, right?
SGTM, thanks.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-23 1:01 ` Drew Adams
@ 2018-07-23 4:15 ` Phil Sainty
2018-07-23 4:19 ` Drew Adams
0 siblings, 1 reply; 11+ messages in thread
From: Phil Sainty @ 2018-07-23 4:15 UTC (permalink / raw)
To: Drew Adams; +Cc: Stephen Berman, 32212, bug-gnu-emacs, Noam Postavsky
On 2018-07-23 13:01, Drew Adams wrote:
>> Would it be better if the \\{some-keymap} substitution handled the
>> case where there were no bindings, and printed nothing?
>
> No. A doc string can introduce the list of bindings any
> way its author wants. We cannot predict what text might
> precede or follow the text \\{some-keymap}.
Ah, yes, agreed -- a search shows quite a variety of such introductory
phrases:
"The following key bindings are currently in effect in the buffer:"
"Customized bindings may be defined in `ielm-map', which currently
contains:"
"The following commands are available:"
"In addition to Emacs-Lisp Mode, the following commands are available:"
"Keys specific to Follow mode:"
"Instead these commands are provided:"
"In the browser, use the following keys:"
"Key bindings:"
"Special commands:"
"The keymap for this second window is:"
"Commands:"
"Tree mode key bindings:"
"Key definitions:"
"Commands:"
"Here are all keybindings."
etc, etc...
I think there's a lot of unnecessary inconsistency here which would
probably benefit from a common phrasing. That could feasibly be
provided via an alternative variant of the \\{...} syntax (at which
point it could make more sense to include some automated variations
for edge cases), but that all sounds like more trouble than it's
worth, so I'm not really suggesting that this should be done (even
if it strikes me as a "nice to have").
-Phil
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-23 4:15 ` Phil Sainty
@ 2018-07-23 4:19 ` Drew Adams
0 siblings, 0 replies; 11+ messages in thread
From: Drew Adams @ 2018-07-23 4:19 UTC (permalink / raw)
To: Phil Sainty; +Cc: Stephen Berman, 32212, bug-gnu-emacs, Noam Postavsky
> >> Would it be better if the \\{some-keymap} substitution handled the
> >> case where there were no bindings, and printed nothing?
> >
> > No. A doc string can introduce the list of bindings any
> > way its author wants. We cannot predict what text might
> > precede or follow the text \\{some-keymap}.
>
> Ah, yes, agreed -- a search shows quite a variety of such introductory
> phrases:...
>
> I think there's a lot of unnecessary inconsistency here which would
> probably benefit from a common phrasing. That could feasibly be
> provided via an alternative variant of the \\{...} syntax (at which
> point it could make more sense to include some automated variations
> for edge cases), but that all sounds like more trouble than it's
> worth, so I'm not really suggesting that this should be done (even
> if it strikes me as a "nice to have").
Agreed on all counts. Except that before thinking about
variants of \\{...} (YAGNI), I'd say that if you think
such inconsistency is really a problem then the best fix
is to suggest a convention to users in the manual.
(But I don't think such inconsistency is a problem.)
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#32212: 26; `subword-mode' doc string shows empty key-binding list
2018-07-23 2:26 ` Eli Zaretskii
@ 2018-07-23 12:22 ` Noam Postavsky
0 siblings, 0 replies; 11+ messages in thread
From: Noam Postavsky @ 2018-07-23 12:22 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: stephen.berman, 32212
tags 32212 fixed
close 32212 26.2
quit
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Noam Postavsky <npostavs@gmail.com>
>> Cc: Eli Zaretskii <eliz@gnu.org>, 32212@debbugs.gnu.org
>> Date: Sun, 22 Jul 2018 16:22:51 -0400
>>
>> Aha, then we should just remove it from the docstring, right?
>
> SGTM, thanks.
Done in emacs-26.
[1: 1208aaa989]: 2018-07-23 08:20:07 -0400
Omit keymap from subword-mode docstring (Bug#32212)
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=1208aaa9893700292693a6b85ae7d1abdb0460ef
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2018-07-23 12:22 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-07-19 15:10 bug#32212: 26; `subword-mode' doc string shows empty key-binding list Drew Adams
2018-07-20 0:58 ` Noam Postavsky
2018-07-20 7:01 ` Eli Zaretskii
2018-07-20 8:38 ` Stephen Berman
2018-07-22 20:22 ` Noam Postavsky
2018-07-22 22:36 ` Phil Sainty
2018-07-23 1:01 ` Drew Adams
2018-07-23 4:15 ` Phil Sainty
2018-07-23 4:19 ` Drew Adams
2018-07-23 2:26 ` Eli Zaretskii
2018-07-23 12:22 ` Noam Postavsky
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).