Clarify documentation of functions reading character events

* doc/lispref/help.texi (Describing Characters):
* doc/lispref/commands.texi (Keyboard Events)
(Reading One Event, Classifying Events): Make the distinction
between characters and character events more explicit.

* src/keymap.c (Ftext_char_description)
(Fsingle_key_description):
* src/lread.c (Fread_char, Fread_char_exclusive): Doc fixes,
to make a clear distinction between a character input event
and a character code.  (Bug#32562)

2 files changed, 49 insertions, 29 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 0753d6fb67c..3e74f05e4c8 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1076,9 +1076,10 @@ the current Emacs session.  If a symbol has not yet been so used,
 @cindex keyboard events
 
 There are two kinds of input you can get from the keyboard: ordinary
-keys, and function keys.  Ordinary keys correspond to characters; the
-events they generate are represented in Lisp as characters.  The event
-type of a character event is the character itself (an integer); see
+keys, and function keys.  Ordinary keys correspond to (possibly
+modified) characters; the events they generate are represented in Lisp
+as characters.  The event type of a character event is the character
+itself (an integer), which might have some modifier bits set; see
 @ref{Classifying Events}.
 
 @cindex modifier bits (of input character)
@@ -1123,7 +1124,7 @@ for @kbd{%} plus
 2**26
 @end ifnottex
 (assuming the terminal supports non-@acronym{ASCII}
-control characters).
+control characters), i.e.@: with the 27th bit set.
 
 @item shift
 The
@@ -1133,8 +1134,8 @@ The
 @ifnottex
 2**25
 @end ifnottex
-bit in the character code indicates an @acronym{ASCII} control
-character typed with the shift key held down.
+bit (the 26th bit) in the character event code indicates an
+@acronym{ASCII} control character typed with the shift key held down.
 
 For letters, the basic code itself indicates upper versus lower case;
 for digits and punctuation, the shift key selects an entirely different
@@ -1146,7 +1147,7 @@ character with a different basic code.  In order to keep within the
 @ifnottex
 2**25
 @end ifnottex
-bit for those characters.
+bit for those character events.
 
 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
 @kbd{C-a}, so Emacs uses the
@@ -1167,7 +1168,7 @@ The
 @ifnottex
 2**24
 @end ifnottex
-bit in the character code indicates a character
+bit in the character event code indicates a character
 typed with the hyper key held down.
 
 @item super
@@ -1178,7 +1179,7 @@ The
 @ifnottex
 2**23
 @end ifnottex
-bit in the character code indicates a character
+bit in the character event code indicates a character
 typed with the super key held down.
 
 @item alt
@@ -1189,9 +1190,9 @@ The
 @ifnottex
 2**22
 @end ifnottex
-bit in the character code indicates a character typed with the alt key
-held down.  (The key labeled @key{Alt} on most keyboards is actually
-treated as the meta key, not this.)
+bit in the character event code indicates a character typed with the
+alt key held down.  (The key labeled @key{Alt} on most keyboards is
+actually treated as the meta key, not this.)
 @end table
 
   It is best to avoid mentioning specific bit numbers in your program.
@@ -1949,6 +1950,10 @@ Here are some examples:
 
 The modifiers list for a click event explicitly contains @code{click},
 but the event symbol name itself does not contain @samp{click}.
+Similarly, the modifiers list for an @acronym{ASCII} control
+character, such as @samp{C-a}, contains @code{control}, even though
+reading such an event via @code{read-char} will return the value 1
+with the control modifier bit removed.
 @end defun
 
 @defun event-basic-type event
@@ -2545,17 +2550,31 @@ right-arrow function key:
 @end defun
 
 @defun read-char &optional prompt inherit-input-method seconds
-This function reads and returns a character of command input.  If the
+This function reads and returns a character input event.  If the
 user generates an event which is not a character (i.e., a mouse click or
 function key event), @code{read-char} signals an error.  The arguments
 work as in @code{read-event}.
 
-In the first example, the user types the character @kbd{1} (@acronym{ASCII}
-code 49).  The second example shows a keyboard macro definition that
-calls @code{read-char} from the minibuffer using @code{eval-expression}.
-@code{read-char} reads the keyboard macro's very next character, which
-is @kbd{1}.  Then @code{eval-expression} displays its return value in
-the echo area.
+If the event has modifiers, Emacs attempts to resolve them and return
+the code of the corresponding character.  For example, if the user
+types @kbd{C-a}, the function returns 1, which is the @acronym{ASCII}
+code of the @samp{C-a} character.  If some of the modifiers cannot be
+reflected in the character code, @code{read-char} leaves the
+unresolved modifier bits set in the returned event.  For example, if
+the user types @kbd{C-M-a}, the function returns 134217729, 8000001 in
+hex, i.e.@: @samp{C-a} with the Meta modifier bit set.  This value is
+not a valid character code: it fails the @code{characterp} test
+(@pxref{Character Codes}).  Use @code{event-basic-type}
+(@pxref{Classifying Events}) to recover the character code with the
+modifier bits removed; use @code{event-modifiers} to test for
+modifiers in the character event returned by @code{read-char}.
+
+In the first example below, the user types the character @kbd{1}
+(@acronym{ASCII} code 49).  The second example shows a keyboard macro
+definition that calls @code{read-char} from the minibuffer using
+@code{eval-expression}.  @code{read-char} reads the keyboard macro's
+very next character, which is @kbd{1}.  Then @code{eval-expression}
+displays its return value in the echo area.
 
 @example
 @group
@@ -2577,10 +2596,11 @@ the echo area.
 @end defun
 
 @defun read-char-exclusive &optional prompt inherit-input-method seconds
-This function reads and returns a character of command input.  If the
-user generates an event which is not a character,
+This function reads and returns a character input event.  If the
+user generates an event which is not a character event,
 @code{read-char-exclusive} ignores it and reads another event, until it
-gets a character.  The arguments work as in @code{read-event}.
+gets a character.  The arguments work as in @code{read-event}.  The
+returned value may include modifier bits, as with @code{read-char}.
 @end defun
 
   None of the above functions suppress quitting.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 6dd55d0b256..a23bc413d25 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -556,13 +556,13 @@ brackets.
 
 @defun text-char-description character
 This function returns a string describing @var{character} in the
-standard Emacs notation for characters that appear in text---like
-@code{single-key-description}, except that control characters are
-represented with a leading caret (which is how control characters in
-Emacs buffers are usually displayed).  Another difference is that
-@code{text-char-description} recognizes the 2**7 bit as the Meta
-character, whereas @code{single-key-description} uses the 2**27 bit
-for Meta.
+standard Emacs notation for characters that can appear in text---like
+@code{single-key-description}, except that the argument must be a
+valid character code that passes a @code{characterp} test
+(@pxref{Character Codes}), control characters are represented with a
+leading caret (which is how control characters in Emacs buffers are
+usually displayed), and the 2**7 bit is treated as the Meta bit,
+whereas @code{single-key-description} uses the 2**27 bit for Meta.
 
 @smallexample
 @group