upstream

16 files changed, 3172 insertions, 3367 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index d16443ccf31..7857295de92 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,232 @@
+2011-12-26  Chong Yidong  <cyd@gnu.org>
+
+	* dired.texi (Dired Enter, Misc Dired Features): Document
+	dired-use-ls-dired changes.  Mention quit-window.
+	(Dired Navigation): Add index entries.
+	(Dired Visiting): Fix View Mode xref.
+	(Marks vs Flags): Prefer C-/ binding for undo.
+	(Subdirectories in Dired): Add xrefs.
+	(Misc Dired Features): Document some Emacs 24 changes.  Add index
+	entries.
+
+	* abbrevs.texi (Abbrev Concepts): No need to mention abbrev-mode
+	variable, since it is explained in Minor Modes node.
+	(Defining Abbrevs): Copyedits.
+	(Expanding Abbrevs): State default of abbrev-all-caps.  Prefer the
+	C-/ binding for undo.
+	(Dabbrev Customization): Add xrefs for case-fold-search and
+	case-replace.
+
+	* dired-xtra.texi (Subdir Switches): Add xref.
+
+	* maintaining.texi (VC Directory Commands): Mention quit-window.
+
+2011-12-25  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (Tags): Mention Semantic.
+	(Create Tags Table, Etags Regexps): Copyedits.
+	(Find Tag): Mention minibuffer completion.
+	(List Tags): Mention completion-at-point.  Completion is actually
+	available in M-x list-tags.
+
+	* vc1-xtra.texi (VC Delete/Rename): Rename from Renaming and VC.
+	Document vc-delete-file.
+
+	* files.texi (Misc File Ops): Mention vc-delete-file.
+
+	* programs.texi (Symbol Completion): Mention completion-at-point
+	explicitly.
+
+2011-12-22  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (Change Log Commands): Don't specially mention
+	vc-update-change-log which is CVS-only.
+
+	* vc1-xtra.texi (Version Headers): Note that these are for
+	Subversion, CVS, etc. only.
+	(General VC Options): De-document vc-keep-workfiles.  Fix
+	RCS-isms.
+
+2011-12-22  Eli Zaretskii  <eliz@gnu.org>
+
+	* building.texi (Debugger Operation): Fix a typo: "@end iftext"
+	should be @end iftex".
+
+2011-12-21  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (Advanced C-x v v): Use fileset terminology.
+	(VC With A Merging VCS, VC Change Log): Add xref to VC Pull node.
+	(VC Pull): Mention vc-log-incoming.
+	(Log Buffer): Add CVS/RCS only disclaimer.
+
+	* vc1-xtra.texi (Remote Repositories): Update introduction.
+	(Local Version Control): Node deleted (obsolete with DVCSes).
+	(Remote Repositories, Version Backups): Node deleted.  Move
+	documentation of vc-cvs-stay-local to CVS Options.
+	(CVS Options): Reduce verbosity of description of obscure CVS
+	locking feature.
+	(Making Revision Tags, Revision Tag Caveats): Merge into Revision
+	Tags node.
+	(Revision Tags): Move under Miscellaneous VC subsection.
+	(Change Logs and VC): Note that this is wrong for DVCSs.
+	De-document log entry manipulating features.
+	(Renaming and VC): Describe how it works on modern VCSes.
+
+	* files.texi (Misc File Ops): Mention vc-rename-file.
+
+	* programs.texi (Custom C Indent): Add index entries.
+
+2011-12-20  Alan Mackenzie  <acm@muc.de>
+
+	* programs.texi (Motion in C): Update the description of C-M-a and
+	C-M-e, they now DTRT in enclosing scopes.
+	(Custom C Indent): Add @dfn{guessing} of the indentation style.
+
+2011-12-20  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (VCS Concepts): Add "working tree" terminology.
+	(Old Revisions): Use it.
+	(VCS Repositories): Add "distributed" terminology.
+	(Log Buffer): Remove duplicate description
+	about changesets.  Fix "current VC fileset" ambiguity.
+	(Multi-User Branching): Node deleted.
+	(Branches, Switching Branches): Discuss decentralized version
+	control systems.
+	(VC Pull): New node.
+	(Merging): Document merging on decentralized systems.
+	(Creating Branches): Note that this is specific to CVS and related
+	systems.
+
+2011-12-19  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (VCS Merging, VCS Changesets): Index entries.
+	(VC Mode Line): Add index entry for "version control status".
+	(VC Undo): Use vc-revert instead of its vc-revert-buffer alias.
+	Document vc-revert-show-diff.  De-document vc-rollback.
+	(VC Directory Mode): Rewrite introduction.  Move prefix arg
+	documentation here from VC Directory Buffer node.
+	(VC Directory Buffer): Use a decentralized VCS example.
+	(VC Directory Commands): Use a table.  Remove material duplicated
+	in previous nodes on multi-file VC filsets.
+
+2011-12-17  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (VCS Concepts): Make "revision" terminology
+	less CVS-specific.
+	(VC With A Merging VCS, VC With A Locking VCS): Add xref to
+	Registering node.
+	(Secondary VC Commands): Deleted.  Promote subnodes.
+	(Log Buffer): Add command name for C-c C-c.  Fix the name of the
+	log buffer.  Add index entries.
+	(VCS Changesets, Types of Log File, VC With A Merging VCS): Use
+	"commit" terminology.
+	(Old Revisions): Move it to just before VC Change Log.  "Tag" here
+	doesn't refer to tags tables.  Note other possible forms of the
+	revision ID.  C-x v = does not save.
+	(Registering): Note similarity to C-x v v action.  Fix description
+	of how backends are chosen.  De-document vc-default-init-revision.
+	(VC Change Log): Document C-x v l in VC-Dir buffer.  Document RET
+	in root log buffers.
+
+2011-12-16  Chong Yidong  <cyd@gnu.org>
+
+	* maintaining.texi (Version Control Systems): Drop Meta-CVS.
+	(Basic VC Editing): Remove redundant descriptions.
+	(VC With A Merging VCS): Make description more general instead of
+	CVS-specific.
+	(VC With A Locking VCS): Use VC fileset terminology.
+
+2011-12-12  Chong Yidong  <cyd@gnu.org>
+
+	* building.texi (Executing Lisp): Fix xref for C-M-x.
+	(Lisp Libraries): Add xref to node explaining `load' in Lisp
+	manual.  Note that load-path is not customizable.
+	(Lisp Eval): Note that listed commands are available globally.
+	Explain the meaning of "defun" in the C-M-x context.
+	(Lisp Interaction): Copyedits.
+	(External Lisp): Fix name of inferior Lisp buffer.  Mention
+	Scheme.
+	(Compilation): Define "inferior process".
+
+2011-12-10  Eli Zaretskii  <eliz@gnu.org>
+
+	* msdog.texi (Windows Fonts): Document how to force GDI font
+	backend on MS-Windows.
+
+2011-12-10  Chong Yidong  <cyd@gnu.org>
+
+	* building.texi (Compilation): Say what the -k flag to make does.
+	Move subprocess discussion to Compilation Shell.
+	(Compilation Mode): Add xref for grep, occur, and mouse
+	references.  Define "locus".
+	(Grep Searching): Use @command.
+	(Debuggers, Commands of GUD, GDB Graphical Interface): Clarify
+	intro.
+	(Starting GUD): Clarify how arguments are specified.
+	(Debugger Operation): Index entry for "GUD interaction buffer",
+	and move basic description here from Commands of GUD node.
+	(GDB User Interface Layout): Copyedits.
+	(Source Buffers): Remove gdb-find-source-frame, which is not in
+	gdb-mi.el.
+	(Other GDB Buffers): Remove gdb-use-separate-io-buffer and
+	toggle-gdb-all-registers, which are not in gdb-mi.el.  Don't
+	re-document GUD interaction buffers.
+
+	* programs.texi (Symbol Completion): M-TAB can now use Semantic.
+	(Semantic): Add cindex entries for Semantic.
+
+2011-12-06  Chong Yidong  <cyd@gnu.org>
+
+	* programs.texi (Man Page): Clarify how to use Man-switches.
+	Don't bother documenting Man-fontify-manpage-flag.
+	(Lisp Doc): Add xref to Name Help node.
+	(Hideshow): Add cindex.  Mention role of ellipses, and default
+	value of hs-isearch-open.  Don't bother documenting
+	hs-special-modes-alist.
+	(Symbol Completion): Add kindex for C-M-i.  Don't recommend
+	changing the window manager binding of M-TAB.
+
+2011-12-05  Chong Yidong  <cyd@gnu.org>
+
+	* programs.texi (Comment Commands): Fix description of for M-; on
+	blank lines.  Move documentation of comment-region here.
+	(Multi-Line Comments): Clarify the role of comment-multi-line.
+	Refer to Comment Commands for comment-region doc.
+	(Options for Comments): Refer to Multi-Line Comments for
+	comment-multi-line doc, instead of duplicating it.  Fix default
+	values of comment-padding and comment-start-skip.
+
+2011-12-04  Chong Yidong  <cyd@gnu.org>
+
+	* programs.texi (Program Modes): Mention modes that are not
+	included with Emacs.  Fix references to other manuals for tex.
+	Add index entry for backward-delete-char-untabify.  Mention
+	prog-mode-hook.
+	(Which Function): Use "global minor mode" terminology.
+	(Basic Indent, Multi-line Indent): Refer to previous descriptions
+	in Indentation chapter to avoid duplication.
+	(Expressions): Copyedit.
+	(Matching): Document Electric Pair mode.
+
+	* ack.texi (Acknowledgments):
+	* rmail.texi (Movemail, Other Mailbox Formats):
+	* frames.texi (Frames): Don't capitalize "Unix".
+
+2011-12-04  Chong Yidong  <cyd@gnu.org>
+
+	* text.texi (Nroff Mode): Mention what nroff is.
+	(Text Based Tables, Table Recognition): Don't say "Table mode"
+	since it's not a major or minor mode.
+	(Text Based Tables): Reduce the size of the example.
+	(Table Definition): Clarify definitions.
+	(Table Creation): Add key table.
+	(Cell Commands): Use kbd for commands.
+	(Table Rows and Columns): Combine nodes Row Commands and Column
+	Commands.
+	(Fixed Width Mode): Node deleted; contents moved to parent.
+	(Table Conversion): Shorten example.
+	(Measuring Tables): Merge into Table Misc.
+
 2011-12-03  Chong Yidong  <cyd@gnu.org>
 
 	* text.texi (TeX Mode): Mention AUCTeX package.
@@ -1597,7 +1826,7 @@
 2009-08-31  Nick Roberts  <nickrob@snap.net.nz>
 
 	* building.texi (Threads Buffer, Multithreaded Debugging):
-	Re-organise these two sections.
+	Reorganize these two sections.
 
 2009-08-29  Eli Zaretskii  <eliz@gnu.org>
 
diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi
index 2eafadf4841..5868010806c 100644
--- a/doc/emacs/abbrevs.texi
+++ b/doc/emacs/abbrevs.texi
@@ -45,17 +45,14 @@ expanding to @samp{find outer otter}, then you can insert @samp{find
 outer otter.} into the buffer by typing @kbd{f o o .}.
 
 @findex abbrev-mode
-@vindex abbrev-mode
 @cindex Abbrev mode
 @cindex mode, Abbrev
-  Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
-Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
-but they do not expand until Abbrev mode is enabled again.  The command
-@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
-turns Abbrev mode on if the argument is positive, off otherwise.
-@xref{Minor Modes}.  @code{abbrev-mode} is also a variable; Abbrev mode is
-on when the variable is non-@code{nil}.  The variable @code{abbrev-mode}
-automatically becomes local to the current buffer when it is set.
+  Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is
+enabled.  Disabling Abbrev mode does not cause abbrev definitions to
+be forgotten, but they do not expand until Abbrev mode is enabled
+again.  The command @kbd{M-x abbrev-mode} toggles Abbrev mode; with a
+numeric argument, it turns Abbrev mode on if the argument is positive,
+off otherwise.  @xref{Minor Modes}.
 
   Abbrevs can have @dfn{mode-specific} definitions, active only in one major
 mode.  Abbrevs can also have @dfn{global} definitions that are active in
@@ -108,22 +105,18 @@ region as the expansion of the abbrev being defined.
 @kindex C-x a l
 @findex add-mode-abbrev
   The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but
-defines a mode-specific abbrev.  Mode-specific abbrevs are active only in a
-particular major mode.  @kbd{C-x a l} defines an abbrev for the major mode
-in effect at the time @kbd{C-x a l} is typed.  The arguments work the same
-as for @kbd{C-x a g}.
+defines a mode-specific abbrev for the current major mode.  The
+arguments work the same as for @kbd{C-x a g}.
 
 @kindex C-x a i g
 @findex inverse-add-global-abbrev
 @kindex C-x a i l
 @findex inverse-add-mode-abbrev
-  If the abbrev text itself is already in the buffer, you can use the
-commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and
-@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an
-abbrev by specify the expansion in the minibuffer.  These commands are
-called ``inverse'' because they invert the meaning of the two text
-strings they use (one from the buffer and one read with the
-minibuffer).
+  @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and @kbd{C-x a i
+l} (@code{inverse-add-mode-abbrev}) perform the opposite task: if the
+abbrev text is already in the buffer, you use these commands to define
+an abbrev by specifying the expansion in the minibuffer.  These
+commands will expand the abbrev text used for the definition.
 
 @findex define-mode-abbrev
 @findex define-global-abbrev
@@ -132,8 +125,8 @@ expansion in the buffer using the command @code{define-global-abbrev}.
 It reads two arguments---the abbrev, and its expansion.  The command
 @code{define-mode-abbrev} does likewise for a mode-specific abbrev.
 
-  To change the definition of an abbrev, just define a new definition.
-When the abbrev has a prior definition, the abbrev definition commands
+  To change the definition of an abbrev, just make a new definition.
+When an abbrev has a prior definition, the abbrev definition commands
 ask for confirmation before replacing it.
 
 @findex kill-all-abbrevs
@@ -155,11 +148,11 @@ The most common way to use an abbrev is to insert it and then insert a
 punctuation or whitespace character to expand it.
 
 @vindex abbrev-all-caps
-  Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
-outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
-@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
-variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies
-@samp{FIND OUTER OTTER}).
+  Abbrev expansion preserves case: @samp{foo} expands to @samp{find
+outer otter}, and @samp{Foo} to @samp{Find outer otter}.  @samp{FOO}
+expands to @samp{Find Outer Otter} by default, but if you change the
+variable @code{abbrev-all-caps} to a non-@code{nil} value, it expands
+to @samp{FIND OUTER OTTER}.
 
   These commands are used to control abbrev expansion:
 
@@ -196,14 +189,14 @@ punctuation with @kbd{C-q}.  Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
 the buffer, not expanding it.
 
 @findex unexpand-abbrev
-  If you expand an abbrev by mistake, you can undo the expansion and
-bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}).
-This also undoes the insertion of the non-word character that expanded
-the abbrev.  If the result you want is the terminating non-word
-character plus the unexpanded abbrev, you must reinsert the terminating
-character, quoting it with @kbd{C-q}.  You can also use the command
-@kbd{M-x unexpand-abbrev} to cancel the last expansion without
-deleting the terminating character.
+  If you expand an abbrev by mistake, you can undo the expansion by
+typing @kbd{C-/} (@code{undo}).  @xref{Undo}.  This undoes the
+insertion of the abbrev expansion and brings back the abbrev text.  If
+the result you want is the terminating non-word character plus the
+unexpanded abbrev, you must reinsert the terminating character,
+quoting it with @kbd{C-q}.  You can also use the command @kbd{M-x
+unexpand-abbrev} to cancel the last expansion without deleting the
+terminating character.
 
 @findex expand-region-abbrevs
   @kbd{M-x expand-region-abbrevs} searches through the region for defined
@@ -409,12 +402,11 @@ you are expanding.
 
 @vindex dabbrev-case-fold-search
   This feature is controlled by the variable
-@code{dabbrev-case-fold-search}.  If it is @code{t}, case is ignored in
-this search; if it is @code{nil}, the word and the expansion must match
-in case.  If the value of @code{dabbrev-case-fold-search} is
-@code{case-fold-search}, which is true by default, then the variable
-@code{case-fold-search} controls whether to ignore case while searching
-for expansions.
+@code{dabbrev-case-fold-search}.  If it is @code{t}, case is ignored
+in this search; if it is @code{nil}, the word and the expansion must
+match in case.  If the value is @code{case-fold-search} (the default),
+then the variable @code{case-fold-search} controls whether to ignore
+case while searching for expansions (@pxref{Search Case}).
 
 @vindex dabbrev-case-replace
   Normally, dynamic abbrev expansion preserves the case pattern
@@ -425,10 +417,10 @@ expansion to that case pattern.
   The variable @code{dabbrev-case-replace} controls whether to
 preserve the case pattern of the dynamic abbrev.  If it is @code{t},
 the dynamic abbrev's case pattern is preserved in most cases; if it is
-@code{nil}, the expansion is always copied verbatim.  If the value of
-@code{dabbrev-case-replace} is @code{case-replace}, which is true by
-default, then the variable @code{case-replace} controls whether to
-copy the expansion verbatim.
+@code{nil}, the expansion is always copied verbatim.  If the value is
+@code{case-replace} (the default), then the variable
+@code{case-replace} controls whether to copy the expansion verbatim
+(@pxref{Replacement and Case}).
 
   However, if the expansion contains a complex mixed case pattern, and
 the dynamic abbrev matches this pattern as far as it goes, then the
diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi
index d7022ba739b..ae6338ce5a6 100644
--- a/doc/emacs/ack.texi
+++ b/doc/emacs/ack.texi
@@ -1272,8 +1272,8 @@ Colin Walters wrote Ibuffer, an enhanced buffer menu.
 Barry Warsaw wrote @file{assoc.el}, a set of utility functions for
 working with association lists; @file{cc-mode.el}, a mode for editing
 C, C@t{++}, and Java code, based on earlier work by Dave Detlefs,
-Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler
-for Emacs Lisp programs; @file{man.el}, a mode for reading UNIX manual
+Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler for
+Emacs Lisp programs; @file{man.el}, a mode for reading Unix manual
 pages; @file{regi.el}, providing an AWK-like functionality for use in
 lisp programs; @file{reporter.el}, providing customizable bug
 reporting for lisp packages; and @file{supercite.el}, a minor mode for
diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 9c5b2e7dcd7..963bd510f67 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -8,9 +8,9 @@
 @cindex program building
 @cindex running Lisp functions
 
-  The previous chapter discusses the Emacs commands that are useful for
-making changes in programs.  This chapter deals with commands that assist
-in the larger process of compiling and testing programs.
+  The previous chapter discusses the Emacs commands that are useful
+for making changes in programs.  This chapter deals with commands that
+assist in the process of compiling and testing programs.
 
 @menu
 * Compilation::         Compiling programs in languages other
@@ -24,7 +24,7 @@ in the larger process of compiling and testing programs.
 * Executing Lisp::      Various modes for editing Lisp programs,
                           with different facilities for running
                           the Lisp programs.
-* Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
+* Libraries: Lisp Libraries.      How Lisp programs are loaded into Emacs.
 * Eval: Lisp Eval.      Executing a single Lisp expression in Emacs.
 * Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
 * External Lisp::       Communicating through Emacs with a separate Lisp.
@@ -37,10 +37,9 @@ in the larger process of compiling and testing programs.
 @cindex compilation errors
 @cindex error log
 
-  Emacs can run compilers for noninteractive languages such as C and
-Fortran as inferior processes, feeding the error log into an Emacs buffer.
-It can also parse the error messages and show you the source lines where
-compilation errors occurred.
+  Emacs can run compilers for languages such as C and Fortran, feeding
+the compilation log into an Emacs buffer.  It can also parse the error
+messages and show you where the errors occurred.
 
 @table @kbd
 @item M-x compile
@@ -54,65 +53,60 @@ Kill the running compilation subprocess.
 @end table
 
 @findex compile
-  To run @code{make} or another compilation command, do @kbd{M-x
-compile}.  This command reads a shell command line using the minibuffer,
-and then executes the command in an inferior shell, putting output in
-the buffer named @samp{*compilation*}.  The current buffer's default
-directory is used as the working directory for the execution of the
-command; normally, therefore, the compilation happens in this
-directory.
+  To run @code{make} or another compilation command, type @kbd{M-x
+compile}.  This reads a shell command line using the minibuffer, and
+then executes the command by running a shell as a subprocess (or
+@dfn{inferior process}) of Emacs.  The output is inserted in a buffer
+named @samp{*compilation*}.  The current buffer's default directory is
+used as the working directory for the execution of the command;
+normally, therefore, compilation takes place in this directory.
 
 @vindex compile-command
-  The default for the compilation command is normally @samp{make -k},
-which is correct most of the time for nontrivial programs.
-@xref{Top,, Make, make, GNU Make Manual}.  If you have done @kbd{M-x
-compile} before, the default each time is the command you used the
-previous time.  @code{compile} stores this command in the variable
-@code{compile-command}, so setting that variable specifies the default
-for the next use of @kbd{M-x compile}.  If a file specifies a file
-local value for @code{compile-command}, that provides the default when
-you type @kbd{M-x compile} in that file's buffer.  @xref{File
-Variables}.
-
-  Starting a compilation displays the buffer @samp{*compilation*} in
-another window but does not select it.  The buffer's mode line tells
-you whether compilation is finished, with the word @samp{run},
-@samp{signal} or @samp{exit} inside the parentheses.  You do not have
-to keep this buffer visible; compilation continues in any case.  While
-a compilation is going on, the string @samp{Compiling} appears in the
-mode lines of all windows.  When this string disappears, the
-compilation is finished.
-
-  If you want to watch the compilation transcript as it appears, switch
-to the @samp{*compilation*} buffer and move point to the end of the
-buffer.  When point is at the end, new compilation output is inserted
-above point, which remains at the end.  If point is not at the end of
-the buffer, it remains fixed while more compilation output is added at
-the end of the buffer.
+  The default compilation command is @samp{make -k}, which is usually
+correct for programs compiled using the @command{make} utility (the
+@samp{-k} flag tells @command{make} to continue compiling as much as
+possible after an error).  @xref{Top,, Make, make, GNU Make Manual}.
+If you have done @kbd{M-x compile} before, the command that you
+specified is automatically stored in the variable
+@code{compile-command}; this is used as the default the next time you
+type @kbd{M-x compile}.  A file can also specify a file-local value
+for @code{compile-command} (@pxref{File Variables}).
+
+  Starting a compilation displays the @samp{*compilation*} buffer in
+another window but does not select it.  While the compilation is
+running, the word @samp{run} is shown in the major mode indicator for
+the @samp{*compilation*} buffer, and the word @samp{Compiling} appears
+in all mode lines.  You do not have to keep the @samp{*compilation*}
+buffer visible while compilation is running; it continues in any case.
+When the compilation ends, for whatever reason, the mode line of the
+@samp{*compilation*} buffer changes to say @samp{exit} (followed by
+the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a
+signal terminated the process).
+
+  If you want to watch the compilation transcript as it appears,
+switch to the @samp{*compilation*} buffer and move point to the end of
+the buffer.  When point is at the end, new compilation output is
+inserted above point, which remains at the end.  Otherwise, point
+remains fixed while compilation output is added at the end of the
+buffer.
 
 @cindex compilation buffer, keeping point at end
 @vindex compilation-scroll-output
   If you change the variable @code{compilation-scroll-output} to a
-non-@code{nil} value, the compilation buffer will scroll automatically
-to follow the output as it comes in.  If the value is
-@code{first-error}, the scrolling stops at the first error that
-appears, leaving point at that error.  For any other non-@code{nil}
-value, the buffer continues scrolling until there is no more output.
+non-@code{nil} value, the @samp{*compilation*} buffer scrolls
+automatically to follow the output.  If the value is
+@code{first-error}, scrolling stops when the first error appears,
+leaving point at that error.  For any other non-@code{nil} value,
+scrolling continues until there is no more output.
 
 @findex recompile
   To rerun the last compilation with the same command, type @kbd{M-x
-recompile}.  This automatically reuses the compilation command from
-the last invocation of @kbd{M-x compile}.  It also reuses the
+recompile}.  This reuses the compilation command from the last
+invocation of @kbd{M-x compile}.  It also reuses the
 @samp{*compilation*} buffer and starts the compilation in its default
 directory, which is the directory in which the previous compilation
 was started.
 
-  When the compiler process terminates, for whatever reason, the mode
-line of the @samp{*compilation*} buffer changes to say @samp{exit}
-(followed by the exit code, @samp{[0]} for a normal exit), or
-@samp{signal} (if a signal terminated the process), instead of
-@samp{run}.
-
 @findex kill-compilation
   Starting a new compilation also kills any compilation already
 running in @samp{*compilation*}, as the buffer can only handle one
@@ -126,27 +120,6 @@ the @samp{*compilation*} buffer (perhaps using @code{rename-uniquely};
 @pxref{Misc Buffer}), then switch buffers and start the other
 compilation.  This will create a new @samp{*compilation*} buffer.
 
-  Emacs does not expect a compiler process to launch asynchronous
-subprocesses; if it does, and they keep running after the main
-compiler process has terminated, Emacs may kill them or their output
-may not arrive in Emacs.  To avoid this problem, make the main process
-wait for its subprocesses to finish.  In a shell script, you can do this
-using @samp{$!} and @samp{wait}, like this:
-
-@example
-(sleep 10; echo 2nd)& pid=$!  # @r{Record pid of subprocess}
-echo first message
-wait $pid                     # @r{Wait for subprocess}
-@end example
-
-  If the background process does not output to the compilation buffer,
-so you only need to prevent it from being killed when the main
-compilation process terminates, this is sufficient:
-
-@example
-nohup @var{command}; sleep 1
-@end example
-
 @vindex compilation-environment
   You can control the environment passed to the compilation command
 with the variable @code{compilation-environment}.  Its value is a list
@@ -159,153 +132,154 @@ variable settings override the usual ones.
 
 @cindex Compilation mode
 @cindex mode, Compilation
-  The @samp{*compilation*} buffer uses a special major mode,
-Compilation mode, whose main feature is to provide a convenient way to
-visit the source line corresponding to an error message.  These
-commands are also available in other special buffers that list
-locations in files, including those made by @kbd{M-x grep} and
-@kbd{M-x occur}.
+@cindex locus
+  The @samp{*compilation*} buffer uses a major mode called Compilation
+mode.  Compilation mode turns each error message in the buffer into a
+hyperlink; you can move point to it and type @key{RET}, or click on it
+with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of
+the error message in a separate window.  The locus is the specific
+position in a file where that error occurred.
+
+@findex compile-goto-error
+@vindex compilation-auto-jump-to-first-error
+  If you change the variable
+@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
+Emacs automatically visits the locus of the first error message that
+appears in the @samp{*compilation*} buffer.
+
+  Compilation mode provides the following additional commands.  These
+commands can also be used in @samp{*grep*} buffers, where the
+hyperlinks are search matches rather than error messages (@pxref{Grep
+Searching}).
 
 @table @kbd
 @item M-g M-n
 @itemx M-g n
 @itemx C-x `
-Visit the locus of the next error message or match.
+Visit the locus of the next error message or match (@code{next-error}).
 @item M-g M-p
 @itemx M-g p
-Visit the locus of the previous error message or match.
-@item @key{RET}
-Visit the locus of the error message that point is on.
-This command is used in the compilation buffer.
-@item Mouse-2
-Visit the locus of the error message that you click on.
+Visit the locus of the previous error message or match
+(@code{previous-error}).
 @item M-n
-Find and highlight the locus of the next error message, without
-selecting the source buffer.
+Move point to the next error message or match, without visiting its
+locus (@code{compilation-next-error}).
 @item M-p
-Find and highlight the locus of the previous error message, without
-selecting the source buffer.
+Move point to the previous error message or match, without visiting
+its locus (@code{compilation-previous-error}).
 @item M-@}
-Move point to the next error for a different file than the current
-one.
+Move point to the next error message or match occurring in a different
+file (@code{compilation-next-file}).
 @item M-@{
-Move point to the previous error for a different file than the current
-one.
+Move point to the previous error message or match occurring in a
+different file (@code{compilation-previous-file}).
 @item C-c C-f
 Toggle Next Error Follow minor mode, which makes cursor motion in the
 compilation buffer produce automatic source display.
 @end table
 
-@findex compile-goto-error
-@vindex compilation-auto-jump-to-first-error
-  You can visit the source for any particular error message by moving
-point in the @samp{*compilation*} buffer to that error message and
-typing @key{RET} (@code{compile-goto-error}).  Alternatively, you can
-click @kbd{Mouse-2} on the error message; you need not switch to the
-@samp{*compilation*} buffer first.  If you set the variable
-@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
-Emacs automatically jumps to the first error, if any, as soon as it
-appears in the @samp{*compilation*} buffer.
-
 @kindex M-g M-n
 @kindex M-g n
 @kindex C-x `
 @findex next-error
 @vindex next-error-highlight
-  To parse the compiler error messages sequentially, type @kbd{C-x `}
-(@code{next-error}).  The character following the @kbd{C-x} is the
-backquote or ``grave accent,'' not the single-quote.  This command is
-available in all buffers, not just in @samp{*compilation*}; it
-displays the next error message at the top of one window and source
-location of the error in another window.  It also temporarily
-highlights the relevant source line, for a period controlled by the
-variable @code{next-error-highlight}.
-
-  The first time @w{@kbd{C-x `}} is used after the start of a compilation,
-it moves to the first error's location.  Subsequent uses of @kbd{C-x
-`} advance down to subsequent errors.  If you visit a specific error
-message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}}
-commands advance from there.  When @w{@kbd{C-x `}} gets to the end of the
-buffer and finds no more error messages to visit, it fails and signals
-an Emacs error.  @w{@kbd{C-u C-x `}} starts scanning from the beginning of
-the compilation buffer, and goes to the first error's location.
+  To visit errors sequentially, type @w{@kbd{C-x `}}
+(@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}.
+This command can be invoked from any buffer, not just a Compilation
+mode buffer.  The first time you invoke it after a compilation, it
+visits the locus of the first error message.  Each subsequent
+@w{@kbd{C-x `}} visits the next error, in a similar fashion.  If you
+visit a specific error with @key{RET} or a mouse click in the
+@samp{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
+advance from there.  When @w{@kbd{C-x `}} finds no more error messages
+to visit, it signals an error.  @w{@kbd{C-u C-x `}} starts again from
+the beginning of the compilation buffer, and visits the first locus.
+
+  @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates
+through errors in the opposite direction.
+
+  The @code{next-error} and @code{previous-error} commands don't just
+act on the errors or matches listed in @samp{*compilation*} and
+@samp{*grep*} buffers; they also know how to iterate through error or
+match lists produced by other commands, such as @kbd{M-x occur}
+(@pxref{Other Repeating Search}).  If you are already in a buffer
+containing error messages or matches, those are the ones that are
+iterated through; otherwise, Emacs looks for a buffer containing error
+messages or matches amongst the windows of the selected frame, then
+for one that @code{next-error} or @code{previous-error} previously
+iterated through, and finally amongst all other buffers.  If the
+buffer chosen for iterating through is not currently displayed in a
+window, it will be displayed.
 
 @vindex compilation-skip-threshold
-  By default, @w{@kbd{C-x `}} skips less important messages.  The variable
-@code{compilation-skip-threshold} controls this.  If its value is 2,
-@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less
-than warning, and 0 doesn't skip any messages.  The default is 1.
-
-  When the window has a left fringe, an arrow in the fringe points to
-the current message in the compilation buffer. The variable
-@code{compilation-context-lines} controls the number of lines of
-leading context to display before the current message.  Going to an
-error message location scrolls the @samp{*compilation*} buffer to put
-the message that far down from the top.  The value @code{nil} is
-special: if there's a left fringe, the window doesn't scroll at all
-if the message is already visible.  If there is no left fringe,
-@code{nil} means display the message at the top of the window.
-
-  If you're not in the compilation buffer when you run
-@code{next-error}, Emacs will look for a buffer that contains error
-messages.  First, it looks for one displayed in the selected frame,
-then for one that previously had @code{next-error} called on it, and
-then at the current buffer.  Finally, Emacs looks at all the remaining
-buffers.  @code{next-error} signals an error if it can't find any such
-buffer.
+  By default, the @code{next-error} and @code{previous-error} commands
+skip less important messages.  The variable
+@code{compilation-skip-threshold} controls this.  The default value,
+1, means to skip anything less important than a warning.  A value of 2
+means to skip anything less important than an error, while 0 means not
+to skip any messages.
+
+  When Emacs visits the locus of an error message, it momentarily
+highlights the relevant source line.  The duration of this highlight
+is determined by the variable @code{next-error-highlight}.
+
+@vindex compilation-context-lines
+  If the @samp{*compilation*} buffer is shown in a window with a left
+fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
+the fringe, pointing to the current error message.  If the window has
+no left fringe, such as on a text-only terminal, these commands scroll
+the window so that the current message is at the top of the window.
+If you change the variable @code{compilation-context-lines} to an
+integer value @var{n}, these commands scroll the window so that the
+current error message is @var{n} lines from the top, whether or not
+there is a fringe; the default value, @code{nil}, gives the behavior
+described above.
 
 @vindex compilation-error-regexp-alist
 @vindex grep-regexp-alist
   To parse messages from the compiler, Compilation mode uses the
 variable @code{compilation-error-regexp-alist} which lists various
-formats of error messages and tells Emacs how to extract the source file
-and the line number from the text of a message.  If your compiler isn't
-supported, you can tailor Compilation mode to it by adding elements to
-that list.  A similar variable @code{grep-regexp-alist} tells Emacs how
-to parse output of a @code{grep} command.
+error message formats and tells Emacs how to extract the locus from
+each.  A similar variable, @code{grep-regexp-alist}, tells Emacs how
+to parse output from a @code{grep} command (@pxref{Grep Searching}).
 
 @findex compilation-next-error
 @findex compilation-previous-error
 @findex compilation-next-file
 @findex compilation-previous-file
-  Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
-scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
-and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
-or previous error message.  You can also use @kbd{M-@{}
-(@code{compilation-next-file} and @kbd{M-@}}
-(@code{compilation-previous-file}) to move up or down to an error
-message for a different source file.
+  Compilation mode also defines the keys @key{SPC} and @key{DEL} to
+scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and
+@kbd{M-p} (@code{compilation-previous-error}) to move to the next or
+previous error message; and @kbd{M-@{} (@code{compilation-next-file})
+and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next
+or previous error message for a different source file.
 
 @cindex Next Error Follow mode
 @findex next-error-follow-minor-mode
   You can type @kbd{C-c C-f} to toggle Next Error Follow mode.  In
 this minor mode, ordinary cursor motion in the compilation buffer
-automatically updates the source buffer.  For instance, moving the
-cursor to the next error message causes the location of that error to
-be displayed immediately.
+automatically updates the source buffer, i.e.@: moving the cursor over
+an error message causes the locus of that error to be displayed.
 
   The features of Compilation mode are also available in a minor mode
 called Compilation Minor mode.  This lets you parse error messages in
-any buffer, not just a normal compilation output buffer.  Type @kbd{M-x
-compilation-minor-mode} to enable the minor mode.  This defines the keys
-@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
-
-  Compilation minor mode works in any buffer, as long as the contents
-are in a format that it understands.  In an Rlogin buffer (@pxref{Remote
-Host}), Compilation minor mode automatically accesses remote source
-files by FTP (@pxref{File Names}).
+any buffer, not just a normal compilation output buffer.  Type
+@kbd{M-x compilation-minor-mode} to enable the minor mode.  For
+instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor
+mode automatically accesses remote source files by FTP (@pxref{File
+Names}).
 
 @node Compilation Shell
 @section Subshells for Compilation
 
-  Emacs uses a shell to run the compilation command, but specifies the
-option for a noninteractive shell.  This means, in particular, that
-the shell should start with no prompt.  If you find your usual shell
-prompt making an unsightly appearance in the @samp{*compilation*}
-buffer, it means you have made a mistake in your shell's init file by
-setting the prompt unconditionally.  (This init file's name may be
-@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
-various other things, depending on the shell you use.)  The shell init
+  The @kbd{M-x compile} command uses a shell to run the compilation
+command, but specifies the option for a noninteractive shell.  This
+means, in particular, that the shell should start with no prompt.  If
+you find your usual shell prompt making an unsightly appearance in the
+@samp{*compilation*} buffer, it means you have made a mistake in your
+shell's init file by setting the prompt unconditionally.  (This init
+file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc},
+@file{.shrc}, etc., depending on what shell you use.)  The shell init
 file should set the prompt only if there already is a prompt.  Here's
 how to do it in bash:
 
@@ -322,67 +296,80 @@ And here's how to do it in csh:
 if ($?prompt) set prompt = @dots{}
 @end example
 
-  There may well be other things that your shell's init file
-ought to do only for an interactive shell.  You can use the same
-method to conditionalize them.
+  Emacs does not expect a compiler process to launch asynchronous
+subprocesses; if it does, and they keep running after the main
+compiler process has terminated, Emacs may kill them or their output
+may not arrive in Emacs.  To avoid this problem, make the main
+compilation process wait for its subprocesses to finish.  In a shell
+script, you can do this using @samp{$!} and @samp{wait}, like this:
+
+@example
+(sleep 10; echo 2nd)& pid=$!  # @r{Record pid of subprocess}
+echo first message
+wait $pid                     # @r{Wait for subprocess}
+@end example
+
+@noindent
+If the background process does not output to the compilation buffer,
+so you only need to prevent it from being killed when the main
+compilation process terminates, this is sufficient:
+
+@example
+nohup @var{command}; sleep 1
+@end example
 
-  The MS-DOS ``operating system'' does not support asynchronous
-subprocesses; to work around this lack, @kbd{M-x compile} runs the
-compilation command synchronously on MS-DOS.  As a consequence, you must
-wait until the command finishes before you can do anything else in
-Emacs.
-@iftex
-@inforef{MS-DOS,,emacs-xtra}.
-@end iftex
 @ifnottex
-@xref{MS-DOS}.
+  On the MS-DOS ``operating system'', asynchronous subprocesses are
+not supported, so @kbd{M-x compile} runs the compilation command
+synchronously (i.e.@: you must wait until the command finishes before
+you can do anything else in Emacs).  @xref{MS-DOS}.
 @end ifnottex
 
 @node Grep Searching
 @section Searching with Grep under Emacs
 
   Just as you can run a compiler from Emacs and then visit the lines
-with compilation errors, you can also run @code{grep} and then visit
-the lines on which matches were found.  This works by treating the
-matches reported by @code{grep} as if they were ``errors.''  The
-buffer of matches uses Grep mode, which is a variant of Compilation
+with compilation errors, you can also run @command{grep} and then
+visit the lines on which matches were found.  This works by treating
+the matches reported by @command{grep} as if they were ``errors.''
+The output buffer uses Grep mode, which is a variant of Compilation
 mode (@pxref{Compilation Mode}).
 
 @table @kbd
 @item M-x grep
 @itemx M-x lgrep
-Run @code{grep} asynchronously under Emacs, with matching lines
-listed in the buffer named @samp{*grep*}.
+Run @command{grep} asynchronously under Emacs, listing matching lines in
+the buffer named @samp{*grep*}.
 @item M-x grep-find
 @itemx M-x find-grep
 @itemx M-x rgrep
-Run @code{grep} via @code{find}, and collect output in the buffer
-named @samp{*grep*}.
+Run @command{grep} via @code{find}, and collect output in the
+@samp{*grep*} buffer.
 @item M-x zrgrep
-Run @code{zgrep} and collect output in the buffer named @samp{*grep*}.
+Run @code{zgrep} and collect output in the @samp{*grep*} buffer.
 @item M-x kill-grep
-Kill the running @code{grep} subprocess.
+Kill the running @command{grep} subprocess.
 @end table
 
 @findex grep
-  To run @code{grep}, type @kbd{M-x grep}, then enter a command line
-that specifies how to run @code{grep}.  Use the same arguments you
-would give @code{grep} when running it normally: a @code{grep}-style
+  To run @command{grep}, type @kbd{M-x grep}, then enter a command line
+that specifies how to run @command{grep}.  Use the same arguments you
+would give @command{grep} when running it normally: a @command{grep}-style
 regexp (usually in single-quotes to quote the shell's special
 characters) followed by file names, which may use wildcards.  If you
 specify a prefix argument for @kbd{M-x grep}, it finds the tag
 (@pxref{Tags}) in the buffer around point, and puts that into the
-default @code{grep} command.
+default @command{grep} command.
 
-  Your command need not simply run @code{grep}; you can use any shell
+  Your command need not simply run @command{grep}; you can use any shell
 command that produces output in the same format.  For instance, you
-can chain @code{grep} commands, like this:
+can chain @command{grep} commands, like this:
 
 @example
 grep -nH -e foo *.el | grep bar | grep toto
 @end example
 
-  The output from @code{grep} goes in the @samp{*grep*} buffer.  You
+  The output from @command{grep} goes in the @samp{*grep*} buffer.  You
 can find the corresponding lines in the original files using @w{@kbd{C-x
 `}}, @key{RET}, and so forth, just like compilation errors.
 
@@ -397,30 +384,31 @@ match will be highlighted, instead of the entire source line.
   The command @kbd{M-x grep-find} (also available as @kbd{M-x
 find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
 initial default for the command---one that runs both @code{find} and
-@code{grep}, so as to search every file in a directory tree.  See also
+@command{grep}, so as to search every file in a directory tree.  See also
 the @code{find-grep-dired} command, in @ref{Dired and Find}.
 
 @findex lgrep
 @findex rgrep
 @findex zrgrep
   The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
-(recursive grep) are more user-friendly versions of @code{grep} and
+(recursive grep) are more user-friendly versions of @command{grep} and
 @code{grep-find}, which prompt separately for the regular expression
 to match, the files to search, and the base directory for the search.
 Case sensitivity of the search is controlled by the current value of
 @code{case-fold-search}.  The command @kbd{M-x zrgrep} is similar to
-@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to
-search the contents of gzipped files.
+@kbd{M-x rgrep}, but it calls @command{zgrep} instead of
+@command{grep} to search the contents of gzipped files.
 
   These commands build the shell commands based on the variables
 @code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
 (for @code{rgrep}).  The files to search can use aliases defined in
 the variable @code{grep-files-aliases}.
 
-  Subdirectories listed in the variable
-@code{grep-find-ignored-directories} such as those typically used by
-various version control systems, like CVS and arch, are automatically
-skipped by @code{rgrep}.
+@vindex grep-find-ignored-directories
+  Directories listed in the variable
+@code{grep-find-ignored-directories} are automatically skipped by
+@kbd{M-x rgrep}.  The default value includes the data directories used
+by various version control systems.
 
 @node Flymake
 @section Finding Syntax Errors On The Fly
@@ -444,8 +432,13 @@ flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}.  To
 display any error messages associated with the current line, use
 @kbd{M-x flymake-display-err-menu-for-current-line}.
 
-  For more details about using Flymake, see @ref{Top, Flymake,
-Flymake, flymake, The Flymake Manual}.
+  For more details about using Flymake,
+@ifnottex
+see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}.
+@end ifnottex
+@iftex
+see the Flymake Info manual, which is distributed with Emacs.
+@end iftex
 
 @node Debuggers
 @section Running Debuggers Under Emacs
@@ -459,16 +452,18 @@ Flymake, flymake, The Flymake Manual}.
 @cindex JDB
 @cindex PDB
 
-@c Do you believe in GUD?
 The GUD (Grand Unified Debugger) library provides an Emacs interface
-to a wide variety of symbolic debuggers.  Unlike the GDB graphical
-interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
-can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
-PDB, or the Java Debugger JDB.
+to a wide variety of symbolic debuggers.  It can run the GNU Debugger
+(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python
+debugger PDB, and the Java Debugger JDB.
 
-  In addition, Emacs contains a built-in system for debugging Emacs
-Lisp programs.  @xref{Debugging,, The Lisp Debugger, elisp, the Emacs
-Lisp Reference Manual}, for information on the Emacs Lisp debugger.
+  Emacs provides a special interface to GDB, which uses extra Emacs
+windows to display the state of the debugged program.  @xref{GDB
+Graphical Interface}.
+
+  Emacs also has a built-in debugger for Emacs Lisp programs.
+@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
+Manual}.
 
 @menu
 * Starting GUD::        How to start a debugger subprocess.
@@ -483,146 +478,136 @@ Lisp Reference Manual}, for information on the Emacs Lisp debugger.
 @node Starting GUD
 @subsection Starting GUD
 
-  There are several commands for starting a debugger under GUD, each
+  There are several commands for starting a debugger subprocess, each
 corresponding to a particular debugger program.
 
 @table @kbd
-@item M-x gdb @key{RET} @var{file} @key{RET}
+@item M-x gdb
 @findex gdb
-Run GDB as a subprocess of Emacs.  This uses an IDE-like graphical
-interface; see @ref{GDB Graphical Interface}.  Only GDB works with the
-graphical interface.
+Run GDB as a subprocess, and interact with it via an IDE-like Emacs
+interface.  @xref{GDB Graphical Interface}, for more information about
+this command.
 
-@item M-x gud-gdb @key{RET} @var{file} @key{RET}
+@item M-x gud-gdb
 @findex gud-gdb
-Run GDB as a subprocess of Emacs.  This command creates a buffer for
-input and output to GDB, and switches to it.  If a GDB buffer already
-exists, it just switches to that buffer.
-
-@item M-x dbx @key{RET} @var{file} @key{RET}
-@findex dbx
-Run DBX as a subprocess of Emacs.  Since Emacs does not implement a
-graphical interface for DBX, communication with DBX works by typing
-commands in the GUD interaction buffer.  The same is true for all
-the other supported debuggers.
+Run GDB, using a GUD interaction buffer for input and output to the
+GDB subprocess (@pxref{Debugger Operation}).  If such a buffer already
+exists, switch to it; otherwise, create the buffer and switch to it.
 
-@item M-x xdb @key{RET} @var{file} @key{RET}
-@findex xdb
-@vindex gud-xdb-directories
-Run XDB as a subprocess of Emacs.  Use the variable
-@code{gud-xdb-directories} to specify directories to search for source
-files.
-
-@item M-x sdb @key{RET} @var{file} @key{RET}
-@findex sdb
-Run SDB as a subprocess of Emacs.
+The other commands in this list do the same, for other debugger
+programs.
 
-Some versions of SDB do not mention source file names in their
-messages.  When you use them, you need to have a valid tags table
-(@pxref{Tags}) in order for GUD to find functions in the source code.
-If you have not visited a tags table or the tags table doesn't list
-one of the functions, you get a message saying @samp{The sdb support
-requires a valid tags table to work}.  If this happens, generate a
-valid tags table in the working directory and try again.
-
-@item M-x perldb @key{RET} @var{file} @key{RET}
+@item M-x perldb
 @findex perldb
-Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
+Run the Perl interpreter in debug mode.
 
-@item M-x jdb @key{RET} @var{file} @key{RET}
+@item M-x jdb
 @findex jdb
-Run the Java debugger to debug @var{file}.
+Run the Java debugger.
 
-@item M-x pdb @key{RET} @var{file} @key{RET}
+@item M-x pdb
 @findex pdb
-Run the Python debugger to debug @var{file}.
+Run the Python debugger.
+
+@item M-x dbx
+@findex dbx
+Run the DBX debugger.
+
+@item M-x xdb
+@findex xdb
+@vindex gud-xdb-directories
+Run the XDB debugger.
+
+@item M-x sdb
+@findex sdb
+Run the SDB debugger.
 @end table
 
-  Each of these commands takes one argument: a command line to invoke
-the debugger.  In the simplest case, specify just the name of the
-executable file you want to debug.  You may also use options that the
-debugger supports.  However, shell wildcards and variables are not
-allowed.  GUD assumes that the first argument not starting with a
-@samp{-} is the executable file name.
+  Each of these commands reads a command line to invoke the debugger,
+using the minibuffer.  The minibuffer's initial contents contain the
+standard executable name and options for the debugger, and sometimes
+also a guess for the name of the executable file you want to debug.
+Shell wildcards and variables are not allowed in this command line.
+Emacs assumes that the first command argument which does not start
+with a @samp{-} is the executable file name.
 
 @cindex remote host, debugging on
-Tramp provides a facility to debug programs on remote hosts
-(@pxref{Running a debugger on a remote host, Running a debugger on a
-remote host,, tramp, The Tramp Manual}), whereby both the debugger and
-the program being debugged are on the same remote host.  This should
-not be confused with debugging programs remotely, where the program
-and the debugger run on different machines, as can be done using the
-GDB remote debugging feature, for example (@pxref{Remote Debugging,,
-Debugging Remote Programs, gdb, The GNU debugger}).
+  Tramp provides a facility for remote debugging, whereby both the
+debugger and the program being debugged are on the same remote host.
+@xref{Running a debugger on a remote host,,, tramp, The Tramp Manual},
+for details.  This is separate from GDB's remote debugging feature,
+where the program and the debugger run on different machines
+(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU
+debugger}).
 
 @node Debugger Operation
 @subsection Debugger Operation
+@cindex GUD interaction buffer
+
+  The @dfn{GUD interaction buffer} is an Emacs buffer which is used to
+send text commands to a debugger subprocess, and record its output.
+This is the basic interface for interacting with a debugger, used by
+@kbd{M-x gud-gdb} and other commands listed in
+@iftex
+the preceding section.
+@end iftex
+@ifnottex
+@ref{Starting GUD}.
+@end ifnottex
+The @kbd{M-x gdb} command extends this interface with additional
+specialized buffers for controlling breakpoints, stack frames, and
+other aspects of the debugger state (@pxref{GDB Graphical Interface}).
 
-@cindex fringes, and current execution line in GUD
-  Generally when you run a debugger with GUD, the debugger uses an Emacs
-buffer for its ordinary input and output.  This is called the GUD
-buffer.  Input and output from the program you are debugging also use
-this buffer.  We call this @dfn{text command mode}.  The GDB Graphical
-Interface can use further buffers (@pxref{GDB Graphical Interface}).
-
-  The debugger displays the source files of the program by visiting
-them in Emacs buffers.  An arrow in the left fringe indicates the
-current execution line.@footnote{On a text-only terminal, the arrow
-appears as @samp{=>} and overlays the first two text columns.}  Moving
-point in this buffer does not move the arrow.  The arrow is not part
-of the file's text; it appears only on the screen.
-
-  You can start editing these source files at any time in the buffers
-that display them.  If you do modify a source file, keep in mind that
-inserting or deleting lines will throw off the arrow's positioning;
-GUD has no way of figuring out which line corresponded before your
-changes to the line number in a debugger message.  Also, you'll
-typically have to recompile and restart the program for your changes
-to be reflected in the debugger's tables.
-
-@cindex tooltips with GUD
-@vindex tooltip-gud-modes
-@vindex gud-tooltip-mode
+  The GUD interaction buffer uses a variant of Shell mode, so the
+Emacs commands defined by Shell mode are available (@pxref{Shell
+Mode}).  Completion is available for most debugger commands
+(@pxref{Completion}), and you can use the usual Shell mode history
+commands to repeat them.
+@iftex
+See the next section
+@end iftex
+@ifnottex
+@xref{Commands of GUD},
+@end ifnottex
+for special commands that can be used in the GUD interaction buffer.
+
+  As you debug a program, Emacs displays the relevant source files by
+visiting them in Emacs buffers, with an arrow in the left fringe
+indicating the current execution line.  (On a text-only terminal, the
+arrow appears as @samp{=>}, overlaid on the first two text columns.)
+Moving point in such a buffer does not move the arrow.  You are free
+to edit these source files, but note that inserting or deleting lines
+will throw off the arrow's positioning, as Emacs has no way to figure
+out which edited source line corresponds to the line reported by the
+debugger subprocess.  To update this information, you typically have
+to recompile and restart the program.
+
+@cindex GUD Tooltip mode
+@cindex mode, GUD Tooltip
+@findex gud-tooltip-mode
 @vindex gud-tooltip-echo-area
-  The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
-You activate this feature by turning on the minor mode
-@code{gud-tooltip-mode}.  Then you can display a variable's value in a
-tooltip simply by pointing at it with the mouse.  This operates in the
-GUD buffer and in source buffers with major modes in the list
-@code{gud-tooltip-modes}.  If the variable @code{gud-tooltip-echo-area}
-is non-@code{nil} then the variable's value is displayed in the echo
-area.  When debugging a C program using the GDB Graphical Interface, you
-can also display macro definitions associated with an identifier when
-the program is not executing.
-
-  GUD tooltips are disabled when you use GDB in text command mode
-(@pxref{GDB Graphical Interface}), because displaying an expression's
-value in GDB can sometimes expand a macro and result in a side effect
-that interferes with the program's operation.  The GDB graphical
-interface supports GUD tooltips and assures they will not cause side
-effects.
+  GUD Tooltip mode is a global minor mode that adds tooltip support to
+GUD.  To toggle this mode, type @kbd{M-x gud-tooltip-mode}.  It is
+disabled by default.  If enabled, you can move the mouse cursor over a
+variable to show its value in a tooltip (@pxref{Tooltips}); this takes
+effect in the GUD interaction buffer, and in all source buffers with
+major modes listed in the variable @code{gud-tooltip-modes}.  If the
+variable @code{gud-tooltip-echo-area} is non-@code{nil}, values are
+shown in the echo area instead of a tooltip.
+
+  When using GUD Tooltip mode with @kbd{M-x gud-gdb}, you should note
+that displaying an expression's value in GDB can sometimes expand a
+macro, potentially causing side effects in the debugged program.  If
+you use the @kbd{M-x gdb} interface, this problem does not occur, as
+there is special code to avoid side-effects; furthermore, you can
+display macro definitions associated with an identifier when the
+program is not executing.
 
 @node Commands of GUD
 @subsection Commands of GUD
 
-  The GUD interaction buffer uses a variant of Shell mode, so the
-Emacs commands of Shell mode are available (@pxref{Shell Mode}).  All
-the usual commands for your debugger are available, and you can use
-the Shell mode history commands to repeat them.  If you wish, you can
-control your debugger process entirely through this buffer.
-
-  GUD mode also provides commands for setting and clearing
-breakpoints, for selecting stack frames, and for stepping through the
-program.  These commands are available both in the GUD buffer and
-globally, but with different key bindings.  It also has its own tool
-bar from which you can invoke the more common commands by clicking on
-the appropriate icon.  This is particularly useful for repetitive
-commands like @code{gud-next} and @code{gud-step}, and allows you to
-keep the GUD buffer hidden.
-
-  The breakpoint commands are normally used in source file buffers,
-because that is the easiest way to specify where to set or clear the
-breakpoint.  Here's the global command to set a breakpoint:
+  GUD provides commands for setting and clearing breakpoints,
+selecting stack frames, and stepping through the program.
 
 @table @kbd
 @item C-x @key{SPC}
@@ -630,35 +615,42 @@ breakpoint.  Here's the global command to set a breakpoint:
 Set a breakpoint on the source line that point is on.
 @end table
 
+  @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source
+buffer, sets a debugger breakpoint on the current source line.  This
+command is available only after starting GUD.  If you call it in a
+buffer that is not associated with any debugger subprocess, it signals
+a error.
+
 @kindex C-x C-a @r{(GUD)}
-  Here are the other special commands provided by GUD@.  The keys
+  The following commands are available both in the GUD interaction
+buffer and globally, but with different key bindings.  The keys
 starting with @kbd{C-c} are available only in the GUD interaction
-buffer.  The key bindings that start with @kbd{C-x C-a} are available
-in the GUD interaction buffer and also in source files.  Some of these
-commands are not available to all the supported debuggers.
+buffer, while those starting with @kbd{C-x C-a} are available
+globally.  Some of these commands are also available via the tool bar;
+some are not supported by certain debuggers.
 
 @table @kbd
 @item C-c C-l
 @kindex C-c C-l @r{(GUD)}
 @itemx C-x C-a C-l
 @findex gud-refresh
-Display in another window the last line referred to in the GUD
-buffer (that is, the line indicated in the last location message).
-This runs the command @code{gud-refresh}.
+Display, in another window, the last source line referred to in the
+GUD interaction buffer (@code{gud-refresh}).
 
 @item C-c C-s
 @kindex C-c C-s @r{(GUD)}
 @itemx C-x C-a C-s
 @findex gud-step
-Execute a single line of code (@code{gud-step}).  If the line contains
-a function call, execution stops after entering the called function.
+Execute the next single line of code (@code{gud-step}).  If the line
+contains a function call, execution stops after entering the called
+function.
 
 @item C-c C-n
 @kindex C-c C-n @r{(GUD)}
 @itemx C-x C-a C-n
 @findex gud-next
-Execute a single line of code, stepping across entire function calls
-at full speed (@code{gud-next}).
+Execute the next single line of code, stepping across function calls
+without stopping inside the functions (@code{gud-next}).
 
 @item C-c C-i
 @kindex C-c C-i @r{(GUD)}
@@ -769,17 +761,17 @@ Instead, type @kbd{C-q @key{TAB}} to enter a tab.
 @vindex perldb-mode-hook
 @vindex pdb-mode-hook
 @vindex jdb-mode-hook
-  On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
-if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
-@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
-are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
-@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB.  You can
-use these hooks to define custom key bindings for the debugger
-interaction buffer.  @xref{Hooks}.
-
-  Here is a convenient way to define a command that sends a particular
-command string to the debugger, and set up a key binding for it in the
-debugger interaction buffer:
+  On startup, GUD runs one of the following hooks:
+@code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if
+you are using DBX; @code{sdb-mode-hook}, if you are using SDB;
+@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook},
+for Perl debugging mode; @code{pdb-mode-hook}, for PDB;
+@code{jdb-mode-hook}, for JDB.  @xref{Hooks}.
+
+  The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the
+Emacs Lisp Reference Manual}) provides a convenient way to define an
+Emacs command that sends a particular command string to the debugger,
+and set up a key binding for in the GUD interaction buffer:
 
 @findex gud-def
 @example
@@ -835,21 +827,22 @@ Fully qualified class name derived from the expression surrounding point
 @node GDB Graphical Interface
 @subsection GDB Graphical Interface
 
-  The command @code{gdb} starts GDB in a graphical interface, using
-Emacs windows for display program state information.  With it, you do
-not need to use textual GDB commands; you can control the debugging
-session with the mouse.  For example, you can click in the fringe of a
-source buffer to set a breakpoint there, or on a stack frame in the
-stack buffer to select that frame.
-
-  This mode requires telling GDB that its ``screen size'' is
-unlimited, so it sets the height and width accordingly.  For correct
-operation you must not change these values during the GDB session.
+  The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with
+specialized buffers for controlling breakpoints, stack frames, and
+other aspects of the debugger state.  It also provides additional ways
+to control the debugging session with the mouse, such as clicking in
+the fringe of a source buffer to set a breakpoint there.
 
 @vindex gud-gdb-command-name
-  To run GDB in text command mode, like the other debuggers in Emacs,
-use @kbd{M-x gud-gdb}.  You need to use text command mode to debug
-multiple programs within one Emacs session.
+  To run GDB using just the GUD interaction buffer interface, without
+these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting
+GUD}).  You must use this if you want to debug multiple programs
+within one Emacs session, as that is currently unsupported by @kbd{M-x
+gdb}.
+
+  Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is
+unlimited; for correct operation, you must not change GDB's screen
+height and width values during the debugging session.
 
 @menu
 * GDB User Interface Layout::   Control the number of displayed buffers.
@@ -858,8 +851,7 @@ multiple programs within one Emacs session.
 * Breakpoints Buffer::          A breakpoint control panel.
 * Threads Buffer::              Displays your threads.
 * Stack Buffer::                Select a frame from the call stack.
-* Other GDB Buffers::           Input/output, locals, registers,
-                                assembler, threads and memory buffers.
+* Other GDB Buffers::           Other buffers for controlling the GDB state.
 * Watch Expressions::           Monitor variable values in the speedbar.
 * Multithreaded Debugging::     Debugging programs with several threads.
 @end menu
@@ -869,12 +861,12 @@ multiple programs within one Emacs session.
 @cindex GDB User Interface layout
 
 @vindex gdb-many-windows
-  If the variable @code{gdb-many-windows} is @code{nil} (the default
-value) then @kbd{M-x gdb} normally displays only the GUD buffer.
+  If the variable @code{gdb-many-windows} is @code{nil} (the default),
+@kbd{M-x gdb} normally displays only the GUD interaction buffer.
 However, if the variable @code{gdb-show-main} is also non-@code{nil},
-it starts with two windows: one displaying the GUD buffer, and the
-other showing the source for the @code{main} function of the program
-you are debugging.
+it starts with two windows: one displaying the GUD interaction buffer,
+and the other showing the source for the @code{main} function of the
+program you are debugging.
 
   If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
 displays the following frame layout:
@@ -882,7 +874,7 @@ displays the following frame layout:
 @smallexample
 @group
 +--------------------------------+--------------------------------+
-|   GUD buffer (I/O of GDB)      |   Locals/Registers buffer      |
+|   GUD interaction buffer       |   Locals/Registers buffer      |
 |--------------------------------+--------------------------------+
 |   Primary Source buffer        |   I/O buffer for debugged pgm  |
 |--------------------------------+--------------------------------+
@@ -896,264 +888,233 @@ buffer does not appear and the primary source buffer occupies the full
 width of the frame.
 
 @findex gdb-restore-windows
-  If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore this standard window
-layout with the command @code{gdb-restore-windows}.
-
 @findex gdb-many-windows
-  To switch between this standard layout and a simple layout
-containing just the GUD buffer and a source file, type @kbd{M-x
-gdb-many-windows}.
+  If you ever change the window layout, you can restore the ``many
+windows'' layout by typing @kbd{M-x gdb-restore-windows}.  To toggle
+between the many windows layout and a simple layout with just the GUD
+interaction buffer and a source file, type @kbd{M-x gdb-many-windows}.
 
   You may also specify additional GDB-related buffers to display,
 either in the same frame or a different one.  Select the buffers you
-want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames}
-sub-menus.  If the menu-bar is unavailable, type @code{M-x
-gdb-display-@var{buffertype}-buffer} or @code{M-x
-gdb-frame-@var{buffertype}-buffer} respectively, where
-@var{buffertype} is the relevant buffer type, such as
-@samp{breakpoints}.  Most of these buffers are read-only, and typing
-@kbd{q} in them kills them.
-
-  When you finish debugging, kill the GUD buffer with @kbd{C-x k},
-which will also kill all the buffers associated with the session.
-However you need not do this if, after editing and re-compiling your
-source code within Emacs, you wish continue debugging.  When you
-restart execution, GDB will automatically find your new executable.
-Keeping the GUD buffer has the advantage of keeping the shell history
-as well as GDB's breakpoints.  You do need to check that the
-breakpoints in recently edited source files are still in the right
-places.
+want by typing @code{M-x gdb-display-@var{buffertype}-buffer} or
+@code{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype}
+is the relevant buffer type, such as @samp{breakpoints}.  You can do
+the same with the menu bar, with the @samp{GDB-Windows} and
+@samp{GDB-Frames} sub-menus of the @samp{GUD} menu.
+
+  When you finish debugging, kill the GUD interaction buffer with
+@kbd{C-x k}, which will also kill all the buffers associated with the
+session.  However you need not do this if, after editing and
+re-compiling your source code within Emacs, you wish to continue
+debugging.  When you restart execution, GDB automatically finds the
+new executable.  Keeping the GUD interaction buffer has the advantage
+of keeping the shell history as well as GDB's breakpoints.  You do
+need to check that the breakpoints in recently edited source files are
+still in the right places.
 
 @node Source Buffers
 @subsubsection Source Buffers
-@cindex GDB commands in Fringe
-
-@c @findex gdb-mouse-set-clear-breakpoint
-@c @findex gdb-mouse-toggle-breakpoint
-Many GDB commands can be entered using key bindings or the tool bar but
-sometimes it is quicker to use the fringe.  These commands either
-manipulate breakpoints or control program execution.  When there is no
-fringe, you can use the margin but this is only present when the
-source file already has a breakpoint.
-
-You can click @kbd{Mouse-1} in the fringe or display margin of a
-source buffer to set a breakpoint there and, on a graphical display, a
-red bullet will appear on that line.  If a breakpoint already exists
-on that line, the same click will remove it.  You can also enable or
-disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
-
-A solid arrow in the left fringe of a source buffer indicates the line
-of the innermost frame where the debugged program has stopped. A
-hollow arrow indicates the current execution line of higher level
-frames.
-
-If you drag the arrow in the fringe with @kbd{Mouse-1}
-(@code{gdb-mouse-until}), execution will continue to the line where
-you release the button, provided it is still in the same frame.
-Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
-of this buffer and execution will advance to there.  A similar command
-(@code{gdb-mouse-jump}) allows you to jump to a source line without
-executing the intermediate lines by clicking @kbd{C-Mouse-3}.  This
-command allows you to go backwards which can be useful for running
-through code that has already executed, in order to examine its
-execution in more detail.
+@cindex fringes, for debugging
 
-@table @kbd
-@item Mouse-1
-Set or clear a breakpoint.
+@table @asis
+@item @kbd{Mouse-1} (in fringe)
+Set or clear a breakpoint on that line.
 
-@item C-Mouse-1
-Enable or disable a breakpoint.
+@item @kbd{C-Mouse-1} (in fringe)
+Enable or disable a breakpoint on that line.
 
-@item Mouse-3
-Continue execution to here.
+@item @kbd{Mouse-3} (in fringe)
+Continue execution to that line.
 
-@item C-Mouse-3
-Jump to here.
+@item @kbd{C-Mouse-3} (in fringe)
+Jump to that line.
 @end table
 
-If the variable @code{gdb-find-source-frame} is non-@code{nil} and
-execution stops in a frame for which there is no source code e.g after
-an interrupt, then Emacs finds and displays the first frame further up
-stack for which there is source.  If it is @code{nil} then the source
-buffer continues to display the last frame which maybe more useful,
-for example, when re-setting a breakpoint.
+  On a graphical display, you can click @kbd{Mouse-1} in the fringe of
+a source buffer, to set a breakpoint on that line (@pxref{Fringes}).
+A red dot appears in the fringe, where you clicked.  If a breakpoint
+already exists there, the click removes it.  A @kbd{C-Mouse-1} click
+enables or disables an existing breakpoint; a breakpoint that is
+disabled, but not unset, is indicated by a gray dot.
+
+  On a text-only terminal, or when fringes are disabled, enabled
+breakpoints are indicated with a @samp{B} character in the left margin
+of the window.  Disabled breakpoints are indicated with @samp{b}.
+(The margin is only displayed if a breakpoint is present.)
+
+  A solid arrow in the left fringe of a source buffer indicates the
+line of the innermost frame where the debugged program has stopped. A
+hollow arrow indicates the current execution line of a higher-level
+frame.  If you drag the arrow in the fringe with @kbd{Mouse-1}, that
+causes execution to advance to the line where you release the button.
+Alternatively, you can click @kbd{Mouse-3} in the fringe to advance to
+that line.  You can click @kbd{C-Mouse-3} in the fringe to jump to
+that line without executing the intermediate lines.  This command
+allows you to go backwards, which can be useful for running through
+code that has already executed, in order to examine its execution in
+more detail.
 
 @node Breakpoints Buffer
 @subsubsection Breakpoints Buffer
 
-  The breakpoints buffer shows the existing breakpoints, watchpoints and
-catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}).  It has
-these special commands, which mostly apply to the @dfn{current
-breakpoint}, the breakpoint which point is on.
+  The GDB Breakpoints buffer shows the breakpoints, watchpoints and
+catchpoints in the debugger session.  @xref{Breakpoints,,, gdb, The
+GNU debugger}.  It provides the following commands, which mostly apply
+to the @dfn{current breakpoint} (the breakpoint which point is on):
 
 @table @kbd
 @item @key{SPC}
-@kindex SPC @r{(GDB breakpoints buffer)}
+@kindex SPC @r{(GDB Breakpoints buffer)}
 @findex gdb-toggle-breakpoint
-Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).
-On a graphical display, this changes the color of a bullet in the
-margin of a source buffer at the relevant line.  This is red when
-the breakpoint is enabled and gray when it is disabled.  Text-only
-terminals correspondingly display a @samp{B} or @samp{b}.
+Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).  On
+a graphical display, this changes the color of the dot in the fringe
+of the source buffer at that line.  The dot is red when the breakpoint
+is enabled, and gray when it is disabled.
 
 @item D
-@kindex D @r{(GDB breakpoints buffer)}
+@kindex D @r{(GDB Breakpoints buffer)}
 @findex gdb-delete-breakpoint
 Delete the current breakpoint (@code{gdb-delete-breakpoint}).
 
 @item @key{RET}
-@kindex RET @r{(GDB breakpoints buffer)}
+@kindex RET @r{(GDB Breakpoints buffer)}
 @findex gdb-goto-breakpoint
 Visit the source line for the current breakpoint
 (@code{gdb-goto-breakpoint}).
 
 @item Mouse-2
-@kindex Mouse-2 @r{(GDB breakpoints buffer)}
+@kindex Mouse-2 @r{(GDB Breakpoints buffer)}
 Visit the source line for the breakpoint you click on.
 @end table
 
 @vindex gdb-show-threads-by-default
-When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
-shares its window with the threads buffer.  To switch from one to the
-other click with @kbd{Mouse-1} on the relevant button in the header
-line.  If @code{gdb-show-threads-by-default} is non-@code{nil}, the
-threads buffer, rather than the breakpoints buffer, is shown at start
-up.
+  When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints
+buffer shares its window with the GDB Threads buffer.  To switch from
+one to the other click with @kbd{Mouse-1} on the relevant button in
+the header line.  If @code{gdb-show-threads-by-default} is
+non-@code{nil}, the GDB Threads buffer is the one shown by default.
 
 @node Threads Buffer
 @subsubsection Threads Buffer
 
 @findex gdb-select-thread
-The threads buffer displays a summary of all threads currently in your
-program (@pxref{Threads, Threads, Debugging programs with multiple
-threads, gdb, The GNU debugger}).  Move point to any thread in the list
-and press @key{RET} to select it (@code{gdb-select-thread}) and
-display the associated source in the primary source buffer.
-Alternatively, click @kbd{Mouse-2} on a thread to select it.  Contents
-of all GDB buffers are updated whenever you select a thread.
+  The GDB Threads buffer displays a summary of the threads in the
+debugged program.  @xref{Threads, Threads, Debugging programs with
+multiple threads, gdb, The GNU debugger}.  To select a thread, move
+point there and type @key{RET} (@code{gdb-select-thread}), or click on
+it with @kbd{Mouse-2}.  This also displays the associated source
+buffer, and updates the contents of the other GDB buffers.
 
   You can customize variables under @code{gdb-buffers} group to select
-fields included in threads buffer.
+fields included in GDB Threads buffer.
 
 @table @code
 @item gdb-thread-buffer-verbose-names
 @vindex gdb-thread-buffer-verbose-names
-Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in
-threads buffer.
+Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}.
 
 @item gdb-thread-buffer-arguments
 @vindex gdb-thread-buffer-arguments
-Show arguments of thread top frames in threads buffer.
+Show arguments of thread top frames.
 
 @item gdb-thread-buffer-locations
 @vindex gdb-thread-buffer-locations
-Show file information or library names in threads buffer.
+Show file information or library names.
 
 @item gdb-thread-buffer-addresses
 @vindex gdb-thread-buffer-addresses
 Show addresses for thread frames in threads buffer.
 @end table
 
-  It's possible to observe information for several threads
-simultaneously (in addition to buffers which show information for
-currently selected thread) using the following keys from the threads
-buffer.
+  To view information for several threads simultaneously, use the
+following commands from the GDB Threads buffer.
 
 @table @kbd
 @item d
 @kindex d @r{(GDB threads buffer)}
 @findex gdb-display-disassembly-for-thread
-Display disassembly buffer for the thread at current line.
-(@code{gdb-display-disassembly-for-thread})
+Display disassembly buffer for the thread at current line
+(@code{gdb-display-disassembly-for-thread}).
 
 @item f
 @kindex f @r{(GDB threads buffer)}
 @findex gdb-display-stack-for-thread
-Display stack buffer for the thread at current line.
+Display the GDB Stack buffer for the thread at current line
 (@code{gdb-display-stack-for-thread}).
 
 @item l
 @kindex l @r{(GDB threads buffer)}
 @findex gdb-display-locals-for-thread
-Display locals buffer for the thread at current line.
+Display the GDB Locals buffer for the thread at current line
 (@code{gdb-display-locals-for-thread}).
 
 @item r
 @kindex r @r{(GDB threads buffer)}
 @findex gdb-display-registers-for-thread
-Display registers buffer for the thread at current line.
+Display the GDB Registers buffer for the thread at current line
 (@code{gdb-display-registers-for-thread}).
 @end table
 
-Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and
-@kbd{R} displays the corresponding buffer in a new frame.
+@noindent
+Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R},
+display the corresponding buffer in a new frame.
 
   When you create a buffer showing information about some specific
 thread, it becomes bound to that thread and keeps showing actual
-information while you debug your program.  Every GDB buffer contains a
-number of thread it shows information for in its mode name.  Thread
-number is also included in the buffer name of bound buffers to prevent
-buffer names clashing.
+information while you debug your program.  The mode indicator for each
+GDB buffer shows the number of thread it is showing information about.
+The thread number is also included in the buffer name of bound
+buffers.
 
-Further commands are available in the threads buffer which depend on the
-mode of GDB that is used for controlling execution of your program.
-(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}).
+  Further commands are available in the GDB Threads buffer which
+depend on the mode of GDB that is used for controlling execution of
+your program.  @xref{Multithreaded Debugging}.
 
 @node Stack Buffer
 @subsubsection Stack Buffer
 
-  The stack buffer displays a @dfn{call stack}, with one line for each
-of the nested subroutine calls (@dfn{stack frames}) now active in the
-program.  @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
+  The GDB Stack buffer displays a @dfn{call stack}, with one line for
+each of the nested subroutine calls (@dfn{stack frames}) in the
+debugger session.  @xref{Backtrace,, Backtraces, gdb, The GNU
+debugger}.
 
 @findex gdb-frames-select
-An arrow in the fringe points to the selected frame or, if the fringe is
-not present, the number of the selected frame is displayed in reverse
-contrast.  To select a frame in GDB, move point in the stack buffer to
-that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
-@kbd{Mouse-2} on a stack frame.  If the locals buffer is visible,
-selecting a stack frame updates it to display the local variables of the
-new frame.
+  On graphical displays, the selected stack frame is indicated by an
+arrow in the fringe.  On text-only terminals, or when fringes are
+disabled, the selected stack frame is displayed in reverse contrast.
+To select a stack frame, move point in its line and type @key{RET}
+(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it.  Doing so
+also updates the Locals buffer
+@ifnottex
+(@pxref{Other GDB Buffers}).
+@end ifnottex
+@iftex
+(described in the next section).
+@end iftex
 
 @node Other GDB Buffers
-@subsubsection Other Buffers
+@subsubsection Other GDB Buffers
 
 @table @asis
-@item Input/Output Buffer
-@vindex gdb-use-separate-io-buffer
-If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
-the program being debugged takes its input and displays its output
-here.  Otherwise it uses the GUD buffer for that.  To toggle whether
-GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
-This takes effect when you next restart the program you are debugging.
-
-The history and replay commands from Shell mode are available here,
-as are the commands to send signals to the debugged program.
-@xref{Shell Mode}.
-
 @item Locals Buffer
-The locals buffer displays the values of local variables of the
-current frame for simple data types (@pxref{Frame Info, Frame Info,
+This buffer displays the values of local variables of the current
+frame for simple data types (@pxref{Frame Info, Frame Info,
 Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
 click @kbd{Mouse-2} on the value if you want to edit it.
 
 Arrays and structures display their type only.  With GDB 6.4 or later,
-move point to their name and press @key{RET}, or alternatively click
-@kbd{Mouse-2} there, to examine their values.  With earlier versions
-of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
+you can examine the value of the local variable at point by typing
+@key{RET}, or with a @kbd{Mouse-2} click.  With earlier versions of
+GDB, use @key{RET} or @kbd{Mouse-2} on the type description
 (@samp{[struct/union]} or @samp{[array]}).  @xref{Watch Expressions}.
 
 @item Registers Buffer
 @findex toggle-gdb-all-registers
-The registers buffer displays the values held by the registers
+This buffer displays the values held by the registers
 (@pxref{Registers,,, gdb, The GNU debugger}).  Press @key{RET} or
-click @kbd{Mouse-2} on a register if you want to edit its value.
-With GDB 6.4 or later, recently changed register values display with
-@code{font-lock-warning-face}.  With earlier versions of GDB, you can
-press @key{SPC} to toggle the display of floating point registers
-(@code{toggle-gdb-all-registers}).
+click @kbd{Mouse-2} on a register if you want to edit its value.  With
+GDB 6.4 or later, recently changed register values display with
+@code{font-lock-warning-face}.
 
 @item Assembler Buffer
 The assembler buffer displays the current frame as machine code.  An
@@ -1172,8 +1133,8 @@ size for these data items.
 @end table
 
 When @code{gdb-many-windows} is non-@code{nil}, the locals buffer
-shares its window with the registers buffer, just like breakpoints
-and threads buffers. To switch from one to the other click with
+shares its window with the registers buffer, just like breakpoints and
+threads buffers. To switch from one to the other, click with
 @kbd{Mouse-1} on the relevant button in the header line.
 
 @node Watch Expressions
@@ -1188,14 +1149,15 @@ in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}.  If you
 specify a prefix argument, you can enter the variable name in the
 minibuffer.
 
-  Each watch expression is displayed in the speedbar.  Complex data
-types, such as arrays, structures and unions are represented in a tree
-format.  Leaves and simple data types show the name of the expression
-and its value and, when the speedbar frame is selected, display the
-type as a tooltip.  Higher levels show the name, type and address
-value for pointers and just the name and type otherwise.  Root expressions
-also display the frame address as a tooltip to help identify the frame
-in which they were defined.
+  Each watch expression is displayed in the speedbar
+(@pxref{Speedbar}).  Complex data types, such as arrays, structures
+and unions are represented in a tree format.  Leaves and simple data
+types show the name of the expression and its value and, when the
+speedbar frame is selected, display the type as a tooltip.  Higher
+levels show the name, type and address value for pointers and just the
+name and type otherwise.  Root expressions also display the frame
+address as a tooltip to help identify the frame in which they were
+defined.
 
   To expand or contract a complex data type, click @kbd{Mouse-2} or
 press @key{SPC} on the tag to the left of the expression.  Emacs asks
@@ -1243,51 +1205,43 @@ non-@code{nil}.  This can be useful if you are debugging with a full
 screen Emacs frame.
 
 @node Multithreaded Debugging
-@subsubsection Stopping and Starting Multi-threaded Programs
+@subsubsection Multithreaded Debugging
 @cindex Multithreaded debugging in GDB
-
-@subsubheading All-stop Debugging
-
-In all-stop mode, whenever your program stops, @emph{all} threads of
-execution stop.  Likewise, whenever you restart the program, all
-threads start executing.  @xref{All-Stop Mode, , All-Stop Mode, gdb,
-The GNU debugger}.  You can enable this behavior in Emacs by setting
-@code{gdb-non-stop-setting} to @code{nil} before starting a debugging
-session.
-
-@subsubheading Non-stop Debugging
 @cindex Non-stop debugging in GDB
 
-For some multi-threaded targets, GDB supports a further mode of
-operation in which you can examine stopped program threads in the
-debugger while other threads continue to execute freely.
-@xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}.
-This is referred to as @dfn{non-stop} mode.
-
-Versions of GDB prior to 7.0 do not support non-stop mode and it does
-not work on all targets.  In such cases, Emacs uses all-stop mode
-regardless of the value of @code{gdb-non-stop-setting}.
+  In GDB's @dfn{all-stop mode}, whenever your program stops, all
+execution threads stop.  Likewise, whenever you restart the program,
+all threads start executing.  @xref{All-Stop Mode, , All-Stop Mode,
+gdb, The GNU debugger}.  For some multi-threaded targets, GDB supports
+a further mode of operation, called @dfn{non-stop mode}, in which you
+can examine stopped program threads in the debugger while other
+threads continue to execute freely.  @xref{Non-Stop Mode, , Non-Stop
+Mode, gdb, The GNU debugger}.  Versions of GDB prior to 7.0 do not
+support non-stop mode, and it does not work on all targets.
 
 @vindex gdb-non-stop-setting
-If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the
-default value), Emacs tries to start GDB in non-stop mode.  Note that
-GDB debugging session needs to be restarted for change of this setting
-to take effect.
+  The variable @code{gdb-non-stop-setting} determines whether Emacs
+runs GDB in all-stop mode or non-stop mode.  The default is @code{t},
+which means it tries to use non-stop mode if that is available.  If
+you change the value to @code{nil}, or if non-stop mode is
+unavailable, Emacs runs GDB in all-stop mode.  The variable takes
+effect when Emacs begins a debugging session; if you change its value,
+you should restart any active debugging session.
 
 @vindex gdb-switch-when-another-stopped
-When a thread stops in non-stop mode, Emacs automatically switches to
-that thread.  It may be undesirable to allow switching of current
-thread when some other stopped thread is already selected.  Set
-@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this.
+  When a thread stops in non-stop mode, Emacs usually switches to that
+thread.  If you don't want Emacs to do this switch if another stopped
+thread is already selected, change the variable
+@code{gdb-switch-when-another-stopped} to @code{nil}.
 
 @vindex gdb-switch-reasons
-Emacs can decide whether or not to switch to the stopped thread
-depending on the reason which caused the stop.  Customize
-@code{gdb-switch-reasons} to select stop reasons which make Emacs
-switch thread.
+  Emacs can decide whether or not to switch to the stopped thread
+depending on the reason which caused the stop.  Customize the variable
+@code{gdb-switch-reasons} to select the stop reasons which will cause
+a thread switch.
 
 @vindex gdb-stopped-hooks
-The variable @code{gdb-stopped-hooks} allows you to execute your
+  The variable @code{gdb-stopped-hooks} allows you to execute your
 functions whenever some thread stops.
 
   In non-stop mode, you can switch between different modes for GUD
@@ -1297,7 +1251,7 @@ execution control commands.
 @table @dfn
 @item Non-stop/A
 
-When @code{gdb-gud-control-all-threads} is @code{t} (the default
+  When @code{gdb-gud-control-all-threads} is @code{t} (the default
 value), interruption and continuation commands apply to all threads,
 so you can halt or continue all your threads with one command using
 @code{gud-stop-subjob} and @code{gud-cont}, respectively.  The
@@ -1318,127 +1272,132 @@ from the tool bar or from @samp{GUD->GDB-MI} menu.
 
   Stepping commands always apply to the current thread.
 
-@subsubheading Fine Thread Control
-
   In non-stop mode, you can interrupt/continue your threads without
 selecting them.  Hitting @kbd{i} in threads buffer interrupts thread
 under point, @kbd{c} continues it, @kbd{s} steps through.  More such
 commands may be added in the future.
 
-Combined with creating bound buffers for any thread, this allows you
-to change and track state of many threads in the same time.
-
-  Note that when you interrupt a thread, it stops with @samp{signal
-received} reason.  If that reason is included in your
+  Note that when you interrupt a thread, it stops with the
+@samp{signal received} reason.  If that reason is included in your
 @code{gdb-switch-reasons} (it is by default), Emacs will switch to
 that thread.
 
 @node Executing Lisp
 @section Executing Lisp Expressions
 
-  Emacs has several different major modes for Lisp and Scheme.  They are
-the same in terms of editing commands, but differ in the commands for
-executing Lisp expressions.  Each mode has its own purpose.
+  Emacs has major modes for several variants of Lisp.  They use the
+same editing commands as other programming language modes
+(@pxref{Programs}).  In addition, they provide special commands for
+executing Lisp expressions.
 
 @table @asis
-@item Emacs-Lisp mode
-The mode for editing source files of programs to run in Emacs Lisp.
-This mode defines @kbd{C-M-x} to evaluate the current defun.
-@xref{Lisp Libraries}.
+@item Emacs Lisp mode
+The mode for editing Emacs Lisp source files.  It defines @kbd{C-M-x}
+to evaluate the current top-level Lisp expression.  @xref{Lisp Eval}.
+
 @item Lisp Interaction mode
-The mode for an interactive session with Emacs Lisp.  It defines
-@kbd{C-j} to evaluate the sexp before point and insert its value in the
+The mode for an interactive Emacs Lisp session.  It defines @kbd{C-j}
+to evaluate the expression before point and insert its value in the
 buffer.  @xref{Lisp Interaction}.
+
 @item Lisp mode
 The mode for editing source files of programs that run in Lisps other
-than Emacs Lisp.  This mode defines @kbd{C-M-x} to send the current defun
-to an inferior Lisp process.  @xref{External Lisp}.
+than Emacs Lisp.  It defines @kbd{C-M-x} to evaluate the current
+top-level expression in an external Lisp.  @xref{External Lisp}.
+
 @item Inferior Lisp mode
-The mode for an interactive session with an inferior Lisp process.
-This mode combines the special features of Lisp mode and Shell mode
-(@pxref{Shell Mode}).
+The mode for an interactive session with an external Lisp which is
+being run as a subprocess (or @dfn{inferior process}) of Emacs.
+@ifnottex
+@xref{External Lisp}.
+@end ifnottex
+
 @item Scheme mode
-Like Lisp mode but for Scheme programs.
+Like Lisp mode, but for Scheme programs.
+
 @item Inferior Scheme mode
-The mode for an interactive session with an inferior Scheme process.
+Like Inferior Lisp mode, but for Scheme.
 @end table
 
-  Most editing commands for working with Lisp programs are in fact
-available globally.  @xref{Programs}.
-
 @node Lisp Libraries
 @section Libraries of Lisp Code for Emacs
 @cindex libraries
 @cindex loading Lisp code
 
-  Lisp code for Emacs editing commands is stored in files whose names
-conventionally end in @file{.el}.  This ending tells Emacs to edit them in
-Emacs-Lisp mode (@pxref{Executing Lisp}).
+  Emacs Lisp code is stored in files whose names conventionally end in
+@file{.el}.  Such files are automatically visited in Emacs Lisp mode.
 
 @cindex byte code
   Emacs Lisp code can be compiled into byte-code, which loads faster,
-takes up less space, and executes faster.  @xref{Byte Compilation,,
-Byte Compilation, elisp, the Emacs Lisp Reference Manual}.  By
-convention, the compiled code for a library goes in a separate file
-whose name ends in @samp{.elc}.  Thus, the compiled code for
-@file{foo.el} goes in @file{foo.elc}.
+takes up less space, and executes faster.  By convention, compiled
+Emacs Lisp code goes in a separate file whose name ends in
+@samp{.elc}.  For example, the compiled code for @file{foo.el} goes in
+@file{foo.elc}.  @xref{Byte Compilation,, Byte Compilation, elisp, the
+Emacs Lisp Reference Manual}.
 
 @findex load-file
-  To execute a file of Emacs Lisp code, use @kbd{M-x load-file}.  This
-command reads a file name using the minibuffer and then executes the
-contents of that file as Lisp code.  It is not necessary to visit the
-file first; in any case, this command reads the file as found on disk,
-not text in an Emacs buffer.
+  To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}.  This
+command reads a file name using the minibuffer, and executes the
+contents of that file as Emacs Lisp code.  It is not necessary to
+visit the file first; this command reads the file directly from disk,
+not from an existing Emacs buffer.
 
 @findex load
 @findex load-library
-  Once a file of Lisp code is installed in the Emacs Lisp library
-directories, users can load it using @kbd{M-x load-library}.  Programs
-can load it by calling @code{load}, a more primitive function that is
-similar but accepts some additional arguments.
-
-  @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
-searches a sequence of directories and tries three file names in each
-directory.  Suppose your argument is @var{lib}; the three names are
-@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
-@file{@var{lib}}.  If @file{@var{lib}.elc} exists, it is by convention
-the result of compiling @file{@var{lib}.el}; it is better to load the
-compiled file, since it will load and run faster.
-
-  If @code{load-library} finds that @file{@var{lib}.el} is newer than
-@file{@var{lib}.elc} file, it issues a warning, because it's likely
-that somebody made changes to the @file{.el} file and forgot to
-recompile it.  Nonetheless, it loads @file{@var{lib}.elc}.  This is
-because people often leave unfinished edits the source file, and don't
-recompile it until they think it is ready to use.
+@cindex load path for Emacs Lisp
+  If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path}
+(defined below), you can load it by typing @kbd{M-x load-library},
+instead of using @kbd{M-x load-file}.  The @kbd{M-x load-library}
+command prompts for a @dfn{library name} rather than a file name; it
+searches through each directory in the Emacs Lisp load path, trying to
+find a file matching that library name.  If the library name is
+@samp{@var{foo}}, it tries looking for files named
+@file{@var{foo}.elc}, @file{@var{foo}.el}, and lastly just
+@file{@var{foo}}; the first one found is loaded.  This command prefers
+@file{.elc} files over @file{.el} files because compiled files load
+and run faster.  If it finds that @file{@var{lib}.el} is newer than
+@file{@var{lib}.elc}, it issues a warning, in case someone made
+changes to the @file{.el} file and forgot to recompile it, but loads
+the @file{.elc} file anyway.  (Due to this behavior, you can save
+unfinished edits to Emacs Lisp source files, and not recompile until
+your changes are ready for use.)
+
+  Emacs Lisp programs usually load Emacs Lisp files using the
+@code{load} function.  This is similar to @code{load-library}, but is
+lower-level and accepts additional arguments.  @xref{How Programs Do
+Loading,,, elisp, the Emacs Lisp Reference Manual}.
 
 @vindex load-path
-  The variable @code{load-path} specifies the sequence of directories
-searched by @kbd{M-x load-library}.  Its value should be a list of
-strings that are directory names; in addition, @code{nil} in this list
-stands for the current default directory.  (Generally, it is not a
-good idea to put @code{nil} in the list; if you find yourself wishing
+  The Emacs Lisp load path is specified by the variable
+@code{load-path}.  Its value should be a list of directory names
+(strings).  These directories are searched, in the specified order, by
+the @kbd{M-x load-library} command, the lower-level @code{load}
+function, and other Emacs functions that find Emacs Lisp libraries.  A
+list entry in @code{load-path} can also have the special value
+@code{nil}, which stands for the current default directory, but it is
+almost always a bad idea to use this.  (If you find yourself wishing
 that @code{nil} were in the list, most likely what you really want is
-to do @kbd{M-x load-file} this once.)
+to use @kbd{M-x load-file}.)
 
   The default value of @code{load-path} is a list of directories where
 the Lisp code for Emacs itself is stored.  If you have libraries of
-your own, put them in a single directory and add that directory to
-@code{load-path}, by adding a line like this to your init file
-(@pxref{Init File}):
+your own in another directory, you can add that directory to the load
+path.  Unlike most other variables described in this manual,
+@code{load-path} cannot be changed via the Customize interface
+(@pxref{Easy Customization}), but you can add a directory to it by
+putting a line like this in your init file (@pxref{Init File}):
 
 @example
-(add-to-list 'load-path "/path/to/lisp/libraries")
+(add-to-list 'load-path "/path/to/my/lisp/library")
 @end example
 
 @cindex autoload
-  Some commands are @dfn{autoloaded}: when you run them, Emacs will
-automatically load the associated library first.  For instance, the
-@code{compile} and @code{compilation-mode} commands
-(@pxref{Compilation}) are autoloaded; if you call either command,
-Emacs automatically loads the @code{compile} library.  In contrast,
-the command @code{recompile} is not autoloaded, so it is unavailable
-until you load the @code{compile} library.
+  Some commands are @dfn{autoloaded}: when you run them, Emacs
+automatically loads the associated library first.  For instance, the
+@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you
+call it, Emacs automatically loads the @code{compile} library first.
+In contrast, the command @kbd{M-x recompile} is not autoloaded, so it
+is unavailable until you load the @code{compile} library.
 
 @vindex load-dangerous-libraries
 @cindex Lisp files byte-compiled by XEmacs
@@ -1449,38 +1408,35 @@ Emacs to crash.  Set the variable @code{load-dangerous-libraries} to
 
 @node Lisp Eval
 @section Evaluating Emacs Lisp Expressions
-@cindex Emacs-Lisp mode
-@cindex mode, Emacs-Lisp
+@cindex Emacs Lisp mode
+@cindex mode, Emacs Lisp
 
 @findex emacs-lisp-mode
-  Lisp programs intended to be run in Emacs should be edited in
-Emacs-Lisp mode; this happens automatically for file names ending in
-@file{.el}.  By contrast, Lisp mode itself is used for editing Lisp
-programs intended for other Lisp systems.  To switch to Emacs-Lisp mode
-explicitly, use the command @kbd{M-x emacs-lisp-mode}.
-
-  For testing of Lisp programs to run in Emacs, it is often useful to
-evaluate part of the program as it is found in the Emacs buffer.  For
-example, after changing the text of a Lisp function definition,
-evaluating the definition installs the change for future calls to the
-function.  Evaluation of Lisp expressions is also useful in any kind of
-editing, for invoking noninteractive functions (functions that are
-not commands).
+  Emacs Lisp mode is the major mode for editing Emacs Lisp.  Its mode
+command is @kbd{M-x emacs-lisp-mode}.
 
-@table @kbd
-@item M-:
-Read a single Lisp expression in the minibuffer, evaluate it, and print
-the value in the echo area (@code{eval-expression}).
-@item C-x C-e
-Evaluate the Lisp expression before point, and print the value in the
-echo area (@code{eval-last-sexp}).
-@item C-M-x
+  Emacs provides several commands for evaluating Emacs Lisp
+expressions.  You can use these commands in Emacs Lisp mode, to test
+your Emacs Lisp code as it is being written.  For example, after
+re-writing a function, you can evaluate the function definition to
+make it take effect for subsequent function calls.  These commands are
+also available globally, and can be used outside Emacs Lisp mode.
+
+@table @asis
+@item @kbd{M-:}
+Read a single Emacs Lisp expression in the minibuffer, evaluate it,
+and print the value in the echo area (@code{eval-expression}).
+@item @kbd{C-x C-e}
+Evaluate the Emacs Lisp expression before point, and print the value
+in the echo area (@code{eval-last-sexp}).
+@item @kbd{C-M-x} @r{(in Emacs Lisp mode)}
+@itemx @kbd{M-x eval-defun}
 Evaluate the defun containing or after point, and print the value in
 the echo area (@code{eval-defun}).
-@item M-x eval-region
-Evaluate all the Lisp expressions in the region.
-@item M-x eval-buffer
-Evaluate all the Lisp expressions in the buffer.
+@item @kbd{M-x eval-region}
+Evaluate all the Emacs Lisp expressions in the region.
+@item @kbd{M-x eval-buffer}
+Evaluate all the Emacs Lisp expressions in the buffer.
 @end table
 
 @ifinfo
@@ -1492,150 +1448,144 @@ Evaluate all the Lisp expressions in the buffer.
 @kindex M-:
 @end ifnotinfo
 @findex eval-expression
-  @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
-a Lisp expression interactively.  It reads the expression using the
-minibuffer, so you can execute any expression on a buffer regardless of
-what the buffer contains.  When the expression is evaluated, the current
-buffer is once again the buffer that was current when @kbd{M-:} was
-typed.
-
-@kindex C-M-x @r{(Emacs-Lisp mode)}
-@findex eval-defun
-  In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
-@code{eval-defun}, which parses the defun containing or following point
-as a Lisp expression and evaluates it.  The value is printed in the echo
-area.  This command is convenient for installing in the Lisp environment
-changes that you have just made in the text of a function definition.
-
-  @kbd{C-M-x} treats @code{defvar} expressions specially.  Normally,
-evaluating a @code{defvar} expression does nothing if the variable it
-defines already has a value.  But @kbd{C-M-x} unconditionally resets the
-variable to the initial value specified in the @code{defvar} expression.
-@code{defcustom} expressions are treated similarly.
-This special feature is convenient for debugging Lisp programs.
-Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
-the face according to the @code{defface} specification.
+  @kbd{M-:} (@code{eval-expression}) reads an expression using the
+minibuffer, and evaluates it.  (Before evaluating the expression, the
+current buffer switches back to the buffer that was current when you
+typed @kbd{M-:}, not the minibuffer into which you typed the
+expression.)
 
 @kindex C-x C-e
 @findex eval-last-sexp
-  The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
-expression preceding point in the buffer, and displays the value in the
-echo area.  It is available in all major modes, not just Emacs-Lisp
-mode.  It does not treat @code{defvar} specially.
-
-  When the result of an evaluation is an integer, you can type
-@kbd{C-x C-e} a second time to display the value of the integer result
-in additional formats (octal, hexadecimal, and character).
-
-  If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it
-inserts the value into the current buffer at point, rather than
-displaying it in the echo area.  The argument's value does not matter.
-@kbd{C-M-x} with a numeric argument instruments the function
-definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
+  The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the
+Emacs Lisp expression preceding point in the buffer, and displays the
+value in the echo area.  When the result of an evaluation is an
+integer, you can type @kbd{C-x C-e} a second time to display the value
+of the integer result in additional formats (octal, hexadecimal, and
+character).
+
+  If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts
+the value into the current buffer at point, rather than displaying it
+in the echo area.  The argument's value does not matter.
+
+@kindex C-M-x @r{(Emacs Lisp mode)}
+@findex eval-defun
+  The @code{eval-defun} command is bound to @kbd{C-M-x} in Emacs Lisp
+mode.  It evaluates the top-level Lisp expression containing or
+following point, and prints the value in the echo area.  In this
+context, a top-level expression is referred to as a ``defun'', but it
+need not be an actual @code{defun} (function definition).  In
+particular, this command treats @code{defvar} expressions specially.
+Normally, evaluating a @code{defvar} expression does nothing if the
+variable it defines already has a value.  But this command
+unconditionally resets the variable to the initial value specified by
+the @code{defvar}; this is convenient for debugging Emacs Lisp
+programs.  @code{defcustom} and @code{defface} expressions are treated
+similarly.  Note that the other commands documented in this section do
+not have this special feature.
+
+  With a prefix argument, @kbd{C-M-x} instruments the function
+definition for Edebug, the Emacs Lisp Debugger.  @xref{Instrumenting,
+Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}.
 
 @findex eval-region
 @findex eval-buffer
-  The most general command for evaluating Lisp expressions from a buffer
-is @code{eval-region}.  @kbd{M-x eval-region} parses the text of the
-region as one or more Lisp expressions, evaluating them one by one.
-@kbd{M-x eval-buffer} is similar but evaluates the entire
-buffer.  This is a reasonable way to install the contents of a file of
-Lisp code that you are ready to test.  Later, as you find bugs and
-change individual functions, use @kbd{C-M-x} on each function that you
-change.  This keeps the Lisp world in step with the source file.
+  The command @kbd{M-x eval-region} parses the text of the region as
+one or more Lisp expressions, evaluating them one by one.  @kbd{M-x
+eval-buffer} is similar but evaluates the entire buffer.
 
 @vindex eval-expression-print-level
 @vindex eval-expression-print-length
 @vindex eval-expression-debug-on-error
-  The two customizable variables @code{eval-expression-print-level} and
-@code{eval-expression-print-length} control the maximum depth and length
-of lists to print in the result of the evaluation commands before
-abbreviating them.  @code{eval-expression-debug-on-error} controls
-whether evaluation errors invoke the debugger when these commands are
-used; its default is @code{t}.
+  The customizable variables @code{eval-expression-print-level} and
+@code{eval-expression-print-length} control the maximum depth and
+length of lists to print in the result of the evaluation commands
+before abbreviating them.  @code{eval-expression-debug-on-error}
+controls whether evaluation errors invoke the debugger when these
+commands are used; its default is @code{t}.
 
 @node Lisp Interaction
 @section Lisp Interaction Buffers
 
+@findex lisp-interaction-mode
   When Emacs starts up, it contains a buffer named @samp{*scratch*},
-which is provided for evaluating Lisp expressions interactively inside
-Emacs.  Its major mode is Lisp Interaction mode.
+which is provided for evaluating Emacs Lisp expressions interactively.
+Its major mode is Lisp Interaction mode.  You can also enable Lisp
+Interaction mode by typing @kbd{M-x lisp-interaction-mode}.
 
 @findex eval-print-last-sexp
 @kindex C-j @r{(Lisp Interaction mode)}
-  The simplest way to use the @samp{*scratch*} buffer is to insert
-Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp})
-after each expression.  This command reads the Lisp expression before
-point, evaluates it, and inserts the value in printed representation
-before point.  The result is a complete typescript of the expressions
-you have evaluated and their values.
+  In the @samp{*scratch*} buffer, and other Lisp Interaction mode
+buffers, @kbd{C-j} (@code{eval-print-last-sexp}) evaluates the Lisp
+expression before point, and inserts the value at point.  Thus, as you
+type expressions into the buffer followed by @kbd{C-j} after each
+expression, the buffer records a transcript of the evaluated
+expressions and their values.  All other commands in Lisp Interaction
+mode are the same as in Emacs Lisp mode.
 
 @vindex initial-scratch-message
   At startup, the @samp{*scratch*} buffer contains a short message, in
 the form of a Lisp comment, that explains what it is for.  This
 message is controlled by the variable @code{initial-scratch-message},
-which should be either a string or @code{nil}.  If you set it to the
-empty string, or @code{nil}, the initial message is suppressed.
-
-@findex lisp-interaction-mode
-  All other commands in Lisp Interaction mode are the same as in Emacs
-Lisp mode.  You can enable Lisp Interaction mode by typing @kbd{M-x
-lisp-interaction-mode}.
+which should be either a string, or @code{nil} (which means to
+suppress the message).
 
 @findex ielm
-  An alternative way of evaluating Emacs Lisp expressions interactively
-is to use Inferior Emacs-Lisp mode, which provides an interface rather
-like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
-expressions.  Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
-which uses this mode.  For more information see that command's
-documentation.
+  An alternative way of evaluating Emacs Lisp expressions
+interactively is to use Inferior Emacs Lisp mode, which provides an
+interface rather like Shell mode (@pxref{Shell Mode}) for evaluating
+Emacs Lisp expressions.  Type @kbd{M-x ielm} to create an
+@samp{*ielm*} buffer which uses this mode.  For more information, see
+that command's documentation.
 
 @node External Lisp
 @section Running an External Lisp
+@cindex Lisp mode
+@cindex mode, Lisp
+@cindex Common Lisp
 
-  Emacs has facilities for running programs in other Lisp systems.  You can
-run a Lisp process as an inferior of Emacs, and pass expressions to it to
-be evaluated.  You can also pass changed function definitions directly from
-the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
-process.
+  Lisp mode is the major mode for editing programs written in
+general-purpose Lisp dialects, such as Common Lisp.  Its mode command
+is @kbd{M-x lisp-mode}.  Emacs uses Lisp mode automatically for files
+whose names end in @file{.l}, @file{.lsp}, or @file{.lisp}.
 
 @findex run-lisp
 @vindex inferior-lisp-program
 @kindex C-x C-z
-  To run an inferior Lisp process, type @kbd{M-x run-lisp}.  This runs
-the program named @code{lisp}, the same program you would run by typing
-@code{lisp} as a shell command, with both input and output going through
-an Emacs buffer named @samp{*lisp*}.  That is to say, any ``terminal
-output'' from Lisp will go into the buffer, advancing point, and any
-``terminal input'' for Lisp comes from text in the buffer.  (You can
-change the name of the Lisp executable file by setting the variable
-@code{inferior-lisp-program}.)
-
-  To give input to Lisp, go to the end of the buffer and type the input,
-terminated by @key{RET}.  The @samp{*lisp*} buffer is in Inferior Lisp
-mode, which combines the special characteristics of Lisp mode with most
-of the features of Shell mode (@pxref{Shell Mode}).  The definition of
-@key{RET} to send a line to a subprocess is one of the features of Shell
-mode.
-
-@findex lisp-mode
-  For the source files of programs to run in external Lisps, use Lisp
-mode.  You can switch to this mode with @kbd{M-x lisp-mode}, and it is
-used automatically for files whose names end in @file{.l},
-@file{.lsp}, or @file{.lisp}.
+  You can run an external Lisp session as a subprocess or
+@dfn{inferior process} of Emacs, and pass expressions to it to be
+evaluated.  To begin an external Lisp session, type @kbd{M-x
+run-lisp}.  This runs the program named @command{lisp}, and sets it up
+so that both input and output go through an Emacs buffer named
+@samp{*inferior-lisp*}.  To change the name of the Lisp program run by
+@kbd{M-x run-lisp}, change the variable @code{inferior-lisp-program}.
+
+  The major mode for the @samp{*lisp*} buffer is Inferior Lisp mode,
+which combines the characteristics of Lisp mode and Shell mode
+(@pxref{Shell Mode}).  To send input to the Lisp session, go to the
+end of the @samp{*lisp*} buffer and type the input, followed by
+@key{RET}.  Terminal output from the Lisp session is automatically
+inserted in the buffer.
 
 @kindex C-M-x @r{(Lisp mode)}
 @findex lisp-eval-defun
-  When you edit a function in a Lisp program you are running, the easiest
-way to send the changed definition to the inferior Lisp process is the key
-@kbd{C-M-x}.  In Lisp mode, this runs the function @code{lisp-eval-defun},
-which finds the defun around or following point and sends it as input to
-the Lisp process.  (Emacs can send input to any inferior process regardless
-of what buffer is current.)
-
-  Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing
-programs to be run in another Lisp system) and Emacs-Lisp mode (for
-editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in
-both modes it has the effect of installing the function definition
-that point is in, but the way of doing so is different according to
-where the relevant Lisp environment is found.
+  When you edit a Lisp program in Lisp mode, you can type @kbd{C-M-x}
+(@code{lisp-eval-defun}) to send an expression from the Lisp mode
+buffer to a Lisp session that you had started with @kbd{M-x run-lisp}.
+The expression sent is the top-level Lisp expression at or following
+point.  The resulting value goes as usual into the
+@samp{*inferior-lisp*} buffer.  Note that the effect of @kbd{C-M-x} in
+Lisp mode is thus very similar to its effect in Emacs Lisp mode
+(@pxref{Lisp Eval}), except that the expression is sent to a different
+Lisp environment instead of being evaluated in Emacs.
+
+@findex scheme-mode
+@findex run-scheme
+@cindex Scheme mode
+@cindex mode, Scheme
+@kindex C-M-x @r{(Scheme mode)}
+  The facilities for editing Scheme code, and for sending expressions
+to a Scheme subprocess, are very similar.  Scheme source files are
+edited in Scheme mode, which can be explicitly enabled with @kbd{M-x
+scheme-mode}.  You can initiate a Scheme session by typing @kbd{M-x
+run-scheme} (the buffer for interacting with Scheme is named
+@samp{*scheme*}), and send expressions to it by typing @kbd{C-M-x}.
diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi
index 6d20c92a6d9..2d2b32943f5 100644
--- a/doc/emacs/cal-xtra.texi
+++ b/doc/emacs/cal-xtra.texi
@@ -41,12 +41,12 @@ customize the variables @code{calendar-intermonth-header} and
 
 @vindex calendar-holiday-marker
 @vindex diary-entry-marker
-@vindex calenday-today-marker
+@vindex calendar-today-marker
   The variable @code{calendar-holiday-marker} specifies how to mark a
 date as being a holiday.  Its value may be a single-character string to
 insert next to the date, or a face name to use for displaying the date.
 Likewise, the variable @code{diary-entry-marker} specifies how to mark a
-date that has diary entries, and @code{calenday-today-marker} is used by
+date that has diary entries, and @code{calendar-today-marker} is used by
 the function @code{calendar-mark-today} to mark today's date.  By
 default, the calendar uses faces named @code{holiday}, @code{diary}, and
 @code{calendar-today} for these purposes.
diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi
index efb05226ba8..52ccccce58c 100644
--- a/doc/emacs/dired-xtra.texi
+++ b/doc/emacs/dired-xtra.texi
@@ -7,24 +7,24 @@
 @node Subdir Switches
 @section Subdirectory Switches in Dired
 
-You can insert subdirectories with specified @code{ls} switches in
-Dired buffers using @kbd{C-u i}.  You can change the @code{ls}
+You can insert subdirectories with specified @command{ls} switches in
+Dired buffers using @kbd{C-u i}.  You can change the @command{ls}
 switches of an already inserted subdirectory using @kbd{C-u l}.
 
 Dired preserves the switches if you revert the buffer.  Deleting a
 subdirectory forgets about its switches.
 
-Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u})
-to reinsert or delete subdirectories that were inserted with explicit
-switches can bypass Dired's machinery for remembering (or forgetting)
-switches.  Deleting a subdirectory using @code{dired-undo} does not
-forget its switches.  When later reinserted using @kbd{i}, it will be
-reinserted using its old switches.  Using @code{dired-undo} to
-reinsert a subdirectory that was deleted using the regular
-Dired commands (not @code{dired-undo}) will originally insert it with
-its old switches.  Reverting the buffer, however, will relist it using
-the buffer's default switches.  If any of this yields problems, you
-can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}.
+Using @code{dired-undo} (@pxref{Marks vs Flags}) to reinsert or delete
+subdirectories that were inserted with explicit switches can bypass
+Dired's machinery for remembering (or forgetting) switches.  Deleting
+a subdirectory using @code{dired-undo} does not forget its switches.
+When later reinserted using @kbd{i}, it will be reinserted using its
+old switches.  Using @code{dired-undo} to reinsert a subdirectory that
+was deleted using the regular Dired commands (not @code{dired-undo})
+will originally insert it with its old switches.  Reverting the
+buffer, however, will relist it using the buffer's default switches.
+If any of this yields problems, you can easily correct the situation
+using @kbd{C-u i} or @kbd{C-u l}.
 
 Dired does not remember the @code{R} switch.  Inserting a subdirectory
 with switches that include the @code{R} switch is equivalent to
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index b6ed47fdb3f..5097565830e 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -73,32 +73,45 @@ completion commands can be used in the minibuffer; in particular,
 a directory name.
 
   The variable @code{dired-listing-switches} specifies the options to
-give to @code{ls} for listing the directory; this string @emph{must}
-contain @samp{-l}.  If you use a prefix argument with the @code{dired}
-command, you can specify the @code{ls} switches with the minibuffer
-before you enter the directory specification.  No matter how they are
-specified, the @code{ls} switches can include short options (that is,
-single characters) requiring no arguments, and long options (starting
-with @samp{--}) whose arguments are specified with @samp{=}.
+give to @command{ls} for listing the directory; this string
+@emph{must} contain @samp{-l}.  If you use a prefix argument with the
+@code{dired} command, you can specify the @command{ls} switches with the
+minibuffer before you enter the directory specification.  No matter
+how they are specified, the @command{ls} switches can include short
+options (that is, single characters) requiring no arguments, and long
+options (starting with @samp{--}) whose arguments are specified with
+@samp{=}.
 
 @vindex dired-use-ls-dired
-  Note that Dired automatically adds the option @samp{--dired}, if
-your @code{ls} program supports it, unless you explicitly set
-the variable @code{dired-use-ls-dired} to @code{nil}.  Without this
-option, Dired will have trouble parsing some @samp{unusual} file-names.
-See the documentation of @code{dired-use-ls-dired} for more details.
-
-  On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls};
-see @ref{ls in Lisp}, for options and peculiarities of that emulation.
+  If your @command{ls} program supports the @samp{--dired} option,
+Dired automatically passes it that option; this causes @command{ls} to
+emit special escape sequences for certain unusual file names, without
+which Dired will not be able to parse those names.  The first time you
+run Dired in an Emacs session, it checks whether @command{ls} supports
+the @samp{--dired} option by calling it once with that option.  If the
+exit code is 0, Dired will subsequently use the @samp{--dired} option;
+otherwise it will not.  You can inhibit this check by customizing the
+variable @code{dired-use-ls-dired}.  The value @code{unspecified} (the
+default) means to perform the check; any other non-@code{nil} value
+means to use the @samp{--dired} option; and @code{nil} means not to
+use the @samp{--dired} option.
+
+  On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}.
+@xref{ls in Lisp}, for options and peculiarities of this emulation.
 
 @findex dired-other-window
 @kindex C-x 4 d
 @findex dired-other-frame
 @kindex C-x 5 d
-  To display the Dired buffer in another window rather than in the
-selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead
-of @kbd{C-x d}.  @kbd{C-x 5 d} (@code{dired-other-frame}) uses a
-separate frame to display the Dired buffer.
+  To display the Dired buffer in another window, use @kbd{C-x 4 d}
+(@code{dired-other-window}) instead of @kbd{C-x d}.  @kbd{C-x 5 d}
+(@code{dired-other-frame}) displays the Dired buffer in a separate
+frame.
+
+@kindex q @r{(Dired)}
+@findex quit-window
+  Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and
+deletes its window if the window was created just for that buffer.
 
 @node Dired Navigation
 @section Navigation in the Dired Buffer
@@ -124,7 +137,11 @@ minibuffer, and moves point to the line in the Dired buffer describing
 that file.
 
 @cindex searching Dired buffers
+@findex dired-isearch-filenames
 @vindex dired-isearch-filenames
+@findex dired-isearch-filenames-regexp
+@kindex M-s f C-s @r{(Dired)}
+@kindex M-s f M-C-s @r{(Dired)}
   @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward
 incremental search in the Dired buffer, looking for matches only
 amongst the file names and ignoring the rest of the text in the
@@ -331,18 +348,16 @@ another window, but do not select that window (@code{dired-display-file}).
 @item Mouse-1
 @itemx Mouse-2
 @findex dired-mouse-find-file-other-window
-Visit the file named by the line you click on
+Visit the file whose name you clicked on
 (@code{dired-mouse-find-file-other-window}).  This uses another window
 to display the file, like the @kbd{o} command.
 
 @item v
 @kindex v @r{(Dired)}
 @findex dired-view-file
-View the file described on the current line, using @kbd{M-x view-file}
-(@code{dired-view-file}).  Viewing a file with @code{view-file} is
-like visiting it, but is slanted toward moving around in the file
-conveniently and does not allow changing the file.  @xref{Misc File
-Ops, View File, Miscellaneous File Operations}.
+View the file described on the current line, with View mode
+(@code{dired-view-file}).  View mode provides convenient commands to
+navigate the buffer but forbids changing it; @xref{View Mode}.
 
 @item ^
 @kindex ^ @r{(Dired)}
@@ -520,9 +535,9 @@ the regular expression @var{regexp}
 @kbd{% m}, except that it searches the file contents instead of the file
 name.
 
-@item C-x u
+@item C-/
+@itemx C-x u
 @itemx C-_
-@itemx C-/
 @kindex C-_ @r{(Dired)}
 @findex dired-undo
 Undo changes in the Dired buffer, such as adding or removing
@@ -615,7 +630,7 @@ Like the other commands in this section, this command operates on the
 Rename the specified files (@code{dired-do-rename}).  If you rename a
 single file, the argument @var{new} is the new name of the file.  If
 you rename several files, the argument @var{new} is the directory into
-which to move the files (this is like the shell command @code{mv}).
+which to move the files (this is like the shell command @command{mv}).
 
 Dired automatically changes the visited file name of buffers associated
 with renamed files so that they refer to the new names.
@@ -625,7 +640,7 @@ with renamed files so that they refer to the new names.
 @cindex hard links (in Dired)
 @item H @var{new} @key{RET}
 Make hard links to the specified files (@code{dired-do-hardlink}).
-This is like the shell command @code{ln}.  The argument @var{new} is
+This is like the shell command @command{ln}.  The argument @var{new} is
 the directory to make the links in, or (if making just one link) the
 name to give the link.
 
@@ -642,9 +657,10 @@ link.
 @kindex M @r{(Dired)}
 @cindex changing file permissions (in Dired)
 @item M @var{modespec} @key{RET}
-Change the mode (also called ``permission bits'') of the specified files
-(@code{dired-do-chmod}).  @var{modespec} can be in octal or symbolic
-notation like arguments handled by the @code{chmod} program.
+Change the mode (also called @dfn{permission bits}) of the specified
+files (@code{dired-do-chmod}).  @var{modespec} can be in octal or
+symbolic notation, like arguments handled by the @command{chmod}
+program.
 
 @findex dired-do-chgrp
 @kindex G @r{(Dired)}
@@ -663,8 +679,8 @@ this.)
 
 @vindex dired-chown-program
 The variable @code{dired-chown-program} specifies the name of the
-program to use to do the work (different systems put @code{chown} in
-different places).
+program to use to do the work (different systems put @command{chown}
+in different places).
 
 @findex dired-do-touch
 @kindex T @r{(Dired)}
@@ -952,17 +968,17 @@ The backup file is the first file given to @code{diff}.
 @cindex subdirectories in Dired
 @cindex expanding subdirectories in Dired
 
-  A Dired buffer displays just one directory in the normal case;
-but you can optionally include its subdirectories as well.
+  A Dired buffer usually displays just one directory, but you can
+optionally include its subdirectories as well.
 
   The simplest way to include multiple directories in one Dired buffer is
-to specify the options @samp{-lR} for running @code{ls}.  (If you give a
+to specify the options @samp{-lR} for running @command{ls}.  (If you give a
 numeric argument when you run Dired, then you can specify these options
 in the minibuffer.)  That produces a recursive directory listing showing
 all subdirectories at all levels.
 
   More often, you will want to show only specific subdirectories.  You
-can do this with the @kbd{i} command:
+can do this with @kbd{i} (@code{dired-maybe-insert-subdir}):
 
 @table @kbd
 @findex dired-maybe-insert-subdir
@@ -973,25 +989,27 @@ can do this with the @kbd{i} command:
 Insert the contents of a subdirectory later in the buffer.
 @end table
 
-Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
-that describes a file which is a directory.  It inserts the contents of
-that directory into the same Dired buffer, and moves there.  Inserted
-subdirectory contents follow the top-level directory of the Dired
-buffer, just as they do in @samp{ls -lR} output.
-
-If the subdirectory's contents are already present in the buffer, the
-@kbd{i} command just moves to it.
-
-In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u
-C-@key{SPC}} takes you back to the old position in the buffer (the line
-describing that subdirectory).  You can also use @samp{^} to return
-to the parent directory in the same Dired buffer.
-
-Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
-subdirectory's contents.  Use @kbd{C-u k} on the subdirectory header
-line to remove the subdirectory listing (@pxref{Dired Updating}).  You
-can also hide and show inserted subdirectories (@pxref{Hiding
-Subdirectories}).
+@noindent
+If you use this command on a line that describes a file which is a
+directory, it inserts the contents of that directory into the same
+Dired buffer, and moves there.  Inserted subdirectory contents follow
+the top-level directory of the Dired buffer, just as they do in
+@samp{ls -lR} output.
+
+  If the subdirectory's contents are already present in the buffer,
+the @kbd{i} command just moves to it.
+
+  In either case, @kbd{i} sets the Emacs mark before moving, so
+@kbd{C-u C-@key{SPC}} returns to your previous position in the Dired
+buffer (@pxref{Setting Mark}).  You can also use @samp{^} to return to
+the parent directory in the same Dired buffer (@pxref{Dired
+Visiting}).
+
+  Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
+subdirectory's contents, and use @kbd{C-u k} on the subdirectory
+header line to remove the subdirectory listing (@pxref{Dired
+Updating}).  You can also hide and show inserted subdirectories
+(@pxref{Hiding Subdirectories}).
 
 @ifnottex
 @include dired-xtra.texi
@@ -1209,10 +1227,10 @@ tell @command{find} what condition to test.  To use this command, you
 need to know how to use @command{find}.
 
 @vindex find-ls-option
-  The format of listing produced by these commands is controlled by the
-variable @code{find-ls-option}, whose default value specifies using
-options @samp{-ld} for @code{ls}.  If your listings are corrupted, you
-may need to change the value of this variable.
+  The format of listing produced by these commands is controlled by
+the variable @code{find-ls-option}, whose default value specifies
+using options @samp{-ld} for @command{ls}.  If your listings are
+corrupted, you may need to change the value of this variable.
 
 @findex locate
 @findex locate-with-filter
@@ -1338,10 +1356,14 @@ rotation is lossless, and uses an external utility called JpegTRAN.
 @kindex + @r{(Dired)}
 @findex dired-create-directory
   The command @kbd{+} (@code{dired-create-directory}) reads a
-directory name, and creates the directory if it does not already
-exist.
+directory name, and creates that directory.  It signals an error if
+the directory already exists.
 
 @cindex searching multiple files via Dired
+@kindex M-s a C-s @r{(Dired)}
+@kindex M-s a M-C-s @r{(Dired)}
+@findex dired-do-isearch
+@findex dired-do-isearch-regexp
   The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a
 ``multi-file'' incremental search on the marked files.  If a search
 fails at the end of a file, typing @kbd{C-s} advances to the next
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index aca3735ff03..7f703fbaad0 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -602,11 +602,8 @@ Editing Text-based Tables
 * Table Recognition::   How to activate and deactivate tables.
 * Cell Commands::       Cell-oriented commands in a table.
 * Cell Justification::  Justifying cell contents.
-* Row Commands::        Manipulating rows of table cell.
-* Column Commands::     Manipulating columns of table cell.
-* Fixed Width Mode::    Fixing cell width.
+* Table Rows and Columns:: Inserting and deleting rows and columns.
 * Table Conversion::    Converting between plain text and tables.
-* Measuring Tables::    Analyzing table dimension.
 * Table Misc::          Table miscellany.
 
 Editing Programs
@@ -702,7 +699,7 @@ Compiling and Testing Programs
 * Executing Lisp::      Various modes for editing Lisp programs,
                           with different facilities for running
                           the Lisp programs.
-* Lisp Libraries::      Creating Lisp programs to run in Emacs.
+* Lisp Libraries::      How Lisp programs are loaded into Emacs.
 * Lisp Eval::           Executing a single Lisp expression in Emacs.
 * Lisp Interaction::    Executing Lisp in an Emacs buffer.
 * External Lisp::       Communicating through Emacs with a separate Lisp.
@@ -725,8 +722,7 @@ GDB Graphical Interface
 * Breakpoints Buffer::          A breakpoint control panel.
 * Threads Buffer::              Displays your threads.
 * Stack Buffer::                Select a frame from the call stack.
-* Other GDB Buffers::           Input/output, locals, registers,
-                                assembler, threads and memory buffers.
+* Other GDB Buffers::           Other buffers for controlling the GDB state.
 * Watch Expressions::           Monitor variable values in the speedbar.
 * Multithreaded Debugging::     Debugging programs with several threads.
 
@@ -745,15 +741,16 @@ Version Control
 * 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.
+* Registering::         Putting a file under version control.
 * Old Revisions::       Examining and comparing old versions.
-* Secondary VC Commands:: The commands used a little less frequently.
+* VC Change Log::       Viewing the VC Change Log.
+* VC Undo::             Canceling changes before or after committing.
 * VC Directory Mode::   Listing files managed by version control.
 * Branches::            Multiple lines of development.
-* Remote Repositories:: Efficient access to remote CVS servers.
 * Revision Tags::       Symbolic names for revisions.
 * Miscellaneous VC::    Various other commands and features of VC.
 * Customizing VC::      Variables that change VC's behavior.
-  
+
 Introduction to Version Control
 
 * Why Version Control?::    Understanding the problems it addresses.
@@ -770,12 +767,6 @@ Basic Editing under Version Control
 * 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.
 
-The Secondary Commands of VC
-
-* Registering::         Putting a file under version control.
-* VC Change Log::       Viewing the VC Change Log.
-* VC Undo::             Canceling changes before or after check-in.
-
 VC Directory Mode
 
 * VC Directory Buffer::   What the buffer looks like and means.
@@ -784,26 +775,15 @@ VC Directory Mode
 Multiple Branches of a File
 
 * Switching Branches::    How to get to another existing branch.
-* Creating Branches::     How to start a new branch.
+* VC Pull::               Updating a branch from another branch.
 * Merging::               Transferring changes between branches.
-* Multi-User Branching::  Multiple users working at multiple branches
-                            in parallel.
-
-Remote Repositories
-
-* Version Backups::       Keeping local copies of repository versions.
-* Local Version Control:: Using another version system for local editing.
-
-Revision Tags
-
-* Making Revision Tags::  The tag facilities.
-* Revision Tag Caveats::  Things to be careful of when using tags.
+* Creating Branches::     How to start a new branch.
 
 Miscellaneous Commands and Features of VC
 
 * Change Logs and VC::    Generating a change log file from log entries.
-* Renaming and VC::       A command to rename both the source and master
-                            file correctly.
+* VC Delete/Rename::      Deleting and renaming version-controlled files.
+* Revision Tags::         Symbolic names for revisions.
 * Version Headers::       Inserting version control headers into working files.
 
 Customizing VC
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index e3da0ca44e6..9b2322e1850 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1485,6 +1485,12 @@ argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
 them delete outright, instead of using the Trash, regardless of
 @code{delete-by-moving-to-trash}.
 
+@ifnottex
+  If a file is under version control (@pxref{Version Control}), you
+should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x
+delete-file}.  @xref{VC Delete/Rename}.
+@end ifnottex
+
 @findex copy-file
 @cindex copying files
   @kbd{M-x copy-file} reads the file @var{old} and writes a new file
@@ -1498,6 +1504,7 @@ it creates a copy of the @var{old} directory and puts it in @var{new}.
 If @var{new} is not an existing directory, it copies all the contents
 of @var{old} into a new directory named @var{new}.
 
+@cindex renaming files
 @findex rename-file
   @kbd{M-x rename-file} reads two file names @var{old} and @var{new}
 using the minibuffer, then renames file @var{old} as @var{new}.  If
@@ -1512,6 +1519,12 @@ RET /tmp RET} renames @file{~/foo} to @file{/tmp/foo}.  The same rule
 applies to all the remaining commands in this section.  All of them
 ask for confirmation when the new file name already exists, too.
 
+@ifnottex
+  If a file is under version control (@pxref{Version Control}), you
+should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x
+rename-file}.  @xref{VC Delete/Rename}.
+@end ifnottex
+
 @findex add-name-to-file
 @cindex hard links (creation)
   @kbd{M-x add-name-to-file} adds an additional name to an existing
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 1445d25be15..dec5aa771ea 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -32,7 +32,7 @@ unavailable.  However, it is still possible to create multiple
 ``frames'' on text-only terminals; such frames are displayed one at a
 time, filling the entire terminal screen (@pxref{Non-Window
 Terminals}).  It is also possible to use the mouse on some text-only
-terminals (@pxref{Text-Only Mouse}, for doing so on GNU and UNIX
+terminals (@pxref{Text-Only Mouse}, for doing so on GNU and Unix
 systems; and
 @iftex
 @pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features},
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 354812edc1f..6ce298c1795 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -49,13 +49,13 @@ variable @code{vc-handled-backends} to @code{nil}
 * 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.
+* Registering::         Putting a file under version control.
 * Old Revisions::       Examining and comparing old versions.
-* Secondary VC Commands::    The commands used a little less frequently.
+* VC Change Log::       Viewing the VC Change Log.
+* VC Undo::             Canceling changes before or after committing.
 * VC Directory Mode::   Listing files managed by version control.
 * Branches::            Multiple lines of development.
 @ifnottex
-* Remote Repositories:: Efficient access to remote CVS servers.
-* Revision Tags::       Symbolic names for revisions.
 * Miscellaneous VC::    Various other commands and features of VC.
 * Customizing VC::      Variables that change VC's behavior.
 @end ifnottex
@@ -71,7 +71,7 @@ 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.
+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
@@ -125,7 +125,7 @@ which it refers to as @dfn{back ends}:
 @item
 SCCS was the first version control system ever built, and was long ago
 superseded by more advanced ones.  VC compensates for certain features
-missing in SCCS (e.g., tag names for releases) by implementing them
+missing in SCCS (e.g.@: tag names for releases) by implementing them
 itself.  Other VC features, such as multiple branches, are simply
 unavailable.  Since SCCS is non-free, we recommend avoiding it.
 
@@ -154,7 +154,7 @@ 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
+Subversion (svn) is a free version control system designed to be
 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).
@@ -162,37 +162,33 @@ meta-data, renames, copies, and deletes).
 @cindex GNU Arch
 @cindex Arch
 @item
-GNU Arch is one of the earliest @dfn{distributed} version control
+GNU Arch is one of the earliest @dfn{decentralized} version control
 systems (the other being Monotone).  @xref{VCS Concepts}, for a
-description of distributed version control systems.  It is no longer
+description of decentralized 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 originally invented by
+Git is a decentralized 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
+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 git.  VC supports most Mercurial commands, with the
+Mercurial (hg) is a decentralized version control system broadly
+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.  VC supports most
+Bazaar (bzr) is a decentralized version control system that supports
+both repository-based and decentralized 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 was dropped due to limited interest from users
-and developers.
-
 @node VCS Concepts
 @subsubsection Concepts of Version Control
 
@@ -210,16 +206,19 @@ as @dfn{log entries} that describe the changes made to each file.
   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.
+may @dfn{commit} (or @dfn{check in}) the changes; this records the
+changes in the repository, along with a descriptive log entry.
+
+@cindex working tree
+  A directory tree of work files is called a @dfn{working tree}.
 
 @cindex revision
 @cindex revision ID
-  A copy of a file stored in a repository is called a @dfn{revision}.
-The history of a file is a sequence of revisions.  Each revision is
-named by a @dfn{revision ID}.  The format of the revision ID depends
-on the version control system; in the simplest case, it is just an
-integer.
+  Each commit creates a new @dfn{revision} in the repository.  The
+version control system keeps track of all past revisions and the
+changes that were made in each revision.  Each revision is named by a
+@dfn{revision ID}, whose format depends 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.  As explained in the
@@ -229,17 +228,18 @@ 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.
 
-  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 committed, with the latest changes that others have committed.
+@cindex merging-based version
+  In a version control system that uses merging, each user may modify
+a work file at any time.  The system lets you @dfn{merge} your work
+file, which may contain changes that have not been committed, with the
+latest changes that others have committed.
 
+@cindex locking-based version
   Older version control systems use a @dfn{locking} scheme instead.
 Here, work files are normally read-only.  To edit a file, you ask the
 version control system to make it writable for you by @dfn{locking}
@@ -264,7 +264,7 @@ number and severity of conflicts that actually occur.
   SCCS always uses locking.  RCS is lock-based by default but can be
 told to operate in a merging style.  CVS and Subversion are
 merge-based by default but can be told to operate in a locking mode.
-Distributed version control systems, such as GNU Arch, git, and
+Decentralized version control systems, such as GNU Arch, Git, and
 Mercurial, are exclusively merging-based.
 
   VC mode supports both locking and merging version control.  The
@@ -276,15 +276,16 @@ possible.
 @node VCS Changesets
 @subsubsection Changeset-based vs File-based Version Control
 
-@cindex changesets
+@cindex file-based version control
   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.  Newer
 systems, beginning with Subversion, are @dfn{changeset-based}: a
-checkin may include changes to several files, and the entire set of
+commit 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.
 
+@cindex changeset-based version control
   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
@@ -295,18 +296,20 @@ all of it.
 
 @cindex centralized version control
 @cindex decentralized version control
+@cindex distributed 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
 kind of model.  One of its drawbacks is that the repository is a choke
 point for reliability and efficiency.
 
-  GNU Arch pioneered the concept of @dfn{decentralized} version
-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.  In effect, there is one repository for each
-developer, and repository merges take the place of commit operations.
+  GNU Arch pioneered the concept of @dfn{distributed} or
+@dfn{decentralized} version 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.  In
+effect, there is one repository for each developer, and repository
+merges take the place of commit operations.
 
   VC helps you manage the traffic between your personal workfiles and
 a repository.  Whether the repository is a single master, or one of a
@@ -346,10 +349,9 @@ policy, which you should follow.
   When the policy is to use both, you typically want to write an entry
 for each change just once, then put it into both logs.  You can write
 the entry in @file{ChangeLog}, then copy it to the log buffer with
-@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}).  Or
-you can write the entry in the log buffer while checking in the
-change, and later use the @kbd{C-x v a} command to copy it to
-@file{ChangeLog}
+@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}).  Or you
+can write the entry in the log buffer while committing the change, and
+later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
 @iftex
 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
 @end iftex
@@ -359,20 +361,22 @@ change, and later use the @kbd{C-x v a} command to copy it to
 
 @node VC Mode Line
 @subsection Version Control and the Mode Line
-@cindex VC, mode line indicator
+@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{Bzr-1223} says that Bazaar
 is used for that file, and the current revision ID is 1223.
 
+@cindex version control status
   The character between the back-end name and the revision ID
-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.
+indicates the @dfn{version control 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
@@ -402,6 +406,7 @@ system, but is usually not excessive.
 @subsection Basic Editing under Version Control
 
 @cindex filesets, VC
+@cindex VC filesets
    Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
 collection of one or more files that a VC operation acts on.  When you
 type VC commands in a buffer visiting a version-controlled file, the
@@ -409,37 +414,34 @@ VC fileset is simply that one file.  When you type them in a VC
 Directory buffer, and some files in it are marked, the VC fileset
 consists of the marked files (@pxref{VC Directory Mode}).
 
-  The principal VC command is an all-purpose command, @kbd{C-x v v}
-(@code{vc-next-action}), that performs either registration, locking,
-merging or a check-in (depending on the situation) on the current VC
-fileset.  You can use @kbd{C-x v v} in a file-visiting buffer or in a
-VC Directory buffer.
+  On modern changeset-based version control systems (@pxref{VCS
+Changesets}), VC commands handle multi-file VC filesets as a group.
+For example, committing a multi-file VC fileset generates a single
+revision, containing the changes to all those files.  On older
+file-based version control systems like CVS, each file in a multi-file
+VC fileset is handled individually; for example, a commit generates
+one revision for each changed file.
 
 @table @kbd
 @itemx C-x v v
-Perform the appropriate next version control operation on the VC fileset.
+Perform the next appropriate version control operation on the current
+VC fileset.
 @end table
 
 @findex vc-next-action
 @kindex C-x v v
-  The precise action of @kbd{C-x v v} depends on the state of the VC
-fileset, and whether the version control system uses locking or
-merging.  This is described in detail in the subsequent sections.
-
-  VC filesets are the way that VC mode bridges the gap between
-file-based and changeset-based version control systems.  They are,
-essentially, a way to pass multiple file arguments as a group to
-version control commands.  For example, on Subversion, a checkin with
-a multi-file VC fileset becomes a joint commit, as though you had
-typed @command{svn commit} with those file arguments at the shell
-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.
-
-  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
-across sessions.
+  The principal VC command is a multi-purpose command, @kbd{C-x v v}
+(@code{vc-next-action}), which performs the ``most appropriate''
+action on the current VC fileset: either registering it with a version
+control system, or committing it, or unlocking it, or merging changes
+into it.  The precise actions are described in detail in the following
+subsections.  You can use @kbd{C-x v v} either in a file-visiting
+buffer or in a VC Directory buffer.
+
+  Note that 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 across sessions.
 
 @menu
 * VC With A Merging VCS::  Without locking: default mode for CVS.
@@ -450,46 +452,44 @@ across sessions.
 @node VC With A Merging VCS
 @subsubsection Basic Version Control with Merging
 
-  When your version control system is merging-based (the default for
-CVS and all newer version control systems), work files are always
-writable; you need not do anything special to begin editing a file.
-The status indicator on the mode line is @samp{-} if the file is
-unmodified; it flips to @samp{:} as soon as you save any changes
-(@pxref{VC Mode Line}).
-
-  Here is what @kbd{C-x v v} does when using a merging-based system:
+  On a merging-based version control system (i.e.@: most modern ones;
+@pxref{VCS Merging}), @kbd{C-x v v} does the following:
 
 @itemize @bullet
 @item
-If the work file is in a directory that is not controlled by any
-version control system, prompt for a repository type.  Then, create a
-version control repository of that type and register the file with it.
+If there is more than one file in the VC fileset and the files have
+inconsistent version control statuses, signal an error.  (Note,
+however, that a fileset is allowed to include both ``newly-added''
+files and ``modified'' files; @pxref{Registering}.)
 
 @item
-If the work file is in a directory that is controlled by a version
-control system but not registered with it, register the file.
+If none of the files in the VC fileset are registered with a version
+control system, register the VC fileset, i.e.@: place it under version
+control.  @xref{Registering}.  If Emacs cannot find a system to
+register under, it prompts for a repository type, creates a new
+repository, and registers the VC fileset with it.
 
 @item
-If the work file is the same as in the repository, do nothing.
+If every work file in the VC fileset is unchanged, do nothing.
 
 @item
-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.
+If every work file in the VC fileset has been modified, commit the
+changes.  To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
+desired log entry for the new revision, followed by @kbd{C-c C-c} to
+commit.  @xref{Log Buffer}.
+
+If committing to a shared repository, the commit may fail if the
+repository that has been changed since your last update.  In that
+case, you must perform an update before trying again.  On a
+decentralized version control system, use @kbd{C-x v +} (@pxref{VC
+Pull}) or @kbd{C-x v m} (@pxref{Merging}).  On a centralized version
+control system, type @kbd{C-x v v} again to merge in the repository
+changes.
 
 @item
-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''
-state.  Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
-regards the file as up-to-date and modified, and you can try to check
-it in again.
-
-To pick up any recent changes from the repository @emph{without}
-trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
-@xref{Merging}.
+Finally, if you are using a centralized version control system, check
+if each work file in the VC fileset is up-to-date.  If any file has
+been changed in the repository, offer to update it.
 @end itemize
 
   These rules also apply when you use RCS in its ``non-locking'' mode,
@@ -498,7 +498,7 @@ 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
+current revision is unchanged before committing your changes.  In
 addition, locking is possible with RCS even in this mode: @kbd{C-x v
 v} with an unmodified file locks the file, just as it does with RCS in
 its normal locking mode (@pxref{VC With A Locking VCS}).
@@ -506,32 +506,44 @@ its normal locking mode (@pxref{VC With A Locking VCS}).
 @node VC With A Locking VCS
 @subsubsection Basic Version Control with Locking
 
-  Under a locking-based version control system (such as SCCS, and RCS
-in its default mode), @kbd{C-x v v} does the following:
+  On a locking-based version control system (such as SCCS, and RCS in
+its default mode), @kbd{C-x v v} does the following:
 
 @itemize @bullet
 @item
-If the file is not locked, lock it and make it writable, so that you
-can change it.
+If there is more than one file in the VC fileset and the files have
+inconsistent version control statuses, signal an error.
+
+@item
+If each file in the VC fileset is not registered with a version
+control system, register the VC fileset.  @xref{Registering}.  If
+Emacs cannot find a system to register under, it prompts for a
+repository type, creates a new repository, and registers the VC
+fileset with it.
+
+@item
+If each file is registered and unlocked, lock it and make it writable,
+so that you can begin to edit it.
 
 @item
-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}.
+If each file is locked by you and contains changes, commit the
+changes.  To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
+desired log entry for the new revision, followed by @kbd{C-c C-c} to
+commit (@pxref{Log Buffer}).
 
 @item
-If the file is locked by you, but you have not changed it since you
-locked it, release the lock and makes the file read-only again.
+If each file is locked by you, but you have not changed it, release
+the lock and make the file read-only again.
 
 @item
-If the file is locked by some other user, ask whether you want to
-``steal the lock'' from that user.  If you say yes, the file becomes
-locked by you, but a message is sent to the person who had formerly
-locked the file, to inform him of what has happened.
+If each file is locked by another user, ask whether you want to
+``steal the lock''.  If you say yes, the file becomes locked by you,
+and a warning message is sent to the user who had formerly locked the
+file.
 @end itemize
 
   These rules also apply when you use CVS in locking mode, except
-that CVS does not support stealing a lock.
+that CVS does not support stealing locks.
 
 @node Advanced C-x v v
 @subsubsection Advanced Control in @kbd{C-x v v}
@@ -544,49 +556,55 @@ 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 commit.  This is one way to create
-a new branch (@pxref{Branches}).
+@cindex specific version control system
+You can specify the name of a version control system.  This is useful
+if the fileset can be managed by more than one version control system,
+and Emacs fails to detect the correct one.
 
 @item
-If the file is not modified (and unlocked), you can specify the
-revision to select; this lets you start working from an older
-revision, or on another branch.  If you do not enter any revision,
-that takes you to the highest (``head'') revision on the current
-branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to
-get the latest version of a file from the repository.
+Otherwise, if using CVS or RCS, you can specify a revision ID.
 
-@item
-@cindex specific version control system
-Instead of the revision ID, you can also specify the name of a
-version control system.  This is useful when one file is being managed
-with two version control systems at the same time
-@iftex
-(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
-Features}).
-@end iftex
-@ifnottex
-(@pxref{Local Version Control}).
-@end ifnottex
+If the fileset is modified (or locked), this makes Emacs commit with
+that revision ID.  You can create a new branch by supplying an
+appropriate revision ID (@pxref{Branches}).
+
+If the fileset is unmodified (and unlocked), this checks the specified
+revision into the working tree.  You can also specify a revision on
+another branch by giving its revision or branch ID (@pxref{Switching
+Branches}).  An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}})
+checks out the latest (``head'') revision on the current branch.
 
+This signals an error on a decentralized version control system.
+Those systems do not let you specify your own revision IDs, nor do
+they use the concept of ``checking out'' individual files.
 @end itemize
 
 @node Log 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}
+@cindex C-c C-c @r{(Log Edit mode)}
+@findex log-edit-done
+  When you tell VC to commit a change, it pops up a buffer named
+@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.
+After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
+the buffer and commit 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:
+@cindex Log Edit mode
+@cindex mode, Log Edit
+@vindex vc-log-mode-hook
+  The major mode for the @samp{*vc-log*} buffer is Log Edit mode, a
+variant of Text mode (@pxref{Text Mode}).  On entering Log Edit mode,
+Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
+(@pxref{Hooks}).
+
+  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:
 
 @smallexample
 Author: J. R. Hacker <jrh@@example.com>
@@ -597,196 +615,215 @@ 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.
+while Git, Mercurial, and Monotone recognize only @samp{Author} and
+@samp{Date}.  If you specify a header for a system that does not
+support it, the header is treated as part of the log entry.
 
+@kindex C-c C-f @r{(Log Edit mode)}
 @findex log-edit-show-files
+@kindex C-c C-d @r{(Log Edit mode)}
 @findex log-edit-show-diff
-  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.
-
+  While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is
+considered to be the fileset that will be committed if you type
+@w{@kbd{C-c C-c}}.  To view a list of the files in the VC fileset,
+type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}).  To view a diff
+of changes between the VC fileset and the version from which you
+started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
+(@code{log-edit-show-diff}).
+
+@kindex C-c C-a @r{(Log Edit mode)}
 @findex log-edit-insert-changelog
-  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}
+  If the 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
+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.
-@iftex
-@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
-@end iftex
+this command searches that item for entries matching the file(s) to be
+committed, and inserts them.
 @ifnottex
-@xref{Change Logs and VC},
+If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
+opposite way of working---generating ChangeLog entries from the Log
+Edit buffer.
 @end ifnottex
-for the opposite way of working---generating ChangeLog entries from
-the revision control log.
 
-  To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
+  To abort a commit, 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 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.
-
-  If you change several source files for the same reason, it is often
-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 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}.
-
+don't try to make another commit, 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 commit.
+
+@kindex M-n @r{(Log Edit mode)}
+@kindex M-p @r{(Log Edit mode)}
+@kindex M-s @r{(Log Edit mode)}
+@kindex M-r @r{(Log Edit mode)}
   You can also browse the history of previous log entries to duplicate
-a checkin comment. This can be useful when you want several files to
-have checkin comments that vary only slightly from each other. The
-commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this
-work just like the minibuffer history commands (except that these
-versions are used outside the minibuffer).
+a commit comment.  This can be useful when you want to make several
+commits with similar comments.  The commands @kbd{M-n}, @kbd{M-p},
+@kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
+history commands (@pxref{Minibuffer History}), except that they are
+used outside the minibuffer.
 
-@vindex vc-log-mode-hook
-  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}.
+@node Registering
+@subsection Registering a File for Version Control
+
+@table @kbd
+@item C-x v i
+Register the visited file for version control.
+@end table
+
+@kindex C-x v i
+@findex vc-register
+  The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
+file in the current VC fileset, placing it under version control.
+This is essentially equivalent to the action of @kbd{C-x v v} on an
+unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
+VC fileset is already registered, @kbd{C-x v i} signals an error
+whereas @kbd{C-x v v} performs some other action.
+
+  To register a file, Emacs must choose a version control system.  For
+a multi-file VC fileset, the VC Directory buffer specifies the system
+to use (@pxref{VC Directory Mode}).  For a single-file VC fileset, if
+the file's directory already contains files registered in a version
+control system, or if the directory is part of a directory tree
+controlled by a version control system, Emacs chooses that system.  In
+the event that more than one version control system is applicable,
+Emacs uses the one that appears first in the variable
+@iftex
+@code{vc-handled-backends}.
+@end iftex
+@ifnottex
+@code{vc-handled-backends} (@pxref{Customizing VC}).
+@end ifnottex
+If Emacs cannot find a version control system to register the file
+under, it prompts for a repository type, creates a new repository, and
+registers the file into that repository.
+
+  On most version control systems, registering a file with @kbd{C-x v
+i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the
+repository.  Such files are labeled as @samp{added} in the VC
+Directory buffer, and show a revision ID of @samp{@@@@} in the mode
+line.  To make the registration take effect in the repository, you
+must perform a commit (@pxref{Basic VC Editing}).  Note that a single
+commit can include both file additions and edits to existing files.
+
+  On a locking-based version control system (@pxref{VCS Merging}),
+registering a file leaves it unlocked and read-only.  Type @kbd{C-x v
+v} if you wish to start editing it.
 
 @node Old Revisions
 @subsection Examining And Comparing Old Revisions
 
-  One of the convenient features of version control is the ability
-to examine any revision of a file, or compare two revisions.
-
 @table @kbd
-@item C-x v ~
-Prompt for a revision of the current file, and visit it in a buffer of
-its own (@code{vc-revision-other-window}).
-
 @item C-x v =
-Compare the files in the current fileset with the working revision(s)
-you started from (@code{vc-diff}).  With a prefix argument, prompt for
-two revisions of the current fileset and compare them.  You can call
-this command from a Dired buffer (@pxref{Dired}).
+Compare the work files in the current VC fileset with the versions you
+started from (@code{vc-diff}).  With a prefix argument, prompt for two
+revisions of the current VC fileset and compare them.  You can also
+call this command from a Dired buffer (@pxref{Dired}).
+
+@ifnottex
+@item M-x vc-ediff
+Like @kbd{C-x v =}, but using Ediff.  @xref{Top, Ediff, ediff, The
+Ediff Manual}.
+@end ifnottex
 
 @item C-x v D
-Compare the entire tree corresponding to the current fileset with the
-tree you started from (@code{vc-root-diff}).  With a prefix argument,
-prompt for two revisions and compare their trees.
+Compare the entire working tree to the revision you started from
+(@code{vc-root-diff}).  With a prefix argument, prompt for two
+revisions and compare their trees.
+
+@item C-x v ~
+Prompt for a revision of the current file, and visit it in a separate
+buffer (@code{vc-revision-other-window}).
 
 @item C-x v g
-Display an annotated version of the file: for each line, show the
-latest revision in which it was modified (@code{vc-annotate}).
+Display an annotated version of the current file: for each line, show
+the latest revision in which it was modified (@code{vc-annotate}).
 @end table
 
-@findex vc-revision-other-window
-@kindex C-x v ~
-  To examine an old revision, visit the work file and type @kbd{C-x v
-~ @var{revision} @key{RET}} (@code{vc-revision-other-window}).  Here,
-@var{revision} is either the desired revision ID (@pxref{VCS
-Concepts}), or the name of a tag or branch
-@iftex
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Tags}).
-@end ifnottex
-This command puts the text of the old revision in a file named
-@file{@var{filename}.~@var{revision}~}, and visits it in its own
-buffer in a separate window.
-
 @findex vc-diff
 @kindex C-x v =
-  @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 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.
+  @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
+each work file in the current VC fileset to the version(s) from which
+you started editing.  The diff is displayed in another window, in a
+Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}.  The
+usual Diff mode commands are available in this buffer.  In particular,
+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 =
   To compare two arbitrary revisions of the current VC fileset, call
 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}.  This
-prompts for two revision IDs, using the minibuffer, and displays the
-diff in a special buffer in another window.  Instead of providing a
-revision ID, you can give an empty input, which specifies the current
-contents of the work file; or a tag or branch name
-@iftex
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
+prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
+diff between those versions of the fileset.  This will not work
+reliably for multi-file VC filesets, if the version control system is
+file-based rather than changeset-based (e.g.@: CVS), since then
+revision IDs for different files would not be related in any
+meaningful way.
+
+  Instead of the revision ID, some version control systems let you
+specify revisions in other formats.  For instance, under Bazaar you
+can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
+(and related commands) to specify the first revision committed after
+yesterday.  See the documentation of the version control system for
+details.
+
+  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
+(@pxref{Dired}), the file listed on the current line is treated as the
+current VC fileset.
+
 @ifnottex
-(@pxref{Tags}).
+@findex vc-ediff
+  @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
+Ediff session.  @xref{Top, Ediff, ediff, The Ediff Manual}.
 @end ifnottex
-If your version control system is file-based (e.g. CVS) rather than
-changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a
-revision ID for a multi-file fileset (as opposed to a symbolic tag
-name) is unlikely to return diffs that are connected in any meaningful
-way.
-
-  The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to
-@kbd{C-x v =}, but it compares the entire tree associated with the
-current VC fileset with the tree you started with.  This means all the
-files controlled by the current version control repository, even those
-that are not part of the current VC fileset.
-
-  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that
-is neither visiting a version-controlled file nor a VC directory
-buffer, these commands generate a diff of all registered files in the
-current directory and its subdirectories.
 
-@findex vc-ediff
-The function @code{vc-ediff} works like @code{vc-diff} and provides a way to
-visually compare two revisions of a file in an Ediff session, @pxref{Top,
-Ediff, ediff, The Ediff Manual}.  It compares the file associated with the
-current buffer with the last repository revision.  To compare two arbitrary
-revisions of the current file, call @code{vc-ediff} with a prefix argument.
+@findex vc-root-diff
+@kindex C-x v D
+  @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
+it displays the changes in the entire current working tree (i.e.@: the
+working tree containing the current VC fileset).  If you invoke this
+command from a Dired buffer, it applies to the working tree containing
+the directory.
 
 @vindex vc-diff-switches
-@vindex vc-rcs-diff-switches
-  @kbd{C-x v =} works by running a variant of the @code{diff} utility
-designed to work with the version control system in use.  The options
-to pass to the @code{diff} command are taken from the first non-@code{nil}
-value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches},
-and @code{diff-switches} (@pxref{Comparing Files}), in that order.
-Since @code{nil} means to check the next variable in the sequence,
-either of the first two may use the value @code{t} to mean no switches at all.
-Most of the @samp{vc@dots{}diff-switches} variables default to
-@code{nil}, but some default to @code{t}.  These are for those version
-control systems (e.g. SVN) whose @code{diff} implementations do not
-accept common options (e.g. @samp{-c}) likely to be in
-@code{diff-switches}.
-
-  The buffer produced by @kbd{C-x v =} supports the commands of
-Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
-@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
-find the corresponding locations in the current work file.  (Older
-revisions are not, in general, present as files on your disk.)
+  You can customize the @command{diff} options that @kbd{C-x v =} and
+@kbd{C-x v D} use for generating diffs.  The options used are taken
+from the first non-@code{nil} value amongst the variables
+@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
+@code{diff-switches} (@pxref{Comparing Files}), in that order.  Here,
+@var{backend} stands for the relevant version control system,
+e.g.@: @code{bzr} for Bazaar.  Since @code{nil} means to check the
+next variable in the sequence, either of the first two may use the
+value @code{t} to mean no switches at all.  Most of the
+@code{vc-@var{backend}-diff-switches} variables default to @code{nil},
+but some default to @code{t}; these are for version control systems
+whose @code{diff} implementations do not accept common diff options,
+such as Subversion.
+
+@findex vc-revision-other-window
+@kindex C-x v ~
+  To directly examine an older version of a file, visit the work file
+and type @kbd{C-x v ~ @var{revision} @key{RET}}
+(@code{vc-revision-other-window}).  This retrieves the file version
+corresponding to @var{revision}, saves it to
+@file{@var{filename}.~@var{revision}~}, and visits it in a separate
+window.
 
 @findex vc-annotate
 @kindex C-x v g
-  For some back ends, you can display the file @dfn{annotated} with
-per-line revision information, by typing @kbd{C-x v g}
+  Many version control systems allow you to view files @dfn{annotated}
+with per-line revision information, by typing @kbd{C-x v g}
 (@code{vc-annotate}).  This creates a new buffer (the ``annotate
-buffer'') displaying the file's text, with each part colored to show
-how old it is.  Text colored red is new, blue means old, and
-intermediate colors indicate intermediate ages.  By default, the color
-is scaled over the full range of ages, such that the oldest changes
-are blue, and the newest changes are red.
+buffer'') displaying the file's text, with each line colored to show
+how old it is.  Red text is new, blue is old, and intermediate colors
+indicate intermediate ages.  By default, the color is scaled over the
+full range of ages, such that the oldest changes are blue, and the
+newest changes are red.
 
   When you give a prefix argument to this command, Emacs reads two
-arguments using the minibuffer: the ID of which revision to display and
-annotate (instead of the current file contents), and the time span in
-days the color range should cover.
+arguments using the minibuffer: the revision to display and annotate
+(instead of the current file contents), and the time span in days the
+color range should cover.
 
   From the annotate buffer, these and other color scaling options are
 available from the @samp{VC-Annotate} menu.  In this buffer, you can
@@ -795,13 +832,13 @@ view diffs, or view log entries:
 
 @table @kbd
 @item p
-Annotate the previous revision, that is to say, the revision before
-the one currently annotated.  A numeric prefix argument is a repeat
-count, so @kbd{C-u 10 p} would take you back 10 revisions.
+Annotate the previous revision, i.e.@: the revision before the one
+currently annotated.  A numeric prefix argument is a repeat count, so
+@kbd{C-u 10 p} would take you back 10 revisions.
 
 @item n
-Annotate the next revision---the one after the revision currently
-annotated.  A numeric prefix argument is a repeat count.
+Annotate the next revision, i.e.@: the revision after the one
+currently annotated.  A numeric prefix argument is a repeat count.
 
 @item j
 Annotate the revision indicated by the current line.
@@ -840,76 +877,12 @@ Toggle the annotation visibility.  This is useful for looking just at
 the file contents without distraction from the annotations.
 @end table
 
-@node Secondary VC Commands
-@subsection The Secondary Commands of VC
-
-  This section explains the secondary commands of VC.
-
-@menu
-* Registering::         Putting a file under version control.
-* VC Change Log::       Viewing the VC Change Log.
-* VC Undo::             Canceling changes before or after check-in.
-@end menu
-
-@node Registering
-@subsubsection Registering a File for Version Control
-
-@kindex C-x v i
-@findex vc-register
-  You can put any file under version control by simply visiting it, and
-then typing @w{@kbd{C-x v i}} (@code{vc-register}).
-
-@table @kbd
-@item C-x v i
-Register the visited file for version control.
-@end table
-
-  To register the file, Emacs must choose which version control system
-to use for it.  If the file's directory already contains files
-registered in a version control system, Emacs uses that system.  If
-there is more than one system in use for a directory, Emacs uses the
-one that appears first in @code{vc-handled-backends}
-@iftex
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Customizing VC}).
-@end ifnottex
-On the other hand, if there are no files already registered, Emacs uses
-the first system from @code{vc-handled-backends} that could register
-the file (for example, you cannot register a file under CVS if its
-directory is not already part of a CVS tree); with the default value
-of @code{vc-handled-backends}, this means that Emacs uses RCS in this
-situation.
-
-  If locking is in use, @kbd{C-x v i} leaves the file unlocked and
-read-only.  Type @kbd{C-x v v} if you wish to start editing it.  After
-registering a file with CVS, you must subsequently commit the initial
-revision by typing @kbd{C-x v v}.  Until you do that, the revision ID
-appears as @samp{@@@@} in the mode line.
-
-@vindex vc-default-init-revision
-@cindex initial revision ID to register
-  The default initial revision ID for a newly registered file
-varies by what VCS you are using; normally it will be 1.1 on VCSes
-that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
-You can specify a different default by setting the variable
-@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a
-numeric argument; then it reads the initial revision ID for this
-particular file using the minibuffer.
-
-@c See http://debbugs.gnu.org/9745
-@c @vindex vc-initial-comment
-@c   If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
-@c initial comment to describe the purpose of this source file.  Reading
-@c the initial comment works like reading a log entry (@pxref{Log Buffer}).
-
 @node VC Change Log
-@subsubsection VC Change Log
+@subsection VC Change Log
 
 @table @kbd
 @item C-x v l
-Display revision control state and change history
+Display the change history for the current fileset
 (@code{vc-print-log}).
 
 @item C-x v L
@@ -928,85 +901,91 @@ Display the changes that will be sent by the next push operation
 @kindex C-x v l
 @findex vc-print-log
   The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
-named @samp{*vc-change-log*} in a new window.  This buffer lists the
-changes to the current file, including the associated log entries.
-(These are the log entries associated with the version control system,
-i.e. the ones you enter via the @samp{*VC-Log*} buffer.  @xref{Log
-Buffer}.)  Point is centered at the revision of the file currently
-being visited.  With a prefix argument, the command prompts for the
-revision to center on, and the maximum number of revisions to display.
-You can call this command from a Dired buffer (@pxref{Dired}).
+named @samp{*vc-change-log*}, showing the history of changes made to
+the current file, including who made the changes, the dates, and the
+log entry for each change (these are the same log entries you would
+enter via the @samp{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
+centered at the revision of the file currently being visited.  With a
+prefix argument, the command prompts for the revision to center on,
+and the maximum number of revisions to display.
+
+  If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
+Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
+file listed on the current line.
 
 @findex vc-print-root-log
-  Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
-@samp{*vc-change-log*} buffer showing the history of the
-version-controlled directory tree as a whole.  With a prefix argument,
-the command prompts for the maximum number of revisions to display.
-RCS, SCCS, and CVS do not support this feature.
-
-  On a distributed version control system, the @kbd{C-x v I}
+@findex log-view-toggle-entry-display
+  @kbd{C-x v L} (@code{vc-print-root-log}) displays a
+@samp{*vc-change-log*} buffer showing the history of the entire
+version-controlled directory tree (RCS, SCCS, and CVS do not support
+this feature).  With a prefix argument, the command prompts for the
+maximum number of revisions to display.
+
+  The @kbd{C-x v L} history is shown in a compact form, usually
+showing only the first line of each log entry.  However, you can type
+@key{RET} (@code{log-view-toggle-entry-display}) in the
+@samp{*vc-change-log*} buffer to reveal the entire log entry for the
+revision at point.  A second @key{RET} hides it again.
+
+  On a decentralized version control system, the @kbd{C-x v I}
 (@code{vc-log-incoming}) command displays a log buffer showing the
 changes that will be applied, the next time you run the version
 control system's ``pull'' command to get new revisions from another
-repository.  This other repository is the default one from which
-changes are pulled, as defined by the version control system; with a
-prefix argument, @code{vc-log-incoming} prompts for a specific
-repository from which changes would be pulled, and lists the changes
-accordingly.  Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows
-the changes that will be sent to another repository, the next time you
-run the ``push'' command; with a prefix argument, it prompts for a
-specific repository to which changes would be pushed.
+repository (@pxref{VC Pull}).  This other repository is the default
+one from which changes are pulled, as defined by the version control
+system; with a prefix argument, @code{vc-log-incoming} prompts for a
+specific repository.  Similarly, @kbd{C-x v O}
+(@code{vc-log-outgoing}) shows the changes that will be sent to
+another repository, the next time you run the ``push'' command; with a
+prefix argument, it prompts for a specific destination repository.
 
   In the @samp{*vc-change-log*} buffer, you can use the following keys
-to move between the logs of revisions and of files, to view past
-revisions, to modify change comments, to view annotations and to view
-diffs:
+to move between the logs of revisions and of files, and to examine and
+compare past revisions (@pxref{Old Revisions}):
 
 @table @kbd
 @item p
-Move to the previous revision-item in the buffer.  (Revision entries in the log
+Move to the previous revision entry.  (Revision entries in the log
 buffer are usually in reverse-chronological order, so the previous
 revision-item usually corresponds to a newer revision.)  A numeric
 prefix argument is a repeat count.
 
 @item n
-Move to the next revision-item (which most often corresponds to the
-previous revision of the file).  A numeric prefix argument is a repeat
-count.
+Move to the next revision entry.  A numeric prefix argument is a
+repeat count.
 
 @item P
-Move to the log of the previous file, when the logs of multiple files
-are in the log buffer (@pxref{VC Directory Mode}).  Otherwise, just
-move to the beginning of the log.  A numeric prefix argument is a
-repeat count, so @kbd{C-u 10 P} would move backward 10 files.
+Move to the log of the previous file, if showing logs for a multi-file
+VC fileset.  Otherwise, just move to the beginning of the log.  A
+numeric prefix argument is a repeat count.
 
 @item N
-Move to the log of the next file, when the logs of multiple files are
-in the log buffer (@pxref{VC Directory Mode}).  It also takes a
-numeric prefix argument as a repeat count.
+Move to the log of the next file, if showing logs for a multi-file VC
+fileset.  A numeric prefix argument is a repeat count.
 
 @item a
-Annotate the revision indicated by the current line.
+Annotate the revision on the current line (@pxref{Old Revisions}).
 
 @item e
 Modify the change comment displayed at point.  Note that not all VC
 systems support modifying change comments.
 
 @item f
-Visit the revision indicated at the current line, like typing @kbd{C-x
-v ~} and specifying this revision's ID (@pxref{Old Revisions}).
+Visit the revision indicated at the current line.
 
 @item d
-Display the diff (@pxref{Comparing Files}) between the revision
-indicated at the current line and the next earlier revision.  This is
-useful to see what actually changed in the file when the revision
-indicated on the current line was committed.
+Display a diff between the revision at point and the next earlier
+revision, for the specific file.
 
 @item D
-Display the changeset diff (@pxref{Comparing Files}) between the
-revision indicated at the current line and the next earlier revision.
-This is useful to see all the changes to all files that the revision
-indicated on the current line did when it was committed.
+Display the changeset diff between the revision at point and the next
+earlier revision.  This shows the changes to all files made in that
+revision.
+
+@item @key{RET}
+In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v
+L}), toggle between showing and hiding the full log entry for the
+revision at point.
 @end table
 
 @vindex vc-log-show-limit
@@ -1020,62 +999,71 @@ entries} or @samp{Show unlimited entries} buttons at the end of the
 buffer.  However, RCS, SCCS, and CVS do not support this feature.
 
 @node VC Undo
-@subsubsection Undoing Version Control Actions
+@subsection Undoing Version Control Actions
 
 @table @kbd
 @item C-x v u
-Revert the buffer and the file to the working revision from which you started
-editing the file.
-
-@item C-x v c
-Remove the last-entered change from the master for the visited file.
-This undoes your last check-in.
+Revert the work file(s) in the current VC fileset to the last revision
+(@code{vc-revert}).
 @end table
 
+@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific.
+
 @kindex C-x v u
-@findex vc-revert-buffer
-  If you want to discard your current set of changes and revert to the
-working revision from which you started editing the file, use @kbd{C-x
-v u} (@code{vc-revert-buffer}).  If the version control system is
-locking-based, this leaves the file unlocked, and you must lock it
-again before making new changes.  @kbd{C-x v u} requires confirmation,
-unless it sees that you haven't made any changes with respect to the
-master copy of the working revision.
-
-  @kbd{C-x v u} is also the command to unlock a file if you lock it and
-then decide not to change it.
-
-@kindex C-x v c
-@findex vc-rollback
-  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
-is not the latest on its branch.  Note that many version control
-systems do not support rollback at all; this command is something of a
-historical relic.
+@findex vc-revert
+@vindex vc-revert-show-diff
+  If you want to discard all the changes you have made to the current
+VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}).  This shows
+you a diff between the work file(s) and the revision from which you
+started editing, and asks for confirmation for discarding the changes.
+If you agree, the fileset is reverted.  If you don't want @kbd{C-x v
+u} to show a diff, set the variable @code{vc-revert-show-diff} to
+@code{nil} (you can still view the diff directly with @kbd{C-x v =};
+@pxref{Old Revisions}).  Note that @kbd{C-x v u} cannot be reversed
+with the usual undo commands (@pxref{Undo}), so use it with care.
+
+  On locking-based version control systems, @kbd{C-x v u} leaves files
+unlocked; you must lock again to resume editing.  You can also use
+@kbd{C-x v u} to unlock a file if you lock it and then decide not to
+change it.
 
 @node VC Directory Mode
 @subsection VC Directory Mode
 
+@cindex VC Directory buffer
+  The @dfn{VC Directory buffer} is a specialized buffer for viewing
+the version control statuses of the files in a directory tree, and
+performing version control operations on those files.  In particular,
+it is used to specify multi-file VC filesets for commands like
+@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
+
 @kindex C-x v d
 @findex vc-dir
-  When you are working on a large program, it is often useful to find
-out which files have changed within an entire directory tree, or to
-view the status of all files under version control at once, and to
-perform version control operations on collections of files.  You can
-use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory
-listing that includes only files relevant for version control.  This
-creates a @dfn{VC Directory buffer} and displays it in a separate
-window.
+  To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
+This reads a directory name using the minibuffer, and switches to a VC
+Directory buffer for that directory.  By default, the buffer is named
+@samp{*vc-dir*}.  Its contents are described
+@iftex
+below.
+@end iftex
+@ifnottex
+in @ref{VC Directory Buffer}.
+@end ifnottex
+
+  The @code{vc-dir} command automatically detects the version control
+system to be used in the specified directory.  In the event that more
+than one system is being used in the directory, you should invoke the
+command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
+the version control system which the VC Directory buffer should use.
 
+@ifnottex
 @cindex PCL-CVS
 @pindex cvs
 @cindex CVS directory mode
-  The VC Directory buffer works with all the version control systems
-that VC supports.  For CVS, Emacs also offers a more powerful facility
-called PCL-CVS.  @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
-Emacs Front-End to CVS}.
+  In addition to the VC Directory buffer, Emacs has a similar facility
+called PCL-CVS which is specialized for CVS.  @xref{Top, , About
+PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+@end ifnottex
 
 @menu
 * Buffer: VC Directory Buffer.      What the buffer looks like and means.
@@ -1086,369 +1074,367 @@ Emacs Front-End to CVS}.
 @subsubsection The VC Directory Buffer
 
   The VC Directory buffer contains a list of version-controlled files
-in the current directory and its subdirectories.  Files which are
-up-to-date (have no local differences from the repository copy) are
-usually hidden; if all files in a subdirectory are up-to-date, the
-subdirectory is hidden as well.  There is an exception to this rule:
-if VC mode detects that a file has changed to an up-to-date state
-since you last looked at it, that file and its state are shown.
-
-  If a directory uses more that one version control system, you can
-select which system to use for the @code{vc-dir} command by invoking
-@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}.
-
-  The line for an individual file shows the version control state of
-the file.  Under RCS and SCCS, the name of the user locking the file
-is shown; under CVS, an abbreviated version of the @samp{cvs status}
-output is used.  Here is an example using CVS:
+and their version control statuses.  It lists files in the current
+directory (the one specified when you called @kbd{C-x v d}) and its
+subdirectories, but only those with a ``noteworthy'' status.  Files
+that are up-to-date (i.e.@: the same as in the repository) are
+omitted.  If all the files in a subdirectory are up-to-date, the
+subdirectory is not listed either.  As an exception, if a file has
+become up-to-date as a direct result of a VC command, it is listed.
+
+  Here is an example of a VC Directory buffer listing:
 
 @smallexample
 @group
-                       ./
-    modified           file1.c
-    needs-update       file2.c
-    needs-merge        file3.c
+                     ./
+    edited           configure.ac
+*   added            README
+    unregistered     temp.txt
+                     src/
+*   edited           src/main.c
 @end group
 @end smallexample
 
 @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 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
-  In the above, if the repository were on a remote machine, VC only
-contacts it when the variable @code{vc-stay-local} (or
-@code{vc-cvs-stay-local}) is @code{nil}
+Two work files have been modified but not committed:
+@file{configure.ac} in the current directory, and @file{foo.c} in the
+@file{src/} subdirectory.  The file named @file{README} has been added
+but is not yet committed, while @file{temp.txt} is not under version
+control (@pxref{Registering}).
+
+The @samp{*} characters next to the entries for @file{README} and
+@file{src/main.c} indicate that the user has marked out these files as
+the current VC fileset
 @iftex
-(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
+(see below).
 @end iftex
 @ifnottex
-(@pxref{CVS Options}).
+(@pxref{VC Directory Commands}).
+@end ifnottex
+
+  The above example is typical for a decentralized version control
+system like Bazaar, Git, or Mercurial.  Other systems can show other
+statuses.  For instance, CVS shows the @samp{needs-update} status if
+the repository has changes that have not been applied to the work
+file.  RCS and SCCS show the name of the user locking a file as its
+status.
+
+@ifnottex
+@vindex vc-stay-local
+@vindex vc-cvs-stay-local
+  On CVS and Subversion, the @code{vc-dir} command normally contacts
+the repository, which may be on a remote machine, to check for
+updates.  If you change the variable @code{vc-stay-local} or
+@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
+Options}), then Emacs avoids contacting a remote repository when
+generating the VC Directory buffer (it will still contact it when
+necessary, e.g.@: when doing a commit).  This may be desirable if you
+are working offline or the network is slow.
 @end ifnottex
-This is because access to the repository may be slow, or you may be
-working offline and not have access to the repository at all.  As a
-consequence, VC would not be able to tell you that @samp{file3.c} is
-in the ``merge'' state; you would learn that only when you try to
-check-in your modified copy of the file, or use a command such as
-@kbd{C-x v m}.
-
-  In practice, this is not a problem because CVS handles this case
-consistently whenever it arises.  In VC, you'll simply get prompted to
-merge the remote changes into your work file first.  The benefits of
-less network communication usually outweigh the disadvantage of not
-seeing remote changes immediately.
 
 @vindex vc-directory-exclusion-list
-  When a VC directory displays subdirectories it omits some that
-should never contain any files under version control.  By default,
-this includes Version Control subdirectories such as @samp{RCS} and
-@samp{CVS}; you can customize this by setting the variable
-@code{vc-directory-exclusion-list}.
+  The VC Directory buffer omits subdirectories listed in the variable
+@code{vc-directory-exclusion-list}.  Its default value contains
+directories that are used internally by version control systems.
 
 @node VC Directory Commands
 @subsubsection VC Directory Commands
 
-  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 @kbd{mouse-2}.
+  Emacs provides several commands for navigating the VC Directory
+buffer, and for ``marking'' files as belonging to the current VC
+fileset.
 
-  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
-@key{TAB} behave like down-arrow, and @key{BackTab} behaves like
-up-arrow.
+@table @kbd
+@item n
+@itemx @key{SPC}
+Move point to the next entry (@code{vc-dir-next-line}).
 
-  Both @kbd{C-m} and @kbd{f} visit the file on the current
-line.  @kbd{o} visits that file in another window.  @kbd{q} dismisses
-the directory buffer.
+@item p
+Move point to the previous entry (@code{vc-dir-previous-line}).
 
-  @kbd{x} hides up-to-date files.
+@item @key{TAB}
+Move to the next directory entry (@code{vc-dir-next-directory}).
 
-  @kbd{m} marks the file or directory on the current line.  If the
-region is active, @kbd{m} marks all the files in the region.  There
-are some restrictions when marking: a file cannot be marked if any of
-its parent directories are marked, and a directory cannot be marked if
-any files in it or in its child directories are marked.
+@item S-@key{TAB}
+Move to the previous directory entry
+(@code{vc-dir-previous-directory}).
 
-  @kbd{M} marks all the files with the same VC state as the current
-file if the cursor is on a file.  If the cursor is on a directory, it
-marks all child files.  With a prefix argument: marks all files and
-directories.
+@item @key{RET}
+@itemx f
+Visit the file or directory listed on the current line
+(@code{vc-dir-find-file}).
 
-  @kbd{u} unmarks the file or directory on the current line.  If the
-region is active, it unmarks all the files in the region.
+@item o
+Visit the file or directory on the current line, in a separate window
+(@code{vc-dir-find-file-other-window}).
 
-  @kbd{U} marks all the files with the same VC state as the current file
-if the cursor is on a file.  If the cursor is on a directory, it
-unmarks all child files.  With a prefix argument: unmarks all marked
+@item m
+Mark the file or directory on the current line (@code{vc-dir-mark}),
+putting it in the current VC fileset.  If the region is active, mark
+all files in the region.
+
+A file cannot be marked with this command if it is already in a marked
+directory, or one of its subdirectories.  Similarly, a directory
+cannot be marked with this command if any file in its tree is marked.
+
+@item M
+If point is on a file entry, mark all files with the same status; if
+point is on a directory entry, mark all files in that directory tree
+(@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
+listed files and directories.
+
+@kindex q @r{(VC Directory)}
+@findex quit-window
+@item q
+Bury the VC Directory buffer, and delete its window if the window was
+created just for that buffer.
+
+@item u
+Unmark the file or directory on the current line.  If the region is
+active, unmark all the files in the region (@code{vc-dir-unmark}).
+
+@item U
+If point is on a file entry, unmark all files with the same status; if
+point is on a directory entry, unmark all files in that directory tree
+(@code{vc-dir-unmark-all-files}).  With a prefix argument, unmark all
 files and directories.
 
-  It is possible to do search, search and replace, incremental search,
-and incremental regexp search on multiple files.  These commands will
-work on all the marked files or the current file if nothing is marked.
-If a directory is marked, the files in that directory shown in the VC
-directory buffer will be used.
+@item x
+Hide files with @samp{up-to-date} status
+(@code{vc-dir-hide-up-to-date}).
 
-  @kbd{S} searches the marked files.
+@item q
+Quit the VC Directory buffer, and bury it (@code{quit-window}).
+@end table
 
-  @kbd{Q} does a query replace on the marked files.
+@findex vc-dir-mark
+@findex vc-dir-mark-all-files
+  While in the VC Directory buffer, all the files that you mark with
+@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in
+the current VC fileset.  If you mark a directory entry with @kbd{m},
+all the listed files in that directory tree are in the current VC
+fileset.  The files and directories that belong to the current VC
+fileset are indicated with a @samp{*} character in the VC Directory
+buffer, next to their VC status.  In this way, you can set up a
+multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v
+v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old
+Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
+
+  The VC Directory buffer also defines some single-key shortcuts for
+VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
+@kbd{i}, and @kbd{v}.
+
+  For example, you can commit a set of edited files by opening a VC
+Directory buffer, where the files are listed with the @samp{edited}
+status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
+(@code{vc-next-action}).  If the version control system is
+changeset-based, Emacs will commit the files in a single revision.
+
+  While in the VC Directory buffer, you can also perform search and
+replace on the current VC fileset, with the following commands:
 
-  @kbd{M-s a C-s} does an incremental search on the marked files.
+@table @kbd
+@item S
+Search the fileset (@code{vc-dir-search}).
 
-  @kbd{M-s a C-M-s} does an incremental regular expression search
-on the marked files.
+@item Q
+Do a regular expression query replace on the fileset
+(@code{vc-dir-query-replace-regexp}).
+
+@item M-s a C-s
+Do an incremental search on the fileset (@code{vc-dir-isearch}).
+
+@item M-s a C-M-s
+Do an incremental regular expression search on the fileset
+(@code{vc-dir-isearch-regexp}).
+@end table
+
+@noindent
+Apart from acting on multiple files, these commands behave much like
+their single-buffer counterparts (@pxref{Search}).
 
 @cindex stashes in version control
 @cindex shelves in version control
-  Commands are also accessible from the VC-dir menu.  Note that some
-VC backends use the VC-dir menu to make available extra,
-backend-specific, commands.  For example, Git and Bazaar allow you to
-manipulate @dfn{stashes} and @dfn{shelves}.  (These provide a
-mechanism to temporarily store uncommitted changes somewhere out of
-the way, and bring them back at a later time.)
-
-  Normal VC commands with the @kbd{C-x v} prefix work in VC directory
-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 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
-compatible states (added, modified and removed states are considered
-compatible).  Otherwise it signals an error.  This differs from the
-behavior of older versions of VC, which did not have fileset
-operations and simply did @code{vc-next-action} on each file
-individually.
-
-  If any files are in a state that calls for commit, @kbd{C-x v v} reads a
-single log entry and uses it for the changeset as a whole.  If the
-underling VCS is file- rather than changeset-oriented, the log entry
-will be replicated into the history of each file.
+  The above commands are also available via the menu bar, and via a
+context menu invoked by @kbd{Mouse-2}.  Furthermore, some VC backends
+use the menu to provide extra backend-specific commands.  For example,
+Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
+(where are a way to temporarily put aside uncommitted changes, and
+bring them back at a later time).
 
 @node Branches
-@subsection Multiple Branches of a File
+@subsection Version Control Branches
 @cindex branch (version control)
-@cindex trunk (version control)
-
-  One use of version control is to maintain multiple ``current''
-revisions of a file.  For example, you might have different revisions of a
-program in which you are gradually adding various unfinished new
-features.  Each such independent line of development is called a
-@dfn{branch}.  VC allows you to create branches, switch between
-different branches, and merge changes from one branch to another.
-Please note, however, that branches are not supported for SCCS.
-
-  A file's main line of development is usually called the @dfn{trunk}.
-You can create multiple branches from the trunk.  How the difference
-between trunk and branch is made visible is dependent on whether the
-VCS uses dot-pair or monotonic version IDs.
-
-  In VCSes with dot-pair revision IDs, the revisions on the trunk are
-normally IDed 1.1, 1.2, 1.3, etc.  At any such revision, you can
-start an independent branch.  A branch starting at revision 1.2 would
-have revision ID 1.2.1.1, and consecutive revisions on this branch
-would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on.  If there is
-a second branch also starting at revision 1.2, it would consist of
-revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
-
-   In VCSes with monotonic revision IDs, trunk revisions are IDed as
-1, 2, 3, etc.  A branch from (say) revision 2 might start with 2.1 and
-continue through 2.2, 2.3, etc.  But naming conventions for branches
-and subbranches vary widely on these systems, and some (like
-Mercurial) never depart from the monotonic integer sequence at all.
-Consult the documentation of the VCS you are using.
-
-@cindex head revision
-  If you omit the final component of a dot-pair revision ID, that is called a
-@dfn{branch ID}.  It refers to the highest existing revision on that
-branch---the @dfn{head revision} of that branch.  The branches in the
-dot-pair example above have branch IDs 1.2.1 and 1.2.2.
+
+  One use of version control is to support multiple independent lines
+of development, which are called @dfn{branches}.  Branches are used
+for maintaining separate ``stable'' and ``development'' versions of a
+program, and for developing unrelated features in isolation from one
+another.
+
+  VC's support for branch operations is currently fairly limited.  For
+decentralized version control systems, it provides commands for
+@dfn{updating} one branch with the contents of another, and for
+@dfn{merging} the changes made to two different branches
+(@pxref{Merging}).  For centralized version control systems, it
+supports checking out different branches and committing into new or
+different branches.
 
 @menu
 * Switching Branches::    How to get to another existing branch.
-* Creating Branches::     How to start a new branch.
+* VC Pull::               Updating the contents of a branch.
 * Merging::               Transferring changes between branches.
-* Multi-User Branching::  Multiple users working at multiple branches
-                            in parallel.
+* Creating Branches::     How to start a new branch.
 @end menu
 
 @node Switching Branches
 @subsubsection Switching between Branches
 
-  To switch between branches, type @kbd{C-u C-x v v} and specify the
-revision ID you want to select.  On a locking-based system, this
-version is then visited @emph{unlocked} (write-protected), so you can
-examine it before locking it.  Switching branches in this way is allowed
-only when the file is not locked.
-
-  On a VCS with dot-pair IDs, you can omit the minor part, thus giving
-only the branch ID; this takes you to the head version on the
-chosen branch.  If you only type @key{RET}, Emacs goes to the highest
-version on the trunk.
+  The various version control systems differ in how branches are
+implemented, and these differences cannot be entirely concealed by VC.
+
+  On some decentralized version control systems, including Bazaar and
+Mercurial in its normal mode of operation, each branch has its own
+working directory tree, so switching between branches just involves
+switching directories.  On Git, switching between branches is done
+using the @command{git branch} command, which changes the contents of
+the working tree itself.
+
+  On centralized version control systems, you can switch between
+branches by typing @kbd{C-u C-x v v} in an up-to-date work file
+(@pxref{Advanced C-x v v}), and entering the revision ID for a
+revision on another branch.  On CVS, for instance, revisions on the
+@dfn{trunk} (the main line of development) normally have IDs of the
+form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
+revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
+branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
+@dots{}, and so forth.  You can also specify the @dfn{branch ID},
+which is a branch revision ID omitting its final component
+(e.g.@: 1.2.1), to switch to the latest revision on that branch.
+
+  On a locking-based system, switching to a different branch also
+unlocks (write-protects) the working tree.
+
+  Once you have switched to a branch, VC commands will apply to that
+branch until you switch away; for instance, any VC filesets that you
+commit will be committed to that specific branch.
+
+@node VC Pull
+@subsubsection Pulling Changes into a Branch
 
-  After you have switched to any branch (including the main branch), you
-stay on it for subsequent VC commands, until you explicitly select some
-other branch.
+@table @kbd
+@itemx C-x v +
+On a decentralized version control system, update the current branch
+by ``pulling in'' changes from another location.
 
-@node Creating Branches
-@subsubsection Creating New Branches
+On a centralized version control system, update the current VC
+fileset.
+@end table
 
-  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
-Branches}).  Your procedure will then differ depending on whether you
-are using a locking or merging-based VCS.
+@kindex C-x v +
+@findex vc-pull
+  On a decentralized version control system, the command @kbd{C-x v +}
+(@code{vc-pull}) updates the current branch and working tree.  It is
+typically used to update a copy of a remote branch.  If you supply a
+prefix argument, the command prompts for the exact version control
+command to use, which lets you specify where to pull changes from.
+Otherwise, it pulls from a default location determined by the version
+control system.
 
-  On a locking VCS, you will need to lock the old revision branch with
-@kbd{C-x v v}.  You'll be asked to confirm, when you lock the old
-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.
+  Amongst decentralized version control systems, @kbd{C-x v +} is
+currently supported only by Bazaar, Git, and Mercurial.  On Bazaar, it
+calls @command{bzr pull} for ordinary branches (to pull from a master
+branch into a mirroring branch), and @command{bzr update} for a bound
+branch (to pull from a central repository).  On Git, it calls
+@command{git pull} to fetch changes from a remote repository and merge
+it into the current branch.  On Mercurial, it calls @command{hg pull
+-u} to fetch changesets from the default remote repository and update
+the working directory.
 
-  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.
+  Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
+to view a log buffer of the changes to be applied.  @xref{VC Change
+Log}.
 
-  After the branch is created, you ``stay'' on it.  That means that
-subsequent check-ins create new revisions on that branch.  To leave the
-branch, you must explicitly select a different revision with @kbd{C-u C-x
-v v}.  To transfer changes from one branch to another, use the merge
-command, described in the next section.
+  On a centralized version control system like CVS, @kbd{C-x v +}
+updates the current VC fileset from the repository.
 
 @node Merging
 @subsubsection Merging Branches
-
 @cindex merging changes
-  When you have finished the changes on a certain branch, you will
-often want to incorporate them into the file's main line of development
-(the trunk).  This is not a trivial operation, because development might
-also have proceeded on the trunk, so that you must @dfn{merge} the
-changes into a file that has already been changed otherwise.  VC allows
-you to do this (and other things) with the @code{vc-merge} command.
 
 @table @kbd
-@item C-x v m (vc-merge)
-Merge changes into the work file.
+@itemx C-x v m
+On a decentralized version control system, merge changes from another
+branch into the current one.
+
+On a centralized version control system, merge changes from another
+branch into the current VC fileset.
 @end table
 
-@kindex C-x v m
-@findex vc-merge
-  @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
-into the current version of the work file.  It firsts asks you in the
-minibuffer where the changes should come from.  If you just type
-@key{RET}, Emacs merges any changes that were made on the same branch
-since you checked the file out (we call this @dfn{merging the news}).
-This is the common way to pick up recent changes from the repository,
-regardless of whether you have already changed the file yourself.
-
-  You can also enter a branch ID or a pair of revision IDs in
-the minibuffer.  Then @kbd{C-x v m} finds the changes from that
-branch, or the differences between the two revisions you specified, and
-merges them into the current revision of the current file.
-
-  As an example, suppose that you have finished a certain feature on
-branch 1.3.1.  In the meantime, development on the trunk has proceeded
-to revision 1.5.  To merge the changes from the branch to the trunk,
-first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
-@key{RET}}.  Revision 1.5 is now current.  If locking is used for the file,
-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 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 commit the merged
-revision, then lock it and make the further changes.  This will keep
-a better record of the history of changes.
+  While developing a branch, you may sometimes need to @dfn{merge} in
+changes that have already been made in another branch.  This is not a
+trivial operation, as overlapping changes may have been made to the
+two branches.
+
+  On a decentralized version control system, merging is done with the
+command @kbd{C-x v m} (@code{vc-merge}).  On Bazaar, this prompts for
+the exact arguments to pass to @command{bzr merge}, offering a
+sensible default if possible.  On Git, this prompts for the name of a
+branch to merge from, with completion (based on the branch names known
+to the current repository).  The output from running the merge command
+is shown in a separate buffer.
+
+  On a centralized version control system like CVS, @kbd{C-x v m}
+prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
+Branches}); then it finds the changes from that branch, or the changes
+between the two revisions you specified, and merges those changes into
+the current VC fileset.  If you just type @key{RET}, Emacs simply
+merges any changes that were made on the same branch since you checked
+the file out.
 
 @cindex conflicts
 @cindex resolving conflicts
-  When you merge changes into a file that has itself been modified, the
-changes might overlap.  We call this situation a @dfn{conflict}, and
-reconciling the conflicting changes is called @dfn{resolving a
-conflict}.
-
-  Whenever conflicts occur during merging, VC detects them, tells you
-about them in the echo area, and asks whether you want help in merging.
-If you say yes, it starts an Ediff session (@pxref{Top,
-Ediff, Ediff, ediff, The Ediff Manual}).
-
-  If you say no, the conflicting changes are both inserted into the
-file, surrounded by @dfn{conflict markers}.  The example below shows how
-a conflict region looks; the file is called @samp{name} and the current
-master file revision with user B's changes in it is 1.11.
-
-@c @w here is so CVS won't think this is a conflict.
-@smallexample
-@group
-@w{<}<<<<<< name
-  @var{User A's version}
-=======
-  @var{User B's version}
-@w{>}>>>>>> 1.11
-@end group
-@end smallexample
+  Immediately after performing a merge, only the working tree is
+modified, and you can review the changes produced by the merge with
+@kbd{C-x v D} and related commands (@pxref{Old Revisions}).  If the
+two branches contained overlapping changes, merging produces a
+@dfn{conflict}; a warning appears in the output of the merge command,
+and @dfn{conflict markers} are inserted into each affected work file,
+surrounding the two sets of conflicting changes.  You must then
+resolve the conflict by editing the conflicted files.  Once you are
+done, the modified files must be committed in the usual way for the
+merge to take effect (@pxref{Basic VC Editing}).
 
-@findex vc-resolve-conflicts
-  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
-commit the merged version afterwards.
-
-@findex vc-find-conflicted-file
-  If there is more than one conflicted file in a merge, type @kbd{M-x
-vc-find-conflicted-file} after resolving the conflicts in each file.
-This command visits the next conflicted file, and moves point to the
-first conflict marker in that file.
-
-@node Multi-User Branching
-@subsubsection Multi-User Branching
-
-  It is often useful for multiple developers to work simultaneously on
-different branches of a file.  CVS and later systems allow this by
-default; for RCS, it is possible if you create multiple source
-directories.  Each source directory should have a link named
-@file{RCS} which points to a common directory of RCS master files.
-Then each source directory can have its own choice of selected
-revisions, but all share the same common RCS records.
-
-  This technique works reliably and automatically, provided that the
-source files contain RCS version headers
-@iftex
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Version Headers}).
-@end ifnottex
-The headers enable Emacs to be sure, at all times, which revision
-ID is present in the work file.
+@node Creating Branches
+@subsubsection Creating New Branches
+
+  On centralized version control systems like CVS, Emacs supports
+creating new branches as part of a commit operation.  When committing
+a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
+with a prefix argument; @pxref{Advanced C-x v v}).  Then Emacs prompts
+for a 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
+Branches}).  Your procedure will then differ depending on whether you
+are using a locking or merging-based VCS.
+
+  On a locking VCS, you will need to lock the old revision branch with
+@kbd{C-x v v}.  You'll be asked to confirm, when you lock the old
+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 commit a new
+revision.  This creates a new branch starting from the selected
+revision.
 
-  If the files do not have version headers, you must instead tell Emacs
-explicitly in each session which branch you are working on.  To do this,
-first find the file, then type @kbd{C-u C-x v v} and specify the correct
-branch ID.  This ensures that Emacs knows which branch it is using
-during this particular editing session.
+  After the branch is created, subsequent commits create new revisions
+on that branch.  To leave the branch, you must explicitly select a
+different revision with @kbd{C-u C-x v v}.
 
 @ifnottex
 @include vc1-xtra.texi
@@ -1458,13 +1444,11 @@ during this particular editing session.
 @section Change Logs
 
 @cindex change log
-  A change log file contains a chronological record of when and why you
-have changed a program, consisting of a sequence of entries describing
-individual changes.  Normally it is kept in a file called
-@file{ChangeLog} in the same directory as the file you are editing, or
-one of its parent directories.  A single @file{ChangeLog} file can
-record changes for all the files in its directory and all its
-subdirectories.
+  Many software projects keep a @dfn{change log}.  This is a file,
+normally named @file{ChangeLog}, containing a chronological record of
+when and how the program was changed.  Sometimes, there are several
+change log files, each recording the changes in one directory or
+directory tree.
 
 @menu
 * Change Log Commands:: Commands for editing change log files.
@@ -1496,7 +1480,7 @@ rather than starting a new item.
 
 You can combine multiple changes of the same nature.  If you don't
 enter any text after the initial @kbd{C-x 4 a}, any subsequent
-@kbd{C-x 4 a} adds another symbol to the change.
+@kbd{C-x 4 a} adds another symbol to the change log entry.
 
 @vindex add-log-always-start-new-record
   If @code{add-log-always-start-new-record} is non-@code{nil},
@@ -1534,15 +1518,7 @@ ordering of entries.
   Version control systems are another way to keep track of changes in
 your program and keep a change log.  In the VC log buffer, typing
 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
-Change Log entry, if one exists (@pxref{Log Buffer}).  You can also
-insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
-(@code{vc-update-change-log}) in the Change Log buffer
-@iftex
-(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Change Logs and VC}).
-@end ifnottex
+Change Log entry, if one exists.  @xref{Log Buffer}.
 
 @node Format of ChangeLog
 @subsection Format of ChangeLog
@@ -1597,8 +1573,8 @@ Of course, you should substitute the proper years and copyright holder.
 @cindex tags and tag tables
 
   A @dfn{tag} is a reference to a subunit in a program or in a
-document.  In program source code, tags reference syntactic elements
-of the program: functions, subroutines, data types, macros, etc.  In a
+document.  In source code, tags reference syntactic elements of the
+program: functions, subroutines, data types, macros, etc.  In a
 document, tags reference chapters, sections, appendices, etc.  Each
 tag specifies the name of the file where the corresponding subunit is
 defined, and the position of the subunit's definition in that file.
@@ -1612,34 +1588,36 @@ a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
 C files; and Fortran files produced by preprocessing @file{.fpp}
 source files.
 
-  To produce a tags table, you use the @samp{etags} command,
-submitting it a document or the source code of a program.
-@samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags
-file} in short.  The conventional name for a tags file is @file{TAGS}.
+@cindex etags
+  To produce a tags table, you run the @command{etags} shell command
+on a document or the source code file.  The @samp{etags} program
+writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
+short.  The conventional name for a tags file is @file{TAGS}.
+@xref{Create Tags Table}.
 
-  Emacs uses the information recorded in tags tables in commands that
-search or replace through multiple source files: these commands use
-the names of the source files recorded in the tags table to know which
-files to search.  Other commands, such as @kbd{M-.}, which finds the
-definition of a function, use the recorded information about the
-function names and positions to find the source file and the position
-within that file where the function is defined.
+  Emacs provides many commands for searching and replacing using the
+information recorded in tags tables.  For instance, the @kbd{M-.}
+(@code{find-tag}) jumps to the location of a specified function
+definition in its source file.  @xref{Find Tag}.
 
 @cindex C++ class browser, tags
 @cindex tags, C++
 @cindex class browser, C++
 @cindex Ebrowse
-  See also the Ebrowse facility, which is tailored for C++.
-@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
+  The Ebrowse facility is similar to @command{etags} but specifically
+tailored for C++.  @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
+Manual}.  The Semantic package provides another way to generate and
+use tags, separate from the @command{etags} facility.
+@xref{Semantic}.
 
 @menu
 * Tag Syntax::          Tag syntax for various types of code and text files.
-* Create Tags Table::   Creating a tags table with @code{etags}.
+* Create Tags Table::   Creating a tags table with @command{etags}.
 * Etags Regexps::       Create arbitrary tags using regular expressions.
 * Select Tags Table::   How to visit a tags table.
 * Find Tag::            Commands to find the definition of a specific tag.
 * Tags Search::         Using a tags table for searching and replacing.
-* List Tags::           Listing and finding tags defined in a file.
+* List Tags::           Using tags for completion, and listing them.
 @end menu
 
 @node Tag Syntax
@@ -1661,7 +1639,7 @@ and @samp{--no-members} can make the tags table file much smaller.
 
 You can tag function declarations and external variables in addition
 to function definitions by giving the @samp{--declarations} option to
-@code{etags}.
+@command{etags}.
 
 @item
 In C++ code, in addition to all the tag constructs of C code, member
@@ -1678,15 +1656,15 @@ Tags for variables and functions in classes are named
 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
 
 @item
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
+In La@TeX{} documents, the arguments for @code{\chapter},
 @code{\section}, @code{\subsection}, @code{\subsubsection},
 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
-@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
+@code{\newenvironment} and @code{\renewenvironment} are tags.
 
 Other commands can make tags as well, if you specify them in the
-environment variable @env{TEXTAGS} before invoking @code{etags}.  The
+environment variable @env{TEXTAGS} before invoking @command{etags}.  The
 value of this environment variable should be a colon-separated list of
 command names.  For example,
 
@@ -1818,9 +1796,9 @@ Regexps}) to handle other formats and languages.
 
 @node Create Tags Table
 @subsection Creating Tags Tables
-@cindex @code{etags} program
+@cindex @command{etags} program
 
-  The @code{etags} program is used to create a tags table file.  It knows
+  The @command{etags} program is used to create a tags table file.  It knows
 the syntax of several languages, as described in
 @iftex
 the previous section.
@@ -1828,58 +1806,51 @@ the previous section.
 @ifnottex
 @ref{Tag Syntax}.
 @end ifnottex
-Here is how to run @code{etags}:
+Here is how to run @command{etags}:
 
 @example
 etags @var{inputfiles}@dots{}
 @end example
 
 @noindent
-The @code{etags} program reads the specified files, and writes a tags
+The @command{etags} program reads the specified files, and writes a tags
 table named @file{TAGS} in the current working directory.  You can
 optionally specify a different file name for the tags table by using the
 @samp{--output=@var{file}} option; specifying @file{-} as a file name
 prints the tags table to standard output.
 
-  If the specified files don't exist, @code{etags} looks for
+  If the specified files don't exist, @command{etags} looks for
 compressed versions of them and uncompresses them to read them.  Under
-MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
+MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
 does not exist.
 
-  @code{etags} recognizes the language used in an input file based on
-its file name and contents.  You can specify the language with the
-@samp{--language=@var{name}} option, described below.
-
-  If the tags table data become outdated due to changes in the files
-described in the table, the way to update the tags table is the same
-way it was made in the first place.  If the tags table fails to record
-a tag, or records it for the wrong file, then Emacs cannot possibly
-find its definition until you update the tags table.  However, if the
-position recorded in the tags table becomes a little bit wrong (due to
-other editing), the worst consequence is a slight delay in finding the
-tag.  Even if the stored position is very far wrong, Emacs will still
-find the tag, after searching most of the file for it.  That delay is
-hardly noticeable with today's computers.
+  If the tags table becomes outdated due to changes in the files
+described in it, you can update it by running the @command{etags}
+program again.  If the tags table does not record a tag, or records it
+for the wrong file, then Emacs will not be able to find that
+definition until you update the tags table.  But if the position
+recorded in the tags table becomes a little bit wrong (due to other
+editing), Emacs will still be able to find the right position, with a
+slight delay.
 
    Thus, there is no need to update the tags table after each edit.
 You should update a tags table when you define new tags that you want
 to have listed, or when you move tag definitions from one file to
 another, or when changes become substantial.
 
-  One tags table can virtually include another.  Specify the included
-tags file name with the @samp{--include=@var{file}} option when
-creating the file that is to include it.  The latter file then acts as
-if it covered all the source files specified in the included file, as
-well as the files it directly contains.
+  You can make a tags table @dfn{include} another tags table, by
+passing the @samp{--include=@var{file}} option to @command{etags}.  It
+then covers all the files covered by the included tags file, as well
+as its own.
 
   If you specify the source files with relative file names when you run
-@code{etags}, the tags file will contain file names relative to the
+@command{etags}, the tags file will contain file names relative to the
 directory where the tags file was initially written.  This way, you can
 move an entire directory tree containing both the tags file and the
 source files, and the tags file will still refer correctly to the source
 files.  If the tags file is @file{-} or is in the @file{/dev} directory,
-however, the file names are 
+however, the file names are
 made relative to the current working directory.  This is useful, for
 example, when writing the tags to @file{/dev/stdout}.
 
@@ -1887,40 +1858,41 @@ example, when writing the tags to @file{/dev/stdout}.
 pointing to a tags file in a different directory, because this would
 generally render the file names invalid.
 
-  If you specify absolute file names as arguments to @code{etags}, then
+  If you specify absolute file names as arguments to @command{etags}, then
 the tags file will contain absolute file names.  This way, the tags file
 will still refer to the same files even if you move it, as long as the
 source files remain in the same place.  Absolute file names start with
 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
 
-  When you want to make a tags table from a great number of files, you
-may have problems listing them on the command line, because some systems
-have a limit on its length.  The simplest way to circumvent this limit
-is to tell @code{etags} to read the file names from its standard input,
-by typing a dash in place of the file names, like this:
+   When you want to make a tags table from a great number of files,
+you may have problems listing them on the command line, because some
+systems have a limit on its length.  You can circumvent this limit by
+telling @command{etags} to read the file names from its standard
+input, by typing a dash in place of the file names, like this:
 
 @smallexample
 find . -name "*.[chCH]" -print | etags -
 @end smallexample
 
-  Use the option @samp{--language=@var{name}} to specify the language
-explicitly.  You can intermix these options with file names; each one
-applies to the file names that follow it.  Specify
-@samp{--language=auto} to tell @code{etags} to resume guessing the
-language from the file names and file contents.  Specify
-@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone
-(@pxref{Etags Regexps}).
+  @command{etags} recognizes the language used in an input file based
+on its file name and contents.  You can specify the language
+explicitly with the @samp{--language=@var{name}} option.  You can
+intermix these options with file names; each one applies to the file
+names that follow it.  Specify @samp{--language=auto} to tell
+@command{etags} to resume guessing the language from the file names
+and file contents.  Specify @samp{--language=none} to turn off
+language-specific processing entirely; then @command{etags} recognizes
+tags by regexp matching alone (@pxref{Etags Regexps}).
 
   The option @samp{--parse-stdin=@var{file}} is mostly useful when
-calling @code{etags} from programs.  It can be used (only once) in
-place of a file name on the command line.  @code{Etags} will read from
+calling @command{etags} from programs.  It can be used (only once) in
+place of a file name on the command line.  @command{etags} will read from
 standard input and mark the produced tags as belonging to the file
 @var{file}.
 
-  @samp{etags --help} outputs the list of the languages @code{etags}
+  @samp{etags --help} outputs the list of the languages @command{etags}
 knows, and the file name rules for guessing the language.  It also prints
-a list of all the available @code{etags} options, together with a short
+a list of all the available @command{etags} options, together with a short
 explanation.  If followed by one or more @samp{--language=@var{lang}}
 options, it outputs detailed information about how tags are generated for
 @var{lang}.
@@ -1928,21 +1900,22 @@ options, it outputs detailed information about how tags are generated for
 @node Etags Regexps
 @subsection Etags Regexps
 
-  The @samp{--regex} option provides a general way of recognizing tags
-based on regexp matching.  You can freely intermix this option with
-file names, and each one applies to the source files that follow it.
-If you specify multiple @samp{--regex} options, all of them are used
-in parallel.  The syntax is:
+  The @samp{--regex} option to @command{etags} allows tags to be
+recognized by regular expression matching.  You can intermix this
+option with file names; each one applies to the source files that
+follow it.  If you specify multiple @samp{--regex} options, all of
+them are used in parallel.  The syntax is:
 
 @smallexample
 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
 @end smallexample
 
-  The essential part of the option value is @var{tagregexp}, the
-regexp for matching tags.  It is always used anchored, that is, it
-only matches at the beginning of a line.  If you want to allow
-indented tags, use a regexp that matches initial whitespace; start it
-with @samp{[ \t]*}.
+@noindent
+The essential part of the option value is @var{tagregexp}, the regexp
+for matching tags.  It is always used anchored, that is, it only
+matches at the beginning of a line.  If you want to allow indented
+tags, use a regexp that matches initial whitespace; start it with
+@samp{[ \t]*}.
 
   In these regular expressions, @samp{\} quotes the next character, and
 all the GCC character escape sequences are supported (@samp{\a} for
@@ -1959,7 +1932,7 @@ completion on tag names more reliably.  You can find some examples
 below.
 
   The @var{modifiers} are a sequence of zero or more characters that
-modify the way @code{etags} does the matching.  A regexp with no
+modify the way @command{etags} does the matching.  A regexp with no
 modifiers is applied sequentially to each line of the input file, in a
 case-sensitive way.  The modifiers and their meanings are:
 
@@ -1984,22 +1957,22 @@ etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
 @end smallexample
 
 @noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
-@file{bar.ber} according to their contents.  @code{etags} also uses
+Here @command{etags} chooses the parsing language for @file{voo.doo} and
+@file{bar.ber} according to their contents.  @command{etags} also uses
 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
 @var{reg1} and @var{reg2} to recognize additional tags in
 @file{bar.ber}.  @var{reg1} is checked against each line of
 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
 @var{reg2} is checked against the whole @file{bar.ber} file,
-permitting multi-line matches, in a case-sensitive way.  @code{etags}
+permitting multi-line matches, in a case-sensitive way.  @command{etags}
 uses only the Lisp tags rules, with no user-specified regexp matching,
 to recognize tags in @file{los.er}.
 
   You can restrict a @samp{--regex} option to match only files of a
 given language by using the optional prefix @var{@{language@}}.
 (@samp{etags --help} prints the list of languages recognized by
-@code{etags}.)  This is particularly useful when storing many
-predefined regular expressions for @code{etags} in a file.  The
+@command{etags}.)  This is particularly useful when storing many
+predefined regular expressions for @command{etags} in a file.  The
 following example tags the @code{DEFVAR} macros in the Emacs source
 files, for the C language only:
 
@@ -2009,7 +1982,7 @@ files, for the C language only:
 
 @noindent
 When you have complex regular expressions, you can store the list of
-them in a file.  The following option syntax instructs @code{etags} to
+them in a file.  The following option syntax instructs @command{etags} to
 read two files of regular expressions.  The regular expressions
 contained in the second file are matched without regard to case.
 
@@ -2018,9 +1991,9 @@ contained in the second file are matched without regard to case.
 @end smallexample
 
 @noindent
-A regex file for @code{etags} contains one regular expression per
+A regex file for @command{etags} contains one regular expression per
 line.  Empty lines, and lines beginning with space or tab are ignored.
-When the first character in a line is @samp{@@}, @code{etags} assumes
+When the first character in a line is @samp{@@}, @command{etags} assumes
 that the rest of the line is the name of another file of regular
 expressions; thus, one such file can include another file.  All the
 other lines are taken to be regular expressions.  If the first
@@ -2083,14 +2056,14 @@ etags --language=none \
 @node Select Tags Table
 @subsection Selecting a Tags Table
 
-@vindex tags-file-name
 @findex visit-tags-table
-  Emacs has at any time one @dfn{selected} tags table, and all the
+  Emacs has at any time one @dfn{selected} tags table.  All the
 commands for working with tags tables use the selected one.  To select
 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
 table file name as an argument, with @file{TAGS} in the default
 directory as the default.
 
+@vindex tags-file-name
   Emacs does not actually read in the tags table contents until you
 try to use them; all @code{visit-tags-table} does is store the file
 name in the variable @code{tags-file-name}, and setting the variable
@@ -2154,27 +2127,25 @@ Pop back to where you previously invoked @kbd{M-.} and friends.
 
 @kindex M-.
 @findex find-tag
-  @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
-a specified tag.  It searches through the tags table for that tag, as a
-string, and then uses the tags table info to determine the file that the
-definition is in and the approximate character position in the file of
-the definition.  Then @code{find-tag} visits that file, moves point to
-the approximate character position, and searches ever-increasing
-distances away to find the tag definition.
-
-  If an empty argument is given (just type @key{RET}), the balanced
-expression in the buffer before or around point is used as the
-@var{tag} argument.  @xref{Expressions}.
+  @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to
+its source definition.  It works by searching through the tags table
+for that tag's file and approximate character position, visiting that
+file, and searching for the tag definition at ever-increasing
+distances away from the recorded approximate position.
+
+  When entering the tag argument to @kbd{M-.}, the usual minibuffer
+completion commands can be used (@pxref{Completion}), with the tag
+names in the selected tags table as completion candidates.  If you
+specify an empty argument, the balanced expression in the buffer
+before or around point is the default argument.  @xref{Expressions}.
 
   You don't need to give @kbd{M-.} the full name of the tag; a part
-will do.  This is because @kbd{M-.} finds tags in the table which
-contain @var{tag} as a substring.  However, it prefers an exact match
-to a substring match.  To find other tags that match the same
-substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
-M-.}; this does not read a tag name, but continues searching the tags
-table's text for another tag containing the same substring last used.
-If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
-alternative to @kbd{C-u M-.}.
+will do.  @kbd{M-.} finds tags which contain that argument as a
+substring.  However, it prefers an exact match to a substring match.
+To find other tags that match the same substring, give @code{find-tag}
+a numeric argument, as in @kbd{C-u M-.}  or @kbd{M-0 M-.}; this does
+not read a tag name, but continues searching the tags table's text for
+another tag containing the same substring last used.
 
 @kindex C-x 4 .
 @findex find-tag-other-window
@@ -2182,23 +2153,23 @@ alternative to @kbd{C-u M-.}.
 @findex find-tag-other-frame
   Like most commands that can switch buffers, @code{find-tag} has a
 variant that displays the new buffer in another window, and one that
-makes a new frame for it.  The former is @w{@kbd{C-x 4 .}}, which invokes
-the command @code{find-tag-other-window}.  The latter is @w{@kbd{C-x 5 .}},
-which invokes @code{find-tag-other-frame}.
+makes a new frame for it.  The former is @w{@kbd{C-x 4 .}}
+(@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}}
+(@code{find-tag-other-frame}).
 
-  To move back to places you've found tags recently, use @kbd{C-u -
-M-.}; more generally, @kbd{M-.} with a negative numeric argument.  This
-command can take you to another buffer.  @w{@kbd{C-x 4 .}} with a negative
-argument finds the previous tag location in another window.
+  To move back to previous tag definitions, use @kbd{C-u - M-.}; more
+generally, @kbd{M-.} with a negative numeric argument.  Similarly,
+@w{@kbd{C-x 4 .}} with a negative argument finds the previous tag
+location in another window.
 
 @kindex M-*
 @findex pop-tag-mark
 @vindex find-tag-marker-ring-length
-  As well as going back to places you've found tags recently, you can go
-back to places @emph{from where} you found them.  Use @kbd{M-*}, which
-invokes the command @code{pop-tag-mark}, for this.  Typically you would
-find and study the definition of something with @kbd{M-.} and then
-return to where you were with @kbd{M-*}.
+  As well as going back to places you've found tags recently, you can
+go back to places @emph{from where} you found them, using @kbd{M-*}
+(@code{pop-tag-mark}).  Thus you can find and examine the definition
+of something with @kbd{M-.} and then return to where you were with
+@kbd{M-*}.
 
   Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
 a depth determined by the variable @code{find-tag-marker-ring-length}.
@@ -2242,10 +2213,10 @@ can follow its progress.  As soon as it finds an occurrence,
 
 @kindex M-,
 @findex tags-loop-continue
-  Having found one match, you probably want to find all the rest.  To find
-one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
-@code{tags-search}.  This searches the rest of the current buffer, followed
-by the remaining files of the tags table.@refill
+  Having found one match, you probably want to find all the rest.
+Type @kbd{M-,} (@code{tags-loop-continue}) to resume the
+@code{tags-search}, finding one more match.  This searches the rest of
+the current buffer, followed by the remaining files of the tags table.
 
 @findex tags-query-replace
   @kbd{M-x tags-query-replace} performs a single
@@ -2282,56 +2253,56 @@ have to search (those which are not already visited in Emacs buffers).
 Buffers in which no match is found are quickly killed; the others
 continue to exist.
 
-  It may have struck you that @code{tags-search} is a lot like
-@code{grep}.  You can also run @code{grep} itself as an inferior of
-Emacs and have Emacs show you the matching lines one by one.
+  As an alternative to @code{tags-search}, you can run @command{grep}
+as a subprocess and have Emacs show you the matching lines one by one.
 @xref{Grep Searching}.
 
 @node List Tags
 @subsection Tags Table Inquiries
 
 @table @kbd
+@item C-M-i
+@itemx M-@key{TAB}
+Perform completion on the text around point, using the selected tags
+table if one is loaded (@code{completion-at-point}).
 @item M-x list-tags @key{RET} @var{file} @key{RET}
 Display a list of the tags defined in the program file @var{file}.
 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
 Display a list of all tags matching @var{regexp}.
 @end table
 
+@cindex completion (symbol names)
+  In most programming language modes, you can type @kbd{C-M-i} or
+@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
+at point.  If there is a selected tags table, this command can use it
+to generate completion candidates.  @xref{Symbol Completion}.
+
 @findex list-tags
-  @kbd{M-x list-tags} reads the name of one of the files described by
-the selected tags table, and displays a list of all the tags defined in
-that file.  The ``file name'' argument is really just a string to
-compare against the file names recorded in the tags table; it is read as
-a string rather than as a file name.  Therefore, completion and
-defaulting are not available, and you must enter the file name the same
-way it appears in the tags table.  Do not include a directory as part of
-the file name unless the file name recorded in the tags table includes a
-directory.
+  @kbd{M-x list-tags} reads the name of one of the files covered by
+the selected tags table, and displays a list of tags defined in that
+file.  Do not include a directory as part of the file name unless the
+file name recorded in the tags table includes a directory.
 
 @findex tags-apropos
 @vindex tags-apropos-verbose
-  @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}).  It finds all the tags in the selected tags table
-whose entries match @var{regexp}, and displays them.  If the variable
-@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
-of the tags files together with the tag names.
-
 @vindex tags-tag-face
 @vindex tags-apropos-additional-actions
-  You can customize the appearance of the output by setting the
-variable @code{tags-tag-face} to a face.  You can display additional
-output with @kbd{M-x tags-apropos} by customizing the variable
-@code{tags-apropos-additional-actions}---see its documentation for
-details.
-
-  You can also use the collection of tag names to complete a symbol
-name in the buffer.  @xref{Symbol Completion}.
-
-  You can use @kbd{M-x next-file} to visit the files in the selected
-tags table.  The first time this command is called, it visits the
-first file in the tags table.  Each subsequent call visits the next
-file in the table, unless a prefix argument is supplied, in which case
-it returns to the first file.
+  @kbd{M-x tags-apropos} is like @code{apropos} for tags
+(@pxref{Apropos}).  It displays a list of tags in the selected tags
+table whose entries match @var{regexp}.  If the variable
+@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
+of the tags files together with the tag names.  You can customize the
+appearance of the output by setting the variable @code{tags-tag-face}
+to a face.  You can display additional output by customizing the
+variable @code{tags-apropos-additional-actions}; see its documentation
+for details.
+
+@findex next-file
+  @kbd{M-x next-file} visits files covered by the selected tags table.
+The first time it is called, it visits the first file covered by the
+table.  Each subsequent call visits the next covered file, unless a
+prefix argument is supplied, in which case it returns to the first
+file.
 
 @node EDE
 @section Emacs Development Environment
diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi
index e3c9b8d4fc2..547d8cbadd9 100644
--- a/doc/emacs/msdog.texi
+++ b/doc/emacs/msdog.texi
@@ -863,15 +863,22 @@ fontconfig library used in modern Free desktops:
 
   The old XLFD based format is also supported for backwards compatibility.
 
-  Emacs 23 supports a number of backends.  Currently, the @code{gdi}
-and @code{uniscribe} font backends are supported on Windows.  The
-@code{gdi} font backend is available on all versions of Windows, and
-supports all fonts that are natively supported by Windows.  The
+@cindex font backend selection (MS-Windows)
+  Emacs 23 and later supports a number of font backends.  Currently,
+the @code{gdi} and @code{uniscribe} backends are supported on Windows.
+The @code{gdi} font backend is available on all versions of Windows,
+and supports all fonts that are natively supported by Windows.  The
 @code{uniscribe} font backend is available on Windows 2000 and later,
 and supports TrueType and OpenType fonts.  Some languages requiring
-complex layout can only be properly supported by the uniscribe
+complex layout can only be properly supported by the Uniscribe
 backend.  By default, both backends are enabled if supported, with
-@code{uniscribe} taking priority over @code{gdi}.
+@code{uniscribe} taking priority over @code{gdi}.  To override that
+and use the GDI backend even if Uniscribe is available, invoke Emacs
+with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or
+add a @code{Emacs.fontBackend} resource with the value @code{gdi} in
+the Registry under either the
+@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the
+@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}).
 
 @cindex font properties (MS Windows)
 @noindent
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 675977c2c35..7301ecfea8a 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -8,8 +8,8 @@
 @cindex C editing
 @cindex program editing
 
-  Emacs provides many features to facilitate editing programs.  Some
-of these features can
+  This chapter describes Emacs features for facilitating editing
+programs.  Some of these features can:
 
 @itemize @bullet
 @item
@@ -25,8 +25,6 @@ Insert, kill or align comments (@pxref{Comments}).
 Highlight program syntax (@pxref{Font Lock}).
 @end itemize
 
-  This chapter describes these features and many more.
-
 @menu
 * Program Modes::       Major modes for editing programs.
 * Defuns::              Commands to operate on major top-level parts
@@ -40,8 +38,8 @@ Highlight program syntax (@pxref{Font Lock}).
 * Glasses::             Making identifiersLikeThis more readable.
 * Semantic::            Suite of editing tools based on source code parsing.
 * Misc for Programs::   Other Emacs features useful for editing programs.
-* C Modes::             Special commands of C, C++, Objective-C,
-                          Java, and Pike modes.
+* C Modes::             Special commands of C, C++, Objective-C, Java,
+                          IDL, Pike and AWK modes.
 * Asm Mode::            Asm mode and its special features.
 @ifnottex
 * Fortran::             Fortran mode and its special features.
@@ -52,21 +50,14 @@ Highlight program syntax (@pxref{Font Lock}).
 @section Major Modes for Programming Languages
 @cindex modes for programming languages
 
-  Emacs has specialized major modes for various programming languages.
-@xref{Major Modes}.  A programming language major mode typically
+  Emacs has specialized major modes (@pxref{Major Modes}) for many
+programming languages.  A programming language mode typically
 specifies the syntax of expressions, the customary rules for
 indentation, how to do syntax highlighting for the language, and how
-to find the beginning or end of a function definition.  It often
-customizes or provides facilities for compiling and debugging programs
-as well.
-
-  Ideally, Emacs should provide a major mode for each programming
-language that you might want to edit; if it doesn't have a mode for
-your favorite language, you can contribute one.  But often the mode
-for one language can serve for other syntactically similar languages.
-The major mode for language @var{l} is called @code{@var{l}-mode},
-and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
-@xref{Choosing Modes}.
+to find the beginning or end of a function definition.  It often has
+features for compiling and debugging programs as well.  The major mode
+for each language is named after the language; for instance, the major
+mode for the C programming language is @code{c-mode}.
 
 @cindex Perl mode
 @cindex Icon mode
@@ -89,40 +80,32 @@ and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
 @cindex Conf mode
 @cindex DNS mode
 @cindex Javascript mode
-  The existing programming language major modes include Lisp, Scheme
-(a variant of Lisp) and the Scheme-based DSSSL expression language,
-Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran, Icon, IDL
-(CORBA), IDLWAVE, Java, Javascript, Metafont (@TeX{}'s companion for
-font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike,
-PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL.  An
-alternative mode for Perl is called CPerl mode.  Modes are available
-for the scripting languages of the common GNU and Unix shells, VMS
-DCL, and MS-DOS/MS-Windows @samp{BAT} files.  There are also major
-modes for editing makefiles, DNS master files, and various sorts of
-configuration files.
+  Emacs has programming language modes for Lisp, Scheme, the
+Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi,
+Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
+(@TeX{}'s companion for font creation), Modula2, Objective-C, Octave,
+Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and
+VHDL.  An alternative mode for Perl is called CPerl mode.  Modes are
+also available for the scripting languages of the common GNU and Unix
+shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for
+makefiles, DNS master files, and various sorts of configuration files.
+
+  Ideally, Emacs should have a major mode for each programming
+language that you might want to edit.  If it doesn't have a mode for
+your favorite language, the mode might be implemented in a package not
+distributed with Emacs (@pxref{Packages}); or you can contribute one.
 
 @kindex DEL @r{(programming modes)}
 @findex c-electric-backspace
+@findex backward-delete-char-untabify
   In most programming languages, indentation should vary from line to
-line to illustrate the structure of the program.  So the major modes
-for programming languages arrange for @key{TAB} to update the
-indentation of the current line (@pxref{Program Indent}).  They also
-rebind @key{DEL} to treat a tab as if it were the equivalent number of
-spaces; this lets you delete one column of indentation without
-worrying whether the whitespace consists of spaces or tabs.  Use
-@kbd{C-b C-d} to delete a tab character before point, in these modes.
-
-  Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
-Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
-(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
-(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).  For Fortran
-mode, see
-@iftex
-@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@ref{Fortran}.
-@end ifnottex
+line to illustrate the structure of the program.  Therefore, in most
+programming language modes, typing @key{TAB} updates the indentation
+of the current line (@pxref{Program Indent}).  Furthermore, @key{DEL}
+is usually bound to @code{backward-delete-char-untabify}, which
+deletes backward treating each tab as if it were the equivalent number
+of spaces, so that you can delete one column of indentation without
+worrying whether the whitespace consists of spaces or tabs.
 
 @cindex mode hook
 @vindex c-mode-hook
@@ -130,13 +113,24 @@ mode, see
 @vindex emacs-lisp-mode-hook
 @vindex lisp-interaction-mode-hook
 @vindex scheme-mode-hook
-  Turning on a major mode runs a normal hook called the @dfn{mode
-hook}, which is the value of a Lisp variable.  Each major mode has a
-mode hook, and the hook's name is always made from the mode command's
-name by adding @samp{-hook}.  For example, turning on C mode runs the
-hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
-@code{lisp-mode-hook}.  The purpose of the mode hook is to give you a
-place to set up customizations for that major mode.  @xref{Hooks}.
+  Entering a programming language mode runs the custom Lisp functions
+specified in the hook variable @code{prog-mode-hook}, followed by
+those specified in the mode's own mode hook (@pxref{Major Modes}).
+For instance, entering C mode runs the hooks @code{prog-mode-hook} and
+@code{c-mode-hook}.  @xref{Hooks}, for information about hooks.
+
+@ifinfo
+  Separate manuals are available for the modes for Ada (@pxref{Top,,
+Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
+IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
+(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
+@end ifinfo
+@ifnotinfo
+  The Emacs distribution contains Info manuals for the major modes for
+Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE.  For
+Fortran mode, see the ``Fortran'' section in the Info version of the
+Emacs manual, which is not included in this printed version.
+@end ifnotinfo
 
 @node Defuns
 @section Top-Level Definitions, or Defuns
@@ -328,20 +322,19 @@ The Speedbar can also use it (@pxref{Speedbar}).
 @subsection Which Function Mode
 @cindex current function name in mode line
 
-  Which Function mode is a minor mode that displays the current
-function name in the mode line, updating it as you move around in a
-buffer.
+  Which Function mode is a global minor mode (@pxref{Minor Modes})
+which displays the current function name in the mode line, updating it
+as you move around in a buffer.
 
 @findex which-function-mode
 @vindex which-func-modes
   To either enable or disable Which Function mode, use the command
-@kbd{M-x which-function-mode}.  This command applies to all buffers,
-both existing ones and those yet to be created.  However, it takes
-effect only in certain major modes, those listed in the value of
-@code{which-func-modes}.  If the value of @code{which-func-modes} is
-@code{t} rather than a list of modes, then Which Function mode applies
-to all major modes that know how to support it---in other words, all
-the major modes that support Imenu.
+@kbd{M-x which-function-mode}.  Although Which Function mode is a
+global minor mode, it takes effect only in certain major modes: those
+listed in the variable @code{which-func-modes}.  If the value of
+@code{which-func-modes} is @code{t} rather than a list of modes, then
+Which Function mode applies to all major modes that know how to
+support it---in other words, all the major modes that support Imenu.
 
 @node Program Indent
 @section Indentation for Programs
@@ -352,6 +345,10 @@ reindent it as you change it.  Emacs has commands to indent either a
 single line, a specified number of lines, or all of the lines inside a
 single parenthetical grouping.
 
+  @xref{Indentation}, for general information about indentation.  This
+section describes indentation features specific to programming
+language modes.
+
 @menu
 * Basic Indent::        Indenting a single line.
 * Multi-line Indent::   Commands to reindent many lines at once.
@@ -361,18 +358,15 @@ single parenthetical grouping.
 @end menu
 
 @cindex pretty-printer
-  Emacs also provides a Lisp pretty-printer in the library @code{pp}.
-This program reformats a Lisp object with indentation chosen to look nice.
+  Emacs also provides a Lisp pretty-printer in the @code{pp} package,
+which reformats Lisp objects with nice-looking indentation.
 
 @node Basic Indent
 @subsection Basic Program Indentation Commands
 
-  The basic indentation commands indent a single line according to the
-usual conventions of the language you are editing.
-
 @table @kbd
 @item @key{TAB}
-Adjust indentation of current line.
+Adjust indentation of current line (@code{indent-for-tab-command}).
 @item C-j
 Insert a newline, then adjust indentation of following line
 (@code{newline-and-indent}).
@@ -382,65 +376,50 @@ Insert a newline, then adjust indentation of following line
 @findex c-indent-command
 @findex indent-line-function
 @findex indent-for-tab-command
-  The basic indentation command is @key{TAB}.  In any
-programming-language major mode, @key{TAB} gives the current line the
-correct indentation as determined from the previous lines.  It does
-this by inserting or deleting whitespace at the beginning of the
-current line.  If point was inside the whitespace at the beginning of
-the line, @key{TAB} puts it at the end of that whitespace; otherwise,
-@key{TAB} keeps point fixed with respect to the characters around it.
-If the region is active (@pxref{Mark}), @key{TAB} indents every line
-within the region instead of just the current line.  The function that
-@key{TAB} runs depends on the major mode; for instance, it is
-@code{c-indent-line-or-region} in C mode.  Each function is aware of
-the syntax and conventions for its particular language.
-
-  Use @kbd{C-q @key{TAB}} to insert a tab character at point.
+  The basic indentation command is @key{TAB}
+(@code{indent-for-tab-command}), which was documented in
+@ref{Indentation}.  In programming language modes, @key{TAB} indents
+the current line, based on the indentation and syntactic content of
+the preceding lines; if the region is active, @key{TAB} indents each
+line within the region, not just the current line.
 
 @kindex C-j @r{(indenting source code)}
 @findex newline-and-indent
-  When entering lines of new code, use @kbd{C-j}
-(@code{newline-and-indent}), which inserts a newline and then adjusts
-indentation after it.  (It also deletes any trailing whitespace which
-remains before the new newline.)  For instance, @kbd{C-j} at the end
-of a line creates a blank line with appropriate indentation.  In
-programming language modes, it is equivalent to @key{RET} @key{TAB}.
-
-  When Emacs indents a line that starts within a parenthetical
-grouping, it usually places the start of the line under the preceding
-line within the group, or under the text after the parenthesis.  If
-you manually give one of these lines a nonstandard indentation, the
-lines below will tend to follow it.  This behavior is convenient in
-cases where you have overridden the standard result of @key{TAB}
-indentation (e.g., for aesthetic purposes).
-
-  Many programming-language modes assume that an open-parenthesis,
-open-brace or other opening delimiter at the left margin is the start
-of a function.  This assumption speeds up indentation commands.  If
-the text you are editing contains opening delimiters in column zero
-that aren't the beginning of a functions---even if these delimiters
-occur inside strings or comments---then you must set
-@code{open-paren-in-column-0-is-defun-start}.  @xref{Left Margin
+  The command @kbd{C-j} (@code{newline-and-indent}), which was
+documented in @ref{Indentation Commands}, does the same as @key{RET}
+followed by @key{TAB}: it inserts a new line, then adjusts the line's
+indentation.
+
+  When indenting a line that starts within a parenthetical grouping,
+Emacs usually places the start of the line under the preceding line
+within the group, or under the text after the parenthesis.  If you
+manually give one of these lines a nonstandard indentation (e.g.@: for
+aesthetic purposes), the lines below will follow it.
+
+  The indentation commands for most programming language modes assume
+that a open-parenthesis, open-brace or other opening delimiter at the
+left margin is the start of a function.  If the code you are editing
+violates this assumption---even if the delimiters occur in strings or
+comments---you must set @code{open-paren-in-column-0-is-defun-start}
+to @code{nil} for indentation to work properly.  @xref{Left Margin
 Paren}.
 
-  Normally, Emacs indents lines using an ``optimal'' mix of tab and
-space characters.  If you want Emacs to use spaces only, set
-@code{indent-tabs-mode} (@pxref{Just Spaces}).
-
 @node Multi-line Indent
 @subsection Indenting Several Lines
 
   Sometimes, you may want to reindent several lines of code at a time.
 One way to do this is to use the mark; when the mark is active and the
-region is non-empty, @key{TAB} indents every line within the region.
-In addition, Emacs provides several other commands for indenting large
-chunks of code:
+region is non-empty, @key{TAB} indents every line in the region.
+Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
+every line in the region, whether or not the mark is active
+(@pxref{Indentation Commands}).
+
+  In addition, Emacs provides the following commands for indenting
+large chunks of code:
 
 @table @kbd
 @item C-M-q
 Reindent all the lines within one parenthetical grouping.
-@item C-M-\
-Reindent all lines in the region (@code{indent-region}).
 @item C-u @key{TAB}
 Shift an entire parenthetical grouping rigidly sideways so that its
 first line is properly indented.
@@ -454,18 +433,13 @@ lines that start inside comments and strings.
   To reindent the contents of a single parenthetical grouping,
 position point before the beginning of the grouping and type
 @kbd{C-M-q}.  This changes the relative indentation within the
-grouping, without affecting its overall indentation (i.e., the
+grouping, without affecting its overall indentation (i.e.@: the
 indentation of the line where the grouping starts).  The function that
 @kbd{C-M-q} runs depends on the major mode; it is
 @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
 etc.  To correct the overall indentation as well, type @key{TAB}
 first.
 
-  @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to the region.
-This is useful when Transient Mark mode is disabled (@pxref{Disabled
-Transient Mark}), because in that case @key{TAB} does not act on the
-region.
-
 @kindex C-u TAB
   If you like the relative indentation within a grouping but not the
 indentation of its first line, move point to that first line and type
@@ -516,9 +490,9 @@ expression.
 @cindex @code{lisp-indent-function} property
   You can override the standard pattern in various ways for individual
 functions, according to the @code{lisp-indent-function} property of
-the function name.  Normally you would use this for macro definitions
-and specify it using the @code{declare} construct (@pxref{Defining
-Macros,,, elisp, the Emacs Lisp Reference Manual}).
+the function name.  This is normally done for macro definitions, using
+the @code{declare} construct.  @xref{Defining Macros,,, elisp, the
+Emacs Lisp Reference Manual}.
 
 @node C Indent
 @subsection Commands for C Indentation
@@ -632,6 +606,14 @@ information on customizing indentation for C and related modes,
 including how to override parts of an existing style and how to define
 your own styles.
 
+@findex c-guess
+@findex c-guess-install
+  As an alternative to specifying a style, you can tell Emacs to guess
+a style by typing @kbd{M-x c-guess} in a sample code buffer.  You can
+then apply the guessed style to other buffers with @kbd{M-x
+c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
+Manual}, for details.
+
 @node Parentheses
 @section Commands for Editing with Parentheses
 
@@ -664,9 +646,13 @@ parentheses and unbalanced string quotes in the buffer.
 @cindex sexp
 @cindex expression
 @cindex balanced expression
-  These commands deal with balanced expressions, also called
-@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
-expression in Lisp.}.
+  Each programming language mode has its own definition of a
+@dfn{balanced expression}.  Balanced expressions typically include
+individual symbols, numbers, and string constants, as well as pieces
+of code enclosed in a matching pair of delimiters.  The following
+commands deal with balanced expressions (in Emacs, such expressions
+are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
+is used to refer to an expression in Lisp.}).
 
 @table @kbd
 @item C-M-f
@@ -682,90 +668,71 @@ Transpose expressions (@code{transpose-sexps}).
 Put mark after following expression (@code{mark-sexp}).
 @end table
 
-  Each programming language major mode customizes the definition of
-balanced expressions to suit that language.  Balanced expressions
-typically include symbols, numbers, and string constants, as well as
-any pair of matching delimiters and their contents.  Some languages
-have obscure forms of expression syntax that nobody has bothered to
-implement in Emacs.
-
-@cindex Control-Meta
-  By convention, the keys for these commands are all Control-Meta
-characters.  They usually act on expressions just as the corresponding
-Meta characters act on words.  For instance, the command @kbd{C-M-b}
-moves backward over a balanced expression, just as @kbd{M-b} moves
-back over a word.
-
 @kindex C-M-f
 @kindex C-M-b
 @findex forward-sexp
 @findex backward-sexp
   To move forward over a balanced expression, use @kbd{C-M-f}
 (@code{forward-sexp}).  If the first significant character after point
-is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
-@samp{@{} in C), @kbd{C-M-f} moves past the matching closing
-delimiter.  If the character begins a symbol, string, or number,
-@kbd{C-M-f} moves over that.
+is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C),
+this command moves past the matching closing delimiter.  If the
+character begins a symbol, string, or number, the command moves over
+that.
 
   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
-balanced expression.  The detailed rules are like those above for
-@kbd{C-M-f}, but with directions reversed.  If there are prefix
-characters (single-quote, backquote and comma, in Lisp) preceding the
-expression, @kbd{C-M-b} moves back over them as well.  The balanced
-expression commands move across comments as if they were whitespace,
-in most modes.
-
-  @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
-specified number of times; with a negative argument, it moves in the
-opposite direction.
+balanced expression---like @kbd{C-M-f}, but in the reverse direction.
+If the expression is preceded by any prefix characters (single-quote,
+backquote and comma, in Lisp), the command moves back over them as
+well.
+
+  @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
+the specified number of times; with a negative argument means to move
+in the opposite direction.  In most modes, these two commands move
+across comments as if they were whitespace.  Note that their keys,
+@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
+which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
+@kbd{M-b}, which move by words (@pxref{Words}).
 
 @cindex killing expressions
 @kindex C-M-k
 @findex kill-sexp
-  Killing a whole balanced expression can be done with @kbd{C-M-k}
-(@code{kill-sexp}).  @kbd{C-M-k} kills the characters that @kbd{C-M-f}
-would move over.
+  To kill a whole balanced expression, type @kbd{C-M-k}
+(@code{kill-sexp}).  This kills the text that @kbd{C-M-f} would move
+over.
 
 @cindex transposition of expressions
 @kindex C-M-t
 @findex transpose-sexps
-  A somewhat random-sounding command which is nevertheless handy is
-@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
-balanced expression across the next one.  An argument serves as a
-repeat count, moving the previous expression over that many following
-ones.  A negative argument drags the previous balanced expression
-backwards across those before it (thus canceling out the effect of
-@kbd{C-M-t} with a positive argument).  An argument of zero, rather
-than doing nothing, transposes the balanced expressions ending at or
-after point and the mark.
+  @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
+previous balanced expression and the next one.  It is analogous to the
+@kbd{C-t} command, which transposes characters (@pxref{Transpose}).
+An argument to @kbd{C-M-t} serves as a repeat count, moving the
+previous expression over that many following ones.  A negative
+argument moves the previous balanced expression backwards across those
+before it.  An argument of zero, rather than doing nothing, transposes
+the balanced expressions ending at or after point and the mark.
 
 @kindex C-M-@@
 @kindex C-M-@key{SPC}
 @findex mark-sexp
-  To operate on balanced expressions with an operation which acts on
-the region, use the command @kbd{C-M-@key{SPC}} (@code{mark-sexp}).
-This sets the mark at the same place that @kbd{C-M-f} would move to.
-@xref{Marking Objects}, for more information about this command.
-
-@kbd{C-M-@key{SPC}} treats
-numeric arguments in the same way as @kbd{C-M-f}; in particular, a
-negative argument puts the mark at the beginning of the previous
-balanced expression.  The alias @kbd{C-M-@@} is equivalent to
-@kbd{C-M-@key{SPC}}.  While the mark is active, each successive use of
-@kbd{C-M-@key{SPC}} extends the region by shifting the mark by one
-sexp.
+  To operate on balanced expressions with a command which acts on the
+region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
+mark where @kbd{C-M-f} would move to.  While the mark is active, each
+successive call to this command extends the region by shifting the
+mark by one expression.  Positive or negative numeric arguments move
+the mark forward or backward by the specified number of expressions.
+The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
+@xref{Marking Objects}, for more information about this and related
+commands.
 
   In languages that use infix operators, such as C, it is not possible
-to recognize all balanced expressions as such because there can be
-multiple possibilities at a given position.  For example, C mode does
-not treat @samp{foo + bar} as a single expression, even though it
-@emph{is} one C expression; instead, it recognizes @samp{foo} as one
-expression and @samp{bar} as another, with the @samp{+} as punctuation
-between them.  Both @samp{foo + bar} and @samp{foo} are legitimate
-choices for ``the expression following point'' when point is at the
-@samp{f}, so the expression commands must perforce choose one or the
-other to operate on.  Note that @samp{(foo + bar)} is recognized as a
-single expression in C mode, because of the parentheses.
+to recognize all balanced expressions because there can be multiple
+possibilities at a given position.  For example, C mode does not treat
+@samp{foo + bar} as a single expression, even though it @emph{is} one
+C expression; instead, it recognizes @samp{foo} as one expression and
+@samp{bar} as another, with the @samp{+} as punctuation between them.
+However, C mode recognizes @samp{(foo + bar)} as a single expression,
+because of the parentheses.
 
 @node Moving by Parens
 @subsection Moving in the Parenthesis Structure
@@ -776,19 +743,18 @@ single expression in C mode, because of the parentheses.
 @cindex braces, moving across
 @cindex list commands
 
-  The Emacs commands for handling parenthetical groupings see nothing
-except parentheses (or whatever characters must balance in the
-language you are working with).  They ignore strings and comments
-(including any parentheses within them) and ignore parentheses quoted
-by an escape character.  They are mainly intended for editing
-programs, but can be useful for editing any text that has parentheses.
-They are sometimes called ``list'' commands because in Lisp these
-groupings are lists.
+  The following commands move over groupings delimited by parentheses
+(or whatever else serves as delimiters in the language you are working
+with).  They ignore strings and comments, including any parentheses
+within them, and also ignore parentheses that are ``quoted'' with an
+escape character.  These commands are mainly intended for editing
+programs, but can be useful for editing any text containing
+parentheses.  They are referred to internally as ``list'' commands
+because in Lisp these groupings are lists.
 
-These commands assume that the starting point is not inside a string
-or a comment.  Sometimes you can invoke them usefully from one of
-these places (for example, when you have a parenthesised clause in a
-comment) but this is unreliable.
+  These commands assume that the starting point is not inside a string
+or a comment.  If you invoke them from inside a string or comment, the
+results are unreliable.
 
 @table @kbd
 @item C-M-n
@@ -826,52 +792,62 @@ delimiter, this is nearly the same as searching for a @samp{(}.  An
 argument specifies the number of levels to go down.
 
 @node Matching
-@subsection Automatic Display Of Matching Parentheses
+@subsection Matching Parentheses
 @cindex matching parentheses
 @cindex parentheses, displaying matches
 
-  The Emacs parenthesis-matching feature is designed to show
-automatically how parentheses (and other matching delimiters) match in
-the text.  Whenever you type a self-inserting character that is a
-closing delimiter, the cursor moves momentarily to the location of the
+  Emacs has a number of @dfn{parenthesis matching} features, which
+make it easy to see how and whether parentheses (or other delimiters)
+match up.
+
+  Whenever you type a self-inserting character that is a closing
+delimiter, the cursor moves momentarily to the location of the
 matching opening delimiter, provided that is on the screen.  If it is
 not on the screen, Emacs displays some of the text near it in the echo
 area.  Either way, you can tell which grouping you are closing off.
-
-  If the opening delimiter and closing delimiter are mismatched---such
+If the opening delimiter and closing delimiter are mismatched---such
 as in @samp{[x)}---a warning message is displayed in the echo area.
 
 @vindex blink-matching-paren
 @vindex blink-matching-paren-distance
 @vindex blink-matching-delay
-  Three variables control parenthesis match display:
+  Three variables control the display of matching parentheses:
 
-  @code{blink-matching-paren} turns the feature on or off: @code{nil}
-disables it, but the default is @code{t} to enable match display.
+@itemize @bullet
+@item
+@code{blink-matching-paren} turns the feature on or off: @code{nil}
+disables it, but the default is @code{t} to enable it.
 
-  @code{blink-matching-delay} says how many seconds to leave the
-cursor on the matching opening delimiter, before bringing it back to
-the real location of point; the default is 1, but on some systems it
-is useful to specify a fraction of a second.
+@item
+@code{blink-matching-delay} says how many seconds to leave the cursor
+on the matching opening delimiter, before bringing it back to the real
+location of point.  This may be an integer or floating-point number;
+the default is 1.
 
-  @code{blink-matching-paren-distance} specifies how many characters
+@item
+@code{blink-matching-paren-distance} specifies how many characters
 back to search to find the matching opening delimiter.  If the match
-is not found in that distance, scanning stops, and nothing is displayed.
-This is to prevent the scan for the matching delimiter from wasting
-lots of time when there is no match.  The default is 102400.
+is not found in that distance, Emacs stops scanning and nothing is
+displayed.  The default is 102400.
+@end itemize
 
 @cindex Show Paren mode
 @cindex highlighting matching parentheses
 @findex show-paren-mode
-  Show Paren mode provides a more powerful kind of automatic matching.
-Whenever point is before an opening delimiter or after a closing
-delimiter, both that delimiter and its opposite delimiter are
-highlighted.  Use the command @kbd{M-x show-paren-mode} to enable or
-disable this mode.
-
-  Show Paren mode uses the faces @code{show-paren-match} and
-@code{show-paren-mismatch} to highlight parentheses; you can customize
-them to control how highlighting looks.  @xref{Face Customization}.
+  Show Paren mode, a global minor mode, provides a more powerful kind
+of automatic matching.  Whenever point is before an opening delimiter
+or after a closing delimiter, both that delimiter and its opposite
+delimiter are highlighted.  To toggle Show Paren mode, type @kbd{M-x
+show-paren-mode}.
+
+@cindex Electric Pair mode
+@cindex inserting matching parentheses
+@findex electric-pair-mode
+  Electric Pair mode, a global minor mode, provides a way to easily
+insert matching delimiters.  Whenever you insert an opening delimiter,
+the matching closing delimiter is automatically inserted as well,
+leaving point between the two.  To toggle Electric Pair mode, type
+@kbd{M-x electric-pair-mode}.
 
 @node Comments
 @section Manipulating Comments
@@ -882,6 +858,23 @@ provides special commands for editing and inserting comments.  It can
 also do spell checking on comments with Flyspell Prog mode
 (@pxref{Spelling}).
 
+  Some major modes have special rules for indenting different kinds of
+comments.  For example, in Lisp code, comments starting with two
+semicolons are indented as if they were lines of code, while those
+starting with three semicolons are supposed to be aligned to the left
+margin and are often used for sectioning purposes.  Emacs understand
+these conventions; for instance, typing @key{TAB} on a comment line
+will indent the comment to the appropriate position.
+
+@example
+;; This function is just an example.
+;;; Here either two or three semicolons are appropriate.
+(defun foo (x)
+;;;  And now, the first part of the function:
+  ;; The following line adds one.
+  (1+ x))           ; This line adds one.
+@end example
+
 @menu
 * Comment Commands::    Inserting, killing, and aligning comments.
 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
@@ -893,12 +886,12 @@ also do spell checking on comments with Flyspell Prog mode
 @cindex indentation for comments
 @cindex alignment for comments
 
-  The commands in this table insert, kill and align comments:
+  The following commands operate on comments:
 
 @table @asis
 @item @kbd{M-;}
-Insert or realign comment on current line; alternatively, comment or
-uncomment the region (@code{comment-dwim}).
+Insert or realign comment on current line; if the region is active,
+comment or uncomment the region instead (@code{comment-dwim}).
 @item @kbd{C-u M-;}
 Kill comment on current line (@code{comment-kill}).
 @item @kbd{C-x ;}
@@ -909,7 +902,7 @@ Like @key{RET} followed by inserting and aligning a comment
 (@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
 @item @kbd{M-x comment-region}
 @itemx @kbd{C-c C-c} (in C-like modes)
-Add or remove comment delimiters on all the lines in the region.
+Add comment delimiters to all the lines in the region.
 @end table
 
 @kindex M-;
@@ -920,65 +913,61 @@ I Mean''; it indicates that this command can be used for many
 different jobs relating to comments, depending on the situation where
 you use it.
 
-  When a region is active, @kbd{M-;} either adds or removes comment
-delimiters on each line of the region.  @xref{Mark}.  If every line in
-the region is a comment, it removes comment delimiters from each;
-otherwise, it adds comment delimiters to each.  You can also use the
-commands @code{comment-region} and @code{uncomment-region} to
-explicitly comment or uncomment the text in the region
-(@pxref{Multi-Line Comments}).  If you supply a prefix argument to
-@kbd{M-;} when a region is active, that specifies how many comment
-delimiters to add or how many to delete.
-
-  If the region is not active, @kbd{M-;} inserts a new comment if
-there is no comment already on the line.  The new comment is normally
-aligned at a specific column called the @dfn{comment column}; if the
-text of the line extends past the comment column, @kbd{M-;} aligns the
-comment start string to a suitable boundary (usually, at least one
-space is inserted).  The comment begins with the string Emacs thinks
-comments should start with (the value of @code{comment-start}; see
-below).  Emacs places point after that string, so you can insert the
-text of the comment right away.  If the major mode has specified a
-string to terminate comments, @kbd{M-;} inserts that string after
-point, to keep the syntax valid.
+  When a region is active (@pxref{Mark}), @kbd{M-;} either adds
+comment delimiters to the region, or removes them.  If every line in
+the region is already a comment, it ``uncomments'' each of those lines
+by removing their comment delimiters.  Otherwise, it adds comment
+delimiters to enclose the text in the region.
+
+  If you supply a prefix argument to @kbd{M-;} when a region is
+active, that specifies the number of comment delimiters to add or
+delete.  A positive argument @var{n} adds @var{n} delimiters, while a
+negative argument @var{-n} removes @var{n} delimiters.
+
+  If the region is not active, and there is no existing comment on the
+current line, @kbd{M-;} adds a new comment to the current line.  If
+the line is blank (i.e.@: empty or containing only whitespace
+characters), the comment is indented to the same position where
+@key{TAB} would indent to (@pxref{Basic Indent}).  If the line is
+non-blank, the comment is placed after the last non-whitespace
+character on the line; normally, Emacs tries putting it at the column
+specified by the variable @code{comment-column} (@pxref{Options for
+Comments}), but if the line already extends past that column, it puts
+the comment at some suitable position, usually separated from the
+non-comment text by at least one space.  In each case, Emacs places
+point after the comment's starting delimiter, so that you can start
+typing the comment text right away.
 
   You can also use @kbd{M-;} to align an existing comment.  If a line
 already contains the comment-start string, @kbd{M-;} realigns it to
-the conventional alignment and moves point after it.  (Exception:
-comments starting in column 0 are not moved.)  Even when an existing
-comment is properly aligned, @kbd{M-;} is still useful for moving
-directly to the start of the text inside the comment.
+the conventional alignment and moves point after the comment's
+starting delimiter.  As an exception, comments starting in column 0
+are not moved.  Even when an existing comment is properly aligned,
+@kbd{M-;} is still useful for moving directly to the start of the
+comment text.
 
 @findex comment-kill
 @kindex C-u M-;
-  @kbd{C-u M-;} kills any comment on the current line, along with the
-whitespace before it.  To reinsert the comment on another line, move
-to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
-realign it.
-
-  Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
-(@code{comment-dwim}) with a prefix argument.  That command is
-programmed so that when it receives a prefix argument it calls
-@code{comment-kill}.  However, @code{comment-kill} is a valid command
-in its own right, and you can bind it directly to a key if you wish.
-
-  Some major modes have special rules for aligning certain kinds of
-comments in certain contexts.  For example, in Lisp code, comments which
-start with two semicolons are indented as if they were lines of code,
-instead of at the comment column.  Comments which start with three
-semicolons are supposed to start at the left margin and are often used
-for sectioning purposes.  Emacs understands
-these conventions by indenting a double-semicolon comment using @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
+  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
+comment on the current line, along with the whitespace before it.
+Since the comment is saved to the kill ring, you can reinsert it on
+another line by moving to the end of that line, doing @kbd{C-y}, and
+then @kbd{M-;} to realign the command.  You can achieve the same
+effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
+(@code{comment-dwim} actually calls @code{comment-kill} as a
+subroutine when it is given a prefix argument).
 
-@example
-;; This function is just an example.
-;;; Here either two or three semicolons are appropriate.
-(defun foo (x)
-;;;  And now, the first part of the function:
-  ;; The following line adds one.
-  (1+ x))           ; This line adds one.
-@end example
+@kindex C-c C-c (C mode)
+@findex comment-region
+@findex uncomment-region
+  The command @kbd{M-x comment-region} is equivalent to calling
+@kbd{M-;} on an active region, except that it always acts on the
+region, even if the mark is inactive.  In C mode and related modes,
+this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
+uncomment-region} uncomments each line in the region; a numeric prefix
+argument specifies the number of comment delimiters to remove
+(negative arguments specify the number of comment to delimiters to
+add).
 
   For C-like modes, you can configure the exact effect of @kbd{M-;} by
 setting the variables @code{c-indent-comment-alist} and
@@ -994,32 +983,31 @@ the brace rather than at @code{comment-column}.  For full details see
 @kindex M-j
 @cindex blank lines in programs
 @findex comment-indent-new-line
-
-  If you are typing a comment and wish to continue it on another line,
-you can use the command @kbd{C-M-j} or @kbd{M-j}
-(@code{comment-indent-new-line}).  If @code{comment-multi-line}
-(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
-line within the comment.  Otherwise it closes the comment and starts a
-new comment on a new line.  When Auto Fill mode is on, going past the
-fill column while typing a comment causes the comment to be continued
-in just this fashion.
-
-@kindex C-c C-c (C mode)
-@findex comment-region
-  To turn existing lines into comment lines, use the @kbd{M-x
-comment-region} command (or type @kbd{C-c C-c} in C-like modes).  It
-adds comment delimiters to the lines that start in the region, thus
-commenting them out.  With a negative argument, it does the
-opposite---it deletes comment delimiters from the lines in the region.
-
-  With a positive argument, @code{comment-region} duplicates the last
-character of the comment start sequence it adds; the argument
-specifies how many copies of the character to insert.  Thus, in Lisp
-mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.
-Duplicating the comment delimiter is a way of calling attention to the
-comment.  It can also affect how the comment is aligned or indented.
-In Lisp, for proper indentation, you should use an argument of two or
-three, if between defuns; if within a defun, it must be three.
+@vindex comment-multi-line
+  If you are typing a comment and wish to continue it to another line,
+type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}).  This
+breaks the current line, and inserts the necessary comment delimiters
+and indentation to continue the comment.
+
+  For languages with closing comment delimiters (e.g.@: @samp{*/} in
+C), the exact behavior of @kbd{M-j} depends on the value of the
+variable @code{comment-multi-line}.  If the value is @code{nil}, the
+command closes the comment on the old line and starts a new comment on
+the new line.  Otherwise, it opens a new line within the current
+comment delimiters.
+
+  When Auto Fill mode is on, going past the fill column while typing a
+comment also continues the comment, in the same way as an explicit
+invocation of @kbd{M-j}.
+
+  To turn existing lines into comment lines, use @kbd{M-;} with the
+region active, or use @kbd{M-x comment-region}
+@ifinfo
+(@pxref{Comment Commands}).
+@end ifinfo
+@ifnotinfo
+as described in the preceding section.
+@end ifnotinfo
 
   You can configure C Mode such that when you type a @samp{/} at the
 start of a line in a multi-line block comment, this closes the
@@ -1032,19 +1020,16 @@ comment.  Enable the @code{comment-close-slash} clean-up for this.
 @vindex comment-column
 @kindex C-x ;
 @findex comment-set-column
-  The @dfn{comment column}, the column at which Emacs tries to place
-comments, is stored in the variable @code{comment-column}.  You can
-set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
-(@code{comment-set-column}) sets the comment column to the column
-point is at.  @kbd{C-u C-x ;} sets the comment column to match the
-last comment before point in the buffer, and then does a @kbd{M-;} to
-align the current line's comment under the previous one.
-
-  The variable @code{comment-column} is per-buffer: setting the variable
-in the normal fashion affects only the current buffer, but there is a
-default value which you can change with @code{setq-default}.
-@xref{Locals}.  Many major modes initialize this variable for the
-current buffer.
+  As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
+adds a comment to a line, it tries to place the comment at the column
+specified by the buffer-local variable @code{comment-column}.  You can
+set either the local value or the default value of this buffer-local
+variable in the usual way (@pxref{Locals}).  Alternatively, you can
+type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
+@code{comment-column} in the current buffer to the column where point
+is currently located.  @kbd{C-u C-x ;} sets the comment column to
+match the last comment before point in the buffer, and then does a
+@kbd{M-;} to align the current line's comment under the previous one.
 
 @vindex comment-start-skip
   The comment commands recognize comments based on the regular
@@ -1053,39 +1038,32 @@ Make sure this regexp does not match the null string.  It may match more
 than the comment starting delimiter in the strictest sense of the word;
 for example, in C mode the value of the variable is
 @c This stops M-q from breaking the line inside that @code.
-@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
-after the @samp{/*} itself, and accepts C++ style comments also.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax.  @xref{Regexp Backslash}.)
+@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
+spaces after the @samp{/*} itself, and accepts C++ style comments
+also.  (Note that @samp{\\} is needed in Lisp syntax to include a
+@samp{\} in the string, which is needed to deny the first star its
+special meaning in regexp syntax.  @xref{Regexp Backslash}.)
 
 @vindex comment-start
 @vindex comment-end
   When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it.  The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will
-insert into the comment.  When @code{comment-end} is non-empty, it
-should start with a space.  For example, in C mode,
-@code{comment-start} has the value @w{@code{"/* "}} and
-@code{comment-end} has the value @w{@code{" */"}}.
+@code{comment-start} as an opening comment delimiter.  It also inserts
+the value of @code{comment-end} after point, as a closing comment
+delimiter.  For example, in Lisp mode, @code{comment-start} is
+@samp{";"} and @code{comment-end} is @code{""} (the empty string).  In
+C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
+@code{" */"}.
 
 @vindex comment-padding
-  The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the comment
-delimiter and the line's original text.  The default is 1, to insert
-one space.  @code{nil} means 0.  Alternatively, @code{comment-padding}
-can hold the actual string to insert.
+  The variable @code{comment-padding} specifies a string that the
+commenting commands should insert between the comment delimiter(s) and
+the comment text.  The default, @samp{" "}, specifies a single space.
+Alternatively, the value can be a number, which specifies that number
+of spaces, or @code{nil}, which means no spaces at all.
 
-@vindex comment-multi-line
-  The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment.
-Specifically, when @code{comment-multi-line} is @code{nil}, the
-command inserts a comment terminator, begins a new line, and finally
-inserts a comment starter.  Otherwise it does not insert the
-terminator and starter, so it effectively continues the current
-comment across multiple lines.  In languages that allow multi-line
-comments, the choice of value for this variable is a matter of taste.
-The default for this variable depends on the major mode.
+  The variable @code{comment-multi-line} controls how @kbd{M-j} and
+Auto Fill mode continue comments over multiple lines.
+@xref{Multi-Line Comments}.
 
 @vindex comment-indent-function
   The variable @code{comment-indent-function} should contain a function
@@ -1139,7 +1117,7 @@ mode which @kbd{C-h S} does support.
 @node Man Page
 @subsection Man Page Lookup
 
-@cindex manual page
+@cindex man page
   On Unix, the main form of on-line documentation was the @dfn{manual
 page} or @dfn{man page}.  In the GNU operating system, we aim to
 replace man pages with better-organized manuals that you can browse
@@ -1148,71 +1126,51 @@ still useful to read manual pages.
 
 @findex manual-entry
   You can read the man page for an operating system command, library
-function, or system call, with the @kbd{M-x man} command.  It
-runs the @code{man} program to format the man page; if the system
-permits, it runs @code{man} asynchronously, so that you can keep on
-editing while the page is being formatted.  (On MS-DOS and MS-Windows
-3, you cannot edit while Emacs waits for @code{man} to finish.)  The
-result goes in a buffer named @samp{*Man @var{topic}*}.  These buffers
-use a special major mode, Man mode, that facilitates scrolling and
-jumping to other manual pages.  For details, type @kbd{C-h m} while in
-a man page buffer.
+function, or system call, with the @kbd{M-x man} command.  This
+prompts for a topic, with completion (@pxref{Completion}), and runs
+the @command{man} program to format the corresponding man page.  If
+the system permits, it runs @command{man} asynchronously, so that you
+can keep on editing while the page is being formatted.  The result
+goes in a buffer named @samp{*Man @var{topic}*}.  These buffers use a
+special major mode, Man mode, that facilitates scrolling and jumping
+to other manual pages.  For details, type @kbd{C-h m} while in a Man
+mode buffer.
 
 @cindex sections of manual pages
   Each man page belongs to one of ten or more @dfn{sections}, each
-named by a digit or by a digit and a letter.  Sometimes there are
-multiple man pages with the same name in different sections.  To read
-a man page from a specific section, type
-@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
-when @kbd{M-x manual-entry} prompts for the topic.  For example, to
-read the man page for the C library function @code{chmod} (as opposed
-to a command of the same name), type @kbd{M-x manual-entry @key{RET}
-chmod(2) @key{RET}}.  (@code{chmod} is a system call, so it is in
-section @samp{2}.)
+named by a digit or by a digit and a letter.  Sometimes there are man
+pages with the same name in different sections.  To read a man page
+from a specific section, type @samp{@var{topic}(@var{section})} or
+@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
+for the topic.  For example, the man page for the C library function
+@code{chmod} is in section 2, but there is a shell command of the same
+name, whose man page is in section 1; to view the former, type
+@kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}.
 
 @vindex Man-switches
-  If you do not specify a section, the results depend on how the
-@code{man} program works on your system.  Some of them display only
-the first man page they find.  Others display all man pages that have
-the specified name, so you can move between them with the @kbd{M-n}
-and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
-accepts a @samp{-a} command-line option which tells it to display all
-the man pages for the specified topic.  If you want this behavior, you
-can add this option to the value of the variable @code{Man-switches}.}.
-The mode line shows how many manual pages are present in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
-  By default, Emacs highlights the text in man pages.  For a long man
-page, highlighting can take substantial time.  You can turn off
-highlighting of man pages by setting the variable
-@code{Man-fontify-manpage-flag} to @code{nil}.
-
-@findex Man-fontify-manpage
-  If you insert the text of a man page into an Emacs buffer in some
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
+@kindex M-n @r{(Man mode)}
+@kindex M-p @r{(Man mode)}
+  If you do not specify a section, @kbd{M-x man} normally displays
+only the first man page found.  On some systems, the @code{man}
+program accepts a @samp{-a} command-line option, which tells it to
+display all the man pages for the specified topic.  To make use of
+this, change the value of the variable @code{Man-switches} to
+@samp{"-a"}.  Then, in the Man mode buffer, you can type @kbd{M-n} and
+@kbd{M-p} to switch between man pages in different sections.  The mode
+line shows how many manual pages are available.
 
 @findex woman
 @cindex manual pages, on MS-DOS/MS-Windows
   An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man,'' since it doesn't use the @code{man}
-program.}.  Unlike @kbd{M-x man}, it does not run any external
-programs to format and display the man pages; instead it does the job
-in Emacs Lisp, so it works on systems such as MS-Windows, where the
-@code{man} program (and other programs it uses) are not generally
-available.
-
-  @kbd{M-x woman} prompts for a name of a manual page, and provides
-completion based on the list of manual pages that are installed on
-your machine; the list of available manual pages is computed
-automatically the first time you invoke @code{woman}.  The word at
-point in the current buffer is used to suggest the default for the
-name of the manual page.
-
-  With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion.  This is useful if you add or delete
-manual pages.
+command.  Unlike @kbd{M-x man}, it does not run any external programs
+to format and display the man pages; the formatting is done by Emacs,
+so it works on systems such as MS-Windows where the @command{man}
+program may be unavailable.  It prompts for a man page, and displays
+it in a buffer named @samp{*WoMan @var{section} @var{topic}}.
+
+  @kbd{M-x woman} computes the completion list for manpages the first
+time you invoke the command.  With a numeric argument, it recomputes
+this list; this is useful if you add or delete manual pages.
 
   If you type a name of a manual page and @kbd{M-x woman} finds that
 several manual pages by the same name exist in different sections, it
@@ -1220,48 +1178,51 @@ pops up a window with possible candidates asking you to choose one of
 them.
 
   For more information about setting up and using @kbd{M-x woman}, see
-@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
-Manual}.
+@ifinfo
+@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
+WoMan Manual}.
+@end ifinfo
+@ifnotinfo
+the WoMan Info manual, which is distributed with Emacs.
+@end ifnotinfo
 
 @node Lisp Doc
 @subsection Emacs Lisp Documentation Lookup
 
-  As you edit Lisp code to be run in Emacs, you can use the commands
-@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
-(@code{describe-variable}) to view documentation of functions and
-variables that you want to use.  These commands use the minibuffer to
-read the name of a function or variable to document, and display the
-documentation in a window.  Their default arguments are based on the
-code in the neighborhood of point.  For @kbd{C-h f}, the default is
-the function called in the innermost list containing point.  @kbd{C-h
-v} uses the symbol name around or adjacent to point as its default.
+  When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
+(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
+to view the built-in documentation for the Lisp functions and
+variables that you want to use.  @xref{Name Help}.
 
 @cindex Eldoc mode
 @findex eldoc-mode
-  A more automatic but less powerful method is Eldoc mode.  This minor
-mode constantly displays in the echo area the argument list for the
-function being called at point.  (In other words, it finds the
-function call that point is contained in, and displays the argument
-list of that function.)  If point is over a documented variable, it
-shows the first line of the variable's docstring.  Eldoc mode applies
-in Emacs Lisp and Lisp Interaction modes, and perhaps a few others
-that provide special support for looking up doc strings.  Use the
-command @kbd{M-x eldoc-mode} to enable or disable this feature.
+  Eldoc is a buffer-local minor mode that helps with looking up Lisp
+documention.  When it is enabled, the echo area displays some useful
+information whenever there is a Lisp function or variable at point;
+for a function, it shows the argument list, and for a variable it
+shows the first line of the variable's documentation string.  To
+toggle Eldoc mode, type @kbd{M-x eldoc-mode}.  Eldoc mode can be used
+with the Emacs Lisp and Lisp Interaction major modes.
 
 @node Hideshow
 @section Hideshow minor mode
+@cindex Hideshow mode
+@cindex mode, Hideshow
 
 @findex hs-minor-mode
-  Hideshow minor mode provides selective display of portions of a
-program, known as @dfn{blocks}.  You can use @kbd{M-x hs-minor-mode}
-to enable or disable this mode, or add @code{hs-minor-mode} to the
-mode hook for certain major modes in order to enable it automatically
-for those modes.
+  Hideshow mode is a buffer-local minor mode that allows you to
+selectively display portions of a program, which are referred to as
+@dfn{blocks}.  Type @kbd{M-x hs-minor-mode} to toggle this minor mode
+(@pxref{Minor Modes}).
+
+  When you use Hideshow mode to hide a block, the block disappears
+from the screen, to be replaced by an ellipsis (three periods in a
+row).  Just what constitutes a block depends on the major mode.  In C
+mode and related modes, blocks are delimited by braces, while in Lisp
+mode they are delimited by parentheses.  Multi-line comments also
+count as blocks.
 
-  Just what constitutes a block depends on the major mode.  In C mode
-or C++ mode, they are delimited by braces, while in Lisp mode and
-similar modes they are delimited by parentheses.  Multi-line comments
-also count as blocks.
+  Hideshow mode provides the following commands:
 
 @findex hs-hide-all
 @findex hs-hide-block
@@ -1285,11 +1246,11 @@ Show the current block (@code{hs-show-block}).
 @item C-c @@ C-c
 Either hide or show the current block (@code{hs-toggle-hiding}).
 @item S-Mouse-2
-Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}).
+Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
 @item C-c @@ C-M-h
 Hide all top-level blocks (@code{hs-hide-all}).
 @item C-c @@ C-M-s
-Show everything in the buffer (@code{hs-show-all}).
+Show all blocks in the buffer (@code{hs-show-all}).
 @item C-c @@ C-l
 Hide all blocks @var{n} levels below this block
 (@code{hs-hide-level}).
@@ -1298,80 +1259,55 @@ Hide all blocks @var{n} levels below this block
 @vindex hs-hide-comments-when-hiding-all
 @vindex hs-isearch-open
 @vindex hs-special-modes-alist
-  These variables exist for customizing Hideshow mode.
+  These variables can be used to customize Hideshow mode:
 
 @table @code
 @item hs-hide-comments-when-hiding-all
-Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
+If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
+comments too.
 
 @item hs-isearch-open
-Specifies what kind of hidden blocks incremental search should make
-visible.  The value should be one of these four symbols:
-
-@table @code
-@item code
-Open only code blocks.
-@item comment
-Open only comments.
-@item t
-Open both code blocks and comments.
-@item nil
-Open neither code blocks nor comments.
-@end table
-
-@item hs-special-modes-alist
-A list of elements, each specifying how to initialize Hideshow
-variables for one major mode.  See the variable's documentation string
-for more information.
+This variable specifies the conditions under which incremental search
+should unhide a hidden block when matching text occurs within the
+block.  Its value should be either @code{code} (unhide only code
+blocks), @code{comment} (unhide only comments), @code{t} (unhide both
+code blocks and comments), or @code{nil} (unhide neither code blocks
+nor comments).  The default value is @code{code}.
 @end table
 
 @node Symbol Completion
 @section Completion for Symbol Names
 @cindex completion (symbol names)
 
-  In Emacs, completion is something you normally do in the minibuffer
-(@pxref{Completion}).  But one kind of completion is available in all
-buffers: completion for symbol names.
+  Completion is normally done in the minibuffer (@pxref{Completion}),
+but you can also complete symbol names in ordinary Emacs buffers.
 
 @kindex M-TAB
-  The character @kbd{M-@key{TAB}} runs a command to complete the
-partial symbol before point against the set of meaningful symbol
-names.  This command inserts at point any additional characters that
-it can determine from the partial name.
-
-  If your window manager defines @kbd{M-@key{TAB}} to switch windows,
-you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead.
-However, most window managers let you customize these shortcuts, so
-you can change any that interfere with the way you use Emacs.
-
-  If the partial name in the buffer has multiple possible completions
-that differ in the very next character, so that it is impossible to
-complete even one more character, @kbd{M-@key{TAB}} displays a list of
-all possible completions in another window.
+@kindex C-M-i
+  In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
+to complete the partial symbol before point.  On graphical displays,
+the @kbd{M-@key{TAB}} key is usually reserved by the window manager
+for switching graphical windows, so you should type @kbd{C-M-i} or
+@kbd{@key{ESC} @key{TAB}} instead.
 
 @cindex tags-based completion
-@cindex Info index completion
-@findex complete-symbol
-  In most programming language major modes, @kbd{M-@key{TAB}} runs the
-command @code{complete-symbol}, which provides two kinds of completion.
-Normally it does completion based on a tags table (@pxref{Tags}); with a
-numeric argument (regardless of the value), it does completion based on
-the names listed in the Info file indexes for your language.  Thus, to
-complete the name of a symbol defined in your own program, use
-@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
-library function, use @kbd{C-u M-@key{TAB}}.  Of course, Info-based
-completion works only if there is an Info file for the standard library
-functions of your language, and only if it is installed at your site.
-
+@findex completion-at-point
 @cindex Lisp symbol completion
 @cindex completion (Lisp symbols)
-@findex lisp-complete-symbol
-  In Emacs-Lisp mode, the name space for completion normally consists of
-nontrivial symbols present in Emacs---those that have function
-definitions, values or properties.  However, if there is an
-open-parenthesis immediately before the beginning of the partial symbol,
-only symbols with function definitions are considered as completions.
-The command which implements this is @code{lisp-complete-symbol}.
+  In most programming language modes, @kbd{C-M-i} (or
+@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
+which generates its completion list in a flexible way.  If Semantic
+mode is enabled, it tries to use the Semantic parser data for
+completion (@pxref{Semantic}).  If Semantic mode is not enabled or
+fails at performing completion, it tries to complete using the
+selected tags table (@pxref{Tags}).  If in Emacs Lisp mode, it
+performs completion using the function, variable, or property names
+defined in the current Emacs session.
+
+  In all other respects, in-buffer symbol completion behaves like
+minibuffer completion.  For instance, if Emacs cannot complete to a
+unique symbol, it displays a list of completion alternatives in
+another window.  @xref{Completion}.
 
   In Text mode and related modes, @kbd{M-@key{TAB}} completes words
 based on the spell-checker's dictionary.  @xref{Spelling}.
@@ -1379,20 +1315,20 @@ based on the spell-checker's dictionary.  @xref{Spelling}.
 @node Glasses
 @section Glasses minor mode
 @cindex Glasses mode
-@cindex identifiers, making long ones readable
-@cindex StudlyCaps, making them readable
-@findex glasses-mode
-
-  Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
-readable by altering the way they display.  It knows two different
-ways to do this: by displaying underscores between a lower-case letter
-and the following capital letter, and by emboldening the capital
-letters.  It does not alter the buffer text, only the way they
-display, so you can use it even on read-only buffers.  You can use the
-command @kbd{M-x glasses-mode} to enable or disable the mode in the
-current buffer; you can also add @code{glasses-mode} to the mode hook
-of the programming language major modes in which you normally want
-to use Glasses mode.
+@cindex camel case
+@findex mode, Glasses
+
+  Glasses mode is a buffer-local minor mode that makes it easier to
+read mixed-case (or ``CamelCase'') symbols like
+@samp{unReadableSymbol}, by altering how they are displayed.  By
+default, it displays extra underscores between each lower-case letter
+and the following capital letter.  This does not alter the buffer
+text, only how it is displayed.
+
+  To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
+Modes}).  When Glasses mode is enabled, the minor mode indicator
+@samp{o^o} appears in the mode line.  For more information about
+Glasses mode, type @kbd{C-h P glasses @key{RET}}.
 
 @node Semantic
 @section Semantic
@@ -1400,23 +1336,24 @@ to use Glasses mode.
 
 Semantic is a package that provides language-aware editing commands
 based on @code{source code parsers}.  This section provides a brief
-description of Semantic;
+description of Semantic; for full details,
 @ifnottex
-for full details, see @ref{Top, Semantic,, semantic, Semantic}.
+see @ref{Top, Semantic,, semantic, Semantic}.
 @end ifnottex
 @iftex
-for full details, type @kbd{C-h i} (@code{info}) and then select the
-Semantic manual.
+see the Semantic Info manual, which is distributed with Emacs.
 @end iftex
 
-  Most of the ``language aware'' features in Emacs, such as font lock
-(@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
+  Most of the ``language aware'' features in Emacs, such as Font Lock
+mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
 expressions and syntax tables.} that usually give good results but are
 never completely exact.  In contrast, the parsers used by Semantic
 have an exact understanding of programming language syntax.  This
 allows Semantic to provide search, navigation, and completion commands
 that are powerful and precise.
 
+@cindex Semantic mode
+@cindex mode, Semantic
   To begin using Semantic, type @kbd{M-x semantic-mode} or click on
 the menu item named @samp{Source Code Parsers (Semantic)} in the
 @samp{Tools} menu.  This enables Semantic mode, a global minor mode.
@@ -1464,30 +1401,30 @@ is idle.
 @node Misc for Programs
 @section Other Features Useful for Editing Programs
 
-  A number of Emacs commands that aren't designed specifically for
-editing programs are useful for that nonetheless.
+  Some Emacs commands that aren't designed specifically for editing
+programs are useful for that nonetheless.
 
   The Emacs commands that operate on words, sentences and paragraphs
 are useful for editing code.  Most symbols names contain words
-(@pxref{Words}); sentences can be found in strings and comments
-(@pxref{Sentences}).  Paragraphs in the strict sense can be found in
-program code (in long comments), but the paragraph commands are useful
-in other places too, because programming language major modes define
-paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
-Judicious use of blank lines to make the program clearer will also
-provide useful chunks of text for the paragraph commands to work on.
-Auto Fill mode, if enabled in a programming language major mode,
-indents the new lines which it creates.
-
-  The selective display feature is useful for looking at the overall
-structure of a function (@pxref{Selective Display}).  This feature
-hides the lines that are indented more than a specified amount.
-Programming modes often support Outline minor mode (@pxref{Outline
-Mode}).  The Foldout package provides folding-editor features
-(@pxref{Foldout}).
-
+(@pxref{Words}), while sentences can be found in strings and comments
+(@pxref{Sentences}).  As for paragraphs, they are defined in most
+programming language modes to begin and end at blank lines
+(@pxref{Paragraphs}).  Therefore, judicious use of blank lines to make
+the program clearer will also provide useful chunks of text for the
+paragraph commands to work on.  Auto Fill mode, if enabled in a
+programming language major mode, indents the new lines which it
+creates.
+
+  Apart from Hideshow mode (@pxref{Hideshow}), another way to
+selectively display parts of a program is to use the selective display
+feature (@pxref{Selective Display}).  Programming modes often also
+support Outline minor mode (@pxref{Outline Mode}), which can be used
+with the Foldout package (@pxref{Foldout}).
+
+@ifinfo
   The ``automatic typing'' features may be useful for writing programs.
 @xref{Top,,Autotyping, autotype, Autotyping}.
+@end ifinfo
 
 @node C Modes
 @section C and Related Modes
@@ -1509,9 +1446,14 @@ Mode}).  The Foldout package provides folding-editor features
 
   This section gives a brief description of the special features
 available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
-(These are called ``C mode and related modes.'')  @xref{Top, , CC Mode,
-ccmode, CC Mode}, for a more extensive description of these modes
-and their special features.
+(These are called ``C mode and related modes.'')
+@ifinfo
+@xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
+@end ifinfo
+@ifnotinfo
+For more details, see the CC mode Info manual, which is distributed
+with Emacs.
+@end ifnotinfo
 
 @menu
 * Motion in C::                 Commands to move by C statements, etc.
@@ -1528,17 +1470,17 @@ and their special features.
 related modes.
 
 @table @code
-@item M-x c-beginning-of-defun
-@itemx M-x c-end-of-defun
+@item C-M-a
+@itemx C-M-e
 @findex c-beginning-of-defun
 @findex c-end-of-defun
 Move point to the beginning or end of the current function or
-top-level definition.  These are found by searching for the least
+top-level definition.  In languages with enclosing scopes (such as
+C++'s classes) the @dfn{current function} is the immediate one,
+possibly inside a scope.  Otherwise it is the one defined by the least
 enclosing braces.  (By contrast, @code{beginning-of-defun} and
-@code{end-of-defun} search for braces in column zero.)  If you are
-editing code where the opening brace of a function isn't placed in
-column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
-these commands.  @xref{Moving by Defuns}.
+@code{end-of-defun} search for braces in column zero.)  @xref{Moving
+by Defuns}.
 
 @item C-c C-u
 @kindex C-c C-u @r{(C mode)}
diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi
index 0df4a3a7bb5..d05af468fa1 100644
--- a/doc/emacs/rmail.texi
+++ b/doc/emacs/rmail.texi
@@ -1340,17 +1340,18 @@ included in GNU mailutils (the ``mailutils version,''
 command line syntax and the same basic subset of options.  However, the
 Mailutils version offers additional features.
 
-  The Emacs version of @code{movemail} is able to retrieve mail from the
-usual UNIX mailbox formats and from remote mailboxes using the POP3
-protocol.
+  The Emacs version of @code{movemail} is able to retrieve mail from
+the usual Unix mailbox formats and from remote mailboxes using the
+POP3 protocol.
 
   The Mailutils version is able to handle a wide set of mailbox
-formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
-mailboxes, etc.  It is able to access remote mailboxes using the POP3 or
-IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
-channel.  It also accepts mailbox arguments in @acronym{URL} form.
-The detailed description of mailbox @acronym{URL}s can be found in
-@ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a @acronym{URL} is:
+formats, such as plain Unix mailboxes, @code{maildir} and @code{MH}
+mailboxes, etc.  It is able to access remote mailboxes using the POP3
+or IMAP4 protocol, and can retrieve mail from them using a TLS
+encrypted channel.  It also accepts mailbox arguments in @acronym{URL}
+form.  The detailed description of mailbox @acronym{URL}s can be found
+in @ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a
+@acronym{URL} is:
 
 @smallexample
 @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
@@ -1381,9 +1382,9 @@ local mailbox.
 
 @table @code
 @item mbox
-Usual UNIX mailbox format.  In this case, neither @var{user} nor
-@var{pass} are used, and @var{host-or-file-name} denotes the file name of
-the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
+Usual Unix mailbox format.  In this case, neither @var{user} nor
+@var{pass} are used, and @var{host-or-file-name} denotes the file name
+of the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
 
 @item mh
 A local mailbox in the @acronym{MH} format.  @var{User} and
@@ -1524,7 +1525,7 @@ use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
 @section Retrieving Mail from Local Mailboxes in Various Formats
 
   If your incoming mail is stored on a local machine in a format other
-than UNIX mailbox, you will need the Mailutils @code{movemail} to
+than Unix mailbox, you will need the Mailutils @code{movemail} to
 retrieve it.  @xref{Movemail}, for the detailed description of
 @code{movemail} versions.  For example, to access mail from a inbox in
 @code{maildir} format located in @file{/var/spool/mail/in}, you would
diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 8f353961afb..37a85a89ea2 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -21,7 +21,10 @@ are also often useful for editing programs.
 the file contains ordinary text, use Text mode, which customizes Emacs
 in small ways for the syntactic conventions of text.  Outline mode
 provides special commands for operating on text with an outline
-structure.
+structure.  Org mode extends Outline mode and turn Emacs into a
+full-fledged organizer: you can manage TODO lists, store notes and
+publish them in many formats.
+
 @iftex
 @xref{Outline Mode}.
 @end iftex
@@ -32,9 +35,14 @@ structure.
 @findex nxml-mode
   Emacs has other major modes for text which contains ``embedded''
 commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML and
-SGML (@pxref{HTML Mode}); XML (@pxref{Top,The nXML Mode
-Manual,,nxml-mode, nXML Mode}); and Groff and Nroff (@pxref{Nroff
-Mode}).
+SGML (@pxref{HTML Mode}); XML
+@ifinfo
+(@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode});
+@end ifinfo
+@ifnotinfo
+(see the nXML mode Info manual, which is distributed with Emacs);
+@end ifnotinfo
+and Groff and Nroff (@pxref{Nroff Mode}).
 
 @cindex ASCII art
   If you need to edit pictures made out of text characters (commonly
@@ -65,6 +73,7 @@ for editing such pictures.
 * Case::                Changing the case of text.
 * Text Mode::           The major modes for editing text files.
 * Outline Mode::        Editing outlines.
+* Org Mode::            The Emacs organizer.
 * TeX Mode::            Editing input to the formatter TeX.
 * HTML Mode::           Editing HTML and SGML files.
 * Nroff Mode::          Editing input to the formatter nroff.
@@ -1245,6 +1254,143 @@ automatically by putting this in your init file (@pxref{Init File}):
 (eval-after-load "outline" '(require 'foldout))
 @end example
 
+@node Org Mode
+@section Org Mode
+@kindex TAB @r{(Org Mode)}
+@kindex S-TAB @r{(Org Mode)}
+@cindex organizer
+@cindex planner
+@findex org-mode
+@cindex fold
+@cindex headline
+@kindex M-<up> @r{(Org Mode)}
+@kindex M-<down> @r{(Org Mode)}
+@kindex M-<left> @r{(Org Mode)}
+@kindex M-<right> @r{(Org Mode)}
+@kindex S-M-<up> @r{(Org Mode)}
+@kindex S-M-<down> @r{(Org Mode)}
+@kindex S-M-<left> @r{(Org Mode)}
+@kindex S-M-<right> @r{(Org Mode)}
+
+Org mode extends Outline mode to turn Emacs into an organizer and an
+authoring system.
+
+When editing a file ending with the @file{.org} extension, Emacs
+automatically uses @code{org-mode} as the major mode.  In this mode,
+headlines start with one (or more) leading star(s) and comments start
+with the @code{#} character at the beginning of a line.
+
+@example
+* This is the first headline
+** This is a first sub-headline
+* This is the second headline
+
+Some content here.
+
+# Some comment here.
+@end example
+
+From here, you can use Org mode as a simple outliner: @key{TAB} on a
+headline will cycle through the various folding states of a subtree,
+and @key{S-TAB} anywhere in the buffer will (un)fold the whole
+structure.
+
+You can also manipulate the structure of your document by moving a
+headline up and down with @key{M-<up>} and @key{M-<down>}, or by
+promoting and demoting a headline with @key{M-<left>} and
+@key{M-<left>}.  If you want to act on the whole subtree (i.e. the
+headline and its content, including other headlines), simply add the
+@kbd{Shift} key and use @key{S-M-<up>}, @key{S-M-<down>},
+@key{S-M-<left>} and @key{S-M-<right>}.
+
+For further details, see @ref{Document Structure,,,org, The Org Manual}.
+
+@menu
+* Org as an organizer::         Manage TODO lists and agendas
+* Org as an authoring system::  Export to various formats
+@end menu
+
+@node Org as an organizer
+@subsection Org as an organizer
+
+@cindex TODO keywords
+@kindex C-c C-t @r{(Org Mode)}
+@kindex C-c C-s @r{(Org Mode)}
+@kindex C-c C-d @r{(Org Mode)}
+@vindex org-todo-keywords
+@findex org-todo
+@findex org-agenda
+@cindex scheduled
+@cindex deadline
+@cindex agenda
+
+Each headline can be turned into a TODO item calling @code{org-todo}
+with @key{C-c C-t} anywhere on it.  This will add the TODO keyword
+@code{TODO}.  Hit @key{C-c C-t} to cycle through the list of available
+TODO keywords: you can configure the variable @code{org-todo-keywords}
+to use your own list of keywords.
+
+Now that you have something to do, let's add a date to it: pressing
+@key{C-c C-s} on a headline will add @code{SCHEDULED} below it, and
+you will be prompted for a date through the calendar.  @key{C-c C-d}
+has the same effect, except that the item will have a @code{DEADLINE}
+instead.
+
+Now that some TODO items are planned in the current file, add it to
+the list of agenda files with @key{C-c [}.  Calling the interactive
+command @code{org-agenda} will prompt you for what you want to see: a
+list of things to do this week, a list of TODO items with specific
+keywords, etc.
+
+For further details, see @ref{TODO items,,,org, The Org Manual} and
+@ref{Dates and times,,,org, The Org Manual}.
+
+@node Org as an authoring system
+@subsection Org as an authoring system
+@cindex export
+@findex org-export
+@cindex publish
+@cindex code block
+@cindex quote
+
+You may want to format your Org notes nicely and to prepare them for
+export and publication.  Org supports simple text formatting:
+
+@example
+- This text is /emphasized/
+- This item uses *a bold font*
+- This text is _underlined_
+- This text uses =a teletype font=
+@end example
+
+If a paragraph is a quote or an example, you can use specific
+environments:
+
+@example
+#+begin_quote
+``This is a quote.''
+#+end_quote
+
+#+begin_example
+This is an example.
+#+end_example
+@end example
+
+These environments will be displayed in a specific way with respect
+to the selected export/publish backend.
+
+To export the current buffer, press the @key{C-c C-e} key anywhere in
+an Org buffer.  Supported export formats include @code{HTML}, La@TeX{}
+and @file{.odt} (OpenDocument format.)  Depending on your system
+installation, you can also directly export to @code{pdf}.
+
+To export several files at once to a specific directory either locally
+or on the Internet, you will need to define a list of projects through
+the variable @code{org-publish-project-alist}.
+
+For further details, see @ref{Exporting,,,org, The Org Manual} and
+@ref{Publishing,,,org, The Org Manual}.
+
 @node TeX Mode
 @section @TeX{} Mode
 @cindex @TeX{} mode
@@ -1298,8 +1444,8 @@ more information, see the documentation string for the command
 @code{bibtex-mode}.
 
 @item
-The Ref@TeX{} package provides a minor mode which can be used in
-conjunction with La@TeX{} mode to manage bibliographic references.
+The Ref@TeX{} package provides a minor mode which can be used with
+La@TeX{} mode to manage bibliographic references.
 @ifinfo
 @xref{Top,The Ref@TeX{} Manual,,reftex}.
 @end ifinfo
@@ -1764,8 +1910,15 @@ xml-mode}.  Emacs uses nXML mode for files which have the extension
 @file{.xml}.  For XHTML files, which have the extension @file{.xhtml},
 Emacs uses HTML mode by default; you can make it use nXML mode by
 customizing the variable @code{auto-mode-alist} (@pxref{Choosing
-Modes}).  nXML mode is described in its own manual: @xref{Top, nXML
+Modes}).
+@ifinfo
+nXML mode is described in its own manual: @xref{Top, nXML
 Mode,,nxml-mode, nXML Mode}.
+@end ifinfo
+@ifnotinfo
+nXML mode is described in an Info manual, which is distributed with
+Emacs.
+@end ifnotinfo
 
 @vindex sgml-xml-mode
   You may choose to use the less powerful SGML mode for editing XML,
@@ -1781,13 +1934,16 @@ always insert explicit closing tags as well.
 
 @cindex nroff
 @findex nroff-mode
-  Nroff mode is a mode like Text mode but modified to handle nroff commands
-present in the text.  Invoke @kbd{M-x nroff-mode} to enter this mode.  It
-differs from Text mode in only a few ways.  All nroff command lines are
-considered paragraph separators, so that filling will never garble the
-nroff commands.  Pages are separated by @samp{.bp} commands.  Comments
-start with backslash-doublequote.  Also, three special commands are
-provided that are not in Text mode:
+@vindex nroff-mode-hook
+  Nroff mode is a major mode derived from Text mode, which is
+specialized for editing nroff files (e.g.@: Unix man pages).  Type
+@kbd{M-x nroff-mode} to enter this mode.  Entering Nroff mode runs the
+hook @code{text-mode-hook}, followed by @code{nroff-mode-hook}
+(@pxref{Hooks}).
+
+  In Nroff mode, nroff command lines are treated as paragraph
+separators, pages are separated by @samp{.bp} commands, and comments
+start with backslash-doublequote.  It also defines these commands:
 
 @findex forward-text-line
 @findex backward-text-line
@@ -1807,23 +1963,16 @@ nroff commands) in the region (@code{count-text-lines}).
 @end table
 
 @findex electric-nroff-mode
-  The other feature of Nroff mode is that you can turn on Electric Nroff
-mode.  This is a minor mode that you can turn on or off with @kbd{M-x
+  Electric Nroff mode is a buffer-local minor mode that can be used
+with Nroff mode.  To toggle this minor mode, type @kbd{M-x
 electric-nroff-mode} (@pxref{Minor Modes}).  When the mode is on, each
-time you use @key{RET} to end a line that contains an nroff command that
-opens a kind of grouping, the matching nroff command to close that
-grouping is automatically inserted on the following line.  For example,
-if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
-this inserts the matching command @samp{.)b} on a new line following
-point.
+time you type @key{RET} to end a line containing an nroff command that
+opens a kind of grouping, the nroff command to close that grouping is
+automatically inserted on the following line.
 
-  If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
-heading lines are lines of the form @samp{.H} followed by a number (the
-header level).
-
-@vindex nroff-mode-hook
-  Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
-the hook @code{nroff-mode-hook} (@pxref{Hooks}).
+  If you use Outline minor mode with Nroff mode (@pxref{Outline
+Mode}), heading lines are lines of the form @samp{.H} followed by a
+number (the header level).
 
 @node Enriched Text
 @section Enriched Text
@@ -2149,18 +2298,16 @@ hides text), and @code{intangible} (which disallows moving point
 within the text).  The @samp{Remove Special} menu item removes all of
 these special properties from the text in the region.
 
-  The @code{invisible} and @code{intangible} properties are @emph{not}
-saved in the text/enriched format.  The @code{read-only} property is
-saved, but it is not a standard part of the text/enriched format, so
-other editors may not respect it.
+  The @code{invisible} and @code{intangible} properties are not saved
+in the @samp{text/enriched} format.
 
 @node Text Based Tables
 @section Editing Text-based Tables
 @cindex table mode
 @cindex text-based tables
 
-  Table mode provides an easy and intuitive way to create and edit
-text-based tables.  Here is an example of such a table:
+  The @code{table} package provides commands to easily edit text-based
+tables.  Here is an example of what such a table looks like:
 
 @smallexample
 @group
@@ -2170,27 +2317,23 @@ text-based tables.  Here is an example of such a table:
 |  forward-char   |Move point right N characters   |       C-f       |
 |                 |(left if N is negative).        |                 |
 |                 |                                |                 |
-|                 |On reaching end of buffer, stop |                 |
-|                 |and signal error.               |                 |
 +-----------------+--------------------------------+-----------------+
 |  backward-char  |Move point left N characters    |       C-b       |
 |                 |(right if N is negative).       |                 |
 |                 |                                |                 |
-|                 |On attempt to pass beginning or |                 |
-|                 |end of buffer, stop and signal  |                 |
-|                 |error.                          |                 |
 +-----------------+--------------------------------+-----------------+
 @end group
 @end smallexample
 
-  Table mode allows the contents of the table such as this one to be
-easily manipulated by inserting or deleting characters inside a cell.
-A cell is effectively a localized rectangular edit region and edits to
-a cell do not affect the contents of the surrounding cells.  If the
-contents do not fit into a cell, then the cell is automatically
-expanded in the vertical and/or horizontal directions and the rest of
-the table is restructured and reformatted in accordance with the
-growth of the cell.
+  When Emacs recognizes such a stretch of text as a table
+(@pxref{Table Recognition}), editing the contents of each table cell
+will automatically resize the table, whenever the contents become too
+large to fit in the cell.  You can use the commands defined in the
+following sections for navigating and editing the table layout.
+
+@findex table-fixed-width-mode
+  To toggle the automatic table resizing feature, type @kbd{M-x
+table-fixed-width-mode}.
 
 @menu
 * Table Definition::          What is a text based table.
@@ -2198,102 +2341,87 @@ growth of the cell.
 * Table Recognition::         How to activate and deactivate tables.
 * Cell Commands::             Cell-oriented commands in a table.
 * Cell Justification::        Justifying cell contents.
-* Row Commands::              Manipulating rows of table cell.
-* Column Commands::           Manipulating columns of table cell.
-* Fixed Width Mode::          Fixing cell width.
+* Table Rows and Columns::    Inserting and deleting rows and columns.
 * Table Conversion::          Converting between plain text and tables.
-* Measuring Tables::          Analyzing table dimension.
 * Table Misc::                Table miscellany.
 @end menu
 
 @node Table Definition
 @subsection What is a Text-based Table?
+@cindex cells, for text-based tables
 
-  Keep the following examples of valid tables in mind as a reference
-while you read this section:
-
-@example
-              +--+----+---+     +-+     +--+-----+
-              |  |    |   |     | |     |  |     |
-              +--+----+---+     +-+     |  +--+--+
-              |  |    |   |             |  |  |  |
-              +--+----+---+             +--+--+  |
-                                        |     |  |
-                                        +-----+--+
-@end example
-
-  A table consists of a rectangular frame whose inside is divided into
-cells.  Each cell must be at least one character wide and one
-character high, not counting its border lines.  A cell can be
-subdivided into multiple rectangular cells, but cells cannot overlap.
+  A @dfn{table} consists of a rectangular text area which is divided
+into @dfn{cells}.  Each cell must be at least one character wide and
+one character high, not counting its border lines.  A cell can be
+subdivided into more cells, but they cannot overlap.
 
-  The table frame and cell border lines are made of three special
-characters.  These variables specify those characters:
+  Cell border lines are drawn with three special characters, specified
+by the following variables:
 
 @table @code
 @vindex table-cell-vertical-char
 @item table-cell-vertical-char
-Holds the character used for vertical lines.  The default value is
-@samp{|}.
+The character used for vertical lines.  The default is @samp{|}.
 
 @vindex table-cell-horizontal-chars
 @item table-cell-horizontal-chars
-Holds the characters used for horizontal lines.  The default value is
-@samp{"-="}.
+The characters used for horizontal lines.  The default is @samp{"-="}.
 
 @vindex table-cell-intersection-char
 @item table-cell-intersection-char
-Holds the character used at where horizontal line and vertical line
-meet.  The default value is @samp{+}.
+The character used for the intersection of horizontal and vertical
+lines.  The default is @samp{+}.
 @end table
 
 @noindent
-Based on this definition, the following five tables are examples of invalid
-tables:
+The following are examples of @emph{invalid} tables:
 
 @example
-   +-----+    +-----+       +--+    +-++--+    ++
-   |     |    |     |       |  |    | ||  |    ++
-   | +-+ |    |     |       |  |    | ||  |
-   | | | |    +--+  |    +--+--+    +-++--+
-   | +-+ |    |  |  |    |  |  |    +-++--+
-   |     |    |  |  |    |  |  |    | ||  |
-   +-----+    +--+--+    +--+--+    +-++--+
-     a           b          c          d        e
+   +-----+       +--+    +-++--+
+   |     |       |  |    | ||  |
+   |     |       |  |    | ||  |
+   +--+  |    +--+--+    +-++--+
+   |  |  |    |  |  |    +-++--+
+   |  |  |    |  |  |    | ||  |
+   +--+--+    +--+--+    +-++--+
+      a          b          c
 @end example
 
+@noindent
 From left to right:
 
 @enumerate a
 @item
 Overlapped cells or non-rectangular cells are not allowed.
 @item
-Same as a.
-@item
 The border must be rectangular.
 @item
 Cells must have a minimum width/height of one character.
-@item
-Same as d.
 @end enumerate
 
 @node Table Creation
-@subsection How to Create a Table?
+@subsection Creating a Table
 @cindex create a text-based table
 @cindex table creation
 
 @findex table-insert
-  The command to create a table is @code{table-insert}.  When called
-interactively, it asks for the number of columns, number of rows, cell
-width and cell height.  The number of columns is the number of cells
-horizontally side by side.  The number of rows is the number of cells
-vertically within the table's height.  The cell width is a number of
-characters that each cell holds, left to right.  The cell height is a
-number of lines each cell holds.  The cell width and the cell height
-can be either an integer (when the value is constant across the table)
-or a series of integer, separated by spaces or commas, where each
-number corresponds to the next cell within a row from left to right,
-or the next cell within a column from top to bottom.
+  To create a text-based table from scratch, type @kbd{M-x
+table-insert}.  This command prompts for the number of table columns,
+the number of table rows, cell width and cell height.  The cell width
+and cell height do not include the cell borders; each can be specified
+as a single integer (which means each cell is given the same
+width/height), or as a sequence of integers separated by spaces or
+commas (which specify the width/height of the individual table
+columns/rows, counting from left to right for table columns and from
+top to bottom for table rows).  The specified table is then inserted
+at point.
+
+  The table inserted by @kbd{M-x table-insert} contains special text
+properties, which tell Emacs to treat it specially as a text-based
+table.  If you save the buffer to a file and visit it again later,
+those properties are lost, and the table appears to Emacs as an
+ordinary piece of text.  See the next section, for how to convert it
+back into a table.
 
 @node Table Recognition
 @subsection Table Recognition
@@ -2301,103 +2429,97 @@ or the next cell within a column from top to bottom.
 
 @findex table-recognize
 @findex table-unrecognize
-  Table mode maintains special text properties in the buffer to allow
-editing in a convenient fashion.  When a buffer with tables is saved
-to its file, these text properties are lost, so when you visit this
-file again later, Emacs does not see a table, but just formatted text.
-To resurrect the table text properties, issue the @kbd{M-x
-table-recognize} command.  It scans the current buffer, recognizes
-valid table cells, and attaches appropriate text properties to allow
-for table editing.  The converse command, @code{table-unrecognize}, is
-used to remove the special text properties and convert the buffer back
-to plain text.
-
-  Special commands exist to enable or disable tables within a region,
-enable or disable individual tables, and enable/disable individual
-cells.  These commands are:
+  Existing text-based tables in a buffer, which lack the special text
+properties applied by @kbd{M-x table-insert}, are not treated
+specially as tables.  To apply those text properties, type @kbd{M-x
+table-recognize}.  This command scans the current buffer,
+@dfn{recognizes} valid table cells, and applies the relevant text
+properties.  Conversely, type @kbd{M-x table-unrecognize} to
+@dfn{unrecognize} all tables in the current buffer, removing the
+special text properties and converting tables back to plain text.
+
+  You can also use the following commands to selectively recognize or
+unrecognize tables:
 
 @table @kbd
 @findex table-recognize-region
 @item M-x table-recognize-region
-Recognize tables within the current region and activate them.
+Recognize tables within the current region.
+
 @findex table-unrecognize-region
 @item M-x table-unrecognize-region
-Deactivate tables within the current region.
+Unrecognize tables within the current region.
+
 @findex table-recognize-table
 @item M-x table-recognize-table
 Recognize the table at point and activate it.
+
 @findex table-unrecognize-table
 @item M-x table-unrecognize-table
 Deactivate the table at point.
+
 @findex table-recognize-cell
 @item M-x table-recognize-cell
 Recognize the cell at point and activate it.
+
 @findex table-unrecognize-cell
 @item M-x table-unrecognize-cell
 Deactivate the cell at point.
 @end table
 
-  For another way of converting text into tables, see @ref{Table
-Conversion}.
+  @xref{Table Conversion}, for another way to recognize a table.
 
 @node Cell Commands
 @subsection Commands for Table Cells
 
 @findex table-forward-cell
 @findex table-backward-cell
-  The commands @code{table-forward-cell} and
-@code{table-backward-cell} move point from the current cell to an
-adjacent cell forward and backward respectively.  The order of the
-cells is cyclic: when point is in the last cell of a table, typing
-@kbd{M-x table-forward-cell} moves to the first cell in the table.
-Likewise @kbd{M-x table-backward-cell} from the first cell in a table
-moves to the last cell.
+  The commands @kbd{M-x table-forward-cell} and @kbd{M-x
+table-backward-cell} move point from the current cell to an adjacent
+cell.  The order is cyclic: when point is in the last cell of a table,
+@kbd{M-x table-forward-cell} moves to the first cell.  Likewise, when
+point is on the first cell, @kbd{M-x table-backward-cell} moves to the
+last cell.
 
 @findex table-span-cell
-  The command @code{table-span-cell} merges the current cell with the
-adjacent cell in a specified direction---right, left, above or below.
-You specify the direction with the minibuffer.  It does not allow
-merges which don't result in a legitimate cell layout.
+  @kbd{M-x table-span-cell} prompts for a direction---right, left,
+above, or below---and merges the current cell with the adjacent cell
+in that direction.  This command signals an error if the merge would
+result in an illegitimate cell layout.
 
 @findex table-split-cell
-@cindex text-based tables, split a cell
-@cindex split table cell
-  The command @code{table-split-cell} splits the current cell
-vertically or horizontally.  This command is a wrapper to the
-direction specific commands @code{table-split-cell-vertically} and
-@code{table-split-cell-horizontally}.  You specify the direction with
-a minibuffer argument.
-
 @findex table-split-cell-vertically
-  The command @code{table-split-cell-vertically} splits the current
-cell vertically and creates a pair of cells above and below where
-point is located.  The content in the original cell is split as well.
-
 @findex table-split-cell-horizontally
-  The command @code{table-split-cell-horizontally} splits the current
-cell horizontally and creates a pair of cells right and left of where
-point is located.  If the cell being split is not empty, this asks you
-how to handle the cell contents.  The three options are: @code{split},
-@code{left}, or @code{right}.  @code{split} splits the contents at
-point literally, while the @code{left} and @code{right} options move
-the entire contents into the left or right cell respectively.
-
-@cindex enlarge a table cell
-@cindex shrink a table cell
-  The next four commands enlarge or shrink a cell.  They use numeric
-arguments (@pxref{Arguments}) to specify how many columns or rows to
-enlarge or shrink a particular table.
+@cindex text-based tables, splitting cells
+@cindex splitting table cells
+  @kbd{M-x table-split-cell} splits the current cell vertically or
+horizontally, prompting for the direction with the minibuffer.  The
+commands @kbd{M-x table-split-cell-vertically} and @kbd{M-x
+table-split-cell-horizontally} split in a specific direction.  When
+splitting vertically, the old cell contents are automatically split
+between the two new cells.  When splitting horizontally, you are
+prompted for how to divide the cell contents, if the cell is
+non-empty; the options are @samp{split} (divide the contents at
+point), @samp{left} (put all the contents in the left cell), and
+@samp{right} (put all the contents in the right cell).
+
+  The following commands enlarge or shrink a cell.  By default, they
+resize by one row or column; if a numeric argument is supplied, that
+specifies the number of rows or columns to resize by.
 
 @table @kbd
 @findex table-heighten-cell
 @item M-x table-heighten-cell
 Enlarge the current cell vertically.
+
 @findex table-shorten-cell
 @item M-x table-shorten-cell
 Shrink the current cell vertically.
+
 @findex table-widen-cell
 @item M-x table-widen-cell
 Enlarge the current cell horizontally.
+
 @findex table-narrow-cell
 @item M-x table-narrow-cell
 Shrink the current cell horizontally.
@@ -2405,107 +2527,76 @@ Shrink the current cell horizontally.
 
 @node Cell Justification
 @subsection Cell Justification
-@cindex cell text justification
+@cindex justification in text-based tables
 
-  You can specify text justification for each cell.  The justification
-is remembered independently for each cell and the subsequent editing
-of cell contents is subject to the specified justification.
+  The command @kbd{M-x table-justify} imposes @dfn{justification} on
+one or more cells in a text-based table.  Justification determines how
+the text in the cell is aligned, relative to the edges of the cell.
+Each cell in a table can be separately justified.
 
 @findex table-justify
-  The command @code{table-justify} ask you to specify what to justify:
-a cell, a column, or a row.  If you select cell justification, this
-command sets the justification only for the current cell.  Selecting
-column or row justification sets the justification for all the cells
-within a column or row respectively.  The command then ask you which
-kind of justification to apply: @code{left}, @code{center},
-@code{right}, @code{top}, @code{middle}, @code{bottom}, or
-@code{none}.  Horizontal justification and vertical justification are
-specified independently.  The options @code{left}, @code{center}, and
-@code{right} specify horizontal justification while the options
-@code{top}, @code{middle}, @code{bottom}, and @code{none} specify
-vertical justification.  The vertical justification @code{none}
-effectively removes vertical justification.  Horizontal justification
-must be one of @code{left}, @code{center}, or @code{right}.
+  @kbd{M-x table-justify} first prompts for what to justify; the
+options are @samp{cell} (just the current cell), @samp{column} (all
+cells in the current table column) and @samp{row} (all cells in the
+current table row).  The command then prompts for the justification
+style; the options are @code{left}, @code{center}, @code{right},
+@code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no
+vertical justification).
+
+  Horizontal and vertical justification styles are specified
+independently, and both types can be in effect simultaneously; for
+instance, you can call @kbd{M-x table-justify} twice, once to specify
+@code{right} justification and once to specify @code{bottom}
+justification, to align the contents of a cell to the bottom right.
 
 @vindex table-detect-cell-alignment
-  Justification information is stored in the buffer as a part of text
-property.  Therefore, this information is ephemeral and does not
-survive through the loss of the buffer (closing the buffer and
-revisiting the buffer erase any previous text properties).  To
-countermand for this, the command @code{table-recognize} and other
-recognition commands (@pxref{Table Recognition}) are equipped with a
-convenience feature (turned on by default).  During table recognition,
-the contents of a cell are examined to determine which justification
-was originally applied to the cell and then applies this justification
-to the cell.  This is a speculative algorithm and is therefore not
-perfect, however, the justification is deduced correctly most of the
-time.  To disable this feature, customize the variable
-@code{table-detect-cell-alignment} and set it to @code{nil}.
-
-@node Row Commands
-@subsection Commands for Table Rows
-@cindex table row commands
-
-@cindex insert row in table
+  The justification style is stored in the buffer as a text property,
+and is lost when you kill the buffer or exit Emacs.  However, the
+table recognition commands, such as @kbd{M-x table-recognize}
+(@pxref{Table Recognition}), attempt to determine and re-apply each
+cell's justification style, by examining its contents.  To disable
+this feature, change the variable @code{table-detect-cell-alignment}
+to @code{nil}.
+
+@node Table Rows and Columns
+@subsection Table Rows and Columns
+@cindex inserting rows and columns in text-based tables
+
 @findex table-insert-row
-  The command @code{table-insert-row} inserts a row of cells before
-the current row in a table.  The current row where point is located is
-pushed down after the newly inserted row.  A numeric prefix argument
-specifies the number of rows to insert.  Note that in order to insert
-rows @emph{after} the last row at the bottom of a table, you must
-place point below the table---that is, outside the table---prior to
-invoking this command.
-
-@cindex delete row in table
-@findex table-delete-row
-  The command @code{table-delete-row} deletes a row of cells at point.
-A numeric prefix argument specifies the number of rows to delete.
-
-@node Column Commands
-@subsection Commands for Table Columns
-@cindex table column commands
-
-@cindex insert column in table
-@findex table-insert-column
-  The command @code{table-insert-column} inserts a column of cells to
-the left of the current row in a table.  This pushes the current
-column to the right.  To insert a column to the right side of the
-rightmost column, place point to the right of the rightmost column,
-which is outside of the table, prior to invoking this command.  A
-numeric prefix argument specifies the number of columns to insert.
-
-@cindex delete column in table
-  A command @code{table-delete-column} deletes a column of cells at
-point.  A numeric prefix argument specifies the number of columns to
-delete.
-
-@node Fixed Width Mode
-@subsection Fix Width of Cells
-@cindex fix width of table cells
+  @kbd{M-x table-insert-row} inserts a row of cells before the current
+table row.  The current row, together with point, is pushed down past
+the new row.  To insert rows after the last row at the bottom of a
+table, invoke this command with point below the table, just below the
+bottom edge.  A numeric prefix argument specifies the number of rows
+to insert.
 
-@findex table-fixed-width-mode
-  The command @code{table-fixed-width-mode} toggles fixed width mode
-on and off.  When fixed width mode is turned on, editing inside a
-cell never changes the cell width; when it is off, the cell width
-expands automatically in order to prevent a word from being folded
-into multiple lines.  By default, fixed width mode is disabled.
+@findex table-insert-column
+  Similarly, @kbd{M-x table-insert-column} inserts a column of cells
+to the left of the current table column.  To insert a column to the
+right side of the rightmost column, invoke this command with point to
+the right of the rightmost column, outside the table.  A numeric
+prefix argument specifies the number of columns to insert.
+
+@cindex deleting rows and column in text-based tables
+  @kbd{M-x table-delete-column} deletes the column of cells at point.
+Similarly, @kbd{M-x table-delete-row} deletes the row of cells at
+point.  A numeric prefix argument to either command specifies the
+number of columns or rows to delete.
 
 @node Table Conversion
-@subsection Conversion Between Plain Text and Tables
+@subsection Converting Between Plain Text and Tables
 @cindex text to table
 @cindex table to text
 
 @findex table-capture
-  The command @code{table-capture} captures plain text in a region and
-turns it into a table.  Unlike @code{table-recognize} (@pxref{Table
-Recognition}), the original text does not have a table appearance but
-may hold a logical table structure.  For example, some elements
-separated by known patterns form a two dimensional structure which can
-be turned into a table.
+  The command @kbd{M-x table-capture} captures plain text in a region
+and turns it into a table.  Unlike @kbd{M-x table-recognize}
+(@pxref{Table Recognition}), the original text does not need to have a
+table appearance; it only needs to have a logical table-like
+structure.
 
-  Here's an example of data that @code{table-capture} can operate on.
-The numbers are horizontally separated by a comma and vertically
-separated by a newline character.
+  For example, suppose we have the following numbers, which are
+divided into three lines and separated horizontally by commas:
 
 @example
 1, 2, 3, 4
@@ -2526,136 +2617,92 @@ Invoking @kbd{M-x table-capture} on that text produces this table:
 +-----+-----+-----+-----+
 @end example
 
-@noindent
-The conversion uses @samp{,} for the column delimiter and newline for
-a row delimiter, cells are left justified, and minimum cell width is
-5.
-
 @findex table-release
-  The command @code{table-release} does the opposite of
-@code{table-capture}.  It releases a table by removing the table frame
-and cell borders.  This leaves the table contents as plain text.  One
-of the useful applications of @code{table-capture} and
-@code{table-release} is to edit a text in layout.  Look at the
-following three paragraphs (the latter two are indented with header
-lines):
+  @kbd{M-x table-release} does the opposite: it converts a table back
+to plain text, removing its cell borders.
+
+  One application of this pair of commands is to edit a text in
+layout.  Look at the following three paragraphs (the latter two are
+indented with header lines):
 
 @example
 table-capture is a powerful command.
 Here are some things it can do:
 
-Parse Cell Items  By using column delimiter regular
-                  expression and raw delimiter regular
-                  expression, it parses the specified text
-                  area and extracts cell items from
-                  non-table text and then forms a table out
-                  of them.
-
-Capture Text Area When no delimiters are specified it
-                  creates a single cell table.  The text in
-                  the specified region is placed in that
-                  cell.
+Parse Cell Items   Using row and column delimiter regexps,
+                   it parses the specified text area and
+                   extracts cell items into a table.
 @end example
 
 @noindent
-Applying @code{table-capture} to a region containing the above three
-paragraphs, with empty strings for column delimiter regexp and row
-delimiter regexp, creates a table with a single cell like the
-following one.
-
-@c The first line's right-hand frame in the following two examples
-@c sticks out to accommodate for the removal of @samp in the
-@c produced output!!
+Applying @code{table-capture} to a region containing the above text,
+with empty strings for the column and row delimiter regexps, creates a
+table with a single cell like the following one.
+
 @smallexample
 @group
-+-------------------------------------------------------------+
-|table-capture is a powerful command.                         |
-|Here are some things it can do:                              |
-|                                                             |
-|Parse Cell Items  By using column delimiter regular          |
-|                  expression and raw delimiter regular       |
-|                  expression, it parses the specified text   |
-|                  area and extracts cell items from          |
-|                  non-table text and then forms a table out  |
-|                  of them.                                   |
-|                                                             |
-|Capture Text Area When no delimiters are specified it        |
-|                  creates a single cell table.  The text in  |
-|                  the specified region is placed in that     |
-|                  cell.                                      |
-+-------------------------------------------------------------+
++----------------------------------------------------------+
+|table-capture is a powerful command.                      |
+|Here are some things it can do:                           |
+|                                                          |
+|Parse Cell Items   Using row and column delimiter regexps,|
+|                   it parses the specified text area and  |
+|                   extracts cell items into a table.      |
++----------------------------------------------------------+
 @end group
 @end smallexample
 
 @noindent
-By splitting the cell appropriately we now have a table consisting of
-paragraphs occupying its own cell.  Each cell can now be edited
-independently without affecting the layout of other cells.
+We can then use the cell splitting commands (@pxref{Cell Commands}) to
+subdivide the table so that each paragraph occupies a cell:
 
 @smallexample
-+--------------------------------------------------------------+
-|table-capture is a powerful command.                          |
-|Here are some things it can do:                               |
-+------------------+-------------------------------------------+
-|Parse Cell Items  |By using column delimiter regular          |
-|                  |expression and raw delimiter regular       |
-|                  |expression, it parses the specified text   |
-|                  |area and extracts cell items from          |
-|                  |non-table text and then forms a table out  |
-|                  |of them.                                   |
-+------------------+-------------------------------------------+
-|Capture Text Area |When no delimiters are specified it        |
-|                  |creates a single cell table.  The text in  |
-|                  |the specified region is placed in that     |
-|                  |cell.                                      |
-+------------------+-------------------------------------------+
++----------------------------------------------------------+
+|table-capture is a powerful command.                      |
+|Here are some things it can do:                           |
++-----------------+----------------------------------------+
+|Parse Cell Items | Using row and column delimiter regexps,|
+|                 | it parses the specified text area and  |
+|                 | extracts cell items into a table.      |
++-----------------+----------------------------------------+
 @end smallexample
 
 @noindent
-By applying @code{table-release}, which does the opposite process, the
-contents become once again plain text.  @code{table-release} works as
-a companion command to @code{table-capture}.
+Each cell can now be edited independently without affecting the layout
+of other cells.  When finished, we can invoke @kbd{M-x table-release}
+to convert the table back to plain text.
 
-@node Measuring Tables
-@subsection Analyzing Table Dimensions
-@cindex table dimensions
+@node Table Misc
+@subsection Table Miscellany
 
+@cindex table dimensions
 @findex table-query-dimension
-  The command @code{table-query-dimension} analyzes a table structure
-and reports information regarding its dimensions.  In case of the
-above example table, the @code{table-query-dimension} command displays
-in echo area:
+  The command @code{table-query-dimension} reports the layout of the
+table and table cell at point.  Here is an example of its output:
 
 @smallexample
 Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
 @end smallexample
 
 @noindent
-This indicates that the current cell is 21 character wide and 6 lines
-high, the entire table is 67 characters wide and 16 lines high.  The
-table has 2 columns and 3 rows.  It has a total of 5 cells, since the
-first row has a spanned cell.
+This indicates that the current cell is 21 characters wide and 6 lines
+high, the table is 67 characters wide and 16 lines high with 2 columns
+and 3 rows, and a total of 5 cells.
 
-@node Table Misc
-@subsection Table Miscellany
-
-@cindex insert string into table cells
 @findex table-insert-sequence
-  The command @code{table-insert-sequence} inserts a string into each
-cell.  Each string is a part of a sequence i.e.@: a series of
-increasing integer numbers.
+  @kbd{M-x table-insert-sequence} inserts a string into each cell.
+Each string is a part of a sequence i.e.@: a series of increasing
+integer numbers.
 
-@cindex table in language format
 @cindex table for HTML and LaTeX
 @findex table-generate-source
-  The command @code{table-generate-source} generates a table formatted
-for a specific markup language.  It asks for a language (which must be
-one of @code{html}, @code{latex}, or @code{cals}), a destination
-buffer where to put the result, and the table caption (a string), and
-then inserts the generated table in the proper syntax into the
-destination buffer.  The default destination buffer is
-@code{table.@var{lang}}, where @var{lang} is the language you
-specified.
+  @kbd{M-x table-generate-source} generates a table formatted for a
+specific markup language.  It asks for a language (which must be one
+of @code{html}, @code{latex}, or @code{cals}), a destination buffer in
+which to put the result, and a table caption, and then inserts the
+generated table into the specified buffer.  The default destination
+buffer is @code{table.@var{lang}}, where @var{lang} is the language
+you specified.
 
 @node Two-Column
 @section Two-Column Editing
@@ -2663,11 +2710,9 @@ specified.
 @cindex splitting columns
 @cindex columns, splitting
 
-  Two-column mode lets you conveniently edit two side-by-side columns of
-text.  It uses two side-by-side windows, each showing its own
-buffer.
-
-  There are three ways to enter two-column mode:
+  Two-column mode lets you conveniently edit two side-by-side columns
+of text.  It uses two side-by-side windows, each showing its own
+buffer.  There are three ways to enter two-column mode:
 
 @table @asis
 @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
index 05e89e69f0e..b65e6f96a6e 100644
--- a/doc/emacs/vc1-xtra.texi
+++ b/doc/emacs/vc1-xtra.texi
@@ -5,301 +5,6 @@
 @c This file is included either in vc-xtra.texi (when producing the
 @c printed version) or in the main Emacs manual (for the on-line version).
 
-@node Remote Repositories
-@subsection Remote Repositories
-@cindex remote repositories
-
-  A common way of using CVS and other more advanced VCSes is to set up
-a central repository on some Internet host, then have each
-developer check out a personal working copy of the files on his local
-machine.  Committing changes to the repository, and picking up changes
-from other users into one's own working area, then works by direct
-interactions with the repository server.
-
-  One difficulty is that access to a repository server is often slow,
-and that developers might need to work off-line as well.  While only
-third-generation decentralized VCses such as GNU Arch or Mercurial
-really solve this problem, VC is designed to reduce the amount of
-network interaction necessary.
-
-  If you are using a truly decentralized VCS you can skip the rest of
-this section. It describes backup and local-repository techniques
-that are only useful for Subversion and earlier VCSes.
-
-@menu
-* Version Backups::        Keeping local copies of repository versions.
-* Local Version Control::  Using another version system for local editing.
-@end menu
-
-@node Version Backups
-@subsubsection Version Backups
-@cindex version backups
-
-@cindex automatic version backups
-  When VC sees that the repository for a file is on a remote
-machine, it automatically makes local backups of unmodified versions
-of the file---@dfn{automatic version backups}.  This means that you
-can compare the file to the repository version (@kbd{C-x v =}), or
-revert to that version (@kbd{C-x v u}), without any network
-interactions.
-
-  The local copy of the unmodified file is called a @dfn{version
-backup} to indicate that it corresponds exactly to a version that is
-stored in the repository.  Note that version backups are not the same
-as ordinary Emacs backup files
-@iftex
-(@pxref{Backup,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Backup}).
-@end ifnottex
-But they follow a similar naming convention.
-
-  For a file that comes from a remote repository, VC makes a
-version backup whenever you save the first changes to the file, and
-removes it after you have committed your modified version to the
-repository. You can disable the making of automatic version backups by
-setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}).
-
-@cindex manual version backups
-  The name of the automatic version backup for version @var{version}
-of file @var{file} is @code{@var{file}.~@var{version}.~}.  This is
-almost the same as the name used by @kbd{C-x v ~}
-@iftex
-(@pxref{Old Revisions,,,emacs, the Emacs Manual}),
-@end iftex
-@ifnottex
-(@pxref{Old Revisions}),
-@end ifnottex
-the only difference being the additional dot (@samp{.})  after the
-version number.  This similarity is intentional, because both kinds of
-files store the same kind of information.  The file made by @kbd{C-x v
-~} acts as a @dfn{manual version backup}.
-
-  All the VC commands that operate on old versions of a file can use
-both kinds of version backups.  For instance, @kbd{C-x v ~} uses
-either an automatic or a manual version backup, if possible, to get
-the contents of the version you request.  Likewise, @kbd{C-x v =} and
-@kbd{C-x v u} use either an automatic or a manual version backup, if
-one of them exists, to get the contents of a version to compare or
-revert to.  If you changed a file outside of Emacs, so that no
-automatic version backup was created for the previous text, you can
-create a manual backup of that version using @kbd{C-x v ~}, and thus
-obtain the benefit of the local copy for Emacs commands.
-
-  The only difference in Emacs's handling of manual and automatic
-version backups, once they exist, is that Emacs deletes automatic
-version backups when you commit to the repository.  By contrast,
-manual version backups remain until you delete them.
-
-@node Local Version Control
-@subsubsection Local Version Control
-@cindex local version control
-@cindex local back end (version control)
-
-When you make many changes to a file that comes from a remote
-repository, it can be convenient to have version control on your local
-machine as well.  You can then record intermediate versions, revert to
-a previous state, etc., before you actually commit your changes to the
-remote server.
-
-VC lets you do this by putting a file under a second, local version
-control system, so that the file is effectively registered in two
-systems at the same time.  For the description here, we will assume
-that the remote system is CVS, and you use RCS locally, although the
-mechanism works with any combination of version control systems
-(@dfn{back ends}).
-
-To make it work with other back ends, you must make sure that the
-``more local'' back end comes before the ``more remote'' back end in
-the setting of @code{vc-handled-backends} (@pxref{Customizing VC}).  By
-default, this variable is set up so that you can use remote CVS and
-local RCS as described here.
-
-To start using local RCS for a file that comes from a remote CVS
-server, you must @emph{register the file in RCS}, by typing @kbd{C-u
-C-x v v rcs @key{RET}}.  (In other words, use @code{vc-next-action} with a
-prefix argument, and specify RCS as the back end.)
-
-You can do this at any time; it does not matter whether you have
-already modified the file with respect to the version in the CVS
-repository.  If possible, VC tries to make the RCS master start with
-the unmodified repository version, then checks in any local changes
-as a new version.  This works if you have not made any changes yet, or
-if the unmodified repository version exists locally as a version
-backup (@pxref{Version Backups}).  If the unmodified version is not
-available locally, the RCS master starts with the modified version;
-the only drawback to this is that you cannot compare your changes
-locally to what is stored in the repository.
-
-The version number of the RCS master is derived from the current CVS
-version, starting a branch from it.  For example, if the current CVS
-version is 1.23, the local RCS branch will be 1.23.1.  Version 1.23 in
-the RCS master will be identical to version 1.23 under CVS; your first
-changes are checked in as 1.23.1.1.  (If the unmodified file is not
-available locally, VC will check in the modified file twice, both as
-1.23 and 1.23.1.1, to make the revision numbers consistent.)
-
-If you do not use locking under CVS (the default), locking is also
-disabled for RCS, so that editing under RCS works exactly as under
-CVS.
-
-When you are done with local editing, you can commit the final version
-back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}.
-This initializes the log entry buffer
-@iftex
-(@pxref{Log Buffer,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Log Buffer})
-@end ifnottex
-to contain all the log entries you have recorded in the RCS master;
-you can edit them as you wish, and then commit in CVS by typing
-@kbd{C-c C-c}.  If the commit is successful, VC removes the RCS
-master, so that the file is once again registered under CVS only.
-(The RCS master is not actually deleted, just renamed by appending
-@samp{~} to the name, so that you can refer to it later if you wish.)
-
-While using local RCS, you can pick up recent changes from the CVS
-repository into your local file, or commit some of your changes back
-to CVS, without terminating local RCS version control.  To do this,
-switch to the CVS back end temporarily, with the @kbd{C-x v b} command:
-
-@table @kbd
-@item C-x v b
-Switch to another back end that the current file is registered
-under (@code{vc-switch-backend}).
-
-@item C-u C-x v b @var{backend} @key{RET}
-Switch to @var{backend} for the current file.
-@end table
-
-@kindex C-x v b
-@findex vc-switch-backend
-@kbd{C-x v b} does not change the buffer contents, or any files; it
-only changes VC's perspective on how to handle the file.  Any
-subsequent VC commands for that file will operate on the back end that
-is currently selected.
-
-If the current file is registered in more than one back end, typing
-@kbd{C-x v b} ``cycles'' through all of these back ends.  With a
-prefix argument, it asks for the back end to use in the minibuffer.
-
-Thus, if you are using local RCS, and you want to pick up some recent
-changes in the file from remote CVS, first visit the file, then type
-@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m
-@key{RET}} to merge the news
-@iftex
-(@pxref{Merging,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Merging}).
-@end ifnottex
-You can then switch back to RCS by typing @kbd{C-x v b} again, and
-continue to edit locally.
-
-But if you do this, the revision numbers in the RCS master no longer
-correspond to those of CVS.  Technically, this is not a problem, but
-it can become difficult to keep track of what is in the CVS repository
-and what is not.  So we suggest that you return from time to time to
-CVS-only operation, by committing your local changes back to the
-repository using @kbd{C-u C-x v v cvs @key{RET}}.
-
-@node Revision Tags
-@subsection Revision Tags
-@cindex tags and version control
-
-  In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS)
-@dfn{tag} is a named set of file versions (one for each registered
-file) that you can treat as a unit.  In a VCS with per-repository
-version numbers (Subversion and most later ones) a tag is simply
-a symbolic name for a revision.
-
-   One important kind of tag is a @dfn{release}, a (theoretically)
-stable version of the system that is ready for distribution to users.
-
-@menu
-* Making Revision Tags::  The tag facilities.
-* Revision Tag Caveats::  Things to be careful of when using tags.
-@end menu
-
-@node Making Revision Tags
-@subsubsection Making and Using Revision Tags
-
-  There are two basic commands for tags; one makes a
-tag with a given name, the other retrieves a named tag.
-
-@table @code
-@kindex C-x v s
-@findex vc-create-tag
-@item C-x v s @var{name} @key{RET}
-Define the working revision of every registered file in or under the
-current directory as a tag named @var{name}
-(@code{vc-create-tag}).
-
-@kindex C-x v r
-@findex vc-retrieve-tag
-@item C-x v r @var{name} @key{RET}
-For all registered files at or below the current directory level,
-retrieve the tagged revision @var{name}. This command will 
-switch to a branch if @var{name} is a branch name and your VCS
-distinguishes branches from tags. 
-(@code{vc-retrieve-tag}).
-
-This command reports an error if any files are locked at or below the
-current directory, without changing anything; this is to avoid
-overwriting work in progress.
-@end table
-
-Tags are inexpensive, so you need not hesitate to create them whenever
-they are useful.  Branches vary in cost depending on your VCS; in
-older ones they may be expensive.
-
-  You can give a tag or branch name as an argument to @kbd{C-x v =} or
-@kbd{C-x v ~}
-@iftex
-(@pxref{Old Revisions,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Old Revisions}).
-@end ifnottex
-Thus, you can use it to compare a tagged version against the current files,
-or two tagged versions against each other.
-
-@node Revision Tag Caveats
-@subsubsection Revision Tag Caveats
-
-  For SCCS, VC implements tags itself; these tags are visible only
-through VC.  Most later systems (including CVS, Subversion, bzr, git,
-and hg) have a native tag facility, and VC uses it where
-available; those tags will be visible even when you bypass VC.
-
-  There is no support for VC tags using GNU Arch yet.
-
-  Under older VCSes (SCCS, RCS, CVS, early versions of Subversion),
-renaming and deletion could create some difficulties with tags.  This is
-not a VC-specific problem, but a general design issue in version
-control systems that was not solved effectively until the earliest
-third-generation systems.
-
-  In a file-oriented VCS, when you rename a registered file you need
-to rename its master along with it; the command @code{vc-rename-file}
-will do this automatically.  If you are using SCCS, you must also
-update the records of the tag, to mention the file by its new name
-(@code{vc-rename-file} does this, too).  An old tag that refers to a
-master file that no longer exists under the recorded name is invalid;
-VC can no longer retrieve it.  It would be beyond the scope of this
-manual to explain enough about RCS and SCCS to explain how to update
-the tags by hand.
-
-  Using @code{vc-rename-file} makes the tag remain valid for
-retrieval, but it does not solve all problems.  For example, some of the
-files in your program probably refer to others by name.  At the very
-least, the makefile probably mentions the file that you renamed.  If you
-retrieve an old tag, the renamed file is retrieved under its new
-name, which is not the name that the makefile expects.  So the program
-won't really work as retrieved.
-
 @node Miscellaneous VC
 @subsection Miscellaneous Commands and Features of VC
 
@@ -307,52 +12,55 @@ won't really work as retrieved.
 
 @menu
 * Change Logs and VC::  Generating a change log file from log entries.
-* Renaming and VC::     A command to rename both the source and master
-                          file correctly.
+* VC Delete/Rename::    Deleting and renaming version-controlled files.
+* Revision Tags::       Symbolic names for revisions.
 * Version Headers::     Inserting version control headers into working files.
 @end menu
 
 @node Change Logs and VC
 @subsubsection Change Logs and VC
 
-  If you use RCS or CVS for a program and also maintain a change log
-file for it
+  If you use RCS or CVS for a program with a @file{ChangeLog} file
 @iftex
 (@pxref{Change Log,,,emacs, the Emacs Manual}),
 @end iftex
 @ifnottex
 (@pxref{Change Log}),
 @end ifnottex
-you can generate change log entries automatically from the version
-control log entries:
+you can generate change log entries from the version control log
+entries of previous commits.
+
+  Note that this only works with RCS or CVS.  This procedure would be
+particularly incorrect on a modern changeset-based version control
+system, where changes to the @file{ChangeLog} file would normally be
+committed as part of a changeset.  In that case, you should write the
+change log entries first, then pull them into the @samp{*vc-log*}
+buffer when you commit
+@iftex
+(@pxref{Log Buffer,,,emacs, the Emacs Manual}).
+@end iftex
+@ifnottex
+(@pxref{Log Buffer}).
+@end ifnottex
 
 @table @kbd
 @item C-x v a
 @kindex C-x v a
 @findex vc-update-change-log
-Visit the current directory's change log file and, for registered files
-in that directory, create new entries for versions checked in since the
-most recent entry in the change log file.
+Visit the current directory's @file{ChangeLog} file and, for
+registered files in that directory, create new entries for versions
+committed since the most recent change log entry
 (@code{vc-update-change-log}).
 
-This command works with RCS or CVS only, not with any of the other
-back ends.
-
 @item C-u C-x v a
 As above, but only find entries for the current buffer's file.
-
-@item M-1 C-x v a
-As above, but find entries for all the currently visited files that are
-maintained with version control.  This works only with RCS, and it puts
-all entries in the log for the default directory, which may not be
-appropriate.
 @end table
 
   For example, suppose the first line of @file{ChangeLog} is dated
 1999-04-10, and that the only check-in since then was by Nathaniel
-Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log
-messages that start with `#'.}.  Then @kbd{C-x v a} visits
-@file{ChangeLog} and inserts text like this:
+Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore
+log messages that start with `#'.}.  Then @kbd{C-x v a} inserts this
+@file{ChangeLog} entry:
 
 @iftex
 @medbreak
@@ -369,17 +77,11 @@ messages that start with `#'.}.  Then @kbd{C-x v a} visits
 @end iftex
 
 @noindent
-You can then edit the new change log entry further as you wish.
-
-  Some of the new change log entries may duplicate what's already in
-ChangeLog.  You will have to remove these duplicates by hand.
-
-  Normally, the log entry for file @file{foo} is displayed as @samp{*
-foo: @var{text of log entry}}.  The @samp{:} after @file{foo} is omitted
-if the text of the log entry starts with @w{@samp{(@var{functionname}):
-}}.  For example, if the log entry for @file{vc.el} is
-@samp{(vc-do-command): Check call-process status.}, then the text in
-@file{ChangeLog} looks like this:
+If the version control log entry specifies a function name (in
+parenthesis at the beginning of a line), that is reflected in the
+@file{ChangeLog} entry.  For example, if a log entry for @file{vc.el}
+is @samp{(vc-do-command): Check call-process status.}, the
+@file{ChangeLog} entry is:
 
 @iftex
 @medbreak
@@ -395,221 +97,184 @@ if the text of the log entry starts with @w{@samp{(@var{functionname}):
 @medbreak
 @end iftex
 
-  When @kbd{C-x v a} adds several change log entries at once, it groups
-related log entries together if they all are checked in by the same
-author at nearly the same time.  If the log entries for several such
-files all have the same text, it coalesces them into a single entry.
-For example, suppose the most recent check-ins have the following log
-entries:
+  When @kbd{C-x v a} adds several change log entries at once, it
+groups related log entries together if they all are checked in by the
+same author at nearly the same time.  If the log entries for several
+such files all have the same text, it coalesces them into a single
+entry.
 
-@flushleft
-@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.}
-@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.}
-@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
-@end flushleft
+@node VC Delete/Rename
+@subsubsection Deleting and Renaming Version-Controlled Files
+@cindex renaming version-controlled files
 
-@noindent
-They appear like this in @file{ChangeLog}:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-@group
-1999-04-01  Nathaniel Bowditch  <nat@@apn.org>
+@table @kbd
+@item M-x vc-delete-file
+Prompt for a file name, delete the file from the working tree, and
+schedule the deletion for committing.
 
-        * vc.texinfo: Fix expansion typos.
+@item M-x vc-rename-file
+Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the
+working tree, and schedule the renaming for committing.
+@end table
 
-        * vc.el, vc-hooks.el: Don't call expand-file-name.
-@end group
-@end smallexample
+@findex vc-delete-file
+  If you wish to delete a version-controlled file, use the command
+@kbd{M-x vc-delete-file}.  This prompts for the file name, and deletes
+it via the version control system.  The file is removed from the
+working tree, and in the VC Directory buffer
 @iftex
-@medbreak
+(@pxref{VC Directory Mode}),
 @end iftex
+@ifnottex
+(@pxref{VC Directory Mode}),
+@end ifnottex
+it is displayed with the @samp{removed} status.  When you commit it,
+the deletion takes effect in the repository.
 
-  Normally, @kbd{C-x v a} separates log entries by a blank line, but you
-can mark several related log entries to be clumped together (without an
-intervening blank line) by starting the text of each related log entry
-with a label of the form @w{@samp{@{@var{clumpname}@} }}.  The label
-itself is not copied to @file{ChangeLog}.  For example, suppose the log
-entries are:
+@findex vc-rename-file
+  To rename a version-controlled file, type @kbd{M-x vc-rename-file}.
+This prompts for two arguments: the name of the file you wish to
+rename, and the new name; then it performs the renaming via the
+version control system.  The renaming takes effect immediately in the
+working tree, and takes effect in the repository when you commit the
+renamed file.
+
+  On modern version control systems that have built-in support for
+renaming, the renamed file retains the full change history of the
+original file.  On CVS and older version control systems, the
+@code{vc-rename-file} command actually works by creating a copy of the
+old file under the new name, registering it, and deleting the old
+file.  In this case, the change history is not preserved.
 
-@flushleft
-@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.}
-@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.}
-@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.}
-@end flushleft
+@node Revision Tags
+@subsubsection Revision Tags
+@cindex revision tag
+@cindex tags for version control
 
-@noindent
-Then the text in @file{ChangeLog} looks like this:
+  Most version control systems allow you to apply a @dfn{revision tag}
+to a specific version of a version-controlled tree.  On modern
+changeset-based version control systems, a revision tag is simply a
+symbolic name for a particular revision.  On older file-based systems
+like CVS, each tag is added to the entire set of version-controlled
+files, allowing them to be handled as a unit.  Revision tags are
+commonly used to identify releases that are distributed to users.
 
-@iftex
-@medbreak
-@end iftex
-@smallexample
-@group
-1999-04-01  Nathaniel Bowditch  <nat@@apn.org>
+  There are two basic commands for tags; one makes a tag with a given
+name, the other retrieves a named tag.
 
-        * vc.texinfo: Fix expansion typos.
-        * vc.el, vc-hooks.el: Don't call expand-file-name.
-@end group
-@end smallexample
-@iftex
-@medbreak
-@end iftex
+@table @code
+@kindex C-x v s
+@findex vc-create-tag
+@item C-x v s @var{name} @key{RET}
+Define the working revision of every registered file in or under the
+current directory as a tag named @var{name}
+(@code{vc-create-tag}).
 
-  A log entry whose text begins with @samp{#} is not copied to
-@file{ChangeLog}.  For example, if you merely fix some misspellings in
-comments, you can log the change with an entry beginning with @samp{#}
-to avoid putting such trivia into @file{ChangeLog}.
+@kindex C-x v r
+@findex vc-retrieve-tag
+@item C-x v r @var{name} @key{RET}
+For all registered files at or below the current directory level,
+retrieve the tagged revision @var{name}. This command will switch to a
+branch if @var{name} is a branch name and your VCS distinguishes
+branches from tags.  (@code{vc-retrieve-tag}).
 
-@node Renaming and VC
-@subsubsection Renaming VC Work Files and Master Files
+This command reports an error if any files are locked at or below the
+current directory, without changing anything; this is to avoid
+overwriting work in progress.
+@end table
 
-@findex vc-rename-file
-  When you rename a registered file, you must also rename its master
-file correspondingly to get proper results.  Use @code{vc-rename-file}
-to rename the source file as you specify, and rename its master file
-accordingly.  It also updates any tags (@pxref{Revision Tags}) that
-mention the file, so that they use the new name; despite this, the
-tag thus modified may not completely work (@pxref{Revision Tag Caveats}).
+  You can give a tag or branch name as an argument to @kbd{C-x v =} or
+@kbd{C-x v ~}
+@iftex
+(@pxref{Old Revisions,,,emacs, the Emacs Manual}).
+@end iftex
+@ifnottex
+(@pxref{Old Revisions}).
+@end ifnottex
+Thus, you can use it to compare a tagged version against the current files,
+or two tagged versions against each other.
 
-  Some back ends do not provide an explicit rename operation to their
-repositories.  After issuing @code{vc-rename-file}, use @kbd{C-x v v}
-on the original and renamed buffers and provide the necessary edit
-log.
+  On SCCS, VC implements tags itself; these tags are visible only
+through VC.  Most later systems (including CVS, Subversion, bzr, git,
+and hg) have a native tag facility, and VC uses it where available;
+those tags will be visible even when you bypass VC.
 
-  You cannot use @code{vc-rename-file} on a file that is locked by
-someone else.
+  In a file-oriented VCS, when you rename a registered file you need
+to rename its master along with it; the command @code{vc-rename-file}
+will do this automatically.  If you are using SCCS, you must also
+update the records of the tag, to mention the file by its new name
+(@code{vc-rename-file} does this, too).  An old tag that refers to a
+master file that no longer exists under the recorded name is invalid;
+VC can no longer retrieve it.  It would be beyond the scope of this
+manual to explain enough about RCS and SCCS to explain how to update
+the tags by hand.  Using @code{vc-rename-file} makes the tag remain
+valid for retrieval, but it does not solve all problems.  For example,
+some of the files in your program probably refer to others by name.
+At the very least, the makefile probably mentions the file that you
+renamed.  If you retrieve an old tag, the renamed file is retrieved
+under its new name, which is not the name that the makefile expects.
+So the program won't really work as retrieved.
 
 @node Version Headers
 @subsubsection Inserting Version Control Headers
 
-   Sometimes it is convenient to put version identification strings
-directly into working files.  Certain special strings called
-@dfn{version headers} are replaced in each successive version by the
-number of that version, the name of the user who created it, and other
-relevant information.  All of the back ends that VC supports have such
-a mechanism, except GNU Arch.
-
-  VC does not normally use the information contained in these headers.
-The exception is RCS---with RCS, version headers are sometimes more
-reliable than the master file to determine which version of the file
-you are editing.  Note that in a multi-branch environment, version
-headers are necessary to make VC behave correctly
-@iftex
-(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Multi-User Branching}).
-@end ifnottex
-
-  Searching for RCS version headers is controlled by the variable
-@code{vc-consult-headers}.  If it is non-@code{nil} (the default),
-Emacs searches for headers to determine the version number you are
-editing.  Setting it to @code{nil} disables this feature.
+  On Subversion, CVS, RCS, and SCCS, you can put certain special
+strings called @dfn{version headers} into a work file.  When the file
+is committed, the version control system automatically puts the
+revision number, the name of the user who made the commit, and other
+relevant information into the version header.
 
-  Note that although CVS uses the same kind of version headers as RCS
-does, VC never searches for these headers if you are using CVS,
-regardless of the above setting.
+@vindex vc-consult-headers
+  VC does not normally use the information in the version headers.  As
+an exception, when using RCS, Emacs uses the version header, if there
+is one, to determine the file version, since it is often more reliable
+than the RCS master file.  To inhibit using the version header this
+way, change the variable @code{vc-consult-headers} to @code{nil}.
 
 @kindex C-x v h
 @findex vc-insert-headers
-  You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
-insert a suitable header string.
-
-@table @kbd
-@item C-x v h
-Insert headers in a file for use with your version-control system.
-@end table
-
 @vindex vc-@var{backend}-header
-  The default header string is @samp{@w{$}Id$} for RCS and
-@samp{@w{%}W%} for SCCS.  You can specify other headers to insert by
-setting the variables @code{vc-@var{backend}-header} where
-@var{backend} is @code{rcs} or @code{sccs}.
-
-  Instead of a single string, you can specify a list of strings; then
-each string in the list is inserted as a separate header on a line of
-its own.
-
-  It may be necessary to use apparently-superfluous backslashes when
-writing the strings that you put in this variable.  For instance, you
-might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}.  The extra
-backslash prevents the string constant from being interpreted as a
-header, if the Emacs Lisp file containing it is maintained with
-version control.
-
-@vindex vc-comment-alist
-  Each header is inserted surrounded by tabs, inside comment delimiters,
-on a new line at point.  Normally the ordinary comment
-start and comment end strings of the current mode are used, but for
-certain modes, there are special comment delimiters for this purpose;
-the variable @code{vc-comment-alist} specifies them.  Each element of
-this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
+  To insert a suitable header string into the current buffer, type
+@kbd{C-x v h} (@code{vc-insert-headers}).  This command works only on
+Subversion, CVS, RCS, and SCCS.  The variable
+@code{vc-@var{backend}-header} contains the list of keywords to insert
+into the version header; for instance, CVS uses @code{vc-cvs-header},
+whose default value is @code{'("\$Id\$")}.  (The extra backslashes
+prevent the string constant from being interpreted as a header, if the
+Emacs Lisp file defining it is maintained with version control.)  The
+@kbd{C-x v h} command inserts each keyword in the list on a new line
+at point, surrounded by tabs, and inside comment delimiters if
+necessary.
 
 @vindex vc-static-header-alist
   The variable @code{vc-static-header-alist} specifies further strings
 to add based on the name of the buffer.  Its value should be a list of
 elements of the form @code{(@var{regexp} . @var{format})}.  Whenever
-@var{regexp} matches the buffer name, @var{format} is inserted as part
-of the header.  A header line is inserted for each element that matches
-the buffer name, and for each string specified by
-@code{vc-@var{backend}-header}.  The header line is made by processing the
-string from @code{vc-@var{backend}-header} with the format taken from the
-element.  The default value for @code{vc-static-header-alist} is as follows:
-
-@example
-@group
-(("\\.c$" .
-  "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
-#endif /* lint */\n"))
-@end group
-@end example
-
-@noindent
-It specifies insertion of text of this form:
-
-@example
-@group
-
-#ifndef lint
-static char vcid[] = "@var{string}";
-#endif /* lint */
-@end group
-@end example
-
-@noindent
-Note that the text above starts with a blank line.
-
-  If you use more than one version header in a file, put them close
-together in the file.  The mechanism in @code{revert-buffer} that
-preserves markers may not handle markers positioned between two version
-headers.
+@var{regexp} matches the buffer name, @var{format} is also inserted as
+part of the version header.  A @samp{%s} in @var{format} is replaced
+with the file's version control type.
 
 @node Customizing VC
 @subsection Customizing VC
 
 @vindex vc-handled-backends
-The variable @code{vc-handled-backends} determines which version
+  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 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}.
-
-The order of systems in the list is significant: when you visit a file
-registered in more than one system (@pxref{Local Version Control}), VC
-uses the system that comes first in @code{vc-handled-backends} by
-default.  The order is also significant when you register a file for
-the first time, see
+these systems, exclude its name from the list.  To disable VC
+entirely, set this variable to @code{nil}.
+
+  The order of systems in the list is significant: when you visit a
+file registered in more than one system, VC uses the system that comes
+first in @code{vc-handled-backends} by default.  The order is also
+significant when you register a file for the first time
 @iftex
-@ref{Registering,,,emacs, the Emacs Manual},
+(@pxref{Registering,,,emacs, the Emacs Manual}).
 @end iftex
 @ifnottex
-@ref{Registering},
+(@pxref{Registering}).
 @end ifnottex
-for details.
 
 @menu
 * General VC Options::  Options that apply to multiple back ends.
@@ -626,40 +291,27 @@ maintained with version control.  If you want to make backup files even
 for files that use version control, set the variable
 @code{vc-make-backup-files} to a non-@code{nil} value.
 
-@vindex vc-keep-workfiles
-  Normally the work file exists all the time, whether it is locked or
-not.  If you set @code{vc-keep-workfiles} to @code{nil}, then checking
-in a new version with @kbd{C-x v v} deletes the work file; but any
-attempt to visit the file with Emacs creates it again.  (With CVS, work
-files are always kept.)
-
 @vindex vc-follow-symlinks
-  Editing a version-controlled file through a symbolic link can be
-dangerous.  It bypasses the version control system---you can edit the
-file without locking it, and fail to check your changes in.  Also,
-your changes might overwrite those of another user.  To protect against
-this, VC checks each symbolic link that you visit, to see if it points
-to a file under version control.
-
-  The variable @code{vc-follow-symlinks} controls what to do when a
-symbolic link points to a version-controlled file.  If it is @code{nil},
-VC only displays a warning message.  If it is @code{t}, VC automatically
-follows the link, and visits the real file instead, telling you about
-this in the echo area.  If the value is @code{ask} (the default), VC
-asks you each time whether to follow the link.
+@cindex symbolic links (and version control)
+  Editing a version-controlled file through a symbolic link may cause
+unexpected results, if you are unaware that the underlying file is
+version-controlled.  The variable @code{vc-follow-symlinks} controls
+what Emacs does if you try to visit a symbolic link pointing to a
+version-controlled file.  If the value is @code{ask} (the default),
+Emacs asks for confirmation.  If it is @code{nil}, Emacs just displays
+a warning message.  If it is @code{t}, Emacs automatically follows the
+link and visits the real file instead.
 
 @vindex vc-suppress-confirm
   If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v}
 and @kbd{C-x v i} can save the current buffer without asking, and
-@kbd{C-x v u} also operates without asking for confirmation.  (This
-variable does not affect @kbd{C-x v c}; that operation is so drastic
-that it should always ask for confirmation.)
+@kbd{C-x v u} also operates without asking for confirmation.
 
 @vindex vc-command-messages
   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.
+appropriate version control system.  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.
 
 @vindex vc-path
   You can specify additional directories to search for version control
@@ -715,37 +367,16 @@ the variable @code{vc-mistrust-permissions} affects SCCS use, but
 @node CVS Options
 @subsubsection Options specific for CVS
 
-@cindex locking (CVS)
-  By default, CVS does not use locking to coordinate the activities of
-several users; anyone can change a work file at any time.  However,
-there are ways to restrict this, resulting in behavior that resembles
-locking.
-
-@cindex CVSREAD environment variable (CVS)
-  For one thing, you can set the @env{CVSREAD} environment variable
-(the value you use makes no difference).  If this variable is defined,
-CVS makes your work files read-only by default.  In Emacs, you must
-type @kbd{C-x v v} to make the file writable, so that editing works
-in fact similar as if locking was used.  Note however, that no actual
-locking is performed, so several users can make their files writable
-at the same time.  When setting @env{CVSREAD} for the first time, make
-sure to check out all your modules anew, so that the file protections
-are set correctly.
-
-@cindex cvs watch feature
-@cindex watching files (CVS)
-  Another way to achieve something similar to locking is to use the
-@dfn{watch} feature of CVS.  If a file is being watched, CVS makes it
-read-only by default, and you must also use @kbd{C-x v v} in Emacs to
-make it writable.  VC calls @code{cvs edit} to make the file writable,
-and CVS takes care to notify other developers of the fact that you
-intend to change the file.  See the CVS documentation for details on
-using the watch feature.
+@vindex vc-cvs-global-switches
+  You can specify additional command line options to pass to all CVS
+operations in the variable @code{vc-cvs-global-switches}.  These
+switches are inserted immediately after the @code{cvs} command, before
+the name of the operation to invoke.
 
 @vindex vc-stay-local
 @vindex vc-cvs-stay-local
 @cindex remote repositories (CVS)
-  When a file's repository is on a remote machine, VC tries to keep
+  When using a CVS repository on a remote machine, VC can try keeping
 network interactions to a minimum.  This is controlled by the variable
 @code{vc-cvs-stay-local}.  There is another variable,
 @code{vc-stay-local}, which enables the feature also for other back
@@ -753,36 +384,58 @@ ends that support it, including CVS.  In the following, we will talk
 only about @code{vc-cvs-stay-local}, but everything applies to
 @code{vc-stay-local} as well.
 
-If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses
-only the entry in the local CVS subdirectory to determine the file's
-state (and possibly information returned by previous CVS commands).
-One consequence of this is that when you have modified a file, and
-somebody else has already checked in other changes to the file, you
-are not notified of it until you actually try to commit.  (But you can
-try to pick up any recent changes from the repository first, using
-@kbd{C-x v m @key{RET}},
+  If @code{vc-cvs-stay-local} is @code{t} (the default), VC determines
+the version control status of each file using only the entry in the
+local CVS subdirectory and the information returned by previous CVS
+commands.  As a consequence, if you have modified a file and somebody
+else has checked in other changes, you will not be notified of the
+conflict until you try to commit.
+
+  If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the
+remote repository @emph{before} it decides what to do in
+@code{vc-next-action} (@kbd{C-x v v}), just as it does for local
+repositories.
+
+  You can also set @code{vc-cvs-stay-local} to a regular expression
+that is matched against the repository host name; VC then stays local
+only for repositories from hosts that match the pattern.
+
+@cindex automatic version backups
+  When using a remote repository, Emacs normally makes @dfn{automatic
+version backups} of the original versions of each edited file.  These
+local backups are made whenever you save the first changes to a file,
+and they are removed after you commit your changes to the repository.
+(Note that these are not the same as ordinary Emacs backup files;
 @iftex
-@pxref{Merging,,,emacs, the Emacs Manual}).
+@pxref{Backup,,,emacs, the Emacs Manual}.)
 @end iftex
 @ifnottex
-@pxref{Merging}).
+@pxref{Backup}.)
 @end ifnottex
+Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic
+version backups, if possible, to avoid having to access the network.
 
-  When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
-version backups, so that simple diff and revert operations are
-completely local (@pxref{Version Backups}).
-
-  On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil},
-then VC queries the remote repository @emph{before} it decides what to
-do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local
-repositories.  It also does not make any version backups.
+  Setting @code{vc-cvs-stay-local} to @code{nil} disables the making
+of automatic version backups.
 
-  You can also set @code{vc-cvs-stay-local} to a regular expression
-that is matched against the repository host name; VC then stays local
-only for repositories from hosts that match the pattern.
+@cindex manual version backups
+  Automatic version backups have names of the form
+@w{@code{@var{file}.~@var{version}.~}}.  This is similar to the name
+that @kbd{C-x v ~} saves old versions to
+@iftex
+(@pxref{Old Revisions,,,emacs, the Emacs Manual}),
+@end iftex
+@ifnottex
+(@pxref{Old Revisions}),
+@end ifnottex
+except for the additional dot (@samp{.}) after the version.  The
+relevant VC commands can use both kinds of version backups.  The main
+difference is that the ``manual'' version backups made by @kbd{C-x v
+~} are not deleted automatically when you commit.
 
-@vindex vc-cvs-global-switches
-  You can specify additional command line options to pass to all CVS
-operations in the variable @code{vc-cvs-global-switches}.  These
-switches are inserted immediately after the @code{cvs} command, before
-the name of the operation to invoke.
+@cindex locking (CVS)
+  CVS does not use locking by default, but there are ways to enable
+locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature;
+see the CVS documentation for details.  If that case, you can use
+@kbd{C-x v v} in Emacs to toggle locking, as you would for a
+locking-based version control system (@pxref{VC With A Locking VCS}).