Document insert-char changes.

* doc/emacs/basic.texi (Inserting Text): Replace ucs-insert with
insert-char.  Provide more details of input.

* doc/lispref/mule.texi (International Chars, Input Methods): Likewise.

* doc/lispref/text.texi (Insertion): Document insert-char changes.

* src/editfns.c (Finsert_char): Doc fix.

2 files changed, 26 insertions, 15 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index 8c8ba4dd143..82bedfdf2c4 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2012-07-17  Chong Yidong  <cyd@gnu.org>
+
+	* editfns.c (Finsert_char): Doc fix.
+
 2012-07-17  Dmitry Antipov  <dmantipov@yandex.ru>
 
 	Fix previous change to make Fmemory_free always accurate.
diff --git a/src/editfns.c b/src/editfns.c
index 5dc561a400e..9cfd0449daa 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -2369,27 +2369,34 @@ usage: (insert-before-markers-and-inherit &rest ARGS)  */)
 }
 
 DEFUN ("insert-char", Finsert_char, Sinsert_char, 1, 3,
-       "(list (read-char-by-name \"Unicode (name or hex): \")\
+       "(list (read-char-by-name \"Insert character (Unicode name or hex): \")\
 	 (prefix-numeric-value current-prefix-arg)\
 	 t))",
        doc: /* Insert COUNT copies of CHARACTER.
-Interactively, prompts for a Unicode character name or a hex number
-using `read-char-by-name'.
+Interactively, prompt for CHARACTER.  You can specify CHARACTER in one
+of these ways:
 
-You can type a few of the first letters of the Unicode name and
-use completion.  If you type a substring of the Unicode name
-preceded by an asterisk `*' and use completion, it will show all
-the characters whose names include that substring, not necessarily
-at the beginning of the name.
+ - As its Unicode character name, e.g. \"LATIN SMALL LETTER A\".
+   Completion is available; if you type a substring of the name
+   preceded by an asterisk `*', Emacs shows all names which include
+   that substring, not necessarily at the beginning of the name.
 
-This function also accepts a hexadecimal number of Unicode code
-point or a number in hash notation, e.g. #o21430 for octal,
-#x2318 for hex, or #10r8984 for decimal.
+ - As a hexadecimal code point, e.g. 263A.  Note that code points in
+   Emacs are equivalent to Unicode up to 10FFFF (which is the limit of
+   the Unicode code space).
 
-Point, and before-insertion markers, are relocated as in the function `insert'.
-The optional third arg INHERIT, if non-nil, says to inherit text properties
-from adjoining text, if those properties are sticky.  If called
-interactively, INHERIT is t.  */)
+ - As a code point with a radix specified with #, e.g. #o21430
+   (octal), #x2318 (hex), or #10r8984 (decimal).
+
+If called interactively, COUNT is given by the prefix argument.  If
+omitted or nil, it defaults to 1.
+
+Inserting the character(s) relocates point and before-insertion
+markers in the same ways as the function `insert'.
+
+The optional third argument INHERIT, if non-nil, says to inherit text
+properties from adjoining text, if those properties are sticky.  If
+called interactively, INHERIT is t.  */)
   (Lisp_Object character, Lisp_Object count, Lisp_Object inherit)
 {
   int i, stringlen;