[Emacs-diffs] /srv/bzr/emacs/trunk r106733: More updates to Maintaining chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106733
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-12-25 22:16:00 +0800
message:
  More updates to Maintaining chapter of Emacs manual.
  
  * files.texi (Misc File Ops): Mention vc-delete-file.
  
  * 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.
  
  * programs.texi (Symbol Completion): Mention completion-at-point
  explicitly.
  
  * vc1-xtra.texi (VC Delete/Rename): Rename from Renaming and VC.
  Document vc-delete-file.
modified:
  admin/FOR-RELEASE
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/files.texi
  doc/emacs/maintaining.texi
  doc/emacs/programs.texi
  doc/emacs/vc1-xtra.texi
  etc/NEWS

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2011-12-19 07:25:46 +0000
+++ b/admin/FOR-RELEASE 2011-12-25 14:16:00 +0000
@@ -153,7 +153,7 @@
 killing.texi      cyd
 kmacro.texi       cyd
 macos.texi        
-maintaining.texi  
+maintaining.texi  cyd
 major.texi        
 mark.texi         cyd
 mini.texi         
@@ -172,8 +172,8 @@
 sending.texi      
 text.texi         cyd
 trouble.texi      
-vc-xtra.texi
-vc1-xtra.texi
+vc-xtra.texi      cyd
+vc1-xtra.texi     cyd
 windows.texi      cyd
 xresources.texi   
 

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-12-22 10:14:41 +0000
+++ b/doc/emacs/ChangeLog       2011-12-25 14:16:00 +0000
@@ -1,3 +1,19 @@
+2011-12-25  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * maintaining.texi (Change Log Commands): Don't specially mention

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-12-21 08:39:32 +0000
+++ b/doc/emacs/emacs.texi      2011-12-25 14:16:00 +0000
@@ -782,9 +782,8 @@
 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.
-* Revision Tags::       Symbolic names for revisions.
+* 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

=== modified file 'doc/emacs/files.texi'
--- a/doc/emacs/files.texi      2011-12-21 08:39:32 +0000
+++ b/doc/emacs/files.texi      2011-12-25 14:16:00 +0000
@@ -1485,6 +1485,12 @@
 them delete outright, instead of using the Trash, regardless of
 @code{delete-by-moving-to-trash}.
 
address@hidden
+  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}.
address@hidden ifnottex
+
 @findex copy-file
 @cindex copying files
   @kbd{M-x copy-file} reads the file @var{old} and writes a new file
@@ -1514,10 +1520,9 @@
 ask for confirmation when the new file name already exists, too.
 
 @ifnottex
-  Note that if a file is under version control (@pxref{Version
-Control}), you normally ought to rename it via the version control
-system instead, using @kbd{M-x vc-rename-file}.  @xref{Renaming and
-VC}.
+  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

=== modified file 'doc/emacs/maintaining.texi'
--- a/doc/emacs/maintaining.texi        2011-12-22 10:14:41 +0000
+++ b/doc/emacs/maintaining.texi        2011-12-25 14:16:00 +0000
@@ -1188,7 +1188,7 @@
 active, unmark all the files in the region (@code{vc-dir-unmark}).
 
 @item U
-If point is on a file entry, umark all files with the same status; if
+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.
@@ -1567,8 +1567,8 @@
 @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.
@@ -1582,34 +1582,36 @@
 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.
address@hidden 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}.
address@hidden 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}.
address@hidden 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++.
address@hidden,, 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.
address@hidden
 
 @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
@@ -1631,7 +1633,7 @@
 
 You can tag function declarations and external variables in addition
 to function definitions by giving the @samp{--declarations} option to
address@hidden
address@hidden
 
 @item
 In C++ code, in addition to all the tag constructs of C code, member
@@ -1648,15 +1650,15 @@
 @address@hidden@var{variable}} and @address@hidden@var{function}}.
 
 @item
-In address@hidden text, the argument of any of the commands @code{\chapter},
+In address@hidden 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},
address@hidden or @code{\renewenvironment} is a address@hidden
address@hidden 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,
 
@@ -1788,9 +1790,9 @@
 
 @node Create Tags Table
 @subsection Creating Tags Tables
address@hidden @code{etags} program
address@hidden @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.
@@ -1798,53 +1800,46 @@
 @ifnottex
 @ref{Tag Syntax}.
 @end ifnottex
-Here is how to run @code{etags}:
+Here is how to run @command{etags}:
 
 @example
 etags @address@hidden
 @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
 @address@hidden 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
address@hidden@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 @address@hidden 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 @address@hidden 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
address@hidden, the tags file will contain file names relative to the
address@hidden, 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
@@ -1857,40 +1852,41 @@
 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 @address@hidden:/} 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 @address@hidden to specify the language
-explicitly.  You can intermix these options with file names; each one
-applies to the file names that follow it.  Specify
address@hidden to tell @code{etags} to resume guessing the
-language from the file names and file contents.  Specify
address@hidden 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 @address@hidden 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
address@hidden 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 @address@hidden 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 @address@hidden
 options, it outputs detailed information about how tags are generated for
 @var{lang}.
@@ -1898,21 +1894,22 @@
 @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
 address@hidden@address@hidden/@var{tagregexp}/address@hidden/address@hidden
 @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]*}.
address@hidden
+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
address@hidden \t]*}.
 
   In these regular expressions, @samp{\} quotes the next character, and
 all the GCC character escape sequences are supported (@samp{\a} for
@@ -1929,7 +1926,7 @@
 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:
 
@@ -1954,22 +1951,22 @@
 @end smallexample
 
 @noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
address@hidden according to their contents.  @code{etags} also uses
+Here @command{etags} chooses the parsing language for @file{voo.doo} and
address@hidden 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 @address@hidden@}}.
 (@samp{etags --help} prints the list of languages recognized by
address@hidden)  This is particularly useful when storing many
-predefined regular expressions for @code{etags} in a file.  The
address@hidden)  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:
 
@@ -1979,7 +1976,7 @@
 
 @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.
 
@@ -1988,9 +1985,9 @@
 @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
@@ -2053,14 +2050,14 @@
 @node Select Tags Table
 @subsection Selecting a Tags Table
 
address@hidden 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.
 
address@hidden 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
@@ -2124,27 +2121,25 @@
 
 @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.
+  @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.
 
-  If an empty argument is given (just type @key{RET}), the balanced
-expression in the buffer before or around point is used as the
address@hidden argument.  @xref{Expressions}.
+  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
@@ -2152,23 +2147,23 @@
 @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 @address@hidden 4 .}}, which invokes
-the command @code{find-tag-other-window}.  The latter is @address@hidden 5 .}},
-which invokes @code{find-tag-other-frame}.
+makes a new frame for it.  The former is @address@hidden 4 .}}
+(@code{find-tag-other-window}), and the latter is @address@hidden 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.  @address@hidden 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,
address@hidden@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
address@hidden
 
   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}.
@@ -2212,10 +2207,10 @@
 
 @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
address@hidden  This searches the rest of the current buffer, followed
-by the remaining files of the tags address@hidden
+  Having found one match, you probably want to find all the rest.
+Type @kbd{M-,} (@code{tags-loop-continue}) to resume the
address@hidden, 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
@@ -2252,56 +2247,56 @@
 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
address@hidden  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
address@hidden C-M-i
address@hidden address@hidden
+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
 
address@hidden completion (symbol names)
+  In most programming language modes, you can type @kbd{C-M-i} or
address@hidden@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
address@hidden tags-tag-face
address@hidden tags-apropos-additional-actions
   @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
+(@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 address@hidden, it displays the names
-of the tags files together with the tag names.
-
address@hidden tags-tag-face
address@hidden 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
address@hidden 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.
+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.
+
address@hidden 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

=== modified file 'doc/emacs/programs.texi'
--- a/doc/emacs/programs.texi   2011-12-21 08:39:32 +0000
+++ b/doc/emacs/programs.texi   2011-12-25 14:16:00 +0000
@@ -1291,18 +1291,18 @@
 @address@hidden @key{TAB}} instead.
 
 @cindex tags-based completion
-  In-buffer symbol completion generates its completion list in a
-number of different ways.  If Semantic mode is enabled, Emacs tries to
-use the Semantic parser data for completion (@pxref{Semantic}).  If
-Semantic mode is not enabled or it fails at performing completion,
-Emacs normally tries to complete using a tags table (@pxref{Tags}).
-
address@hidden completion-at-point
 @cindex Lisp symbol completion
 @cindex completion (Lisp symbols)
-  In Emacs Lisp mode, completion is performed using the function,
-variable, and property names defined in the current Emacs session.  If
-there is an open parenthesis immediately before the beginning of the
-partial symbol, only symbols with function definitions are considered.
+  In most programming language modes, @kbd{C-M-i} (or
address@hidden@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

=== modified file 'doc/emacs/vc1-xtra.texi'
--- a/doc/emacs/vc1-xtra.texi   2011-12-22 10:14:41 +0000
+++ b/doc/emacs/vc1-xtra.texi   2011-12-25 14:16:00 +0000
@@ -12,8 +12,7 @@
 
 @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
@@ -104,33 +103,48 @@
 such files all have the same text, it coalesces them into a single
 entry.
 
address@hidden Renaming and VC
address@hidden Renaming VC Work Files and Master Files
address@hidden VC Delete/Rename
address@hidden Deleting and Renaming Version-Controlled Files
 @cindex renaming version-controlled files
 
 @table @kbd
address@hidden M-x vc-delete-file
+Prompt for a file name, delete the file from the working tree, and
+schedule the deletion for committing.
+
 @item M-x vc-rename-file
-Prompt for two file names, @var{VAR} and @var{OLD}, and rename them in
-the version-controlled working tree.
+Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the
+working tree, and schedule the renaming for committing.
 @end table
 
address@hidden vc-delete-file
+  If you wish to delete a version-controlled file, use the command
address@hidden 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
address@hidden
+(@pxref{VC Directory Mode}),
address@hidden iftex
address@hidden
+(@pxref{VC Directory Mode}),
address@hidden ifnottex
+it is displayed with the @samp{removed} status.  When you commit it,
+the deletion takes effect in the repository.
+
 @findex vc-rename-file
-  If you wish to rename a registered file in a version-controlled
-working tree, use the command @kbd{M-x vc-rename-file}.  This prompts
-for two arguments: the file you wish to rename, followed by the new
-name; then it performs the renaming through the version control
-system.
+  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 renaming operation takes effect immediately in the
-working tree, and takes effect in the repository when you commit the
-renamed file.  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.
+renaming, the renamed file retains the full change history of the
+original file.  On CVS and older version control systems, the
address@hidden 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.
 
 @node Revision Tags
 @subsubsection Revision Tags

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-12-22 23:30:10 +0000
+++ b/etc/NEWS  2011-12-25 14:16:00 +0000
@@ -97,10 +97,10 @@
 ** Completion
 
 *** shell-mode uses pcomplete rules, with the standard completion UI.
-
++++
 *** Many packages have been changed to use `completion-at-point'
 rather than their own completion code.
-
++++
 *** `completion-at-point' now handles tags and semantic completion.
 ---
 *** Completion in a non-minibuffer now tries to detect the end of completion