More accurate docs for 'text-char-description'

* src/keymap.c (Ftext_char_description):
* doc/lispref/help.texi (Describing Characters): More accurate
description of 'text-char-description'.  Remove incorrect
examples from the ELisp manual.  (Bug#32743)

1 files changed, 10 insertions, 20 deletions

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index a23bc413d25..2688a2bff6e 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -556,13 +556,15 @@ brackets.
 
 @defun text-char-description character
 This function returns a string describing @var{character} in the
-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.
+standard Emacs notation for characters that can appear in
+text---similar to @code{single-key-description}, except that the
+argument must be a valid character code that passes a
+@code{characterp} test (@pxref{Character Codes}).  The function
+produces descriptions of control characters with a leading caret
+(which is how Emacs usually displays control characters in buffers).
+Characters with modifier bits will cause this function to signal an
+error (@acronym{ASCII} characters with the Control modifier are an
+exception, they are represented as control characters).
 
 @smallexample
 @group
@@ -571,19 +573,7 @@ whereas @code{single-key-description} uses the 2**27 bit for Meta.
 @end group
 @group
 (text-char-description ?\M-m)
-     @result{} "\xed"
-@end group
-@group
-(text-char-description ?\C-\M-m)
-     @result{} "\x8d"
-@end group
-@group
-(text-char-description (+ 128 ?m))
-     @result{} "M-m"
-@end group
-@group
-(text-char-description (+ 128 ?\C-m))
-     @result{} "M-^M"
+     @error{} Wrong type argument: characterp, 134217837
 @end group
 @end smallexample
 @end defun