Improve doc string and display of 'describe-character'

* lisp/descr-text.el (describe-char): Explain how does the
function obtain the various data about the character.  Don't
display "preferred" before "charset": it tends to confuse
people.

1 files changed, 17 insertions, 8 deletions

diff --git a/lisp/descr-text.el b/lisp/descr-text.el
index 00b40826f48..517e2895cb4 100644
--- a/lisp/descr-text.el
+++ b/lisp/descr-text.el
@@ -386,13 +386,22 @@ The position information includes POS; the total size of BUFFER; the
 region limits, if narrowed; the column number; and the horizontal
 scroll amount, if the buffer is horizontally scrolled.
 
-The character information includes the character code; charset and
-code points in it; syntax; category; how the character is encoded in
-BUFFER and in BUFFER's file; character composition information (if
-relevant); the font and font glyphs used to display the character;
-the character's canonical name and other properties defined by the
-Unicode Data Base; and widgets, buttons, overlays, and text properties
-relevant to POS."
+The character information includes:
+ its codepoint;
+ its charset (see `char-charset'), overridden by the `charset' text
+   property at POS, if any;
+ the codepoint of the character in the above charset;
+ the character's script (as defined by `char-script-table')
+ the character's syntax, as produced by `syntax-after'
+   and `internal-describe-syntax-value';
+ its category (see `char-category-set' and `describe-char-categories');
+ how to input the character using the keyboard and input methods;
+ how the character is encoded in BUFFER and in BUFFER's file;
+ the font and font glyphs used to display the character;
+ the composition information for displaying the character (if relevant);
+ the character's canonical name and other properties defined by the
+   Unicode Data Base;
+ and widgets, buttons, overlays, and text properties relevant to POS."
   (interactive "d")
   (unless (buffer-live-p buffer) (setq buffer (current-buffer)))
   (let ((src-buf (current-buffer)))
@@ -562,7 +571,7 @@ relevant to POS."
                         (apply 'propertize char-description
                                (text-properties-at pos))
                         char char char))
-              ("preferred charset"
+              ("charset"
                ,`(insert-text-button
                   ,(symbol-name charset)
                   'type 'help-character-set 'help-args '(,charset))