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.

8 files changed, 61 insertions, 33 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 72244c6dfa9..6783e843110 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2012-07-17  Chong Yidong  <cyd@gnu.org>
+
+        * basic.texi (Inserting Text): Replace ucs-insert with
+        insert-char.  Provide more details of input.
+
+        * mule.texi (International Chars, Input Methods): Likewise.
+
 2012-07-13  Chong Yidong  <cyd@gnu.org>
 
         * custom.texi (Examining): Update C-h v message.
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 9c4b303d282..16ccdba0866 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -97,28 +97,29 @@ To use decimal or hexadecimal instead of octal, set the variable
 the letters @kbd{a} to @kbd{f} serve as part of a character code,
 just like digits.  Case is ignored.
 
-@findex ucs-insert
+@findex insert-char
 @kindex C-x 8 RET
 @cindex Unicode characters, inserting
 @cindex insert Unicode character
 @cindex characters, inserting by name or code-point
-  Instead of @kbd{C-q}, you can use the command @kbd{C-x 8 @key{RET}}
-(@code{ucs-insert}).  This prompts for the Unicode name or code-point
+  Alternatively, you can use the command @kbd{C-x 8 @key{RET}}
+(@code{insert-char}).  This prompts for the Unicode name or code-point
 of a character, using the minibuffer.  If you enter a name, the
 command provides completion (@pxref{Completion}).  If you enter a
-code-point, it should be a hexadecimal number (which is the convention
-for Unicode).  The command then inserts the corresponding character
-into the buffer.  For example, both of the following insert the
-infinity sign (Unicode code-point @code{U+221E}):
+code-point, it should be as a hexadecimal number (the convention for
+Unicode), or a number with a specified radix, e.g.@: @code{#o23072}
+(octal); @xref{Integer Basics,,, elisp, The Emacs Lisp Reference
+Manual}.  The command then inserts the corresponding character into
+the buffer.  For example, both of the following insert the infinity
+sign (Unicode code-point @code{U+221E}):
 
 @example
 @kbd{C-x 8 @key{RET} infinity @key{RET}}
 @kbd{C-x 8 @key{RET} 221e @key{RET}}
 @end example
 
-  A numeric argument to either @kbd{C-q} or @kbd{C-x 8 @key{RET}}
-specifies how many copies of the character to insert
-(@pxref{Arguments}).
+  A numeric argument to @kbd{C-q} or @kbd{C-x 8 @key{RET}} specifies
+how many copies of the character to insert (@pxref{Arguments}).
 
 @node Moving Point
 @section Changing the Location of Point
diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index 59e945eee96..1dfae79c788 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -146,7 +146,7 @@ displayed on your terminal, they appear as @samp{?} or as hollow boxes
 used, generally don't have keys for all the characters in them.  You
 can insert characters that your keyboard does not support, using
 @kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}}
-(@code{ucs-insert}).  @xref{Inserting Text}.  Emacs also supports
+(@code{insert-char}).  @xref{Inserting Text}.  Emacs also supports
 various @dfn{input methods}, typically one for each script or
 language, which make it easier to type characters in the script.
 @xref{Input Methods}.
@@ -548,7 +548,7 @@ possible characters to type next is displayed in the echo area (but
 not when you are in the minibuffer).
 
   Another facility for typing characters not on your keyboard is by
-using @kbd{C-x 8 @key{RET}} (@code{ucs-insert}) to insert a single
+using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single
 character based on its Unicode name or code-point; see @ref{Inserting
 Text}.
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5378cc16cdb..bc01d64c509 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2012-07-17  Chong Yidong  <cyd@gnu.org>
+
+        * text.texi (Insertion): Document insert-char changes.
+
 2012-07-15  Leo Liu  <sdl.web@gmail.com>
 
         * display.texi (Fringe Bitmaps): Add exclamation-mark.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index c1e12ccf3a3..d115322f84f 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -401,19 +401,23 @@ ends at the insertion point, the inserted text falls inside that
 overlay.
 @end defun
 
-@defun insert-char character count &optional inherit
-This function inserts @var{count} instances of @var{character} into the
-current buffer before point.  The argument @var{count} should be an
-integer, and @var{character} must be a character.  The value is @code{nil}.
+@deffn Command insert-char character &optional count inherit
+This command inserts @var{count} instances of @var{character} into the
+current buffer before point.  The argument @var{count} must be an
+integer, and @var{character} must be a character.
+
+If called interactively, this command prompts for @var{character}
+using its Unicode name or its code point.  @xref{Inserting Text,,,
+emacs, The GNU Emacs Manual}.
 
 This function does not convert unibyte character codes 128 through 255
 to multibyte characters, not even if the current buffer is a multibyte
 buffer.  @xref{Converting Representations}.
 
-If @var{inherit} is non-@code{nil}, then the inserted characters inherit
+If @var{inherit} is non-@code{nil}, the inserted characters inherit
 sticky text properties from the two characters before and after the
 insertion point.  @xref{Sticky Properties}.
-@end defun
+@end deffn
 
 @defun insert-buffer-substring from-buffer-or-name &optional start end
 This function inserts a portion of buffer @var{from-buffer-or-name}
diff --git a/etc/NEWS b/etc/NEWS
index 9eac4af64a3..bf7880bd1ac 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -140,6 +140,7 @@ invokes `set-buffer-file-coding-system'.
 ** Setting `enable-remote-dir-locals' to non-nil allows directory
 local variables on remote hosts.
 
++++
 ** `insert-char' is now a command, and `ucs-insert' an obsolete alias
 for it.
 
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;