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)

4 files changed, 73 insertions, 42 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
diff --git a/src/keymap.c b/src/keymap.c
index c8cc933e782..ec483c7a632 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2205,10 +2205,12 @@ push_key_description (EMACS_INT ch, char *p)
 
 DEFUN ("single-key-description", Fsingle_key_description,
        Ssingle_key_description, 1, 2, 0,
-       doc: /* Return a pretty description of command character KEY.
+       doc: /* Return a pretty description of a character event KEY.
 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.  */)
+around function keys and event symbols.
+
+See `text-char-description' for describing character codes.  */)
   (Lisp_Object key, Lisp_Object no_angles)
 {
   USE_SAFE_ALLOCA;
@@ -2282,11 +2284,12 @@ push_text_char_description (register unsigned int c, register char *p)
 /* This function cannot GC.  */
 
 DEFUN ("text-char-description", Ftext_char_description, Stext_char_description, 1, 1, 0,
-       doc: /* Return a pretty description of file-character CHARACTER.
-Control characters turn into "^char", etc.  This differs from
-`single-key-description' which turns them into "C-char".
-Also, this function recognizes the 2**7 bit as the Meta character,
-whereas `single-key-description' uses the 2**27 bit for Meta.
+       doc: /* Return the description of CHARACTER in standard Emacs notation.
+CHARACTER must be a valid character code that passes the `characterp' test.
+Control characters turn into "^char", the 2**7 bit is treated as Meta, etc.
+This differs from `single-key-description' which accepts character events,
+and thus doesn't enforce the `characterp' condition, turns control
+characters into "C-char", and uses the 2**27 bit for Meta.
 See Info node `(elisp)Describing Characters' for examples.  */)
   (Lisp_Object character)
 {
diff --git a/src/lread.c b/src/lread.c
index d5ba48a170d..2e5cba510c5 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -735,10 +735,14 @@ read_filtered_event (bool no_switch_frame, bool ascii_required,
 }
 
 DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
-       doc: /* Read a character from the command input (keyboard or macro).
+       doc: /* Read a character event from the command input (keyboard or macro).
 It is returned as a number.
-If the character has modifiers, they are resolved and reflected to the
-character code if possible (e.g. C-SPC -> 0).
+If the event has modifiers, they are resolved and reflected in the
+returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
+If some of the modifiers cannot be reflected in the character code, the
+returned value will include those modifiers, and will not be a valid
+character code: it will fail the `characterp' test.  Use `event-basic-type'
+to recover the character code with the modifiers removed.
 
 If the user generates an event which is not a character (i.e. a mouse
 click or function key event), `read-char' signals an error.  As an
@@ -785,10 +789,14 @@ floating-point value.  */)
 }
 
 DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
-       doc: /* Read a character from the command input (keyboard or macro).
+       doc: /* Read a character event from the command input (keyboard or macro).
 It is returned as a number.  Non-character events are ignored.
-If the character has modifiers, they are resolved and reflected to the
-character code if possible (e.g. C-SPC -> 0).
+If the event has modifiers, they are resolved and reflected in the
+returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
+If some of the modifiers cannot be reflected in the character code, the
+returned value will include those modifiers, and will not be a valid
+character code: it will fail the `characterp' test.  Use `event-basic-type'
+to recover the character code with the modifiers removed.
 
 If the optional argument PROMPT is non-nil, display that as a prompt.
 If the optional argument INHERIT-INPUT-METHOD is non-nil and some