procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More accurate docs for 'text-char-description'

Browse source 
* 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)
This commit is contained in:
Eli Zaretskii 2018-09-20 09:41:55 +03:00
parent b3baf997c8
commit d28d54c767
2 changed files with 12 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

30
doc/lispref/help.texi
View file

@ -556,13 +556,15 @@ brackets.
@defun text-char-description character @defun text-char-description character
This function returns a string describing @var{character} in the This function returns a string describing @var{character} in the
standard Emacs notation for characters that can appear in text---like standard Emacs notation for characters that can appear in
@code{single-key-description}, except that the argument must be a text---similar to @code{single-key-description}, except that the
valid character code that passes a @code{characterp} test argument must be a valid character code that passes a
(@pxref{Character Codes}), control characters are represented with a @code{characterp} test (@pxref{Character Codes}). The function
leading caret (which is how control characters in Emacs buffers are produces descriptions of control characters with a leading caret
usually displayed), and the 2**7 bit is treated as the Meta bit, (which is how Emacs usually displays control characters in buffers).
whereas @code{single-key-description} uses the 2**27 bit for Meta. 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 @smallexample
@group @group
@ -571,19 +573,7 @@ whereas @code{single-key-description} uses the 2**27 bit for Meta.
@end group @end group
@group @group
(text-char-description ?\M-m) (text-char-description ?\M-m)
@result{} "\xed" @error{} Wrong type argument: characterp, 134217837
@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"
@end group @end group
@end smallexample @end smallexample
@end defun @end defun

3
src/keymap.c
View file

@ -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, DEFUN ("text-char-description", Ftext_char_description, Stext_char_description, 1, 1, 0,
doc: /* Return the description of CHARACTER in standard Emacs notation. doc: /* Return the description of CHARACTER in standard Emacs notation.
CHARACTER must be a valid character code that passes the `characterp' test. 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, This differs from `single-key-description' which accepts character events,
and thus doesn't enforce the `characterp' condition, turns control and thus doesn't enforce the `characterp' condition, turns control
characters into "C-char", and uses the 2**27 bit for Meta. characters into "C-char", and uses the 2**27 bit for Meta.