bug#45536: [PATCH] Pretty-print keys without <> around modifiers

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 607 bytes --]

It is a bit inconsistent that keys are described as C-x and <return> but <C-return>. It would be more logical to write C-<return>. The key parser will happily accept either, but descriptions without modifiers in <> brackets are more legible, and the result is easier to understand and explain.

Attached is a patch which adapts the code that pretty-prints keys. This is a change for human consumption only; it seems unlikely to affect compatibility. With the patch, <C-M-backspace> is now printed as C-M-<backspace>.

I'd be happy to update the manuals accordingly, and add a NEWS entry if required.


[-- Attachment #2: 0001-Pretty-print-keys-without-around-modifiers.patch --]
[-- Type: application/octet-stream, Size: 1702 bytes --]

From 18c9fc433f75a286abcd459abb77b2667d650021 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Tue, 29 Dec 2020 16:55:06 +0100
Subject: [PATCH] Pretty-print keys without <> around modifiers

Be consistent when pretty-printing keys: put modifiers outside <>,
thus the more logical C-M-<return> instead of <C-M-return>.

* src/keymap.c (Fsingle_key_description):
Skip modifier prefix before adding <>.
---
 src/keymap.c | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/src/keymap.c b/src/keymap.c
index ca2d33dba4..d3cde8e7ab 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2260,11 +2260,21 @@ DEFUN ("single-key-description", Fsingle_key_description,
     {
       if (NILP (no_angles))
 	{
-	  Lisp_Object result;
-	  char *buffer = SAFE_ALLOCA (sizeof "<>"
-				      + SBYTES (SYMBOL_NAME (key)));
-	  esprintf (buffer, "<%s>", SDATA (SYMBOL_NAME (key)));
-	  result = build_string (buffer);
+	  Lisp_Object namestr = SYMBOL_NAME (key);
+	  const char *sym = SSDATA (namestr);
+	  ptrdiff_t len = SBYTES (namestr);
+	  /* Find the extent of the modifier prefix, like "C-M-". */
+	  int i = 0;
+	  while (i < len - 3 && sym[i + 1] == '-' && strchr ("CMSsHA", sym[i]))
+	    i += 2;
+	  /* First I bytes of SYM are modifiers; put <> around the rest. */
+	  char *buffer = SAFE_ALLOCA (len + 3);
+	  memcpy (buffer, sym, i);
+	  buffer[i] = '<';
+	  memcpy (buffer + i + 1, sym + i, len - i);
+	  buffer [len + 1] = '>';
+	  buffer [len + 2] = '\0';
+	  Lisp_Object result = build_string (buffer);
 	  SAFE_FREE ();
 	  return result;
 	}
-- 
2.21.1 (Apple Git-122.3)

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Drew Adams]

> It is a bit inconsistent that keys are described as C-x and <return> but <C-
> return>. It would be more logical to write C-<return>. The key parser will
> happily accept either, but descriptions without modifiers in <> brackets are
> more legible, and the result is easier to understand and explain.
> 
> Attached is a patch which adapts the code that pretty-prints keys. This is a
> change for human consumption only; it seems unlikely to affect compatibility.
> With the patch, <C-M-backspace> is now printed as C-M-<backspace>.
> 
> I'd be happy to update the manuals accordingly, and add a NEWS entry if
> required.

Related:

https://www.emacswiki.org/emacs/NaKeD

https://www.emacswiki.org/emacs/download/naked.el

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

29 dec. 2020 kl. 19.31 skrev Drew Adams <drew.adams@oracle.com>:

> Related:
> 
> https://www.emacswiki.org/emacs/NaKeD
> 
> https://www.emacswiki.org/emacs/download/naked.el

Thank you. This proposal is not nearly as radical (or opinionated) but aims to bring back logic and consistency to the notation.
In particular, it carefully preserves round-trip compatibility with `kbd` (which remains unchanged).

It is good that you posted the links, because it indicates that more people have desired something similar, and the existence of such attempts gives some reassurance that the presented more timid patch would not cause any problems.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Tue, 29 Dec 2020 17:21:03 +0100
> 
> It is a bit inconsistent that keys are described as C-x and <return> but <C-return>. It would be more logical to write C-<return>. The key parser will happily accept either, but descriptions without modifiers in <> brackets are more legible, and the result is easier to understand and explain.
> 
> Attached is a patch which adapts the code that pretty-prints keys. This is a change for human consumption only; it seems unlikely to affect compatibility. With the patch, <C-M-backspace> is now printed as C-M-<backspace>.

IMO, making this kind of changes is just asking for trouble: the gains
are null and void (I don't see why we should care about consistency
here), while the potential for breaking something out there is very
real.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Drew Adams]

> Thank you. This proposal is not nearly as radical (or opinionated) but aims
> to bring back logic and consistency to the notation.
> In particular, it carefully preserves round-trip compatibility with `kbd`
> (which remains unchanged).

`kbd' remains unchanged with `naked.el' as well.
The library just provides function `naked' as
an addition - an alternative to `kbd'.

And `naked.el' nevertheless lets you use angle
brackets, even with its own functions, whenever
you still might want to for some reason.  It
does that with an optional arg.

And even without providing the optional arg,
`naked' accepts angle-bracketed key descriptions
on input, e.g. (naked "M-<foobar>") returns the
same thing as (naked "M-foobar"): [M-foobar].

Prior to Emacs 21, Emacs itself never bothered
with angle brackets - no need.  But someone
around the turn of the century got the idea
that Emacs could not do without them.  Now
they're apparently believed to be indispensable,
because their use is enforced.

> It is good that you posted the links, because it indicates that more people
> have desired something similar, and the existence of such attempts gives some
> reassurance that the presented more timid patch would not cause any problems.

I've desired it because I lived it prior to
Emacs 21, and I find it MUCH clearer.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 629 bytes --]

29 dec. 2020 kl. 21.01 skrev Eli Zaretskii <eliz@gnu.org>:

> IMO, making this kind of changes is just asking for trouble: the gains
> are null and void (I don't see why we should care about consistency
> here), while the potential for breaking something out there is very
> real.

The gains are not null and void (or the change would not have been proposed).
There is no evidence for it being likely to break anything, but we can make the reform optional and turned off by default. That way, code for which it is desirable and safe could bind a dynamic variable during the pretty-printing.

Updated patch attached.


[-- Attachment #2: 0001-Pretty-print-keys-without-around-modifiers-bug-45536.patch --]
[-- Type: application/octet-stream, Size: 3345 bytes --]

From 7aa5bef4a0949846ec565e42b9799e6c910aa492 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Tue, 29 Dec 2020 16:55:06 +0100
Subject: [PATCH] Pretty-print keys without <> around modifiers (bug#45536)

Be consistent when pretty-printing keys: put modifiers outside <>,
thus the more logical C-M-<return> instead of <C-M-return>.
This behaviour is controlled by modifiers-inside-angle-brackets,
by default t (for compatibility).

* src/keymap.c (Fsingle_key_description): Optionally skip modifier
prefix before adding <>.
(syms_of_keymap): Add modifiers-inside-angle-brackets.
---
 src/keymap.c | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/src/keymap.c b/src/keymap.c
index ca2d33dba4..c167772311 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2013,6 +2013,9 @@ DEFUN ("key-description", Fkey_description, Skey_description, 1, 2, 0,
 Optional arg PREFIX is the sequence of keys leading up to KEYS.
 For example, [?\C-x ?l] is converted into the string \"C-x l\".
 
+Modifiers are put inside angle brackets iff `modifiers-inside-angle-brackets'
+is non-nil.
+
 For an approximate inverse of this, see `kbd'.  */)
   (Lisp_Object keys, Lisp_Object prefix)
 {
@@ -2229,6 +2232,8 @@ DEFUN ("single-key-description", Fsingle_key_description,
 Control characters turn into C-whatever, etc.
 Optional argument NO-ANGLES non-nil means don't put angle brackets
 around function keys and event symbols.
+Modifiers are put inside angle brackets iff `modifiers-inside-angle-brackets'
+is non-nil.
 
 See `text-char-description' for describing character codes.  */)
   (Lisp_Object key, Lisp_Object no_angles)
@@ -2260,11 +2265,23 @@ DEFUN ("single-key-description", Fsingle_key_description,
     {
       if (NILP (no_angles))
 	{
-	  Lisp_Object result;
-	  char *buffer = SAFE_ALLOCA (sizeof "<>"
-				      + SBYTES (SYMBOL_NAME (key)));
-	  esprintf (buffer, "<%s>", SDATA (SYMBOL_NAME (key)));
-	  result = build_string (buffer);
+	  Lisp_Object namestr = SYMBOL_NAME (key);
+	  const char *sym = SSDATA (namestr);
+	  ptrdiff_t len = SBYTES (namestr);
+	  /* Optionally find the extent of the modifier prefix, like "C-M-",
+	     to avoid putting modifiers around them. */
+	  int i = 0;
+	  if (!modifiers_inside_angle_brackets)
+	    while (i < len - 3 && sym[i + 1] == '-'
+		   && strchr ("CMSsHA", sym[i]))
+	      i += 2;
+	  char *buffer = SAFE_ALLOCA (len + 3);
+	  memcpy (buffer, sym, i);
+	  buffer[i] = '<';
+	  memcpy (buffer + i + 1, sym + i, len - i);
+	  buffer [len + 1] = '>';
+	  buffer [len + 2] = '\0';
+	  Lisp_Object result = build_string (buffer);
 	  SAFE_FREE ();
 	  return result;
 	}
@@ -3331,6 +3348,13 @@ syms_of_keymap (void)
   Vwhere_is_preferred_modifier = Qnil;
   where_is_preferred_modifier = 0;
 
+  DEFVAR_BOOL ("modifiers-inside-angle-brackets",
+	       modifiers_inside_angle_brackets,
+	       doc: /* Whether modifiers go inside <> in key descriptions.
+When non-nil, <return> with a Control modifier is written <C-return>;
+when nil, it is written C-<return>. */);
+  modifiers_inside_angle_brackets = true;
+
   DEFSYM (Qmenu_bar, "menu-bar");
   DEFSYM (Qmode_line, "mode-line");
 
-- 
2.21.1 (Apple Git-122.3)

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> IMO, making this kind of changes is just asking for trouble: the gains
> are null and void (I don't see why we should care about consistency
> here), while the potential for breaking something out there is very
> real.

I think Mattias' proposed change makes for better readability, so the
gains aren't null...  on the other hand, they aren't huge, and I share
Eli's worry about breaking something.

On the third hand, we could try this out on master for a while and see
whether anything breaks -- my guess would be that nothing will break.

On the fourth hand, I can see people asking "what's the difference
between C-<return> and <C-return>?" on Reddit for decades to come, so it
might just confuse people and waste their time.  So...  I'm leaning
towards not changing this.

I'm running out of hands here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

30 dec. 2020 kl. 04.54 skrev Lars Ingebrigtsen <larsi@gnus.org>:

> On the third hand, we could try this out on master for a while and see
> whether anything breaks -- my guess would be that nothing will break.
> 
> On the fourth hand, I can see people asking "what's the difference
> between C-<return> and <C-return>?" on Reddit for decades to come, so it
> might just confuse people and waste their time.  So...  I'm leaning
> towards not changing this.
> 
> I'm running out of hands here.

Let me give you a hand then! The latest patch puts the change under control of a variable, defaulting to off. This should take care of your concerns for compatibility problems, as well as the possibility of confusion (which I think is minuscule).

The variable can be set permanently by users who prefer the new key binding style. It can also be bound temporarily for specific uses. It was a specific use I had in mind, but there is no reason to withhold an improvement from users in general.

Thanks for your careful reasoning. We can all agree that if we included pleasing everybody on Reddit in our design criteria, no progress would ever be made.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Lars Ingebrigtsen]

Mattias Engdegård <mattiase@acm.org> writes:

> Let me give you a hand then! The latest patch puts the change under
> control of a variable, defaulting to off. This should take care of
> your concerns for compatibility problems, as well as the possibility
> of confusion (which I think is minuscule).

The confusion problem is still present, though -- people will see
different ways of representing keystrokes (in examples on the web,
etc). 

> The variable can be set permanently by users who prefer the new key
> binding style. It can also be bound temporarily for specific uses. It
> was a specific use I had in mind, but there is no reason to withhold
> an improvement from users in general.

What's the specific use case?

> Thanks for your careful reasoning. We can all agree that if we
> included pleasing everybody on Reddit in our design criteria, no
> progress would ever be made.

I wasn't worried about pleasing anybody -- I just want to avoid
unnecessary confusion. 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

31 dec. 2020 kl. 05.35 skrev Lars Ingebrigtsen <larsi@gnus.org>:

> The confusion problem is still present, though -- people will see
> different ways of representing keystrokes (in examples on the web,
> etc). 

Let's not make a mole out of a molehill -- it will be all right. After all, the change is for the better.
Surely we must be able to correct past mistakes?

Remember that this is not a new notation -- 'kbd' has always accepted it, and I'm sure that .emacs files the world over contain instances of it. The manual uses it a bit everywhere, and rightly so. I'm quite sure that nobody ever got confused by it.

Actually it makes sense to let the logical notation be the default, doesn't it? There's no harm in trying it on master.

> What's the specific use case?

The NS port renders <backspace> as the backspace symbol (etc), by convention for that platform. This is done by string replacement and won't work if the key is <M-backspace> instead of M-<backspace>.

Of course we can add messy code to correct for this, but why do that locally in the NS port for this specific purpose when everyone could benefit from a clearer notation in the first place?

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

31 dec. 2020 kl. 10.59 skrev Mattias Engdegård <mattiase@acm.org>:

> The manual uses it a bit everywhere, and rightly so.

Correction: the manual uses the logical notation almost exclusively.
Perhaps the Reddit crowd has been fuming about this for decades, I wouldn't know.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Lars Ingebrigtsen]

Mattias Engdegård <mattiase@acm.org> writes:

> 31 dec. 2020 kl. 10.59 skrev Mattias Engdegård <mattiase@acm.org>:
>
>> The manual uses it a bit everywhere, and rightly so.
>
> Correction: the manual uses the logical notation almost exclusively.
> Perhaps the Reddit crowd has been fuming about this for decades, I
> wouldn't know.

The only instance I could find of "M-<[a-z]" was this from the manual?

(kbd "C-M-<down>") @result{} [C-M-down]

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 296 bytes --]

1 jan. 2021 kl. 11.46 skrev Lars Ingebrigtsen <larsi@gnus.org>:

> The only instance I could find of "M-<[a-z]" was this from the manual?

Thank you for double-checking! But there are more modifiers than Meta, and there is also @key{...} which expands to <...>.
Here are my grep results:


[-- Attachment #2: logical-style-in-manual.log --]
[-- Type: application/octet-stream, Size: 35364 bytes --]

-*- mode: grep; default-directory: "~/emacs/doc/" -*-
Grep started at Fri Jan  1 12:47:19

git --no-pager grep -n -e \[CMAHSs\]-\\\(\[CMAHSs\]-\\\)\*\\\(\<.\*\>\\\|\@key\\\) -- \*.texi
emacs/basic.texi:241:@item C-@key{RIGHT}
emacs/basic.texi:242:@itemx M-@key{RIGHT}
emacs/basic.texi:253:@item C-@key{LEFT}
emacs/basic.texi:254:@itemx M-@key{LEFT}
emacs/basic.texi:282:On graphical displays, @kbd{C-@key{HOME}} does the same.
emacs/basic.texi:289:displays, @kbd{C-@key{END}} does the same.
emacs/basic.texi:416:@item M-@key{DEL}
emacs/basic.texi:417:@itemx M-@key{BACKSPACE}
emacs/buffers.texi:441:@item M-@key{DEL}
emacs/buffers.texi:735:  @kbd{M-@key{TAB}} will select the first completion in the list, like
emacs/buffers.texi:738:@kbd{M-@key{TAB}} can be used a few times to descend in the hierarchy
emacs/buffers.texi:800:bound to @kbd{C-Down-mouse-1} and @kbd{C-@key{F10}}, with its own
emacs/calendar.texi:300:date using @kbd{C-@key{SPC}}, move point to another date, and type @kbd{M-=}
emacs/calendar.texi:316:@itemx S-@key{SPC}
emacs/commands.texi:55:characters, e.g., @kbd{C-@key{F1}} or @kbd{M-@key{LEFT}}.
emacs/commands.texi:73:inputs, including @kbd{M-@key{TAB}}, @kbd{M-@key{SPC}}, @kbd{C-M-d}
emacs/custom.texi:134:field.  @kbd{S-@key{TAB}} (@code{widget-backward}) moves back to the
emacs/custom.texi:254:@kbd{M-@key{TAB}} or @kbd{@key{ESC} @key{TAB}}.  This behaves much
emacs/custom.texi:1833:(global-set-key (kbd "C-<f5>") 'display-line-numbers-mode)
emacs/custom.texi:1834:(global-set-key (kbd "C-<right>") 'forward-sentence)
emacs/custom.texi:2025:@kbd{M-@key{kp-8}}.
emacs/dired.texi:549:@itemx M-@key{DEL}
emacs/dired.texi:554:(@code{dired-unmark-all-files}).  If invoked with @kbd{M-@key{DEL}},
emacs/dired.texi:1187:@kbd{C-u C-@key{SPC}} returns to your previous position in the Dired
emacs/dired.texi:1508:@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to
emacs/display.texi:470:windowful, @kbd{S-@key{SPC}} or @key{DEL} to scroll backward, and @kbd{s} to
emacs/files.texi:1910:operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
emacs/files.texi:2073:When typing a file name in the minibuffer, @kbd{C-@key{TAB}}
emacs/files.texi:2075:name cache.  If you repeat @kbd{C-@key{TAB}}, that cycles through the
emacs/files.texi:2077:that the @kbd{C-@key{TAB}} character cannot be typed on most text
emacs/fixit.texi:288:@item M-@key{TAB}
emacs/fixit.texi:395:  In Text mode and related modes, @kbd{M-@key{TAB}}
emacs/fixit.texi:398:@kbd{M-@key{TAB}}; this shows a list of completions.  (If your
emacs/fixit.texi:399:window manager intercepts @kbd{M-@key{TAB}}, type @w{@kbd{@key{ESC}
emacs/frames.texi:519:@item M-@key{F10}
emacs/frames.texi:1385:@itemx C-@key{TAB}
emacs/frames.texi:1395:@item S-C-@key{TAB}
emacs/glossary.texi:1116:command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS).  @xref{Quitting}.
emacs/help.texi:429:@kbd{S-@key{SPC}} scrolls backward.  A few special commands are also
emacs/help.texi:437:@item S-@key{TAB}
emacs/help.texi:486:forward to the next hyperlink, while @kbd{S-@key{TAB}}
emacs/indent.texi:137:space.  You can also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to
emacs/killing.texi:94:@item M-@key{SPC}
emacs/killing.texi:121:deletes spaces and tab characters before point.  @kbd{M-@key{SPC}}
emacs/killing.texi:211:@item M-@key{DEL}
emacs/killing.texi:239:words, with @kbd{M-@key{DEL}} and @kbd{M-d} (@pxref{Words}); balanced
emacs/killing.texi:305:position, if you wish, with @kbd{C-u C-@key{SPC}} (@pxref{Mark Ring}).
emacs/killing.texi:432:with point shown by @point{}.  If you type @kbd{M-d M-@key{DEL} M-d
emacs/killing.texi:433:M-@key{DEL}}, killing alternately forward and backward, you end up with
emacs/killing.texi:437:@kbd{M-@key{SPC}} or @kbd{M-q}.)
emacs/killing.texi:442:ring.  @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going
emacs/killing.texi:577:@kbd{C-@key{SPC}} and moving point; @pxref{Setting Mark}).
emacs/killing.texi:933:rectangle highlighting.  Use @kbd{C-@key{RET}} to start a rectangle,
emacs/killing.texi:951:copying of text between buffers.  Use @kbd{C-S-@key{SPC}} to toggle the
emacs/kmacro.texi:105:error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{BREAK}}).
emacs/maintaining.texi:1290:@item S-@key{TAB}
emacs/maintaining.texi:2356:@itemx M-@key{TAB}
emacs/maintaining.texi:2372:@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
emacs/mark.texi:72:@item C-@key{SPC}
emacs/mark.texi:92:  The most common way to set the mark is with @kbd{C-@key{SPC}}
emacs/mark.texi:93:(@code{set-mark-command})@footnote{There is no @kbd{C-@key{SPC}}
emacs/mark.texi:94:character in @acronym{ASCII}; usually, typing @kbd{C-@key{SPC}} on a
emacs/mark.texi:98:@kbd{C-@@} as @kbd{C-@key{SPC}}.}.  This sets the mark where point is,
emacs/mark.texi:104:@kbd{C-@key{SPC}}, and move point until the desired portion of text is
emacs/mark.texi:116:@kbd{C-@key{SPC} C-@key{SPC}}), and later jump back there (by typing
emacs/mark.texi:117:@kbd{C-u C-@key{SPC}}).  @xref{Mark Ring}, for details.
emacs/mark.texi:131:similar to @kbd{C-u C-@key{SPC}}.
emacs/mark.texi:142:typing certain cursor motion commands (such as @kbd{S-@key{RIGHT}},
emacs/mark.texi:312:@item C-@key{SPC} C-@key{SPC}
emacs/mark.texi:314:@item C-u C-@key{SPC}
emacs/mark.texi:320:  The command @kbd{C-@key{SPC} C-@key{SPC}} is handy when you want to
emacs/mark.texi:324:actually two consecutive invocations of @kbd{C-@key{SPC}}
emacs/mark.texi:325:(@code{set-mark-command}); the first @kbd{C-@key{SPC}} sets the mark,
emacs/mark.texi:326:and the second @kbd{C-@key{SPC}} deactivates it.  (When Transient Mark
emacs/mark.texi:327:mode is off, @kbd{C-@key{SPC} C-@key{SPC}} instead activates Transient
emacs/mark.texi:332:prefix argument: @kbd{C-u C-@key{SPC}}.  This moves point to where the
emacs/mark.texi:334:@kbd{C-u C-@key{SPC}} jumps to a prior position stored in the mark
emacs/mark.texi:340:then immediately after you type @kbd{C-u C-@key{SPC}}, you can type
emacs/mark.texi:341:@kbd{C-@key{SPC}} instead of @kbd{C-u C-@key{SPC}} to cycle through
emacs/mark.texi:346:current buffer's mark ring.  In particular, @kbd{C-u C-@key{SPC}}
emacs/mark.texi:353:the list is discarded.  Repeating @kbd{C-u C-@key{SPC}} cycles through
emacs/mark.texi:377:  The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to
emacs/mark.texi:379:rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take
emacs/mark.texi:434:Setting the mark, with commands like @kbd{C-@key{SPC}} or @kbd{C-x
emacs/mark.texi:454:using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}.
emacs/mark.texi:457:@item C-@key{SPC} C-@key{SPC}
emacs/mark.texi:459:Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable
emacs/mark.texi:461:is not really a separate command; you are using the @kbd{C-@key{SPC}}
emacs/mini.texi:108:Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names
emacs/mini.texi:230:can also scroll the help text with @kbd{M-@key{PageUp}} and
emacs/mini.texi:231:@kbd{M-@key{PageDown}} (or, equivalently, @kbd{M-@key{prior}} and
emacs/mini.texi:232:@kbd{M-@key{next}}).  This is especially useful with long lists of
emacs/misc.texi:1191:@itemx C-@key{UP}
emacs/misc.texi:1198:@itemx C-@key{DOWN}
emacs/misc.texi:1239:@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
emacs/msdos-xtra.texi:61:  Emacs built for MS-DOS recognizes @kbd{C-@key{Break}} as a quit
emacs/msdos-xtra.texi:71:By contrast, @kbd{C-@key{Break}} @emph{is} detected as soon as you
emacs/msdos-xtra.texi:599:Pressing @kbd{C-c} or @kbd{C-@key{Break}} might sometimes help in these
emacs/msdos.texi:592:@cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows)
emacs/msdos.texi:593:@cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows)
emacs/msdos.texi:595:@kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the
emacs/mule.texi:493:the current alternative with a special color; type @kbd{C-@key{SPC}}
emacs/mule.texi:1933:@kbd{C-@key{RIGHT}}, are sensitive to the base direction of the
emacs/picture-xtra.texi:210:@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing.
emacs/picture-xtra.texi:215:@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting
emacs/picture-xtra.texi:216:character in the current line.  @kbd{M-@key{TAB}} does not change the
emacs/picture-xtra.texi:233:This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
emacs/picture-xtra.texi:236:@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
emacs/programs.texi:642:@itemx C-M-@key{SPC}
emacs/programs.texi:692:region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
emacs/programs.texi:697:The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
emacs/programs.texi:1388:  In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
emacs/programs.texi:1390:the @kbd{M-@key{TAB}} key is usually reserved by the window manager
emacs/programs.texi:1399:@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
emacs/programs.texi:1413:  In Text mode and related modes, @kbd{M-@key{TAB}} completes words
emacs/programs.texi:1741:@item C-c C-@key{DEL}
emacs/programs.texi:1749:@itemx C-c C-@key{Delete}
emacs/rmail.texi:113:@itemx S-@key{SPC}
emacs/rmail.texi:126:(or @kbd{S-@key{SPC}}) do the same as @kbd{C-v} (@code{scroll-up-command})
emacs/rmail.texi:1233:@item S-@key{TAB}
emacs/search.texi:147:@kbd{C-u C-@key{SPC}} or @kbd{C-x C-x} to return to where you were
emacs/search.texi:150:started the search, both @kbd{C-u C-@key{SPC}} and @kbd{C-x C-x} will
emacs/search.texi:472:  Typing @kbd{M-@key{TAB}} in incremental search invokes
emacs/search.texi:476:systems, the @kbd{M-@key{TAB}} key sequence is captured by the window
emacs/search.texi:1467:activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
emacs/text.texi:101:@item M-@key{DEL}
emacs/text.texi:112:cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
emacs/text.texi:137:@kbd{M-@key{DEL}}.)  @kbd{M-d} takes arguments just like @kbd{M-f}.
emacs/text.texi:141:  @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
emacs/text.texi:146:of @kbd{M-@key{DEL}}.
emacs/text.texi:923:  Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}.
emacs/text.texi:927:@kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC}
emacs/text.texi:1217:states.  Typing @kbd{S-@key{TAB}} (@code{outline-cycle-buffer}) cycles
emacs/text.texi:1393:  Typing @kbd{S-@key{TAB}} (@code{org-shifttab}) anywhere in an Org mode
emacs/text.texi:1407:body lines and subtree (if any), by typing @kbd{M-@key{UP}}
emacs/text.texi:1408:(@code{org-metaup}) or @kbd{M-@key{DOWN}} (@code{org-metadown}) on the
emacs/text.texi:1410:with @kbd{M-@key{LEFT}} (@code{org-metaleft}) and @kbd{M-@key{RIGHT}}
emacs/text.texi:2044:@kbd{M-@key{TAB}}, as well as on-the-fly XML
emacs/trouble.texi:23:@itemx C-@key{Break} @r{(MS-DOS only)}
emacs/trouble.texi:60:  On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character
emacs/trouble.texi:64:@kbd{C-@key{Break}} at all times.
emacs/trouble.texi:457:  On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause
emacs/trouble.texi:593:long time.  Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then
lispintro/emacs-lisp-intro.texi:2177:When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
lispintro/emacs-lisp-intro.texi:4244:with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}).  If
lispintro/emacs-lisp-intro.texi:4250:cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
lispintro/emacs-lisp-intro.texi:4915:C-@key{SPC}} twice.
lispintro/emacs-lisp-intro.texi:5918:go back to it with @kbd{C-u C-@key{SPC}}.)  Meanwhile, point is
lispintro/emacs-lisp-intro.texi:10377:with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
lispref/customize.texi:586:provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
lispref/customize.texi:661:@kbd{M-@key{TAB}}.
lispref/keymaps.texi:95:(kbd "C-M-<down>") @result{} [C-M-down]
lispref/keymaps.texi:243:other input events; thus, @kbd{M-@key{end}} has nothing to do with
lispref/keymaps.texi:1267:for other kinds of input events.  Thus, @kbd{M-@key{F1}}, a function
lispref/minibuf.texi:373:@item @kbd{C-@key{TAB}}
lispref/minibuf.texi:1971:the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
lispref/modes.texi:922:(@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to
lispref/modes.texi:1785:@kbd{C-@key{DEL}}.  There are no @var{body} forms---many minor modes
misc/calc.texi:489:front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there,
misc/calc.texi:1544:A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type
misc/calc.texi:1555:  10 @key{RET}         20 @key{RET}         30 @key{RET}         M-@key{TAB}          M-@key{TAB}
misc/calc.texi:1678:2 @key{RET} 3 @key{RET}        (            M-@key{TAB}          M-@key{TAB}            )
misc/calc.texi:2842:    U U            f T         M-@key{RET} M-2 n       f T            -
misc/calc.texi:2857:@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates.
misc/calc.texi:3111:    M-@key{RET}             M-2 A          * /             I C
misc/calc.texi:3139:    r 1 r 2        V C  s 3  M-@key{RET}    M-2 A * /                 A I S
misc/calc.texi:3330:    M-@key{RET}  *                  U @key{TAB} *
misc/calc.texi:3706:(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.)
misc/calc.texi:6168:following form:  Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at
misc/calc.texi:6521:Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3.
misc/calc.texi:6530:                  M-@key{TAB}           1 +           M-@key{TAB}          M-@key{TAB}
misc/calc.texi:6568:enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that.
misc/calc.texi:6569:@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit
misc/calc.texi:7105:Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or
misc/calc.texi:8947:it, then move it back:  @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}.
misc/calc.texi:9151:  @key{RET} M-@key{TAB}         a =             Z /             Z > Z ' C-x )
misc/calc.texi:9186:                   @key{RET} M-@key{TAB}  a =  Z /
misc/calc.texi:9292:  @key{TAB} @key{RET} M-@key{TAB}       - @key{RET} M-@key{TAB}      a =     Z /    2  Z )  Z ' C-x )
misc/calc.texi:9319:                          @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z /
misc/calc.texi:9367:   Z ( @key{TAB}         @key{RET} 0 s l x @key{RET}            M-@key{TAB} ! /  s | 1
misc/calc.texi:9414:           Z (  @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! /  s | 1
misc/calc.texi:9488: M-@key{TAB} M-@key{TAB}     @key{TAB} @key{RET} M-@key{TAB}         z s          *          -
misc/calc.texi:9499:  Z ] Z ] C-x )   Z K s @key{RET}      @key{DEL} 4 @key{RET} 2       z s      M-@key{RET} k s
misc/calc.texi:9516:                 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
misc/calc.texi:10104:You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead
misc/calc.texi:10107:the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.)
misc/calc.texi:10276:The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that
misc/calc.texi:10284:to @kbd{M-@key{RET}}.  @xref{Stack and Trail}.
misc/calc.texi:11783:The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what
misc/calc.texi:11786:Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element,
misc/calc.texi:11787:leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes
misc/calc.texi:11818:The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB}
misc/calc.texi:11822:@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30},
misc/calc.texi:11823:@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20},
misc/calc.texi:11824:@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and
misc/calc.texi:11825:@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}.
misc/calc.texi:11827:A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in
misc/calc.texi:11831:intervening stack elements toward the top.  @kbd{M-@key{TAB}} moves the
misc/calc.texi:11837:stack, and the object in level @mathit{@var{n}+1} to the top.  @kbd{M-@key{TAB}}
misc/calc.texi:12073:the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}).
misc/calc.texi:12076:different than with @kbd{K}:  @kbd{2 @key{RET} 3 + M-@key{RET}} leaves
misc/calc.texi:19359:k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to
misc/calc.texi:30263:``last arguments'' (@kbd{M-@key{RET}}).
misc/calc.texi:31598:instead of @kbd{M-@key{RET}} (@code{calc-last-args}).
misc/calc.texi:36655:@kbd{M-@key{DEL}}, the meaning of the sign is reversed.)
misc/cc-mode.texi:1580:@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.}
misc/cc-mode.texi:1589:to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
misc/cc-mode.texi:1590:natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
misc/cc-mode.texi:1593:@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
misc/cc-mode.texi:1601:to both @kbd{C-c C-@key{Delete}} and @kbd{C-c @key{Delete}} for the
misc/cc-mode.texi:1628:@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
misc/cc-mode.texi:1636:and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
misc/cc-mode.texi:1722:@item     @kbd{M-@key{DEL}} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
misc/efaq.texi:2447:Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
misc/efaq.texi:3842:(define-key function-key-map [M-@key{TAB}] [?\M-\t])
misc/efaq.texi:3846:defines the @kbd{M-@key{TAB}} key sequence.
misc/efaq.texi:3999:@item @kbd{C-2}  or  @kbd{C-@key{SPC}}
misc/erc.texi:281:@item M-@key{TAB} (@code{ispell-complete-word})
misc/ert.texi:265:In the ERT results buffer, @kbd{@key{TAB}} and @kbd{S-@key{TAB}} cycle between
misc/eshell.texi:890:So that @kbd{M-@key{DEL}} acts in a predictable manner, etc.
misc/eshell.texi:904:@item After pressing @kbd{M-@key{RET}}, redisplay before running the next command
misc/eshell.texi:1217:@item @kbd{M-@key{RET}} during a long command (using smart display) doesn't work
misc/eww.texi:113:  The @kbd{M-@key{RET}} command (@code{eww-open-in-new-buffer}) opens the
misc/forms.texi:356:@item S-@key{TAB}
misc/gnus.texi:2201:@item M-@key{RET}
misc/gnus.texi:2209:(i.e., @kbd{0 M-@key{RET}}), Gnus won't even generate the summary buffer,
misc/gnus.texi:2213:@item M-@key{SPC}
misc/gnus.texi:2220:@item C-M-@key{RET}
misc/gnus.texi:3916:@item M-@key{TAB}
misc/gnus.texi:5630:@item M-@key{RET}
misc/gnus.texi:7451:@itemx M-@key{DOWN}
misc/gnus.texi:7460:@itemx M-@key{UP}
misc/gnus.texi:11831:@item M-@key{RET} (Article)
misc/gnus.texi:12383:@item M-@key{TAB}
misc/gnus.texi:28043:@kbd{M-@key{RET}} is a new Message command for breaking cited text.
misc/idlwave.texi:295:@item @kbd{M-@key{RET}}
misc/idlwave.texi:307:@item @kbd{M-@key{TAB}}
misc/idlwave.texi:456:cursor in any line you would like to split and press @kbd{M-@key{RET}}.
misc/idlwave.texi:515:@kbd{M-@key{Tab}}.  A long list of plot's keywords appears.  Aha,
misc/idlwave.texi:700:(@kbd{M-@key{TAB}}) on any routine or partial routine name you know to
misc/idlwave.texi:705:    a=readf@kbd{M-@key{TAB}}
misc/idlwave.texi:941:@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}.
misc/idlwave.texi:943:indents the new line.  The command @kbd{M-@key{RET}} can also be invoked
misc/idlwave.texi:1531:is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE
misc/idlwave.texi:1538:what @kbd{M-@key{TAB}} would try to complete when the cursor is on the
misc/idlwave.texi:1566:name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.
misc/idlwave.texi:1568:Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a
misc/idlwave.texi:1579:@kbd{M-@key{TAB}} repeatedly.  Online help (if installed) for each
misc/idlwave.texi:1682:M-@key{TAB}}.  IDLWAVE will then prompt you for the class in order to
misc/idlwave.texi:2564:@item @kbd{M-@key{TAB}}
misc/idlwave.texi:2947:program, you can use the commands @kbd{C-c C-d C-@key{UP}}
misc/idlwave.texi:2948:(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
misc/idlwave.texi:4063:@item M-@key{TAB} switches among running programs---use @key{ESC}-@key{TAB}
misc/idlwave.texi:4138:@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches
misc/idlwave.texi:4141:Your system is trapping @kbd{M-@key{TAB}} and using it for its own
misc/info.texi:163:@kbd{S-@key{SPC}} (press and hold the @key{Shift} key and then press
misc/info.texi:670:stand-alone reader, type @kbd{M-@key{TAB}}---that is, press and hold
misc/info.texi:673:@kbd{S-@key{TAB}} to move to a previous subtopic line (press and hold
misc/info.texi:785:  The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys,
misc/info.texi:1247:@key{DEL}, or @kbd{S-@key{SPC}}) keys in a menu visit subnodes of the
misc/message.texi:1438:@item M-@key{RET}
misc/message.texi:1449:If point is before @samp{And} and you press @kbd{M-@key{RET}}, you'll get:
misc/mh-e.texi:454:@kbd{C-@key{SPC}}).
misc/mh-e.texi:1701:@item K S-@key{TAB}
misc/mh-e.texi:2347:@kbd{K S-@key{TAB}} (@code{mh-prev-button}). If the beginning of the
misc/mh-e.texi:3027:message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->}
misc/mh-e.texi:4385:@item M-@key{TAB}
misc/mh-e.texi:4401:@item S-@key{TAB}
misc/mh-e.texi:4818:@kbd{S-@key{TAB}} (@code{mh-letter-previous-header-field}) moves
misc/mh-e.texi:4839:@kbd{M-@key{TAB}} (@code{mh-letter-complete}) will provide alias
misc/mh-e.texi:4841:@kbd{M-@key{TAB}} runs @code{mh-letter-complete-function} instead,
misc/mh-e.texi:4843:@kbd{M-@key{TAB}} (@code{mh-letter-complete}) takes a prefix argument
misc/mh-e.texi:5320:@kbd{C-@key{SPC}}, type in the text to be highlighted, and type @kbd{C-c t
misc/mh-e.texi:5718:@item M-@key{TAB}
misc/mh-e.texi:5806:@kbd{M-@key{TAB}} (@code{mh-letter-complete}) or @key{SPC}
misc/mh-e.texi:5823:@samp{To:} field and then @kbd{M-@key{TAB}}, then you'd get the list;
misc/mh-e.texi:5824:if you started with @kbd{m} and then entered @kbd{M-@key{TAB}}, then
misc/mh-e.texi:6615:@item S-@key{TAB}
misc/mh-e.texi:6769:(@code{mh-index-next-folder}) and @kbd{S-@key{TAB}}
misc/newsticker.texi:241:@item M-@key{UP}
misc/newsticker.texi:242:@itemx M-@key{DOWN}
misc/newsticker.texi:248:@item M-S-@key{UP}
misc/newsticker.texi:249:@itemx M-S-@key{DOWN}
misc/nxml-mode.texi:129:@kbd{M-@key{TAB}}.  Note that many window systems and window managers
misc/nxml-mode.texi:130:use @kbd{M-@key{TAB}} themselves (typically for switching between
misc/org.texi:451:* Completion::                   @kbd{M-@key{TAB}} guesses completions.
misc/org.texi:725:@kbd{C-@key{SPC}} twice before moving point.
misc/org.texi:899:document structure, @kbd{M-@key{RIGHT}} will be listed to call
misc/org.texi:999:@kbd{S-@key{TAB}} to change the visibility in the buffer.
misc/org.texi:1015:@item @kbd{S-@key{TAB}} (@code{org-global-cycle})
misc/org.texi:1032:When @kbd{S-@key{TAB}} is called with a numeric prefix argument
misc/org.texi:1036:Note that inside tables (see @ref{Tables}), @kbd{S-@key{TAB}} jumps to the
misc/org.texi:1234:@item @kbd{M-@key{RET}} (@code{org-meta-return})
misc/org.texi:1255:@item @kbd{C-@key{RET}} (@code{org-insert-heading-respect-content})
misc/org.texi:1260:@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading})
misc/org.texi:1267:@item @kbd{C-S-@key{RET}} (@code{org-insert-todo-heading-respect-content})
misc/org.texi:1271:@kbd{C-@key{RET}}, the new headline is inserted after the current
misc/org.texi:1283:@item @kbd{M-@key{LEFT}} (@code{org-do-promote})
misc/org.texi:1284:@itemx @kbd{M-@key{RIGHT}} (@code{org-do-demote})
misc/org.texi:1301:@item @kbd{M-S-@key{LEFT}} (@code{org-promote-subtree})
misc/org.texi:1306:@item @kbd{M-S-@key{RIGHT}} (@code{org-demote-subtree})
misc/org.texi:1311:@item @kbd{M-@key{UP}} (@code{org-move-subtree-up})
misc/org.texi:1316:@item @kbd{M-@key{DOWN}} (@code{org-move-subtree-down})
misc/org.texi:1617:@item @kbd{M-@key{RET}} (@code{org-insert-heading})
misc/org.texi:1629:@item @kbd{M-S-@key{RET}}
misc/org.texi:1633:@item @kbd{S-@key{UP}}
misc/org.texi:1634:@itemx @kbd{S-@key{DOWN}}
misc/org.texi:1643:paragraph jumping commands like @kbd{C-@key{UP}} and
misc/org.texi:1644:@kbd{C-@key{DOWN}} to quite similar effect.
misc/org.texi:1646:@item @kbd{M-@key{UP}}
misc/org.texi:1647:@itemx @kbd{M-@key{DOWN}}
misc/org.texi:1654:@item @kbd{M-@key{LEFT}}
misc/org.texi:1655:@itemx @kbd{M-@key{RIGHT}}
misc/org.texi:1661:@item @kbd{M-S-@key{LEFT}}
misc/org.texi:1662:@itemx @kbd{M-S-@key{RIGHT}}
misc/org.texi:1709:@item @kbd{S-@key{LEFT}}
misc/org.texi:1710:@itemx @kbd{S-@key{RIGHT}}
misc/org.texi:1756:@kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows.
misc/org.texi:1859:@kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}, the field is
misc/org.texi:1905:@item @kbd{S-@key{TAB}} (@code{org-table-previous-field})
misc/org.texi:1933:@item @kbd{M-@key{LEFT}} (@code{org-table-move-column-left})
misc/org.texi:1938:@item @kbd{M-@key{RIGHT}} (@code{org-table-move-column-right})
misc/org.texi:1943:@item @kbd{M-S-@key{LEFT}} (@code{org-table-delete-column})
misc/org.texi:1948:@item @kbd{M-S-@key{RIGHT}} (@code{org-table-insert-column})
misc/org.texi:1954:@item @kbd{M-@key{UP}} (@code{org-table-move-row-up})
misc/org.texi:1959:@item @kbd{M-@key{DOWN}} (@code{org-table-move-row-down})
misc/org.texi:1964:@item @kbd{M-S-@key{UP}} (@code{org-table-kill-row})
misc/org.texi:1969:@item @kbd{S-@key{UP}} (@code{org-table-move-cell-up})
misc/org.texi:1974:@item @kbd{S-@key{DOWN}} (@code{org-table-move-cell-down})
misc/org.texi:1979:@item @kbd{S-@key{LEFT}} (@code{org-table-move-cell-left})
misc/org.texi:1984:@item @kbd{S-@key{RIGHT}} (@code{org-table-move-cell-right})
misc/org.texi:1989:@item @kbd{M-S-@key{DOWN}} (@code{org-table-insert-row})
misc/org.texi:2049:@item @kbd{M-@key{RET}} (@code{org-table-wrap-region})
misc/org.texi:2075:@item @kbd{S-@key{RET}} (@code{org-table-copy-down})
misc/org.texi:3011:@item @kbd{M-@key{TAB}} (@code{lisp-complete-symbol})
misc/org.texi:3016:@item @kbd{S-@key{UP}}, @kbd{S-@key{DOWN}}, @kbd{S-@key{LEFT}}, @kbd{S-@key{RIGHT}}
misc/org.texi:3026:@samp{B3} and you press @kbd{S-@key{RIGHT}}, it becomes @samp{C3}.  This also
misc/org.texi:3029:@item @kbd{M-S-@key{UP}} (@code{org-table-fedit-line-up})
misc/org.texi:3034:@item @kbd{M-S-@key{DOWN}} (@code{org-table-fedit-line-down})
misc/org.texi:3039:@item @kbd{M-@key{UP}} (@code{org-table-fedit-scroll-up})
misc/org.texi:3044:@item @kbd{M-@key{DOWN}} (@code{org-table-fedit-scroll-down})
misc/org.texi:3247:@kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{S-@key{TAB}} in this row.
misc/org.texi:3517:the buffer and press @kbd{M-@key{TAB}}.  All headlines in the current
misc/org.texi:4241:@item @kbd{S-@key{RIGHT}} @kbd{S-@key{LEFT}}
misc/org.texi:4274:@item @kbd{S-M-@key{RET}} (@code{org-insert-todo-heading})
misc/org.texi:4334:the state immediately to @samp{VERIFY}.  Or you can use @kbd{S-@key{RIGHT}}
misc/org.texi:4335:and @kbd{S-@key{LEFT}} to go forward and backward through the states.
misc/org.texi:4406:@itemx @kbd{C-S-@key{RIGHT}}
misc/org.texi:4407:@itemx @kbd{C-S-@key{LEFT}}
misc/org.texi:4412:above example, @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{RIGHT}}
misc/org.texi:4417:@item @kbd{S-@key{RIGHT}}
misc/org.texi:4418:@itemx @kbd{S-@key{LEFT}}
misc/org.texi:4421:@kbd{S-@key{LEFT}} and @kbd{S-@key{RIGHT}} walk through @emph{all} keywords
misc/org.texi:4422:from all sub-sequences, so for example @kbd{S-@key{RIGHT}} would
misc/org.texi:4493:buffer and then use @kbd{M-@key{TAB}} to complete it (see @ref{Completion}).
misc/org.texi:4923:@item @kbd{S-@key{UP}} (@code{org-priority-up})
misc/org.texi:4924:@itemx @kbd{S-@key{DOWN}} (@code{org-priority-down})
misc/org.texi:5124:@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading})
misc/org.texi:5148:@kbd{M-S-@key{RET}}.  TODO statistics cookies update when changing
misc/org.texi:5245:After a colon, @kbd{M-@key{TAB}} offers completion on tags.  There is
misc/org.texi:5736:@item @kbd{M-@key{TAB}} (@code{pcomplete})
misc/org.texi:5766:@item @kbd{S-@key{RIGHT}} (@code{org-property-next-allowed-values})
misc/org.texi:5767:@itemx @kbd{S-@key{LEFT}} (@code{org-property-previous-allowed-value})
misc/org.texi:5959:view---@kbd{S-@key{TAB}} @kbd{S-@key{TAB}}, or simply @kbd{c}
misc/org.texi:6193:@item @kbd{n} or @kbd{S-@key{RIGHT}} (@code{org-columns-next-allowed-value})
misc/org.texi:6194:@itemx @kbd{p} or @kbd{S-@key{LEFT}} (@code{org-columns-previous-allowed-value})
misc/org.texi:6245:@item @kbd{S-M-@key{RIGHT}} (@code{org-columns-new})
misc/org.texi:6250:@item @kbd{S-M-@key{LEFT}} (@code{org-columns-delete})
misc/org.texi:6549:@item @kbd{S-@key{LEFT}} (@code{org-timestamp-down-day})
misc/org.texi:6550:@itemx @kbd{S-@key{RIGHT}} (@code{org-timestamp-up-day})
misc/org.texi:6558:@item @kbd{S-@key{UP}} (@code{org-timestamp-up})
misc/org.texi:6559:@itemx @kbd{S-@key{DOWN}} (@code{org-timestamp-down})
misc/org.texi:6725:@item @kbd{S-@key{RIGHT}}
misc/org.texi:6727:@item @kbd{S-@key{LEFT}}
misc/org.texi:6729:@item @kbd{S-@key{DOWN}}
misc/org.texi:6731:@item @kbd{S-@key{UP}}
misc/org.texi:6733:@item @kbd{M-S-@key{RIGHT}}
misc/org.texi:6735:@item @kbd{M-S-@key{LEFT}}
misc/org.texi:6793:The @kbd{S-@key{UP}} and @kbd{S-@key{DOWN}} keys can no longer be used
misc/org.texi:6795:beginning of the stamp, @kbd{S-@key{UP}} and @kbd{S-@key{DOWN}} change
misc/org.texi:6796:the stamp by one day, just like @kbd{S-@key{LEFT}}
misc/org.texi:6797:@kbd{S-@key{RIGHT}}.  At the end of the stamp, change the time by one
misc/org.texi:7197:change them with @kbd{S-<cursor>} keys, the update is
misc/org.texi:7200:@item @kbd{C-S-@key{UP}} (@code{org-clock-timestamps-up})
misc/org.texi:7201:@itemx @kbd{C-S-@key{DOWN}} (@code{org-clock-timestamps-down})
misc/org.texi:7209:@item @kbd{S-M-@key{UP}} (@code{org-timestamp-up})
misc/org.texi:7210:@itemx @kbd{S-M-@key{DOWN}} (@code{org-timestamp-down})
misc/org.texi:7217:duration.  For example, if you hit @kbd{S-M-@key{UP}} to increase
misc/org.texi:7292:@item @kbd{S-@key{LEFT}}
misc/org.texi:7293:@itemx @kbd{S-@key{RIGHT}} (@code{org-clocktable-try-shift})
misc/org.texi:7384:Use @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to shift the time
misc/org.texi:7712:column mode, and to use @kbd{S-@key{RIGHT}} and @kbd{S-@key{LEFT}} to
misc/org.texi:7783:@item @kbd{M-@key{RET}} (@code{org-insert-heading})
misc/org.texi:7786:Once the timer list is started, you can also use @kbd{M-@key{RET}} to
misc/org.texi:8002:subtrees with @kbd{C-@key{TAB}}, or by setting the option
misc/org.texi:8050:@item @kbd{C-c C-@key{TAB}} (@code{org-force-cycle-archived})
misc/org.texi:10388:modification of the timestamps of items with @kbd{S-@key{LEFT}} and
misc/org.texi:10389:@kbd{S-@key{RIGHT}}.  When the buffer is the global TODO list,
misc/org.texi:10418:@item @kbd{M-@key{UP}} (@code{org-agenda-drag-line-backward})
misc/org.texi:10427:@item @kbd{M-@key{DOWN}} (@code{org-agenda-drag-line-forward})
misc/org.texi:10459:@item @kbd{C-S-@key{RIGHT}} (@code{org-agenda-todo-nextset})
misc/org.texi:10464:@item @kbd{C-S-@key{LEFT}}, @code{org-agenda-todo-previousset}
misc/org.texi:10532:@item @kbd{+} or @kbd{S-@key{UP}} (@code{org-agenda-priority-up})
misc/org.texi:10540:@item @kbd{-} or @kbd{S-@key{DOWN}} (@code{org-agenda-priority-down})
misc/org.texi:10578:@item @kbd{S-@key{RIGHT}} (@code{org-agenda-do-date-later})
misc/org.texi:10584:it by that many days.  For example, @kbd{3 6 5 S-@key{RIGHT}} changes
misc/org.texi:10593:@item @kbd{S-@key{LEFT}} (@code{org-agenda-do-date-earlier})
misc/org.texi:11444:and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
misc/org.texi:12211:@kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows.
misc/org.texi:19399:@item @kbd{M-@key{UP}}
misc/org.texi:19401:@item @kbd{M-@key{DOWN}}
misc/org.texi:19553:* Completion::                   @kbd{M-@key{TAB}} guesses completions.
misc/org.texi:19599:@item @kbd{M-@key{TAB}}
misc/org.texi:19632:pressing @kbd{M-@key{TAB}} again inserts example settings for this
misc/org.texi:20553:with Org's use of @kbd{S-<cursor>} commands to change timestamps,
misc/org.texi:20555:@kbd{S-<cursor>} commands outside of specific contexts do not do
misc/org.texi:20566:Org key bindings conflict with @kbd{S-<cursor>} keys used by
misc/org.texi:20573:@item @kbd{S-@key{UP}}      @result{}  @kbd{M-p}
misc/org.texi:20574:@tab @kbd{S-@key{DOWN}}     @result{}  @kbd{M-n}
misc/org.texi:20575:@item @kbd{S-@key{LEFT}}    @result{}  @kbd{M--}
misc/org.texi:20576:@tab @kbd{S-@key{RIGHT}}    @result{}  @kbd{M-+}
misc/org.texi:20577:@item @kbd{C-S-@key{LEFT}}  @result{}  @kbd{M-S--}
misc/org.texi:20578:@tab @kbd{C-S-@key{RIGHT}}  @result{}  @kbd{M-S-+}
misc/org.texi:20624:This package also uses the @kbd{S-<cursor>} keys, so everything
misc/org.texi:20627:mode does not have special functionality on @kbd{S-<cursor>},
misc/org.texi:20682:@kbd{S-<cursor>} for editing timestamp might be better with
misc/org.texi:20690:@item @kbd{S-@key{TAB}}
misc/org.texi:20694:@item @kbd{M-@key{LEFT}}
misc/org.texi:20698:@item @kbd{M-S-@key{LEFT}}
misc/org.texi:20702:@item @kbd{M-@key{RIGHT}}
misc/org.texi:20706:@item @kbd{M-S-@key{RIGHT}}
misc/org.texi:20710:@item @kbd{M-@key{UP}}
misc/org.texi:20714:@item @kbd{M-S-@key{UP}}
misc/org.texi:20718:@item @kbd{M-@key{DOWN}}
misc/org.texi:20722:@item @kbd{M-S-@key{DOWN}}
misc/org.texi:20726:@item @kbd{S-@key{RET}}
misc/org.texi:20730:@item @kbd{M-@key{RET}}
misc/org.texi:20734:@item @kbd{M-S-@key{RET}}
misc/org.texi:20738:@item @kbd{S-@key{LEFT}}
misc/org.texi:20742:@item @kbd{S-@key{RIGHT}}
misc/org.texi:20746:@item @kbd{S-@key{UP}}
misc/org.texi:20750:@item @kbd{S-@key{DOWN}}
misc/org.texi:20754:@item @kbd{C-S-@key{LEFT}}
misc/org.texi:20758:@item @kbd{C-S-@key{RIGHT}}
misc/pcl-cvs.texi:740:@item M-@key{DEL}
misc/pcl-cvs.texi:1113:selection with @kbd{M-@key{DEL}} (@code{cvs-mode-unmark-all-files}), position
misc/rcirc.texi:246:Use @kbd{C-c C-@key{SPC}} to switch to these buffers.
misc/rcirc.texi:656:channel or nick name.  Use @kbd{C-c C-@key{SPC}} to switch to these
misc/rcirc.texi:672:active channels using @kbd{C-c C-@key{SPC}} no longer works as
misc/rcirc.texi:680:@kbd{C-c C-@key{SPC}} will not switch to low priority channels unless
misc/sem-user.texi:822:behaves like the usual @kbd{M-@key{TAB}} (@code{complete-symbol})
misc/ses.texi:234:@item C-@key{SPC}
misc/ses.texi:297:@item M-@key{TAB}
misc/ses.texi:431:While typing in a lambda, you can use @kbd{M-@key{TAB}} to complete
misc/todo-mode.texi:1420:@itemx S-@key{TAB}
misc/tramp.texi:4735:C-@key{TAB}}.
misc/widget.texi:310:@item @kbd{M-@key{TAB}}
misc/widget.texi:311:@itemx @kbd{S-@key{TAB}}
misc/widget.texi:458:@key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
misc/woman.texi:633:@itemx @kbd{S-@key{SPC}}

Grep finished with matches found at Fri Jan  1 12:47:20

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Lars Ingebrigtsen]

Mattias Engdegård <mattiase@acm.org> writes:

> Thank you for double-checking! But there are more modifiers than Meta,
> and there is also @key{...} which expands to <...>.

Oh, right.  Well, if the manual displays these keys as M-<foo> etc, then
I withdraw all my objections based on possible confusion -- this change
would make things less confusing.  So I'm leaning towards applying the
change and then see whether this breaks anything for anybody.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  45536@debbugs.gnu.org
> Date: Fri, 01 Jan 2021 11:46:00 +0100
> 
> Mattias Engdegård <mattiase@acm.org> writes:
> 
> > 31 dec. 2020 kl. 10.59 skrev Mattias Engdegård <mattiase@acm.org>:
> >
> >> The manual uses it a bit everywhere, and rightly so.
> >
> > Correction: the manual uses the logical notation almost exclusively.
> > Perhaps the Reddit crowd has been fuming about this for decades, I
> > wouldn't know.
> 
> The only instance I could find of "M-<[a-z]" was this from the manual?
> 
> (kbd "C-M-<down>") @result{} [C-M-down]

What the manual uses is the format makeinfo emits for keys and key
sequences in the Info format.  It is only very loosely related to the
way we format key sequences in Emacs.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

1 jan. 2021 kl. 13.00 skrev Eli Zaretskii <eliz@gnu.org>:

> What the manual uses is the format makeinfo emits for keys and key
> sequences in the Info format.  It is only very loosely related to the
> way we format key sequences in Emacs.

But it is what users see when they read the manual in Info, so clearly they cannot be surprised or confused by it.

When the manual seeks to make an explicit example (with '<' instead of @key), it uses the logical style as well. See the examples used to illustrate the manual entry for the 'kbd' function itself.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 1 Jan 2021 13:10:28 +0100
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 45536@debbugs.gnu.org
> 
> 1 jan. 2021 kl. 13.00 skrev Eli Zaretskii <eliz@gnu.org>:
> 
> > What the manual uses is the format makeinfo emits for keys and key
> > sequences in the Info format.  It is only very loosely related to the
> > way we format key sequences in Emacs.
> 
> But it is what users see when they read the manual in Info, so clearly they cannot be surprised or confused by it.

The users also see that in Info manuals that have nothing to do with
Emacs, so their surprise, if it exists, is misguided, and if they use
what's in the manual to request that Emacs behaves the same, those
requests are misdirected.

Besides, your suggested changes don't produce results that are 100%
identical with what's in Info manuals, either, so how would you
explain the differences to those users?

> When the manual seeks to make an explicit example (with '<' instead of @key), it uses the logical style as well. See the examples used to illustrate the manual entry for the 'kbd' function itself.

That's the tiny minority of the examples you show, most of them are
unrelated to 'kbd'.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

1 jan. 2021 kl. 13.28 skrev Eli Zaretskii <eliz@gnu.org>:

>> But it is what users see when they read the manual in Info, so clearly they cannot be surprised or confused by it.
> 
> The users also see that in Info manuals that have nothing to do with
> Emacs, so their surprise, if it exists, is misguided, and if they use
> what's in the manual to request that Emacs behaves the same, those
> requests are misdirected.

I'm not sure what you mean by this paragraph... but it sounds like we agree, which of course makes me happy!

> Besides, your suggested changes don't produce results that are 100%
> identical with what's in Info manuals, either, so how would you
> explain the differences to those users?

Why do they have to be 100 % identical? That is not the reason for the change. The the manual was brought up to illustrate that the logical style is not foreign or confusing at all. Naturally I shall perform any corrections necessary in the documentation. As we have seen, this will not be much work.

> That's the tiny minority of the examples you show, most of them are
> unrelated to 'kbd'.

Which was precisely my point. The vast majority uses something like C-@key{...}. No change required here.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 1 Jan 2021 13:43:17 +0100
> Cc: larsi@gnus.org, 45536@debbugs.gnu.org
> 
> > Besides, your suggested changes don't produce results that are 100%
> > identical with what's in Info manuals, either, so how would you
> > explain the differences to those users?
> 
> Why do they have to be 100 % identical?

Because you use the differences that exist now as argument for the
change you proposed.  If the differences between what we have in Info
and what we have in describe-key are not important, then let's stop
using what the Info manual shows in this discussion.

> Naturally I shall perform any corrections necessary in the documentation. As we have seen, this will not be much work.

What do you mean?  The way @key and @kbd are rendered in an Info
manual are completely outside our control.

> > That's the tiny minority of the examples you show, most of them are
> > unrelated to 'kbd'.
> 
> Which was precisely my point. The vast majority uses something like C-@key{...}. No change required here.

But @key doesn't produce what your changes will produce, not exactly
anyway.  So why we are talking about @key as something related to the
issue at hand?

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

1 jan. 2021 kl. 13.54 skrev Eli Zaretskii <eliz@gnu.org>:

>> Why do they have to be 100 % identical?
> 
> Because you use the differences that exist now as argument for the
> change you proposed.  If the differences between what we have in Info
> and what we have in describe-key are not important, then let's stop
> using what the Info manual shows in this discussion.

We have been talking past one another; I am partly to blame. Please allow me to recap:

It was suggested earlier in the discussion that people might be confused about the meaning of M-<return> and that it therefore would be better to keep the old style <M-return> despite its shortcomings. The Info manual's apparent and pervasive use of the logical style indicates that such concerns are unlikely to be well-founded.

It is not an argument about how the manual (in any format) should present key bindings. Nor is the Info manual's style the reason for the change; it merely supports the claim that the logical style is well-understood and not controversial in the least.

The improvement demands no change from the users at all. Their code and init files will continue to work as before. They will occasionally see keys pretty-printed in a more logical way, in help screens and menus. It is not a momentous change but there is benefit, and no harm.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 1 Jan 2021 14:29:53 +0100
> Cc: larsi@gnus.org, 45536@debbugs.gnu.org
> 
> It was suggested earlier in the discussion that people might be confused about the meaning of M-<return> and that it therefore would be better to keep the old style <M-return> despite its shortcomings. The Info manual's apparent and pervasive use of the logical style indicates that such concerns are unlikely to be well-founded.
> 
> It is not an argument about how the manual (in any format) should present key bindings. Nor is the Info manual's style the reason for the change; it merely supports the claim that the logical style is well-understood and not controversial in the least.

I therefore suggest not to mention the Info manual's representation of
key sequences in this discussion at all.  The Info rendering of key
sequences is almost entirely unrelated to what Emacs does, and can
only confuse and muddy the waters (as it did here).

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Drew Adams]

> The only instance I could find of "M-<[a-z]" was this from the manual?
> (kbd "C-M-<down>") @result{} [C-M-down]

Which manual are we talking about?  And are we
talking about Info or a printed manual?

With Info:

In the Elisp manual, I see `M-<end>' and an
occurrence of (kbd "C-M-<down>").

In the Emacs manual, I see `C-<Delete>',
`M-<PageUp>, `M-<PageDown>', `M-<prior>',
`M-<next>', `M-<kp-8>', ...

(OK, some of those also have an uppercase
letter or a numeral.)

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 452 bytes --]

1 jan. 2021 kl. 12.54 skrev Lars Ingebrigtsen <larsi@gnus.org>:

> Oh, right.  Well, if the manual displays these keys as M-<foo> etc, then
> I withdraw all my objections based on possible confusion -- this change
> would make things less confusing.  So I'm leaning towards applying the
> change and then see whether this breaks anything for anybody.

Good, here is the elaborated patch, complete with NEWS entry, a few doc fixes, and tests.


[-- Attachment #2: 0001-Pretty-print-keys-without-around-modifiers-bug-45536.patch --]
[-- Type: application/octet-stream, Size: 5993 bytes --]

From a50b205b43471938b547e4aec4a517bae7ca162d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Tue, 29 Dec 2020 16:55:06 +0100
Subject: [PATCH] Pretty-print keys without <> around modifiers (bug#45536)

Be consistent when pretty-printing keys: put modifiers outside <>,
thus the more logical C-M-<return> instead of <C-M-return>.

* src/keymap.c (Fsingle_key_description):
Skip modifier prefix before adding <>.
* doc/lispref/help.texi (Describing Characters): Update example.
* doc/lispref/debugging.texi (Backtraces):
* doc/lispref/minibuf.texi (Text from Minibuffer):
Use @kbd instead of @key.
* etc/NEWS: Announce the change.
* test/src/keymap-tests.el (keymap--key-description):
* test/lisp/subr-tests.el (subr--kbd): New tests.
---
 doc/lispref/debugging.texi |  2 +-
 doc/lispref/help.texi      |  2 +-
 doc/lispref/minibuf.texi   |  2 +-
 etc/NEWS                   |  7 +++++++
 src/keymap.c               | 20 +++++++++++++++-----
 test/lisp/subr-tests.el    |  8 ++++++++
 test/src/keymap-tests.el   | 12 ++++++++++++
 7 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 1e779ac705..8e4b0ebfe9 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -424,7 +424,7 @@ Backtraces
 type @key{RET} while point is on any name of a function or variable
 which is not underlined, to see help information for that symbol in a
 help buffer, if any exists.  The @code{xref-find-definitions} command,
-bound to @key{M-.}, can also be used on any identifier in a backtrace
+bound to @kbd{M-.}, can also be used on any identifier in a backtrace
 (@pxref{Looking Up Identifiers,,,emacs, The GNU Emacs Manual}).
 
 In backtraces, the tails of long lists and the ends of long strings,
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 2fd05b7391..298bec5230 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -545,7 +545,7 @@ Describing Characters
 @end group
 @group
 (single-key-description 'C-mouse-1)
-     @result{} "<C-mouse-1>"
+     @result{} "C-<mouse-1>"
 @end group
 @group
 (single-key-description 'C-mouse-1 t)
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 81139b9e74..f0036f0ccf 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -348,7 +348,7 @@ Text from Minibuffer
 @item @key{RET}
 @code{exit-minibuffer}
 
-@item @key{M-<}
+@item @kbd{M-<}
 @code{minibuffer-beginning-of-buffer}
 
 @item @kbd{C-g}
diff --git a/etc/NEWS b/etc/NEWS
index b294ff1d23..671c6c2f56 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -212,6 +212,13 @@ This makes debugging Emacs Lisp scripts run in batch mode easier.  To
 get back the old behavior, set the new variable
 'backtrace-on-error-noninteractive' to a nil value.
 
++++
+** Modifiers now go outside angle brackets in pretty-printed key bindings.
+For example, <return> with Control and Meta modifiers is now shown as
+C-M-<return> instead of <C-M-return>.  Either variant can be used as
+input; functions such as 'kbd' and 'read-kbd-macro' accept both styles
+as equivalent (they have done so for a long time).
+
 \f
 * Editing Changes in Emacs 28.1
 
diff --git a/src/keymap.c b/src/keymap.c
index 1eeea81f62..a91f1456a6 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2217,11 +2217,21 @@ DEFUN ("single-key-description", Fsingle_key_description,
     {
       if (NILP (no_angles))
 	{
-	  Lisp_Object result;
-	  char *buffer = SAFE_ALLOCA (sizeof "<>"
-				      + SBYTES (SYMBOL_NAME (key)));
-	  esprintf (buffer, "<%s>", SDATA (SYMBOL_NAME (key)));
-	  result = build_string (buffer);
+	  Lisp_Object namestr = SYMBOL_NAME (key);
+	  const char *sym = SSDATA (namestr);
+	  ptrdiff_t len = SBYTES (namestr);
+	  /* Find the extent of the modifier prefix, like "C-M-". */
+	  int i = 0;
+	  while (i < len - 3 && sym[i + 1] == '-' && strchr ("CMSsHA", sym[i]))
+	    i += 2;
+	  /* First I bytes of SYM are modifiers; put <> around the rest. */
+	  char *buffer = SAFE_ALLOCA (len + 3);
+	  memcpy (buffer, sym, i);
+	  buffer[i] = '<';
+	  memcpy (buffer + i + 1, sym + i, len - i);
+	  buffer [len + 1] = '>';
+	  buffer [len + 2] = '\0';
+	  Lisp_Object result = build_string (buffer);
 	  SAFE_FREE ();
 	  return result;
 	}
diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el
index 2f5b38d05d..8d19a26877 100644
--- a/test/lisp/subr-tests.el
+++ b/test/lisp/subr-tests.el
@@ -630,5 +630,13 @@ apropos-apropos-internal/predicate
   (should (>= (length (apropos-internal "^help" #'commandp)) 15))
   (should-not (apropos-internal "^next-line$" #'keymapp)))
 
+(ert-deftest subr--kbd ()
+  ;; Check that kbd handles both new and old style key descriptions
+  ;; (bug#45536).
+  (should (equal (kbd "s-<return>") [s-return]))
+  (should (equal (kbd "<s-return>") [s-return]))
+  (should (equal (kbd "C-M-<return>") [C-M-return]))
+  (should (equal (kbd "<C-M-return>") [C-M-return])))
+
 (provide 'subr-tests)
 ;;; subr-tests.el ends here
diff --git a/test/src/keymap-tests.el b/test/src/keymap-tests.el
index 74fb3c892d..d4f5fc3f19 100644
--- a/test/src/keymap-tests.el
+++ b/test/src/keymap-tests.el
@@ -248,6 +248,18 @@ help--describe-vector/bug-9293-same-command-does-not-shadow
 0 .. 3		foo
 ")))))
 
+(ert-deftest keymap--key-description ()
+  (should (equal (key-description [right] [?\C-x])
+                 "C-x <right>"))
+  (should (equal (key-description [M-H-right] [?\C-x])
+                 "C-x M-H-<right>"))
+  (should (equal (single-key-description 'home)
+                 "<home>"))
+  (should (equal (single-key-description 'home t)
+                 "home"))
+  (should (equal (single-key-description 'C-s-home)
+                 "C-s-<home>")))
+
 (provide 'keymap-tests)
 
 ;;; keymap-tests.el ends here
-- 
2.21.1 (Apple Git-122.3)

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Drew Adams]

> > Oh, right.  Well, if the manual displays these keys as M-<foo> etc, then
> > I withdraw all my objections based on possible confusion -- this change
> > would make things less confusing.  So I'm leaning towards applying the
> > change and then see whether this breaks anything for anybody.
> 
> Good, here is the elaborated patch, complete with NEWS entry, a few doc
> fixes, and tests.

FWIW, I think the manuals and Emacs help (`*Help*')
should use the same syntax.  What you see when you
ask Emacs for help interactively should be what
you see when you access the manuals.  And that same
syntax should be what `kbd' accepts as input.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

2 jan. 2021 kl. 18.20 skrev Mattias Engdegård <mattiase@acm.org>:

> Good, here is the elaborated patch, complete with NEWS entry, a few doc fixes, and tests.

Not much of contention here; pushed. As always, I'm happy to carry out any necessary changes.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Mattias Engdegård]

2 jan. 2021 kl. 19.25 skrev Drew Adams <drew.adams@oracle.com>:

> FWIW, I think the manuals and Emacs help (`*Help*')
> should use the same syntax.  What you see when you
> ask Emacs for help interactively should be what
> you see when you access the manuals.  And that same
> syntax should be what `kbd' accepts as input.

Most people would probably agree to something along those lines, but then one realises that there are other constraints that forces us to compromise. In any case, this strays beyond the deliberately narrow scope of this bug.

bug#45536: [PATCH] Pretty-print keys without <> around modifiers

[Lars Ingebrigtsen]

Mattias Engdegård <mattiase@acm.org> writes:

> 2 jan. 2021 kl. 18.20 skrev Mattias Engdegård <mattiase@acm.org>:
>
>> Good, here is the elaborated patch, complete with NEWS entry, a few
>> doc fixes, and tests.
>
> Not much of contention here; pushed. As always, I'm happy to carry out
> any necessary changes.

Looks good to me, and this was many months ago, so I guess there wasn't
any outpouring of protests.  :-)  So I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no