emacs-29 6dda2106ec: ; Improve documentation of "C-x @"

[Eli Zaretskii]

branch: emacs-29
commit 6dda2106ece7c307ed5c0a6cb892e736516effeb
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of "C-x @"
    
    * doc/emacs/custom.texi (Modifier Keys): Document how to enter
    Shift, Control, and Meta using "C-x @".
    
    * lisp/simple.el (function-key-map): Add commentary to "C-x @"
    bindings to make them easier to discover.
---
 doc/emacs/custom.texi | 6 +++++-
 lisp/simple.el        | 2 ++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index aaf41d2aef..f75512a00e 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1990,13 +1990,17 @@ to assign meanings to key bindings that use these 
modifiers.  The
 modifier bits are labeled as @samp{s-}, @samp{H-} and @samp{A-}
 respectively.
 
+@cindex modifier keys unsupported by keyboard
   Even if your keyboard lacks these additional modifier keys, you can
-enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the Hyper flag to
+enter them using @kbd{C-x @@}: @kbd{C-x @@ h} adds the Hyper flag to
 the next character, @kbd{C-x @@ s} adds the Super flag, and
 @kbd{C-x @@ a} adds the Alt flag.  For instance, @kbd{C-x @@ h
 C-a} is a way to enter @kbd{Hyper-Control-a}.  (Unfortunately, there
 is no way to add two modifiers by using @kbd{C-x @@} twice for the
 same character, because the first one goes to work on the @kbd{C-x}.)
+You can similarly enter the Shift, Control, and Meta modifiers by
+using @kbd{C-x @ S}, @kbd{C-x @ c}, and @kbd{C-x @ m}, respectively,
+although this is rarely needed.
 
 @node Function Keys
 @subsection Rebinding Function Keys
diff --git a/lisp/simple.el b/lisp/simple.el
index f85428ca74..4551b749d5 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -10053,6 +10053,8 @@ PREFIX is the string that represents this modifier in 
an event type symbol."
            event-type
          (cons event-type (cdr event)))))))
 
+;; This is what makes "C-x @" followed by [hsmaSc] work even though
+;; you won't find any (define-key ctl-x-map "@" ...) binding.
 (define-key function-key-map [?\C-x ?@ ?h] 'event-apply-hyper-modifier)
 (define-key function-key-map [?\C-x ?@ ?s] 'event-apply-super-modifier)
 (define-key function-key-map [?\C-x ?@ ?m] 'event-apply-meta-modifier)