From d28d54c76754759e5f0fc8254541fbb4ef6a21d8 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 20 Sep 2018 09:41:55 +0300 Subject: [PATCH] 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) --- doc/lispref/help.texi | 30 ++++++++++-------------------- src/keymap.c | 3 ++- 2 files changed, 12 insertions(+), 21 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 diff --git a/src/keymap.c b/src/keymap.c index ec483c7a632..fe0781a7f2a 100644 --- a/src/keymap.c +++ b/src/keymap.c @@ -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. -- 2.39.2