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)

1 files changed, 10 insertions, 7 deletions

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)
 {