Merge changes from emacs-23 branch

17 files changed, 413 insertions, 314 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index cb243825d5d..e390c6cbc16 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,28 @@
+2010-11-27  Bob Rogers  <rogers-emacs@rgrjr.dyndns.org>
+
+        * maintaining.texi (VC With A Locking VCS, VC Directory Commands):
+        * vc1-xtra.texi (Customizing VC, General VC Options): Small fixes.
+
+2010-11-27  Chong Yidong  <cyd@stupidchicken.com>
+
+        * maintaining.texi (Version Control Systems): Fix repeated sentence.
+        Suggested by Štěpán Němec.
+
+2010-11-27  Chong Yidong  <cyd@stupidchicken.com>
+
+        * maintaining.texi (Version Control): Say "commit", not "check in".
+        (Version Control Systems): Simplify descriptions.
+        (VCS Merging, VCS Changesets, VCS Repositories): New nodes, split from
+        VCS Concepts.
+        (VC Mode Line): Update example.
+        (Old Revisions): Document revert-buffer for vc-diff.
+        (Log Buffer): Promote to a subsection.  Document header lines.
+
+        * macos.texi (Mac / GNUstep Basics): Document
+        ns-right-alternate-modifier.
+
+        * emacs.texi (Top): Update node listing.
+
 2010-11-13  Eli Zaretskii  <eliz@gnu.org>
 
         * rmail.texi (Rmail Coding): Characters with no fonts are not
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 1ece1ea6dd8..65a565dbe8e 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -771,6 +771,7 @@ Version Control
 * Introduction to VC::  How version control works in general.
 * VC Mode Line::        How the mode line shows version control status.
 * Basic VC Editing::    How to edit a file under version control.
+* Log Buffer::          Features available in log entry buffers.
 * Old Revisions::       Examining and comparing old versions.
 * Secondary VC Commands:: The commands used a little less frequently.
 * VC Directory Mode::   Listing files managed by version control.
@@ -785,6 +786,9 @@ Introduction to Version Control
 * Why Version Control?::    Understanding the problems it addresses.
 * Version Control Systems:: Supported version control back-end systems.
 * VCS Concepts::            Words and concepts related to version control.
+* VCS Merging::             How file conflicts are handled.
+* VCS Changesets::          Changesets in version control.
+* VCS Repositories::        Where version control repositories are stored.
 * Types of Log File::       The VCS log in contrast to the ChangeLog.
 
 Basic Editing under Version Control
@@ -792,7 +796,6 @@ Basic Editing under Version Control
 * VC With A Merging VCS::  Without locking: default mode for CVS.
 * VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
 * Advanced C-x v v::       Advanced features available with a prefix argument.
-* Log Buffer::             Features available in log entry buffers.
 
 The Secondary Commands of VC
 
diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
index 6fa5666ba6f..044a722a07a 100644
--- a/doc/emacs/macos.texi
+++ b/doc/emacs/macos.texi
@@ -8,23 +8,22 @@
 @cindex Macintosh
 @cindex GNUstep
 
-  This section briefly describes the peculiarities of using Emacs built with
-the GNUstep libraries on GNU/Linux or other operating systems, or on Mac OS X
-with native window system support.  For Mac OS X, Emacs can be built either
-without window system support, with X11, or with the Cocoa interface.  This
-section only applies to the Cocoa build.  Emacs 23 does not support Mac OS
-Classic.
-
-  Emacs, when built on Mac OS X, uses the Cocoa application interface.  For
-various historical and technical reasons, Emacs uses the term @samp{Nextstep}
-internally, instead of ``Cocoa'' or ``Mac OS X''; for instance, most of the
-commands and variables described in the following sections begin with
-@samp{ns-}, which is short for @samp{Nextstep}.  NeXTstep was an application
-interface released by NeXT Inc during the 1980s, of which Cocoa is a direct
-descendant.  Apart from Cocoa, there is another NeXTstep-style system:
-GNUstep, which is free software.  As of this writing, the GNUstep support is
-alpha status (@pxref{GNUstep Support}), but we hope to improve it in the
-future.
+  This section describes the peculiarities of using Emacs built with
+the GNUstep libraries on GNU/Linux or other operating systems, or on
+Mac OS X with native window system support.  On Mac OS X, Emacs can be
+built either without window system support, with X11, or with the
+Cocoa interface; this section only applies to the Cocoa build.  Emacs
+does not support earlier versions of Mac OS.
+
+  For various historical and technical reasons, Emacs uses the term
+@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for
+instance, most of the commands and variables described in this section
+begin with @samp{ns-}, which is short for @samp{Nextstep}.  NeXTstep
+was an application interface released by NeXT Inc during the 1980s, of
+which Cocoa is a direct descendant.  Apart from Cocoa, there is
+another NeXTstep-style system: GNUstep, which is free software.  As of
+this writing, the GNUstep support is alpha status (@pxref{GNUstep
+Support}), but we hope to improve it in the future.
 
 @menu
 * Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or Mac OS.
@@ -37,19 +36,24 @@ future.
 @section Basic Emacs usage under Mac OS and GNUstep
 
   By default, the @key{alt} and @key{option} keys are the same as
-@key{Meta} when running under Mac OS.  The Mac @key{Cmd} key is the
-same as @key{Super}, and Emacs provides a set of keybindings using
-this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac /
-GNUstep Events}).  You can change these bindings in the usual way (@pxref{Key
-Bindings}).
-
-  The standard Mac / GNUstep font and color panels are accessible via Lisp commands.
-  To use the color panel, drag from it to an Emacs frame to change the
-foreground color of the face at that position (if the @key{shift} key
-is held down, it changes the background color instead). To discard the
-settings, create a new frame and close the altered one.
-@c [unclear if the following holds.]
-@c  To finalize the settings for either color or font, choose @samp{Save Options} in the @samp{Options} menu. 
+@key{Meta}.  The Mac @key{Cmd} key is the same as @key{Super}, and
+Emacs provides a set of keybindings using this modifier key that mimic
+other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}).  You
+can change these bindings in the usual way (@pxref{Key Bindings}).
+
+  The variable @code{ns-right-alternate-modifier} controls the
+behavior of the right @key{alt} and @key{option} keys.  These keys
+behave like the left-hand keys if the value is @code{left} (the
+default).  A value of @code{control}, @code{meta}, @code{alt},
+@code{super}, or @code{hyper} makes them behave like the corresponding
+modifier keys; a value of @code{none} tells Emacs to ignore them.
+
+  The standard Mac / GNUstep font and color panels are accessible via
+Lisp commands.  To use the color panel, drag from it to an Emacs frame
+to change the foreground color of the face at that position (if the
+@key{shift} key is held down, it changes the background color
+instead). To discard the settings, create a new frame and close the
+altered one.
 
   @key{S-Mouse-1} (i.e., clicking the left mouse button
 while holding down the @key{Shift} key) adjusts the region to the
@@ -58,7 +62,7 @@ it does not pop up a menu for changing the default face, as
 @key{S-Mouse-1} normally does (@pxref{Temporary Face Changes}).  This
 change makes Emacs behave more like other Mac / GNUstep applications.
 
-  When you open or save files using the menus, or using the 
+  When you open or save files using the menus, or using the
 @key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file
 dialogs to read file names.  However, if you use the regular Emacs key
 sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read
@@ -110,7 +114,7 @@ dragging will alter the foreground color.  Shift dragging will alter the
 background color.
 
 @c To make the changes permanent select the "Save Options"
-@c item in the "Options" menu, or run @code{menu-bar-options-save}. 
+@c item in the "Options" menu, or run @code{menu-bar-options-save}.
 
 Useful in this context is the listing of all faces obtained by @key{M-x}
 @code{list-faces-display}.
@@ -193,7 +197,7 @@ font are stored in the variables @code{ns-input-font} and
 @code{ns-input-fontsize}, respectively.
 
 @item ns-power-off
-This event occurs when the user logs out and Emacs is still running, or when 
+This event occurs when the user logs out and Emacs is still running, or when
 `Quit Emacs' is chosen from the application menu.
 The default behavior is to save all file-visiting buffers.
 @end table
@@ -208,26 +212,9 @@ and return the result as a string.  You can also use the Lisp function
 services and receive the results back.  Note that you may need to
 restart Emacs to access newly-available services.
 
-
 @node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep
 @section GNUstep Support
 
-Emacs can be built and run under GNUstep, however there are still some
+Emacs can be built and run under GNUstep, but there are still some
 issues to be addressed.  Interested developers should contact
 @email{emacs-devel@@gnu.org}.
-
-@c Presumably no longer relevant since CANNOT_DUMP removed 2009-05-06:
-@ignore
-In particular, it may be necessary to run @samp{make bootstrap} with a
-plain X configuration, then @samp{make clean} and @samp{./configure
---with-ns} followed by @samp{make install}.
-
-Currently CANNOT_DUMP is automatically enabled in GNUstep configurations,
-because the unex file(s) for GNUstep, mainly @samp{unexelf.c}, have not been
-updated yet with the ``zone'' code in and related to @samp{unexmacosx.c}.
-@end ignore
-
-
-@ignore
-   arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6
-@end ignore
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index b407f5b9c99..cf504b6be2a 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -24,20 +24,20 @@ programs.
 @section Version Control
 @cindex version control
 
-  A @dfn{version control system} is a package that can record multiple
+  A @dfn{version control system} is a program that can record multiple
 versions of a source file, storing information such as the creation
-time of each version, who created it, and a description of what was
-changed in that version.
-
-  The Emacs version control interface is called VC.  Its commands work
-with several different version control systems; currently, it supports
-GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and
-Subversion.  Of these, the GNU project distributes CVS, GNU Arch, RCS,
-and Bazaar.
-
-  VC is enabled automatically whenever you visit a file that is
-governed by a version control system.  To disable VC entirely, set the
-customizable variable @code{vc-handled-backends} to @code{nil}
+time of each version, who made it, and a description of what was
+changed.
+
+  The Emacs version control interface is called @dfn{VC}.  VC commands
+work with several different version control systems; currently, it
+supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
+SCCS/CSSC, and Subversion.  Of these, the GNU project distributes CVS,
+Arch, RCS, and Bazaar.
+
+  VC is enabled automatically whenever you visit a file governed by a
+version control system.  To disable VC entirely, set the customizable
+variable @code{vc-handled-backends} to @code{nil}
 @iftex
 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
 @end iftex
@@ -49,6 +49,7 @@ customizable variable @code{vc-handled-backends} to @code{nil}
 * Introduction to VC::  How version control works in general.
 * VC Mode Line::        How the mode line shows version control status.
 * Basic VC Editing::    How to edit a file under version control.
+* Log Buffer::          Features available in log entry buffers.
 * Old Revisions::       Examining and comparing old versions.
 * Secondary VC Commands::    The commands used a little less frequently.
 * VC Directory Mode::   Listing files managed by version control.
@@ -65,12 +66,13 @@ customizable variable @code{vc-handled-backends} to @code{nil}
 @subsection Introduction to Version Control
 
   VC allows you to use a version control system from within Emacs,
-integrating the version control operations smoothly with editing.
-Though VC cannot completely bridge the gaps between version control
-systems with widely differing capabilities, it does provide a uniform
-interface to many version control operations. Regardless of which
-version control system is in use, you will be able to do basic
-operations in much the same way.
+integrating the version control operations smoothly with editing.  It
+provides a uniform interface for common operations in many version
+control operations.
+
+  Some uncommon or intricate version control operations, such as
+altering repository settings, are not supported in VC.  You should
+perform such tasks outside Emacs, e.g. via the command line.
 
   This section provides a general overview of version control, and
 describes the version control systems that VC supports.  You can skip
@@ -81,6 +83,9 @@ you want to use.
 * Why Version Control?::    Understanding the problems it addresses.
 * Version Control Systems:: Supported version control back-end systems.
 * VCS Concepts::            Words and concepts related to version control.
+* VCS Merging::             How file conflicts are handled.
+* VCS Changesets::          How changes are grouped.
+* VCS Repositories::        Where version control repositories are stored.
 * Types of Log File::       The VCS log in contrast to the ChangeLog.
 @end menu
 
@@ -112,8 +117,8 @@ vitally important form of communication among developers.
 @subsubsection Supported Version Control Systems
 
 @cindex back end (version control)
-  VC currently works with many different version control systems or
-@dfn{back ends}:
+  VC currently works with many different version control systems,
+which it refers to as @dfn{back ends}:
 
 @itemize @bullet
 
@@ -134,73 +139,60 @@ control system.
 @cindex RCS
 @item
 RCS is the free version control system around which VC was initially
-built.  Almost everything you can do with RCS can be done through VC.
-However, you cannot use RCS over the network, and it only works at the
-level of individual files rather than projects.
+built.  It is relatively primitive: it cannot be used over the
+network, and works at the level of individual files.  Almost
+everything you can do with RCS can be done through VC.
 
 @cindex CVS
 @item
 CVS is the free version control system that was, until recently (circa
 2008), used by the majority of free software projects.  Nowadays, it
 is slowly being superseded by newer systems.  CVS allows concurrent
-multi-user development either locally or over the network.  It lacks
-support for atomic commits or file moving/renaming.  VC supports all
-basic editing operations under CVS.  For some less common tasks, you
-still need to call CVS from the command line.  Note also that before
-using CVS you must set up a repository, which is a subject too complex
-to treat here.
+multi-user development either locally or over the network.  Unlike
+newer systems, it lacks support for atomic commits and file
+moving/renaming.  VC supports all basic editing operations under CVS.
 
 @cindex SVN
 @cindex Subversion
 @item
 Subversion (SVN) is a free version control system designed to be
-similar to CVS but without its problems.  It supports atomic commits
-of filesets, and versioning of directories, symbolic links, meta-data,
-renames, copies, and deletes.
+similar to CVS but without its problems (e.g., it supports atomic
+commits of filesets, and versioning of directories, symbolic links,
+meta-data, renames, copies, and deletes).
 
 @cindex GNU Arch
 @cindex Arch
 @item
-GNU Arch is a version control system designed for distributed work.
-It differs in many ways from older systems like CVS and RCS.  It
-provides different methods for interoperating between users, support
-for offline operations, and good branching and merging features.  It
-also supports atomic commits of filesets and file moving/renaming.  VC
-does not support all operations provided by GNU Arch, so you must
-sometimes invoke it from the command line.
+GNU Arch is one of the earliest @dfn{distributed} version control
+systems (the other being Monotone).  @xref{VCS Concepts}, for a
+description of distributed version control systems.  It is no longer
+under active development, and has been deprecated in favor of Bazaar.
 
 @cindex git
 @item
-Git is a distributed version control system invented by Linus Torvalds to support
-development of Linux (his kernel).  It supports atomic commits of filesets and
-file moving/renaming.  One significant feature of git is that it
-largely abolishes the notion of a single centralized repository;
-instead, each working copy of a git project is its own repository and
-coordination is done through repository-sync operations.  VC supports
-most git operations, with the exception of news merges and repository
-syncing; these must be done from the command line.
+Git is a distributed version control system originally invented by
+Linus Torvalds to support development of Linux (his kernel).  VC
+supports many common git operations, but others, such as repository
+syncing, must be done from the command line.
 
 @cindex hg
 @cindex Mercurial
 @item
 Mercurial (hg) is a distributed version control system broadly
-resembling GNU Arch and git, with atomic fileset commits and file
-moving/renaming.  Like git, it is fully decentralized.  VC supports
-most Mercurial commands, with the exception of repository sync
-operations; this needs to be done from the command line.
+resembling git.  VC supports most Mercurial commands, with the
+exception of repository sync operations.
 
 @cindex bzr
 @cindex Bazaar
 @item
-Bazaar (bzr) is a distributed version control system that supports both
-repository-based and distributed versioning, with atomic fileset
-commits and file moving/renaming.  VC supports most basic editing
-operations under Bazaar.
+Bazaar (bzr) is a distributed version control system that supports
+both repository-based and distributed versioning.  VC supports most
+basic editing operations under Bazaar.
 @end itemize
 
   Previous versions of VC supported a version control system known as
-Meta-CVS.  This support has been dropped because of limited interest
-from users and developers.
+Meta-CVS.  This support was dropped due to limited interest from users
+and developers.
 
 @node VCS Concepts
 @subsubsection Concepts of Version Control
@@ -216,11 +208,11 @@ as @dfn{log entries} that describe the changes made to each file.
 
 @cindex work file
 @cindex checking out files
-  A file @dfn{checked out} of a repository is called the @dfn{work
-file}.  You edit the work file and make changes in it, as you would
-with an ordinary file.  After you are done with a set of changes, you
-@dfn{check in} or @dfn{commit} the file; this records the changes in
-the repository, along with a log entry for those changes.
+  The copy of a version-controlled file that you actually edit is
+called the @dfn{work file}.  You can change each work file as you
+would an ordinary file.  After you are done with a set of changes, you
+@dfn{commit} (or @dfn{check in}) the changes; this records the changes
+in the repository, along with a descriptive log entry.
 
 @cindex revision
 @cindex revision ID
@@ -231,12 +223,15 @@ on the version control system; in the simplest case, it is just an
 integer.
 
   To go beyond these basic concepts, you will need to understand three
-aspects in which version control systems differ.
-They can be locking-based or merging-based; they can be file-based or
-changeset-based; and they can be centralized or decentralized.  VC
-handles all these modes of operation, but it cannot hide the differences.
+aspects in which version control systems differ.  As explained in the
+next three sections, they can be lock-based or merge-based; file-based
+or changeset-based; and centralized or decentralized.  VC handles all
+these modes of operation, but it cannot hide the differences.
 
+@node VCS Merging
+@subsubsection Merge-based vs lock-based Version Control
 @cindex locking versus merging
+
   A version control system typically has some mechanism to coordinate
 between users who want to change the same file.  There are two ways to
 do this: merging and locking.
@@ -244,8 +239,7 @@ do this: merging and locking.
   In a version control system that uses merging, each user may check
 out and modify a work file at any time.  The system lets you
 @dfn{merge} your work file, which may contain changes that have not
-been checked in, with the latest changes that others have checked into
-the repository.
+been committed, with the latest changes that others have committed.
 
   Older version control systems use a @dfn{locking} scheme instead.
 Here, work files are normally read-only.  To edit a file, you ask the
@@ -253,7 +247,7 @@ version control system to make it writable for you by @dfn{locking}
 it; only one user can lock a given file at any given time.  This
 procedure is analogous to, but different from, the locking that Emacs
 uses to detect simultaneous editing of ordinary files
-(@pxref{Interlocking}).  When you check in your changes, that unlocks
+(@pxref{Interlocking}).  When you commit your changes, that unlocks
 the file, and the work file becomes read-only again.  Other users may
 then lock the file to make their own changes.
 
@@ -261,8 +255,8 @@ then lock the file to make their own changes.
 users try to modify the same file at the same time.  Locking systems
 have @dfn{lock conflicts}; a user may try to check a file out and be
 unable to because it is locked.  In merging systems, @dfn{merge
-conflicts} happen when you check in a change to a file that conflicts
-with a change checked in by someone else after your checkout.  Both
+conflicts} happen when you commit a change to a file that conflicts
+with a change committed by someone else after your checkout.  Both
 kinds of conflict have to be resolved by human judgment and
 communication.  Experience has shown that merging is superior to
 locking, both in convenience to developers and in minimizing the
@@ -275,27 +269,33 @@ Distributed version control systems, such as GNU Arch, git, and
 Mercurial, are exclusively merging-based.
 
   VC mode supports both locking and merging version control.  The
-terms ``checkin'' and ``checkout'' come from locking-based version
-control systems; newer version control systems have slightly different
-operations usually called ``commit'' and ``update'', but VC hides the
-differences between them as much as possible.
+terms ``commit'' and ``update'' are used in newer version control
+systems; older lock-based systems use the terms ``check in'' and
+``check out''.  VC hides the differences between them as much as
+possible.
+
+@node VCS Changesets
+@subsubsection Changeset-based vs File-based Version Control
 
-@cindex files versus changesets.
+@cindex changesets
   On SCCS, RCS, CVS, and other early version control systems, version
 control operations are @dfn{file-based}: each file has its own comment
-and revision history separate from that of all other files in the
-system.  Later systems, beginning with Subversion, are
-@dfn{changeset-based}: a checkin may include changes to several files,
-and the entire set of changes is treated as a unit by the system.  Any
-comment associated with the change does not belong to a single file,
-but to the changeset itself.
+and revision history separate from that of all other files.  Newer
+systems, beginning with Subversion, are @dfn{changeset-based}: a
+checkin may include changes to several files, and the entire set of
+changes is handled as a unit.  Any comment associated with the change
+does not belong to a single file, but to the changeset itself.
 
   Changeset-based version control is more flexible and powerful than
 file-based version control; usually, when a change to multiple files
 has to be reversed, it's good to be able to easily identify and remove
 all of it.
 
-@cindex centralized vs. decentralized version control
+@node VCS Repositories
+@subsubsection Decentralized vs Centralized Repositories
+
+@cindex centralized version control
+@cindex decentralized version control
   Early version control systems were designed around a
 @dfn{centralized} model in which each project has only one repository
 used by all developers.  SCCS, RCS, CVS, and Subversion share this
@@ -306,14 +306,12 @@ point for reliability and efficiency.
 control, later implemented in git, Mercurial, and Bazaar.  A project
 may have several different repositories, and these systems support a
 sort of super-merge between repositories that tries to reconcile their
-change histories.  At the limit, each developer has his/her own
-repository, and repository merges replace checkin/commit operations.
+change histories.  In effect, there is one repository for each
+developer, and repository merges take the place of commit operations.
 
-  VC's job is to help you manage the traffic between your personal
-workfiles and a repository.  Whether that repository is a single
-master or one of a network of peer repositories is not something VC
-has to care about.  Thus, the difference between a centralized and a
-decentralized version control system is invisible to VC mode.
+  VC helps you manage the traffic between your personal workfiles and
+a repository.  Whether the repository is a single master, or one of a
+network of peer repositories, is not something VC has to care about.
 
 @node Types of Log File
 @subsubsection Types of Log File
@@ -323,9 +321,9 @@ decentralized version control system is invisible to VC mode.
 
   Projects that use a version control system can have two types of log
 for changes.  One is the log maintained by the version control system:
-each time you check in a change, you fill out a @dfn{log entry} for
-the change (@pxref{Log Buffer}).  This is called the @dfn{version
-control log}.
+each time you commit a change, you fill out a @dfn{log entry} for the
+change (@pxref{Log Buffer}).  This is called the @dfn{version control
+log}.
 
   The other kind of log is the file @file{ChangeLog} (@pxref{Change
 Log}).  It provides a chronological record of all changes to a large
@@ -365,32 +363,29 @@ change, and later use the @kbd{C-x v a} command to copy it to
 @cindex VC, mode line indicator
 
   When you visit a file that is under version control, Emacs indicates
-this on the mode line.  For example, @samp{RCS-1.3} says that the RCS
-back end is used for that file, and the current version of the file is
-1.3.
-
-  The first part of the VC mode-line indicator is the name of the back
-end: @samp{RCS}, @samp{CVS}, @samp{Bzr}, etc.  The back-end name is
-followed by a single character and the version of the file.
+this on the mode line.  For example, @samp{Bzr-1223} says that Bazaar
+is used for that file, and the current revision ID is 1223.
 
   The character between the back-end name and the revision ID
-indicates the version control status of the file.  @samp{-} means that
-the work file is not locked (if locking is in use), or not modified (if
-locking is not in use).  @samp{:} indicates that the file is locked, or
-that it is modified.  If the file is locked by some other user (for
+indicates the status of the work file.  In a merge-based version
+control system, a @samp{-} character indicates that the work file is
+unmodified, and @samp{:} indicates that it has been modified.
+@samp{!} indicates that the file contains conflicts as result of a
+recent merge operation (@pxref{Merging}), or that the file was removed
+from the version control.  Finally, @samp{?}  means that the file is
+under version control, but is missing from the working tree.
+
+  In a lock-based system, @samp{-} indicates an unlocked file, and
+@samp{:} a locked file; if the file is locked by another user (for
 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
 @samp{@@} means that the file was locally added, but not yet committed
-to the master repository.  @samp{!} indicates that the file contains
-conflicts as result of a recent merge operation (@pxref{Merging}), or
-that the file was removed from the version control.  Finally, @samp{?}
-means that the file is under version control, but is missing from the
-working tree.
+to the master repository.
 
   On a graphical display, you can move the mouse over this mode line
 indicator to pop up a ``tool-tip'', which displays a more verbose
 description of the version control status.  Pressing @kbd{Mouse-1}
-over the indicator pops up a menu of VC commands.  This menu is
-identical to the @samp{Tools / Version Control} menu item.
+over the indicator pops up a menu of VC commands, identical to
+@samp{Tools / Version Control} on the menu bar.
 
 @vindex auto-revert-check-vc-info
   When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
@@ -442,12 +437,6 @@ command line.  All files in a VC fileset must be under the same
 version control system; if they are not, Emacs signals an error when
 you attempt to execute a command on the fileset.
 
-  Support for VC filesets and changeset-based version control systems
-is the main improvement to VC in Emacs 23.  When you mark multi-file
-VC in a VC Directory buffer, VC operations treat them as a VC fileset,
-and operate on them all at once if the version control system is
-changeset-based.  @xref{VC Directory Mode}.
-
   VC filesets are distinct from the ``named filesets'' used for
 viewing and visiting files in functional groups (@pxref{Filesets}).
 Unlike named filesets, VC filesets are not named and don't persist
@@ -457,7 +446,6 @@ across sessions.
 * VC With A Merging VCS::  Without locking: default mode for CVS.
 * VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
 * Advanced C-x v v::       Advanced features available with a prefix argument.
-* Log Buffer::             Features available in log entry buffers.
 @end menu
 
 @node VC With A Merging VCS
@@ -490,9 +478,9 @@ If you have not changed the work file, but some other user has checked
 in changes to the repository, merge those changes into the work file.
 
 @item
-If you have made modifications to the work file, attempts to check in
-your changes.  To do this, Emacs first reads the log entry for the new
-revision (@pxref{Log Buffer}).  If some other user has checked in
+If you have made modifications to the work file, attempt to commit
+the changes.  To do this, Emacs first reads the log entry for the new
+revision (@pxref{Log Buffer}).  If some other user has committed
 changes to the repository since you last checked it out, the checkin
 fails.  In that case, type @kbd{C-x v v} again to merge those changes
 into your own work file; this puts the work file into a ``conflicted''
@@ -507,8 +495,8 @@ trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
 
   These rules also apply when you use RCS in its ``non-locking'' mode,
 except that changes are not automatically merged from the repository.
-Nothing informs you if another user has checked in changes in the same
-file since you began editing it; when you check in your revision, his
+Nothing informs you if another user has committed changes in the same
+file since you began editing it; when you commit your revision, his
 changes are removed (however, they remain in the repository and are
 thus not irrevocably lost).  Therefore, you must verify that the
 current revision is unchanged before checking in your changes.  In
@@ -528,7 +516,7 @@ If the file is not locked, lock it and make it writable, so that you
 can change it.
 
 @item
-If the file is locked by you, and contains changes, check in the
+If the file is locked by you, and contains changes, commit the
 changes.  In order to do this, Emacs first reads the log entry for the
 new revision.  @xref{Log Buffer}.
 
@@ -544,12 +532,12 @@ locked the file, to inform him of what has happened.
 @end itemize
 
   These rules also apply when you use CVS in locking mode, except
-that there is no such thing as stealing a lock.
+that CVS does not support stealing a lock.
 
 @node Advanced C-x v v
 @subsubsection Advanced Control in @kbd{C-x v v}
 
-@cindex revision ID to check in/out
+@cindex revision ID in version control
   When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
 C-x v v}), it still performs the next logical version control
 operation, but accepts additional arguments to specify precisely how
@@ -558,8 +546,8 @@ to do the operation.
 @itemize @bullet
 @item
 If the file is modified (or locked), you can specify the revision ID
-to use for the new version that you check in.  This is one way
-to create a new branch (@pxref{Branches}).
+to use for the new version that you commit.  This is one way to create
+a new branch (@pxref{Branches}).
 
 @item
 If the file is not modified (and unlocked), you can specify the
@@ -585,34 +573,53 @@ Features}).
 @end itemize
 
 @node Log Buffer
-@subsubsection Features of the Log Entry Buffer
+@subsection Features of the Log Entry Buffer
+
+  When you tell VC to commit a change, it pops up a buffer called
+@samp{*VC-Log*}.  In this buffer, you should write a @dfn{log entry}
+describing the changes you have made (@pxref{Why Version Control?}).
+After you are done, type @kbd{C-c C-c}; this exits the buffer and
+commits the change, together with your log entry.
+
+  While in the @samp{*VC-Log*} buffer, you can write one or more
+@dfn{header lines}, specifying additional information to be supplied
+to the version control system.  Each header line must occupy a single
+line at the top of the buffer; the first line that is not a header
+line is treated as the start of the log entry.  For example, the
+following header line states that the present change was not written
+by you, but by another developer:
 
-  When you check in changes, Emacs pops up a buffer called
-@samp{*VC-Log*} for you to enter a log entry.
+@smallexample
+Author: J. R. Hacker <jrh@@example.com>
+@end smallexample
 
-  After you have finished editing the log message, type @kbd{C-c C-c}
-to exit the buffer and commit the change.
+@noindent
+Apart from the @samp{Author} header, Emacs recognizes the headers
+@samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
+reference to a bug fixed by the change).  Not all version control
+systems recognize all headers: Bazaar recognizes all three headers,
+while git, Mercurial, and Monotone recognizes only @samp{Author} and
+@samp{Summary}.  If you specify a header for a version control that
+does not support it, the header is treated as part of the log entry.
 
 @findex log-edit-show-files
 @findex log-edit-show-diff
-  In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f}
-(@code{log-edit-show-files}) displays a list of files in the VC
-fileset you are committing.  If you called @kbd{C-x v v} directly from
-a work file, the VC fileset consists of that single file, so this
-command is not very useful.  If you called @kbd{C-x v v} from a VC
-directory buffer, the VC fileset may consist of multiple files
-(@pxref{VC Directory Mode}).
+  Type @kbd{C-c C-f} (@code{log-edit-show-files}) to display a list of
+files in the current VC fileset.  If you called @kbd{C-x v v} directly
+from a work file, the fileset consists of that single file; if you
+called @kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory
+Mode}), the fileset may consist of multiple files.
 
 @findex log-edit-insert-changelog
-  Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of
-the changes you have made (i.e., the differences between the work file
-and the repository revision from which you started editing the file).
-The diff is displayed in a special buffer in another window.
-@xref{Comparing Files}.
-
-  If you have written an entry in the @file{ChangeLog} (@pxref{Change
-Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull
-it into the @samp{*VC-Log*} buffer.  If the topmost item in the
+  Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff}
+of the changes you have made (i.e., the differences between the work
+file and the repository revision from which you started editing).
+@xref{Old Revisions}.
+
+  If the current VC fileset includes one or more @file{ChangeLog}
+files (@pxref{Change Log}), type @kbd{C-c C-a}
+(@code{log-edit-insert-changelog}) to pull the relevant entries into
+the @samp{*VC-Log*} buffer.  If the topmost item in each
 @file{ChangeLog} was made under your user name on the current date,
 this command searches that item for entries that match the file(s) to
 be committed; if found, these entries are inserted.
@@ -627,7 +634,7 @@ the revision control log.
 
   To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
 buffer.  You can switch buffers and do other editing.  As long as you
-don't try to check in another file, the entry you were editing remains
+don't try to commit another file, the entry you were editing remains
 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at
 any time to complete the check-in.
 
@@ -636,7 +643,7 @@ convenient to specify the same log entry for many of the files.  (This
 is the normal way to do things on a changeset-oriented system, where
 comments are attached to changesets rather than the history of
 individual files.)  The most convenient way to do this is to mark all
-the files in VC Directory Mode and check in from there; the log buffer
+the files in VC Directory Mode and commit from there; the log buffer
 will carry the fileset information with it and do a group commit when
 you type @kbd{C-c C-c}.
 
@@ -648,7 +655,7 @@ work just like the minibuffer history commands (except that these
 versions are used outside the minibuffer).
 
 @vindex vc-log-mode-hook
-  Each time you check in a change, the log entry buffer is put into VC
+  Each time you commit a change, the log entry buffer is put into VC
 Log Edit mode, which involves running two hooks: @code{text-mode-hook}
 and @code{vc-log-mode-hook}.  @xref{Hooks}.
 
@@ -700,8 +707,12 @@ buffer in a separate window.
   @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC
 fileset (saving them if necessary) with the repository revision(s)
 from which you started editing.  Note that the latter may or may not
-be the latest revision of the file(s).  The diff is displayed in a
-special buffer in another window.  @xref{Comparing Files}.
+be the latest revision of the file(s).
+
+  The diff is displayed in another window, in a Diff mode buffer
+(@pxref{Diff Mode}) named @file{*vc-diff*}.  In this buffer, the
+@kbd{g} (@code{revert-buffer}) command performs the file comparison
+again, generating a new diff.
 
 @findex vc-diff
 @kindex C-u C-x v =
@@ -1008,7 +1019,7 @@ then decide not to change it.
 
 @kindex C-x v c
 @findex vc-rollback
-  To cancel a change that you already checked in, use @kbd{C-x v c}
+  To cancel a change that you already committed, use @kbd{C-x v c}
 (@code{vc-rollback}).  This command discards all record of the most
 recent checked-in revision, but only if your work file corresponds to
 that revision---you cannot use @kbd{C-x v c} to cancel a revision that
@@ -1075,8 +1086,8 @@ output is used.  Here is an example using CVS:
 @noindent
 In this example, @samp{file1.c} is modified with respect to the
 repository, and @samp{file2.c} is not.  @samp{file3.c} is modified,
-but other changes have also been checked in to the repository---you
-need to merge them with the work file before you can check it in.
+but other changes have also been committed---you need to merge them
+with the work file before you can check it in.
 
 @vindex vc-stay-local
 @vindex vc-cvs-stay-local
@@ -1114,7 +1125,7 @@ this includes Version Control subdirectories such as @samp{RCS} and
 
   VC Directory mode has a full set of navigation and marking commands
 for picking out filesets.  Some of these are also available in a
-context menu invoked by the @kbd{mouse-2} button.
+context menu invoked by @kbd{mouse-2}.
 
   Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p}  also
 move vertically as in other list-browsing modes.  @key{SPC} and
@@ -1158,7 +1169,8 @@ directory buffer will be used.
 
   @kbd{M-s a C-s} does an incremental search on the marked files.
 
-  @kbd{M-s a C-M-s} does an incremental search on the marked files.
+  @kbd{M-s a C-M-s} does an incremental regular expression search
+on the marked files.
 
 @cindex stashes in version control
 @cindex shelves in version control
@@ -1174,11 +1186,11 @@ buffers.  Some single-key shortcuts are available as well; @kbd{=},
 @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
 @kbd{C-x v}.
 
-  The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the
-marked files, so that you can check in several files at once.
-If the underlying VC supports atomic commits of multiple-file
-changesets, @kbd{C-x v v} with a selected set of modified but not
-committed files will commit all of them at once as a single changeset.
+  The command @kbd{C-x v v} (@code{vc-next-action}) operates on all
+the marked files, so that you can commit several files at once.  If
+the underlying VC supports atomic commits of multiple-file changesets,
+@kbd{C-x v v} with a selected set of modified but not committed files
+will commit all of them at once as a single changeset.
 
   When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
 files, all of those files must be either in the same state or in
@@ -1261,15 +1273,15 @@ other branch.
 @node Creating Branches
 @subsubsection Creating New Branches
 
-  To create a new branch from a head revision (one that is the latest in
-the branch that contains it), first select that revision if necessary,
-lock it with @kbd{C-x v v}, and make whatever changes you want.  Then,
-when you check in the changes, use @kbd{C-u C-x v v}.  This lets you
-specify the revision ID for the new revision.  You should specify a
-suitable branch ID for a branch starting at the current revision.
-For example, if the current revision is 2.5, the branch ID should be
-2.5.1, 2.5.2, and so on, depending on the number of existing branches at
-that point.
+  To create a new branch from a head revision (one that is the latest
+in the branch that contains it), first select that revision if
+necessary, lock it with @kbd{C-x v v}, and make whatever changes you
+want.  Then, when you commit the changes, use @kbd{C-u C-x v v}.  This
+lets you specify the revision ID for the new revision.  You should
+specify a suitable branch ID for a branch starting at the current
+revision.  For example, if the current revision is 2.5, the branch ID
+should be 2.5.1, 2.5.2, and so on, depending on the number of existing
+branches at that point.
 
   To create a new branch at an older revision (one that is no longer the
 head of a branch), first select that revision (@pxref{Switching
@@ -1282,11 +1294,11 @@ revision, that you really mean to create a new branch---if you say no,
 you'll be offered a chance to lock the latest revision instead.  On
 a merging-based VCS you will skip this step.
 
-  Then make your changes and type @kbd{C-x v v} again to check in a new
+  Then make your changes and type @kbd{C-x v v} again to commit a new
 revision.  This automatically creates a new branch starting from the
-selected revision.  You need not specially request a new branch, because
-that's the only way to add a new revision at a point that is not the head
-of a branch.
+selected revision.  You need not specially request a new branch,
+because that's the only way to add a new revision at a point that is
+not the head of a branch.
 
   After the branch is created, you ``stay'' on it.  That means that
 subsequent check-ins create new revisions on that branch.  To leave the
@@ -1334,11 +1346,11 @@ type @kbd{C-x v v} to lock revision 1.5 so that you can change it.  Next,
 type @kbd{C-x v m 1.3.1 @key{RET}}.  This takes the entire set of changes on
 branch 1.3.1 (relative to revision 1.3, where the branch started, up to
 the last revision on the branch) and merges it into the current revision
-of the work file.  You can now check in the changed file, thus creating
+of the work file.  You can now commit the changed file, thus creating
 revision 1.6 containing the changes from the branch.
 
   It is possible to do further editing after merging the branch, before
-the next check-in.  But it is usually wiser to check in the merged
+the next check-in.  But it is usually wiser to commit the merged
 revision, then lock it and make the further changes.  This will keep
 a better record of the history of changes.
 
@@ -1374,7 +1386,7 @@ master file revision with user B's changes in it is 1.11.
   Then you can resolve the conflicts by editing the file manually.  Or
 you can type @code{M-x vc-resolve-conflicts} after visiting the file.
 This starts an Ediff session, as described above.  Don't forget to
-check in the merged version afterwards.
+commit the merged version afterwards.
 
 @node Multi-User Branching
 @subsubsection Multi-User Branching
diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
index 5095c3f4764..04d37719013 100644
--- a/doc/emacs/vc1-xtra.texi
+++ b/doc/emacs/vc1-xtra.texi
@@ -594,7 +594,7 @@ headers.
 @vindex vc-handled-backends
 The variable @code{vc-handled-backends} determines which version
 control systems VC should handle.  The default value is @code{(RCS CVS
-SVN SCCS BZR GIT HG Arch)}, so it contains all the version systems
+SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems
 that are currently supported.  If you want VC to ignore one or more of
 these systems, exclude its name from the list.  To disable VC entirely,
 set this variable to @code{nil}.
@@ -657,8 +657,8 @@ variable does not affect @kbd{C-x v c}; that operation is so drastic
 that it should always ask for confirmation.)
 
 @vindex vc-command-messages
-  VC mode does much of its work by running the shell commands for RCS,
-CVS and SCCS.  If @code{vc-command-messages} is non-@code{nil}, VC
+  VC mode does much of its work by running the shell commands for the
+appropriate backend.  If @code{vc-command-messages} is non-@code{nil}, VC
 displays messages to indicate which shell commands it runs, and
 additional messages when the commands finish.
 
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
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 38671f1410c..91ac5f74b0e 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2010-11-27  Glenn Morris  <rgm@gnu.org>
+            James Clark  <none@example.com>
+
+        * nxml-mode.texi (Introduction): New section.
+
 2010-11-21  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * gnus.texi (Server Commands): Document gnus-server-show-server.
diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi
index 423bdc85a24..d076f0dd820 100644
--- a/doc/misc/nxml-mode.texi
+++ b/doc/misc/nxml-mode.texi
@@ -8,7 +8,8 @@
 This manual documents nxml-mode, an Emacs major mode for editing
 XML with RELAX NG support.
 
-Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+Copyright @copyright{} 2007, 2008, 2009, 2010
+Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -43,6 +44,7 @@ license to the document, as described in section 6 of the license.
 This manual is not yet complete.
 
 @menu
+* Introduction::
 * Completion::
 * Inserting end-tags::
 * Paragraphs::
@@ -52,6 +54,58 @@ This manual is not yet complete.
 * Limitations::
 @end menu
 
+@node Introduction
+@chapter Introduction
+
+nXML mode is an Emacs major-mode for editing XML documents.  It supports
+editing well-formed XML documents, and provides schema-sensitive editing
+using RELAX NG Compact Syntax.  To get started, visit a file containing an
+XML document, and, if necessary, use @kbd{M-x nxml-mode} to switch to nXML
+mode.  By default, @code{auto-mode-alist} and @code{magic-fallback-alist}
+put buffers in nXML mode if they have recognizable XML content or file
+extensions.  You may wish to customize the settings, for example to
+recognize different file extensions.
+
+Once in nXML mode, you can type @kbd{C-h m} for basic information on the
+mode.
+
+The @file{etc/nxml} directory in the Emacs distribution contains some data
+files used by nXML mode, and includes two files (@file{test.valid.xml} and
+@file{test.invalid.xml}) that provide examples of valid and invalid XML
+documents.
+
+To get validation and schema-sensitive editing, you need a RELAX NG Compact
+Syntax (RNC) schema for your document (@pxref{Locating a schema}).  The
+@file{etc/schema} directory includes some schemas for popular document
+types.  See @url{http://relaxng.org/} for more information on RELAX NG.
+You can use the @samp{Trang} program from
+@url{http://www.thaiopensource.com/relaxng/trang.html} to
+automatically create RNC schemas.  This program can:
+
+@itemize @bullet
+@item
+infer an RNC schema from an instance document;
+@item
+convert a DTD to an RNC schema;
+@item
+convert a RELAX NG XML syntax schema to an RNC schema.
+@end itemize
+
+@noindent To convert a RELAX NG XML syntax (@samp{.rng}) schema to a RNC
+one, you can also use the XSLT stylesheet from
+@url{http://www.pantor.com/download.html}.
+
+To convert a W3C XML Schema to an RNC schema, you need first to convert it
+to RELAX NG XML syntax using the RELAX NG converter tool @code{rngconv}
+(built on top of MSV).  See @url{https://github.com/kohsuke/msv}
+and @url{https://msv.dev.java.net/}.
+
+For historical discussions only, see the mailing list archives at
+@url{http://groups.yahoo.com/group/emacs-nxml-mode/}.  Please make all new
+discussions on the @samp{help-gnu-emacs} and @samp{emacs-devel} mailing
+lists.  Report any bugs with @kbd{M-x report-emacs-bug}.
+
+
 @node Completion
 @chapter Completion
 
@@ -855,6 +909,3 @@ specification are not enforced.
 
 @bye
 
-@ignore
-   arch-tag: 3b6e8ac2-ae8d-4f38-bd43-ce9f80be04d6
-@end ignore