Merge changes from emacs-23 branch

10 files changed, 90 insertions, 74 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index d1c2d861eb7..c6d851f55ec 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,33 @@
+2010-11-27  Chong Yidong  <cyd@stupidchicken.com>
+
+        * nonascii.texi (Converting Representations): Document
+        byte-to-string.
+
+        * strings.texi (Creating Strings): Don't mention semi-obsolete
+        function char-to-string.
+        (String Conversion): Shorten discussion of semi-obsolete function
+        string-to-char.  Link to Converting Representations.
+
+        * objects.texi (Symbol Type):
+        * text.texi (Near Point):
+        * help.texi (Help Functions):
+        * functions.texi (Mapping Functions): Use string instead of
+        char-to-string in examples.
+
+2010-11-27  Chong Yidong  <cyd@stupidchicken.com>
+
+        * text.texi (Kill Functions, Kill Functions)
+        (Low-Level Kill Ring, Low-Level Kill Ring): Remove obsolete
+        YANK-HANDLER args.
+
+        * symbols.texi (Creating Symbols): Using unintern without an
+        obarray arg is now obsolete.
+
+        * numbers.texi (Float Basics): Document float-e and float-pi.
+
+        * variables.texi (Defining Variables): Change "pi" example to
+        "float-pi".
+
 2010-11-26  Eli Zaretskii  <eliz@gnu.org>
 
         * commands.texi (Click Events): Document the values of X, Y and
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 6f3fd63013c..635245426fb 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -818,7 +818,7 @@ length of @var{sequence}.  For example:
      @result{} (a c e)
 (mapcar '1+ [1 2 3])
      @result{} (2 3 4)
-(mapcar 'char-to-string "abc")
+(mapcar 'string "abc")
      @result{} ("a" "b" "c")
 @end group
 
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index d3e289578c0..f21e16e104a 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -546,7 +546,7 @@ follows:
 
 @smallexample
 @group
-(define-key global-map (char-to-string help-char) 'help-command)
+(define-key global-map (string help-char) 'help-command)
 (fset 'help-command help-map)
 @end group
 @end smallexample
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 40c78d97da7..1c196c93f27 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -199,6 +199,13 @@ unibyte string, it is returned unchanged.  Use this function for
 characters.
 @end defun
 
+@defun byte-to-string byte
+@cindex byte to string
+This function returns a unibyte string containing a single byte of
+character data, @var{character}.  It signals a error if
+@var{character} is not an integer between 0 and 255.
+@end defun
+
 @defun multibyte-char-to-unibyte char
 This converts the multibyte character @var{char} to a unibyte
 character, and returns that character.  If @var{char} is neither
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 62b4796350e..e83da348e05 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -224,6 +224,14 @@ down to an integer.
 @end example
 @end defun
 
+@defvar float-e
+The mathematical constant @math{e} (2.71828@dots{}).
+@end defvar
+
+@defvar float-pi
+The mathematical constant @math{pi} (3.14159@dots{}).
+@end defvar
+
 @node Predicates on Numbers
 @section Type Predicates for Numbers
 @cindex predicates for numbers
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index c8ccb15a2d3..8f72cc01680 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -582,7 +582,6 @@ makes it invalid as a number.
 @group
 foo                 ; @r{A symbol named @samp{foo}.}
 FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
-char-to-string      ; @r{A symbol named @samp{char-to-string}.}
 @end group
 @group
 1+                  ; @r{A symbol named @samp{1+}}
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 1128ca87d8a..94d2765a833 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -126,9 +126,8 @@ This function returns a string made up of @var{count} repetitions of
      @result{} ""
 @end example
 
-  Other functions to compare with this one include @code{char-to-string}
-(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
-@code{make-list} (@pxref{Building Lists}).
+  Other functions to compare with this one include @code{make-vector}
+(@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}).
 @end defun
 
 @defun string &rest characters
@@ -565,38 +564,6 @@ of text characters and general input events
 (@code{single-key-description} and @code{text-char-description}).  These
 are used primarily for making help messages.
 
-@defun char-to-string character
-@cindex character to string
-This function returns a new string containing one character,
-@var{character}.  This function is semi-obsolete because the function
-@code{string} is more general.  @xref{Creating Strings}.
-@end defun
-
-@defun string-to-char string
-@cindex string to character
-  This function returns the first character in @var{string}.  If the
-string is empty, the function returns 0.  The value is also 0 when the
-first character of @var{string} is the null character, @acronym{ASCII} code
-0.
-
-@example
-(string-to-char "ABC")
-     @result{} 65
-
-(string-to-char "xyz")
-     @result{} 120
-(string-to-char "")
-     @result{} 0
-@group
-(string-to-char "\000")
-     @result{} 0
-@end group
-@end example
-
-This function may be eliminated in the future if it does not seem useful
-enough to retain.
-@end defun
-
 @defun number-to-string number
 @cindex integer to string
 @cindex integer to decimal
@@ -659,19 +626,39 @@ this function returns 0.
 @code{string-to-int} is an obsolete alias for this function.
 @end defun
 
+@defun char-to-string character
+@cindex character to string
+This function returns a new string containing one character,
+@var{character}.  This function is semi-obsolete because the function
+@code{string} is more general.  @xref{Creating Strings}.
+@end defun
+
+@defun string-to-char string
+  This function returns the first character in @var{string}.  This
+mostly identical to @code{(aref string 0)}, except that it returns 0
+if the string is empty.  (The value is also 0 when the first character
+of @var{string} is the null character, @acronym{ASCII} code 0.)  This
+function may be eliminated in the future if it does not seem useful
+enough to retain.
+@end defun
+
   Here are some other functions that can convert to or from a string:
 
 @table @code
 @item concat
-@code{concat} can convert a vector or a list into a string.
+This function converts a vector or a list into a string.
 @xref{Creating Strings}.
 
 @item vconcat
-@code{vconcat} can convert a string into a vector.  @xref{Vector
+This function converts a string into a vector.  @xref{Vector
 Functions}.
 
 @item append
-@code{append} can convert a string into a list.  @xref{Building Lists}.
+This function converts a string into a list.  @xref{Building Lists}.
+
+@item byte-to-string
+This function converts a byte of character data into a unibyte string.
+@xref{Converting Representations}.
 @end table
 
 @node Formatting Strings
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 5bb44ff9675..ccf90e33cd0 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -383,7 +383,7 @@ See @code{documentation} in @ref{Accessing Documentation}, for another
 example using @code{mapatoms}.
 @end defun
 
-@defun unintern symbol &optional obarray
+@defun unintern symbol obarray
 This function deletes @var{symbol} from the obarray @var{obarray}.  If
 @code{symbol} is not actually in the obarray, @code{unintern} does
 nothing.  If @var{obarray} is @code{nil}, the current obarray is used.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index b6723a0bee4..45d358366de 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -87,7 +87,7 @@ buffer is @samp{@@}:
 
 @example
 @group
-(char-to-string (char-after 1))
+(string (char-after 1))
      @result{} "@@"
 @end group
 @end example
@@ -122,9 +122,9 @@ but there is no peace.
 @end group
 
 @group
-(char-to-string (preceding-char))
+(string (preceding-char))
      @result{} "a"
-(char-to-string (following-char))
+(string (following-char))
      @result{} "c"
 @end group
 @end example
@@ -866,7 +866,7 @@ adds it to the most recent element.  It determines automatically (using
 @code{last-command}) whether the previous command was a kill command,
 and if so appends the killed text to the most recent entry.
 
-@deffn Command kill-region start end &optional yank-handler
+@deffn Command kill-region start end
 This function kills the text in the region defined by @var{start} and
 @var{end}.  The text is deleted but saved in the kill ring, along with
 its text properties.  The value is always @code{nil}.
@@ -874,17 +874,10 @@ its text properties.  The value is always @code{nil}.
 In an interactive call, @var{start} and @var{end} are point and
 the mark.
 
-@c Emacs 19 feature
 If the buffer or text is read-only, @code{kill-region} modifies the kill
 ring just the same, then signals an error without modifying the buffer.
 This is convenient because it lets the user use a series of kill
 commands to copy text from a read-only buffer into the kill ring.
-
-If @var{yank-handler} is non-@code{nil}, this puts that value onto
-the string of killed text, as a @code{yank-handler} text property.
-@xref{Yanking}.  Note that if @var{yank-handler} is @code{nil}, any
-@code{yank-handler} properties present on the killed text are copied
-onto the kill ring, like other text properties.
 @end deffn
 
 @defopt kill-read-only-ok
@@ -1069,7 +1062,7 @@ it returns the entry pointed at by the yanking pointer and does not
 move the yanking pointer.
 @end defun
 
-@defun kill-new string &optional replace yank-handler
+@defun kill-new string &optional replace
 This function pushes the text @var{string} onto the kill ring and
 makes the yanking pointer point to it.  It discards the oldest entry
 if appropriate.  It also invokes the value of
@@ -1078,25 +1071,15 @@ if appropriate.  It also invokes the value of
 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
 first element of the kill ring with @var{string}, rather than pushing
 @var{string} onto the kill ring.
-
-If @var{yank-handler} is non-@code{nil}, this puts that value onto
-the string of killed text, as a @code{yank-handler} property.
-@xref{Yanking}.  Note that if @var{yank-handler} is @code{nil}, then
-@code{kill-new} copies any @code{yank-handler} properties present on
-@var{string} onto the kill ring, as it does with other text properties.
 @end defun
 
-@defun kill-append string before-p &optional yank-handler
+@defun kill-append string before-p
 This function appends the text @var{string} to the first entry in the
 kill ring and makes the yanking pointer point to the combined entry.
 Normally @var{string} goes at the end of the entry, but if
 @var{before-p} is non-@code{nil}, it goes at the beginning.  This
 function also invokes the value of @code{interprogram-cut-function}
-(see below).  This handles @var{yank-handler} just like
-@code{kill-new}, except that if @var{yank-handler} is different from
-the @code{yank-handler} property of the first entry of the kill ring,
-@code{kill-append} pushes the concatenated string onto the kill ring,
-instead of replacing the original first entry with it.
+(see below).
 @end defun
 
 @defvar interprogram-paste-function
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index a3a550868f5..20fe4dbc9fa 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -544,21 +544,23 @@ not the buffer-local value.  (But you should not be making
 buffer-local bindings for a symbol that is defined with
 @code{defconst}.)
 
-Here, @code{pi} is a constant that presumably ought not to be changed
-by anyone (attempts by the Indiana State Legislature notwithstanding).
-As the second form illustrates, however, this is only advisory.
+An example of the use of @code{defconst} is Emacs' definition of
+@code{float-pi}---the mathematical constant @math{pi}, which ought not
+to be changed by anyone (attempts by the Indiana State Legislature
+notwithstanding).  As the second form illustrates, however,
+@code{defconst} is only advisory.
 
 @example
 @group
-(defconst pi 3.1415 "Pi to five places.")
-     @result{} pi
+(defconst float-pi 3.141592653589793 "The value of Pi.")
+     @result{} float-pi
 @end group
 @group
-(setq pi 3)
-     @result{} pi
+(setq float-pi 3)
+     @result{} float-pi
 @end group
 @group
-pi
+float-pi
      @result{} 3
 @end group
 @end example