Commit d28d54c7 authored by Eli Zaretskii's avatar Eli Zaretskii

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)
parent b3baf997
......@@ -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
......
......@@ -2286,7 +2286,8 @@ push_text_char_description (register unsigned int c, register char *p)
DEFUN ("text-char-description", Ftext_char_description, Stext_char_description, 1, 1, 0,
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.
Control characters turn into "^char", and characters with Meta and other
modifiers signal an error, as they are not valid characterr codes.
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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment