18 files changed, 202 insertions, 120 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f5878dfed74..36d85bc98ba 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,77 @@
+2010-12-08  Glenn Morris  <rgm@gnu.org>
+
+        * buffers.texi (Modification Time):
+        verify-visited-file-modtime now defaults to the current buffer.
+
+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
+        COL, ROW in the event's position, when the click is on the header
+        or mode line, on the fringes, or in the margins.
+
+2010-11-17  Eli Zaretskii  <eliz@gnu.org>
+
+        * customize.texi (Composite Types): Lower-case index entry.
+
+        * loading.texi (How Programs Do Loading): Document
+        load-file-name.  (Bug#7346)
+
+2010-11-17  Glenn Morris  <rgm@gnu.org>
+
+        * text.texi (Kill Functions, Low-Level Kill Ring): Small fixes.
+
+2010-11-13  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Usual Display): Characters with no fonts are not
+        necessarily displayed as empty boxes.
+
+2010-10-31  Glenn Morris  <rgm@gnu.org>
+
+        * maps.texi (Standard Keymaps): Update File menu description.
+
+2010-10-28  Glenn Morris  <rgm@gnu.org>
+
+        * Makefile.in (elisp.dvi, elisp.pdf): Also include $emacsdir.
+
+2010-10-24  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Window Systems): Deprecate use of window-system as
+        a predicate.
+
+2010-10-23  Glenn Morris  <rgm@gnu.org>
+
+        * help.texi (Documentation Basics): Remove mentions of digest-doc and
+        sorted-doc.
+
 2010-10-15  Eli Zaretskii  <eliz@gnu.org>
 
         * os.texi (Dynamic Libraries): New node, with slightly modified
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index f1caa9abfa2..be8b6ca2c9e 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -109,7 +109,7 @@ $(infodir)/elisp: $(srcs)
         $(MAKEINFO) -o $@ $<
 
 elisp.dvi: $(srcs)
-        $(TEXI2DVI) -I $(srcdir) -I $(texinfodir) $<
+        $(TEXI2DVI) -I $(srcdir) -I $(texinfodir) -I $(emacsdir) $<
 
 elisp.html: $(srcs)
         $(MAKEINFO) --html -o $@ $<
@@ -118,7 +118,7 @@ elisp.ps: elisp.dvi
         $(DVIPS) -o $@ $<
 
 elisp.pdf: $(srcs)
-        $(TEXI2PDF) -I $(srcdir) -I $(texinfodir) $<
+        $(TEXI2PDF) -I $(srcdir) -I $(texinfodir) -I $(emacsdir) $<
 
 .PHONY: mostlyclean clean distclean maintainer-clean infoclean
 
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 2a7a603e733..8811178fe92 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
+@c   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/buffers
 @node Buffers, Windows, Backups and Auto-Saving, Top
@@ -594,12 +595,12 @@ therefore checks the file's modification time using the functions
 described below before saving the file.  (@xref{File Attributes},
 for how to examine a file's modification time.)
 
-@defun verify-visited-file-modtime buffer
-This function compares what @var{buffer} has recorded for the
-modification time of its visited file against the actual modification
-time of the file as recorded by the operating system.  The two should be
-the same unless some other process has written the file since Emacs
-visited or saved it.
+@defun verify-visited-file-modtime &optional buffer
+This function compares what @var{buffer} (by default, the
+current-buffer) has recorded for the modification time of its visited
+file against the actual modification time of the file as recorded by the
+operating system.  The two should be the same unless some other process
+has written the file since Emacs visited or saved it.
 
 The function returns @code{t} if the last actual modification time and
 Emacs's recorded modification time are the same, @code{nil} otherwise.
@@ -1223,6 +1224,3 @@ This function returns the current gap position in the current buffer.
 This function returns the current gap size of the current buffer.
 @end defun
 
-@ignore
-   arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
-@end ignore
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 17cfcc0def8..d83396750ca 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1285,8 +1285,12 @@ input stream.  @xref{Key Sequence Input}.
 @item @var{x}, @var{y}
 These are the pixel coordinates of the click, relative to
 the top left corner of @var{window}, which is @code{(0 . 0)}.
-For the mode or header line, @var{y} does not have meaningful data.
-For the vertical line, @var{x} does not have meaningful data.
+For a click on text, these are relative to the top left corner of
+the window's text area.  For the mode or header line, they are
+relative to the top left window edge.  For fringes, margins, and the
+vertical border, @var{x} does not have meaningful data.  For fringes
+and margins, @var{y} is relative to the bottom edge of the header
+line.
 
 @item @var{timestamp}
 This is the time at which the event occurred, in milliseconds.
@@ -1316,7 +1320,12 @@ the window.
 @item @var{col}, @var{row}
 These are the actual coordinates of the glyph under the @var{x},
 @var{y} position, possibly padded with default character width
-glyphs if @var{x} is beyond the last glyph on the line.
+glyphs if @var{x} is beyond the last glyph on the line.  For clicks on
+the header or mode line, these are measured from the top left edge of
+the header or mode line.  For clicks on the fringes and on the
+vertical border, these have no meaningful data.  For clicks on the
+margins, @var{col} is measured from the left edge of the margin area
+and @var{row} is measured from the top of the margin area.
 
 @item @var{image}
 This is the image object on which the click occurred.  It is either
@@ -1333,7 +1342,7 @@ left corner of the character glyph clicked on.
 These are the pixel width and height of @var{object} or, if this is
 @code{nil}, those of the character glyph clicked on.
 @end table
- 
+
 @sp 1
 For mouse clicks on a scroll-bar, @var{position} has this form:
 
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 4b620049b04..bfd45518bc8 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -733,7 +733,7 @@ The value must be a valid color name, and you can do completion with
 
 @node Composite Types
 @subsection Composite Types
-@cindex Composite Types (customization)
+@cindex composite types (customization)
 
   When none of the simple types is appropriate, you can use composite
 types, which build new types from other types or from specified data.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index f4092cfa7ea..6e872ad4233 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5579,9 +5579,9 @@ digit characters representing the character code in octal.  (A display
 table can specify a glyph to use instead of @samp{\}.)
 
 @item
-Multibyte character codes above 256 are displayed as themselves, or as a
-question mark or empty box if the terminal cannot display that
-character.
+Multibyte character codes above 256 are displayed as themselves, or as
+a question mark or a hex code or an empty box if the terminal cannot
+display that character.
 @end itemize
 
   The usual display conventions apply even when there is a display
@@ -5928,6 +5928,14 @@ selected frame).  The list of possible symbols it returns is the same
 one documented for the variable @code{window-system} above.
 @end defun
 
+  Do @emph{not} use @code{window-system} and
+@code{initial-window-system} as predicates or boolean flag variables,
+if you want to write code that works differently on text terminals and
+graphic displays.  That is because @code{window-system} is not a good
+indicator of Emacs capabilities on a given display type.  Instead, use
+@code{display-graphic-p} or any of the other @code{display-*-p}
+predicates described in @ref{Display Feature Testing}.
+
 @defvar window-setup-hook
 This variable is a normal hook which Emacs runs after handling the
 initialization files.  Emacs runs this hook after it has completed
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index d27010d2096..4c44d0a6439 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1748,6 +1748,15 @@ If @var{frame} is not visible, this function does nothing.  The return
 value is not significant.
 @end defun
 
+@defun frame-pointer-visible-p &optional frame
+This predicate function returns non-@code{nil} if the mouse pointer
+displayed on @var{frame} is visible; otherwise it returns @code{nil}.
+@var{frame} omitted or @code{nil} means the selected frame.  This is
+useful when @code{make-pointer-invisible} is set to @code{t}: it
+allows to know if the pointer has been hidden.
+@xref{Mouse Avoidance,,,emacs}.
+@end defun
+
 @need 3000
 
 @node Pop-Up Menus
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index d5c89dd7cf3..e9003601516 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -843,7 +843,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 026258f2472..f21e16e104a 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
+@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/help
 @node Documentation, Files, Modes, Top
@@ -106,12 +107,6 @@ documentation string.  The functions @code{documentation} and
 documentation string from the appropriate file; this is transparent to
 the user.
 
-@c Wordy to prevent overfull hbox.  --rjc 15mar92
-  The @file{emacs/lib-src} directory contains two utilities that you can
-use to print nice-looking hardcopy for the file
-@file{emacs/etc/DOC-@var{version}}.  These are @file{sorted-doc} and
-@file{digest-doc}.
-
 @node Accessing Documentation
 @section Access to Documentation Strings
 
@@ -551,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
@@ -701,6 +696,3 @@ echo area at first, and display the longer @var{help-text} strings only
 if the user types the help character again.
 @end defopt
 
-@ignore
-   arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
-@end ignore
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index dee2a0252eb..05d836140c7 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -107,6 +107,10 @@ in @code{load-path}, where @code{nil} stands for the default directory.
 @code{load-path}, then all three suffixes in the second directory, and
 so on.  @xref{Library Search}.
 
+Whatever the name under which the file is eventually found, and the
+directory where Emacs found it, Emacs sets the value of the variable
+@code{load-file-name} to that file's name.
+
 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
 means you should consider recompiling @file{foo.el}.  @xref{Byte
 Compilation}.
@@ -157,6 +161,12 @@ This variable is non-@code{nil} if Emacs is in the process of loading a
 file, and it is @code{nil} otherwise.
 @end defvar
 
+@defvar load-file-name
+When Emacs is in the process of loading a file, this variable's value
+is the name of that file, as Emacs found it during the search
+described earlier in this section.
+@end defvar
+
 @defvar load-read-function
 @anchor{Definition of load-read-function}
 @c do not allow page break at anchor; work around Texinfo deficiency.
diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi
index a5b126afcb2..4b416a82d64 100644
--- a/doc/lispref/maps.texi
+++ b/doc/lispref/maps.texi
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
-@c   2005, 2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
+@c   2005, 2006, 2007, 2008, 2009, 2010
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/maps
 @node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top
@@ -183,9 +184,9 @@ A sparse keymap used by Lisp mode.
 @vindex menu-bar-edit-menu
 The keymap which displays the Edit menu in the menu bar.
 
-@item menu-bar-files-menu
-@vindex menu-bar-files-menu
-The keymap which displays the Files menu in the menu bar.
+@item menu-bar-file-menu
+@vindex menu-bar-file-menu
+The keymap which displays the File menu in the menu bar.
 
 @item menu-bar-help-menu
 @vindex menu-bar-help-menu
@@ -239,6 +240,3 @@ The keymap defining the contents of the tool bar.
 A full keymap used by View mode.
 @end table
 
-@ignore
-   arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9
-@end ignore
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 b0b0e1d0042..93776f3b4f0 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 04e1e714133..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
@@ -901,10 +894,10 @@ from the buffer.  It returns @code{nil}.
 The command does not set @code{this-command} to @code{kill-region}, so a
 subsequent kill command does not append to the same kill ring entry.
 
-Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
-support Emacs 18.  For newer Emacs versions, it is better to use
-@code{kill-new} or @code{kill-append} instead.  @xref{Low-Level Kill
-Ring}.
+@c FIXME Why is it better?  Why isn't copy-region-as-kill obsolete then?
+@c Why is it used in many places in Emacs?
+In Lisp programs, it is better to use @code{kill-new} or
+@code{kill-append} instead of this command.  @xref{Low-Level Kill Ring}.
 @end deffn
 
 @node Yanking
@@ -1042,8 +1035,8 @@ text property, if there is one.
 @subsection Low-Level Kill Ring
 
   These functions and variables provide access to the kill ring at a
-lower level, but still convenient for use in Lisp programs, because they
-take care of interaction with window system selections
+lower level, but are still convenient for use in Lisp programs,
+because they take care of interaction with window system selections
 (@pxref{Window System Selections}).
 
 @defun current-kill n &optional do-not-move
@@ -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
@@ -4324,6 +4307,4 @@ code that is itself run from a modification hook, then rebind locally
 @code{inhibit-modification-hooks} to @code{nil}.
 @end defvar
 
-@ignore
-   arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
-@end ignore
+
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