GNU bug report logs - #32212
26; `subword-mode' doc string shows empty key-binding list

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 32212 in the body.
You can then email your comments to 32212 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26; `subword-mode' doc string shows empty key-binding list
Date: Thu, 19 Jul 2018 08:10:57 -0700 (PDT)

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

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 32212 <at> debbugs.gnu.org
Subject: Re: bug#32212: 26;
 `subword-mode' doc string shows empty key-binding list
Date: Thu, 19 Jul 2018 20:58:52 -0400

found 32212 25.1
severity 32212 minor
tags 32212 + confirmed
quit

Drew Adams <drew.adams <at> 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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 32212 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#32212: 26;
 `subword-mode' doc string shows empty key-binding list
Date: Fri, 20 Jul 2018 10:01:04 +0300

> From: Noam Postavsky <npostavs <at> gmail.com>
> Date: Thu, 19 Jul 2018 20:58:52 -0400
> Cc: 32212 <at> 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.

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

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Noam Postavsky <npostavs <at> gmail.com>, 32212 <at> debbugs.gnu.org
Subject: Re: bug#32212: 26;
 `subword-mode' doc string shows empty key-binding list
Date: Fri, 20 Jul 2018 10:38:17 +0200

On Fri, 20 Jul 2018 10:01:04 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Noam Postavsky <npostavs <at> gmail.com>
>> Date: Thu, 19 Jul 2018 20:58:52 -0400
>> Cc: 32212 <at> 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 <at> 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

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 32212 <at> debbugs.gnu.org
Subject: Re: bug#32212: 26;
 `subword-mode' doc string shows empty key-binding list
Date: Sun, 22 Jul 2018 16:22:51 -0400

[Message part 1 (text/plain, inline)]

tags 32212 + patch
quit

Stephen Berman <stephen.berman <at> 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?

[0001-Omit-keymap-from-subword-mode-docstring-Bug-32212.patch (text/x-diff, inline)]

From 6fd80dcf0fc6261de80c130fb535ad334858cbf3 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs <at> 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

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: Stephen Berman <stephen.berman <at> gmx.net>, 32212 <at> debbugs.gnu.org,
 bug-gnu-emacs <bug-gnu-emacs-bounces+psainty=orcon.net.nz <at> gnu.org>
Subject: Re: bug#32212: 26; `subword-mode' doc string shows empty
 key-binding list
Date: Mon, 23 Jul 2018 10:36:39 +1200

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Phil Sainty <psainty <at> orcon.net.nz>, Noam Postavsky <npostavs <at> gmail.com>
Cc: Stephen Berman <stephen.berman <at> gmx.net>, 32212 <at> debbugs.gnu.org,
 bug-gnu-emacs <bug-gnu-emacs-bounces+psainty=orcon.net.nz <at> gnu.org>
Subject: RE: bug#32212: 26; `subword-mode' doc string shows empty key-binding
 list
Date: Sun, 22 Jul 2018 18:01:54 -0700 (PDT)

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: stephen.berman <at> gmx.net, 32212 <at> debbugs.gnu.org
Subject: Re: bug#32212: 26;
 `subword-mode' doc string shows empty key-binding list
Date: Mon, 23 Jul 2018 05:26:45 +0300

> From: Noam Postavsky <npostavs <at> gmail.com>
> Cc: Eli Zaretskii <eliz <at> gnu.org>,  32212 <at> 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.

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Stephen Berman <stephen.berman <at> gmx.net>,
 bug-gnu-emacs <bug-gnu-emacs-bounces+psainty=orcon.net.nz <at> gnu.org>,
 Noam Postavsky <npostavs <at> gmail.com>, 32212 <at> debbugs.gnu.org
Subject: Re: bug#32212: 26; `subword-mode' doc string shows empty
 key-binding list
Date: Mon, 23 Jul 2018 16:15:22 +1200

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: Stephen Berman <stephen.berman <at> gmx.net>,
 bug-gnu-emacs <bug-gnu-emacs-bounces+psainty=orcon.net.nz <at> gnu.org>,
 Noam Postavsky <npostavs <at> gmail.com>, 32212 <at> debbugs.gnu.org
Subject: RE: bug#32212: 26; `subword-mode' doc string shows empty key-binding
 list
Date: Sun, 22 Jul 2018 21:19:55 -0700 (PDT)

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

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stephen.berman <at> gmx.net, 32212 <at> debbugs.gnu.org
Subject: Re: bug#32212: 26;
 `subword-mode' doc string shows empty key-binding list
Date: Mon, 23 Jul 2018 08:22:59 -0400

tags 32212 fixed
close 32212 26.2
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Noam Postavsky <npostavs <at> gmail.com>
>> Cc: Eli Zaretskii <eliz <at> gnu.org>,  32212 <at> 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

Previous Next

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