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

2 files changed, 7 insertions, 1 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index aaf41d2aef1..f75512a00e9 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 f85428ca740..4551b749d56 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)