changeset 38198:1381135c49a4

Initial version consists of sections moved from Editing Programs chapter.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/maintaining.texi	Tue Jun 26 13:12:29 2001 +0000
@@ -0,0 +1,1216 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Maintaining, Abbrevs, Building, Top
+@chapter Maintaining Programs
+@cindex Lisp editing
+@cindex C editing
+@cindex program editing
+
+  This chapter describes Emacs features for maintaining programs.  The
+version control features,described in the chapter on files
+(@pxref{Version Control}), are also useful particularly for this
+purpose.
+
+@menu
+* Change Log::	        Maintaining a change history for your program.
+* Authors::             Maintaining an @file{AUTHORS} file.
+* Tags::	        Go direct to any function in your program in one
+			  command.  Tags remembers which file it is in.
+* Emerge::	        A convenient way of merging two versions of a program.
+@end menu
+
+@node Change Log
+@section Change Logs
+
+@cindex change log
+@kindex C-x 4 a
+@findex add-change-log-entry-other-window
+  The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
+file for the file you are editing
+(@code{add-change-log-entry-other-window}).  If that file is actually
+a backup file, it makes an entry appropriate for the file's
+parent---that is useful for making log entries for functions that
+have been deleted in the current version.
+
+  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.
+
+  A change log entry starts with a header line that contains the
+current date, your name, and your email address (taken from the
+variable @code{user-mail-address}).  Aside from these header lines,
+every line in the change log starts with a space or a tab.  The bulk
+of the entry consists of @dfn{items}, each of which starts with a line
+starting with whitespace and a star.  Here are two entries, both dated
+in May 1993, each with two items:
+
+@iftex
+@medbreak
+@end iftex
+@smallexample
[phone]  Richard Stallman  <rms@@gnu.org>
+
+        * man.el: Rename symbols `man-*' to `Man-*'.
+        (manual-entry): Make prompt string clearer.
+
+        * simple.el (blink-matching-paren-distance):
+        Change default to 12,000.
+
[phone]  Richard Stallman  <rms@@gnu.org>
+
+        * vc.el (minor-mode-map-alist): Don't use it if it's void.
+        (vc-cancel-version): Doc fix.
+@end smallexample
+
+  One entry can describe several changes; each change should have its
+own item.  Normally there should be a blank line between items.  When
+items are related (parts of the same change, in different places), group
+them by leaving no blank line between them.  The second entry above
+contains two items grouped in this way.
+
+  @kbd{C-x 4 a} visits the change log file and creates a new entry
+unless the most recent entry is for today's date and your name.  It
+also creates a new item for the current file.  For many languages, it
+can even guess the name of the function or other object that was
+changed.
+
+@vindex add-log-keep-changes-together
+  When the option @code{add-log-keep-changes-together} is
+non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
+rather than starting a new entry.
+
+@vindex change-log-version-info-enabled
+@vindex change-log-version-number-regexp-list
+@cindex file version in change log entries
+  If the value of the variable @code{change-log-version-info-enabled}
+is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
+change log entry.  It finds the version number by searching the first
+ten percent of the file, using regular expressions from the variable
+@code{change-log-version-number-regexp-list}.
+
+@cindex Change Log mode
+@findex change-log-mode
+  The change log file is visited in Change Log mode.  In this major
+mode, each bunch of grouped items counts as one paragraph, and each
+entry is considered a page.  This facilitates editing the entries.
+@kbd{C-j} and auto-fill indent each new line like the previous line;
+this is convenient for entering the contents of an entry.
+
+@findex change-log-merge
+  You can use the command @kbd{M-x change-log-merge} to merge other
+log files into a buffer in Change Log Mode, preserving the date
+ordering of entries.
+
+@findex change-log-redate
+@cindex converting change log date style
+  Versions of Emacs before 20.1 used a different format for the time of
+the change log entry:
+
+@smallexample
+Fri May 25 11:23:23 1993 Richard Stallman  <rms@@gnu.org>
+@end smallexample
+
+@noindent
+The @kbd{M-x change-log-redate} command converts all the old-style
+date entries in the change log file visited in the current buffer to
+the new format, to make the file uniform in style.  This is handy when
+entries are contributed by many different people, some of whom use old
+versions of Emacs.
+
+  Version control systems are another way to keep track of changes in your
+program and keep a change log.  @xref{Log Buffer}.
+
+@node Authors
+@section @file{AUTHORS} files
+@cindex @file{AUTHORS} file
+
+  Programs which have many contributors usually include a file named
+@file{AUTHORS} in their distribution, which lists the individual
+contributions.  Emacs has a special command for maintaining the
+@file{AUTHORS} file that is part of the Emacs distribution.
+
+@findex authors
+  The @kbd{M-x authors} command prompts for the name of the root of the
+Emacs source directory.  It then scans @file{ChageLog} files and Lisp
+source files under that directory for information about authors of
+individual packages and people who made changes in source files, and
+puts the information it gleans into a buffer named @samp{*Authors*}.
+You can then edit the contents of that buffer and merge it with the
+exisiting @file{AUTHORS} file.
+
+  Do not assume that this command finds all the contributors; don't
+assume that a person not listed in the output was not a contributor.
+If you merged in someone's contribution and did not put his name
+in the change log, he won't show up in @kbd{M-x authors} either.
+
+@node Tags
+@section Tags Tables
+@cindex tags table
+
+  A @dfn{tags table} is a description of how a multi-file program is
+broken up into files.  It lists the names of the component files and the
+names and positions of the functions (or other named subunits) in each
+file.  Grouping the related files makes it possible to search or replace
+through all the files with one command.  Recording the function names
+and positions makes possible the @kbd{M-.} command which finds the
+definition of a function by looking up which of the files it is in.
+
+  Tags tables are stored in files called @dfn{tags table files}.  The
+conventional name for a tags table file is @file{TAGS}.
+
+  Each entry in the tags table records the name of one tag, the name of the
+file that the tag is defined in (implicitly), and the position in that file
+of the tag's definition.
+
+  Just what names from the described files are recorded in the tags table
+depends on the programming language of the described file.  They
+normally include all file names, functions and subroutines, and may
+also include global variables, data types, and anything else
+convenient.  Each name recorded is called a @dfn{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}.
+
+@menu
+* Tag Syntax::		Tag syntax for various types of code and text files.
+* Create Tags Table::	Creating a tags table with @code{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.
+@end menu
+
+@node Tag Syntax
+@subsection Source File Tag Syntax
+
+  Here is how tag syntax is defined for the most popular languages:
+
+@itemize @bullet
+@item
+In C code, any C function or typedef is a tag, and so are definitions of
+@code{struct}, @code{union} and @code{enum}.
+@code{#define} macro definitions and @code{enum} constants are also
+tags, unless you specify @samp{--no-defines} when making the tags table.
+Similarly, global variables are tags, unless you specify
+@samp{--no-globals}.  Use of @samp{--no-globals} and @samp{--no-defines}
+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}.
+
+@item
+In C++ code, in addition to all the tag constructs of C code, member
+functions are also recognized, and optionally member variables if you
+use the @samp{--members} option.  Tags for variables and functions in
+classes are named @samp{@var{class}::@var{variable}} and
+@samp{@var{class}::@var{function}}.  @code{operator} definitions have
+tag names like @samp{operator+}.
+
+@item
+In Java code, tags include all the constructs recognized in C++, plus
+the @code{interface}, @code{extends} and @code{implements} constructs.
+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},
+@code{\section}, @code{\subsection}, @code{\subsubsection},
+@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
+@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
+tag.@refill
+
+Other commands can make tags as well, if you specify them in the
+environment variable @env{TEXTAGS} before invoking @code{etags}.  The
+value of this environment variable should be a colon-separated list of
+command names.  For example,
+
+@example
+TEXTAGS="def:newcommand:newenvironment"
+export TEXTAGS
+@end example
+
+@noindent
+specifies (using Bourne shell syntax) that the commands @samp{\def},
+@samp{\newcommand} and @samp{\newenvironment} also define tags.
+
+@item
+In Lisp code, any function defined with @code{defun}, any variable
+defined with @code{defvar} or @code{defconst}, and in general the first
+argument of any expression that starts with @samp{(def} in column zero, is
+a tag.
+
+@item
+In Scheme code, tags include anything defined with @code{def} or with a
+construct whose name starts with @samp{def}.  They also include variables
+set with @code{set!} at top level in the file.
+@end itemize
+
+  Several other languages are also supported:
+
+@itemize @bullet
+
+@item
+In Ada code, functions, procedures, packages, tasks, and types are
+tags.  Use the @samp{--packages-only} option to create tags for
+packages only.
+
+In Ada, the same name can be used for different kinds of entity
+(e.g.@:, for a procedure and for a function).  Also, for things like
+packages, procedures and functions, there is the spec (i.e.@: the
+interface) and the body (i.e.@: the implementation).  To make it
+easier to pick the definition you want, Ada tag name have suffixes
+indicating the type of entity:
+
+@table @samp
+@item /b
+package body.
+@item /f
+function.
+@item /k
+task.
+@item /p
+procedure.
+@item /s
+package spec.
+@item /t
+type.
+@end table
+
+  Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
+directly to the body of the package @code{bidule}, while @kbd{M-x
+find-tag @key{RET} bidule @key{RET}} will just search for any tag
+@code{bidule}.
+
+@item
+In assembler code, labels appearing at the beginning of a line,
+followed by a colon, are tags.
+
+@item
+In Bison or Yacc input files, each rule defines as a tag the nonterminal
+it constructs.  The portions of the file that contain C code are parsed
+as C code.
+
+@item
+In Cobol code, tags are paragraph names; that is, any word starting in
+column 8 and followed by a period.
+
+@item
+In Erlang code, the tags are the functions, records, and macros defined
+in the file.
+
+@item
+In Fortran code, functions, subroutines and blockdata are tags.
+
+@item
+In makefiles, targets are tags.
+
+@item
+In Objective C code, tags include Objective C definitions for classes,
+class categories, methods, and protocols.
+
+@item
+In Pascal code, the tags are the functions and procedures defined in
+the file.
+
+@item
+In Perl code, the tags are the procedures defined by the @code{sub},
+@code{my} and @code{local} keywords.  Use @samp{--globals} if you want
+to tag global variables.
+
+@item
+In PostScript code, the tags are the functions.
+
+@item
+In Prolog code, a tag name appears at the left margin.
+
+@item
+In Python code, @code{def} or @code{class} at the beginning of a line
+generate a tag.
+@end itemize
+
+  You can also generate tags based on regexp matching (@pxref{Etags
+Regexps}) to handle other formats and languages.
+
+@node Create Tags Table
+@subsection Creating Tags Tables
+@cindex @code{etags} program
+
+  The @code{etags} program is used to create a tags table file.  It knows
+the syntax of several languages, as described in
+@iftex
+the previous section.
+@end iftex
+@ifinfo
+@ref{Tag Syntax}.
+@end ifinfo
+Here is how to run @code{etags}:
+
+@example
+etags @var{inputfiles}@dots{}
+@end example
+
+@noindent
+The @code{etags} program reads the specified files, and writes a tags
+table named @file{TAGS} in the current working directory.
+
+  If the specified files don't exist, @code{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}
+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.  But it is not necessary to do
+this very often.
+
+  If the tags table fails to record a tag, or records it for the wrong
+file, then Emacs cannot possibly find its definition.  However, if the
+position recorded in the tags table becomes a little bit wrong (due to
+some editing in the file that the tag definition is in), the only
+consequence is a slight delay in finding the tag.  Even if the stored
+position is very wrong, Emacs will still find the tag, but it must
+search the entire file for it.
+
+  So 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.  Normally there is no need to update
+the tags table after each edit, or even every day.
+
+  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.
+
+  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
+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 you specify absolute file names as arguments to @code{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:
+
+@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}).
+
+  @samp{etags --help} prints the list of the languages @code{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
+explanation.
+
+@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 it with file names.
+Each @samp{--regex} option adds to the preceding ones, and applies only
+to the following files.  The syntax is:
+
+@smallexample
+--regex=/@var{tagregexp}[/@var{nameregexp}]/
+@end smallexample
+
+@noindent
+where @var{tagregexp} is used to match the lines to tag.  It is always
+anchored, that is, it behaves as if preceded by @samp{^}.  If you want
+to account for indentation, just match any initial number of blanks by
+beginning your regular expression with @samp{[ \t]*}.  In the regular
+expressions, @samp{\} quotes the next character, and @samp{\t} stands
+for the tab character.  Note that @code{etags} does not handle the other
+C escape sequences for special characters.
+
+@cindex interval operator (in regexps)
+  The syntax of regular expressions in @code{etags} is the same as in
+Emacs, augmented with the @dfn{interval operator}, which works as in
+@code{grep} and @code{ed}.  The syntax of an interval operator is
+@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
+expression at least @var{m} times and up to @var{n} times.
+
+  You should not match more characters with @var{tagregexp} than that
+needed to recognize what you want to tag.  If the match is such that
+more characters than needed are unavoidably matched by @var{tagregexp}
+(as will usually be the case), you should add a @var{nameregexp}, to
+pick out just the tag.  This will enable Emacs to find tags more
+accurately and to do completion on tag names more reliably.  You can
+find some examples below.
+
+  The option @samp{--ignore-case-regex} (or @samp{-c}) works like
+@samp{--regex}, except that matching ignores case.  This is
+appropriate for certain programming languages.
+
+  The @samp{-R} option deletes all the regexps defined with
+@samp{--regex} options.  It applies to the file names following it, as
+you can see from the following example:
+
+@smallexample
+etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
+    bar.ber -R --lang=lisp los.er
+@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
+@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}.  @code{etags} uses the Lisp tags rules, and no regexp
+matching, to recognize tags in @file{los.er}.
+
+  You can specify a regular expression for a particular language, by
+writing @samp{@{lang@}} in front of it.  Then @code{etags} will use
+the regular expression only for files of that language.  (@samp{etags
+--help} prints the list of languages recognised by @code{etags}.)  The
+following example tags the @code{DEFVAR} macros in the Emacs source
+files, for the C language only:
+
+@smallexample
+--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+@end smallexample
+
+@noindent
+This feature is particularly useful when you store a list of regular
+expressions in a file.  The following option syntax instructs
+@code{etags} to read two files of regular expressions.  The regular
+expressions contained in the second file are matched without regard to
+case.
+
+@smallexample
+--regex=@@first-file --ignore-case-regex=@@second-file
+@end smallexample
+
+@noindent
+A regex file contains one regular expressions 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 that the rest
+of the line is the name of a 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 non-whitespace text on the line
+is @samp{--}, that line is a comment.
+
+  For example, one can create a file called @samp{emacs.tags} with the
+following contents:
+
+@smallexample
+        -- This is for GNU Emacs C source files
+@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+@end smallexample
+
+@noindent
+and then use it like this:
+
+@smallexample
+etags --regex=@@emacs.tags *.[ch] */*.[ch]
+@end smallexample
+
+  Here are some more examples.  The regexps are quoted to protect them
+from shell interpretation.
+
+@itemize @bullet
+
+@item
+Tag Octave files:
+
+@smallexample
+etags --language=none \
+      --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+      --regex='/###key \(.*\)/\1/' \
+      --regex='/[ \t]*global[ \t].*/' \
+      *.m
+@end smallexample
+
+@noindent
+Note that tags are not generated for scripts, so that you have to add
+a line by yourself of the form @samp{###key @var{scriptname}} if you
+want to jump to it.
+
+@item
+Tag Tcl files:
+
+@smallexample
+etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+@end smallexample
+
+@item
+Tag VHDL files:
+
+@smallexample
+etags --language=none \
+  --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+  --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+  \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+@end smallexample
+@end itemize
+
+@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 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.  The name @file{TAGS} in the default directory is used as the
+default file name.
+
+  All this command does is store the file name in the variable
+@code{tags-file-name}.  Emacs does not actually read in the tags table
+contents until you try to use them.  Setting this variable yourself is just
+as good as using @code{visit-tags-table}.  The variable's initial value is
+@code{nil}; that value tells all the commands for working with tags tables
+that they must ask for a tags table file name to use.
+
+  Using @code{visit-tags-table} when a tags table is already loaded
+gives you a choice: you can add the new tags table to the current list
+of tags tables, or start a new list.  The tags commands use all the tags
+tables in the current list.  If you start a new list, the new tags table
+is used @emph{instead} of others.  If you add the new table to the
+current list, it is used @emph{as well as} the others.  When the tags
+commands scan the list of tags tables, they don't always start at the
+beginning of the list; they start with the first tags table (if any)
+that describes the current file, proceed from there to the end of the
+list, and then scan from the beginning of the list until they have
+covered all the tables in the list.
+
+@vindex tags-table-list
+  You can specify a precise list of tags tables by setting the variable
+@code{tags-table-list} to a list of strings, like this:
+
+@c keep this on two lines for formatting in smallbook
+@example
+@group
+(setq tags-table-list
+      '("~/emacs" "/usr/local/lib/emacs/src"))
+@end group
+@end example
+
+@noindent
+This tells the tags commands to look at the @file{TAGS} files in your
+@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
+directory.  The order depends on which file you are in and which tags
+table mentions that file, as explained above.
+
+  Do not set both @code{tags-file-name} and @code{tags-table-list}.
+
+@node Find Tag
+@subsection Finding a Tag
+
+  The most important thing that a tags table enables you to do is to find
+the definition of a specific tag.
+
+@table @kbd
+@item M-.@: @var{tag} @key{RET}
+Find first definition of @var{tag} (@code{find-tag}).
+@item C-u M-.
+Find next alternate definition of last tag specified.
+@item C-u - M-.
+Go back to previous tag found.
+@item C-M-. @var{pattern} @key{RET}
+Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
+@item C-u C-M-.
+Find the next tag whose name matches the last pattern used.
+@item C-x 4 .@: @var{tag} @key{RET}
+Find first definition of @var{tag}, but display it in another window
+(@code{find-tag-other-window}).
+@item C-x 5 .@: @var{tag} @key{RET}
+Find first definition of @var{tag}, and create a new frame to select the
+buffer (@code{find-tag-other-frame}).
+@item M-*
+Pop back to where you previously invoked @kbd{M-.} and friends.
+@end table
+
+@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}.
+
+  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-.}.
+
+@kindex C-x 4 .
+@findex find-tag-other-window
+@kindex C-x 5 .
+@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 @kbd{C-x 4 .}, which invokes
+the command @code{find-tag-other-window}.  The latter is @kbd{C-x 5 .},
+which invokes @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.  @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-*}.
+
+  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}.
+
+@findex find-tag-regexp
+@kindex C-M-.
+  The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
+match a specified regular expression.  It is just like @kbd{M-.} except
+that it does regexp matching instead of substring matching.
+
+@node Tags Search
+@subsection Searching and Replacing with Tags Tables
+@cindex search and replace in multiple files
+@cindex multiple-file search and replace
+
+  The commands in this section visit and search all the files listed in the
+selected tags table, one by one.  For these commands, the tags table serves
+only to specify a sequence of files to search.
+
+@table @kbd
+@item M-x tags-search @key{RET} @var{regexp} @key{RET}
+Search for @var{regexp} through the files in the selected tags
+table.
+@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
+Perform a @code{query-replace-regexp} on each file in the selected tags table.
+@item M-,
+Restart one of the commands above, from the current location of point
+(@code{tags-loop-continue}).
+@end table
+
+@findex tags-search
+  @kbd{M-x tags-search} reads a regexp using the minibuffer, then
+searches for matches in all the files in the selected tags table, one
+file at a time.  It displays the name of the file being searched so you
+can follow its progress.  As soon as it finds an occurrence,
+@code{tags-search} returns.
+
+@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
+
+@findex tags-query-replace
+  @kbd{M-x tags-query-replace} performs a single
+@code{query-replace-regexp} through all the files in the tags table.  It
+reads a regexp to search for and a string to replace with, just like
+ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
+tags-search}, but repeatedly, processing matches according to your
+input.  @xref{Replace}, for more information on query replace.
+
+@vindex tags-case-fold-search
+@cindex case-sensitivity and tags search
+  You can control the case-sensitivity of tags search commands by
+customizing the value of the variable @code{tags-case-fold-search}.  The
+default is to use the same setting as the value of
+@code{case-fold-search} (@pxref{Search Case}).
+
+  It is possible to get through all the files in the tags table with a
+single invocation of @kbd{M-x tags-query-replace}.  But often it is
+useful to exit temporarily, which you can do with any input event that
+has no special query replace meaning.  You can resume the query replace
+subsequently by typing @kbd{M-,}; this command resumes the last tags
+search or replace command that you did.
+
+  The commands in this section carry out much broader searches than the
+@code{find-tag} family.  The @code{find-tag} commands search only for
+definitions of tags that match your substring or regexp.  The commands
+@code{tags-search} and @code{tags-query-replace} find every occurrence
+of the regexp, as ordinary search commands and replace commands do in
+the current buffer.
+
+  These commands create buffers only temporarily for the files that they
+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.  This works
+much like running a compilation; finding the source locations of the
+@code{grep} matches works like finding the compilation errors.
+@xref{Compilation}.
+
+@node List Tags
+@subsection Tags Table Inquiries
+
+@table @kbd
+@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
+
+@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.
+
+@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 with the face
+@code{tags-tag-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}.
+
+@node Emerge, C Modes, Imenu, Programs
+@section Merging Files with Emerge
+@cindex Emerge
+@cindex merging files
+
+It's not unusual for programmers to get their signals crossed and modify
+the same program in two different directions.  To recover from this
+confusion, you need to merge the two versions.  Emerge makes this
+easier.  See also @ref{Comparing Files}, for commands to compare
+in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
+
+@menu
+* Overview of Emerge::	How to start Emerge.  Basic concepts.
+* Submodes of Emerge::	Fast mode vs. Edit mode.
+			  Skip Prefers mode and Auto Advance mode.
+* State of Difference::	You do the merge by specifying state A or B
+			  for each difference.
+* Merge Commands::	Commands for selecting a difference,
+			  changing states of differences, etc.
+* Exiting Emerge::	What to do when you've finished the merge.
+* Combining in Emerge::	    How to keep both alternatives for a difference.
+* Fine Points of Emerge::   Misc.
+@end menu
+
+@node Overview of Emerge
+@subsection Overview of Emerge
+
+To start Emerge, run one of these four commands:
+
+@table @kbd
+@item M-x emerge-files
+@findex emerge-files
+Merge two specified files.
+
+@item M-x emerge-files-with-ancestor
+@findex emerge-files-with-ancestor
+Merge two specified files, with reference to a common ancestor.
+
+@item M-x emerge-buffers
+@findex emerge-buffers
+Merge two buffers.
+
+@item M-x emerge-buffers-with-ancestor
+@findex emerge-buffers-with-ancestor
+Merge two buffers with reference to a common ancestor in a third
+buffer.
+@end table
+
+@cindex merge buffer (Emerge)
+@cindex A and B buffers (Emerge)
+  The Emerge commands compare two files or buffers, and display the
+comparison in three buffers: one for each input text (the @dfn{A buffer}
+and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
+takes place.  The merge buffer shows the full merged text, not just the
+differences.  Wherever the two input texts differ, you can choose which
+one of them to include in the merge buffer.
+
+  The Emerge commands that take input from existing buffers use only the
+accessible portions of those buffers, if they are narrowed
+(@pxref{Narrowing}).
+
+  If a common ancestor version is available, from which the two texts to
+be merged were both derived, Emerge can use it to guess which
+alternative is right.  Wherever one current version agrees with the
+ancestor, Emerge presumes that the other current version is a deliberate
+change which should be kept in the merged version.  Use the
+@samp{with-ancestor} commands if you want to specify a common ancestor
+text.  These commands read three file or buffer names---variant A,
+variant B, and the common ancestor.
+
+  After the comparison is done and the buffers are prepared, the
+interactive merging starts.  You control the merging by typing special
+@dfn{merge commands} in the merge buffer.  The merge buffer shows you a
+full merged text, not just differences.  For each run of differences
+between the input texts, you can choose which one of them to keep, or
+edit them both together.
+
+  The merge buffer uses a special major mode, Emerge mode, with commands
+for making these choices.  But you can also edit the buffer with
+ordinary Emacs commands.
+
+  At any given time, the attention of Emerge is focused on one
+particular difference, called the @dfn{selected} difference.  This
+difference is marked off in the three buffers like this:
+
+@example
+vvvvvvvvvvvvvvvvvvvv
+@var{text that differs}
+^^^^^^^^^^^^^^^^^^^^
+@end example
+
+@noindent
+Emerge numbers all the differences sequentially and the mode
+line always shows the number of the selected difference.
+
+  Normally, the merge buffer starts out with the A version of the text.
+But when the A version of a difference agrees with the common ancestor,
+then the B version is initially preferred for that difference.
+
+  Emerge leaves the merged text in the merge buffer when you exit.  At
+that point, you can save it in a file with @kbd{C-x C-w}.  If you give a
+numeric argument to @code{emerge-files} or
+@code{emerge-files-with-ancestor}, it reads the name of the output file
+using the minibuffer.  (This is the last file name those commands read.)
+Then exiting from Emerge saves the merged text in the output file.
+
+  Normally, Emerge commands save the output buffer in its file when you
+exit.  If you abort Emerge with @kbd{C-]}, the Emerge command does not
+save the output buffer, but you can save it yourself if you wish.
+
+@node Submodes of Emerge
+@subsection Submodes of Emerge
+
+  You can choose between two modes for giving merge commands: Fast mode
+and Edit mode.  In Fast mode, basic merge commands are single
+characters, but ordinary Emacs commands are disabled.  This is
+convenient if you use only merge commands.  In Edit mode, all merge
+commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
+commands are also available.  This allows editing the merge buffer, but
+slows down Emerge operations.
+
+  Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
+Fast mode.  The mode line indicates Edit and Fast modes with @samp{E}
+and @samp{F}.
+
+  Emerge has two additional submodes that affect how particular merge
+commands work: Auto Advance mode and Skip Prefers mode.
+
+  If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
+advance to the next difference.  This lets you go through the merge
+faster as long as you simply choose one of the alternatives from the
+input.  The mode line indicates Auto Advance mode with @samp{A}.
+
+  If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
+skip over differences in states prefer-A and prefer-B (@pxref{State of
+Difference}).  Thus you see only differences for which neither version
+is presumed ``correct.''  The mode line indicates Skip Prefers mode with
+@samp{S}.
+
+@findex emerge-auto-advance-mode
+@findex emerge-skip-prefers-mode
+  Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
+clear Auto Advance mode.  Use @kbd{s s}
+(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
+These commands turn on the mode with a positive argument, turns it off
+with a negative or zero argument, and toggle the mode with no argument.
+
+@node State of Difference
+@subsection State of a Difference
+
+  In the merge buffer, a difference is marked with lines of @samp{v} and
+@samp{^} characters.  Each difference has one of these seven states:
+
+@table @asis
+@item A
+The difference is showing the A version.  The @kbd{a} command always
+produces this state; the mode line indicates it with @samp{A}.
+
+@item B
+The difference is showing the B version.  The @kbd{b} command always
+produces this state; the mode line indicates it with @samp{B}.
+
+@item default-A
+@itemx default-B
+The difference is showing the A or the B state by default, because you
+haven't made a choice.  All differences start in the default-A state
+(and thus the merge buffer is a copy of the A buffer), except those for
+which one alternative is ``preferred'' (see below).
+
+When you select a difference, its state changes from default-A or
+default-B to plain A or B.  Thus, the selected difference never has
+state default-A or default-B, and these states are never displayed in
+the mode line.
+
+The command @kbd{d a} chooses default-A as the default state, and @kbd{d
+b} chooses default-B.  This chosen default applies to all differences
+which you haven't ever selected and for which no alternative is preferred.
+If you are moving through the merge sequentially, the differences you
+haven't selected are those following the selected one.  Thus, while
+moving sequentially, you can effectively make the A version the default
+for some sections of the merge buffer and the B version the default for
+others by using @kbd{d a} and @kbd{d b} between sections.
+
+@item prefer-A
+@itemx prefer-B
+The difference is showing the A or B state because it is
+@dfn{preferred}.  This means that you haven't made an explicit choice,
+but one alternative seems likely to be right because the other
+alternative agrees with the common ancestor.  Thus, where the A buffer
+agrees with the common ancestor, the B version is preferred, because
+chances are it is the one that was actually changed.
+
+These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
+
+@item combined
+The difference is showing a combination of the A and B states, as a
+result of the @kbd{x c} or @kbd{x C} commands.
+
+Once a difference is in this state, the @kbd{a} and @kbd{b} commands
+don't do anything to it unless you give them a numeric argument.
+
+The mode line displays this state as @samp{comb}.
+@end table
+
+@node Merge Commands
+@subsection Merge Commands
+
+  Here are the Merge commands for Fast mode; in Edit mode, precede them
+with @kbd{C-c C-c}:
+
+@table @kbd
+@item p
+Select the previous difference.
+
+@item n
+Select the next difference.
+
+@item a
+Choose the A version of this difference.
+
+@item b
+Choose the B version of this difference.
+
+@item C-u @var{n} j
+Select difference number @var{n}.
+
+@item .
+Select the difference containing point.  You can use this command in the
+merge buffer or in the A or B buffer.
+
+@item q
+Quit---finish the merge.
+
+@item C-]
+Abort---exit merging and do not save the output.
+
+@item f
+Go into Fast mode.  (In Edit mode, this is actually @kbd{C-c C-c f}.)
+
+@item e
+Go into Edit mode.
+
+@item l
+Recenter (like @kbd{C-l}) all three windows.
+
+@item -
+Specify part of a prefix numeric argument.
+
+@item @var{digit}
+Also specify part of a prefix numeric argument.
+
+@item d a
+Choose the A version as the default from here down in
+the merge buffer.
+
+@item d b
+Choose the B version as the default from here down in
+the merge buffer.
+
+@item c a
+Copy the A version of this difference into the kill ring.
+
+@item c b
+Copy the B version of this difference into the kill ring.
+
+@item i a
+Insert the A version of this difference at point.
+
+@item i b
+Insert the B version of this difference at point.
+
+@item m
+Put point and mark around the difference.
+
+@item ^
+Scroll all three windows down (like @kbd{M-v}).
+
+@item v
+Scroll all three windows up (like @kbd{C-v}).
+
+@item <
+Scroll all three windows left (like @kbd{C-x <}).
+
+@item >
+Scroll all three windows right (like @kbd{C-x >}).
+
+@item |
+Reset horizontal scroll on all three windows.
+
+@item x 1
+Shrink the merge window to one line.  (Use @kbd{C-u l} to restore it
+to full size.)
+
+@item x c
+Combine the two versions of this difference (@pxref{Combining in
+Emerge}).
+
+@item x f
+Show the names of the files/buffers Emerge is operating on, in a Help
+window.  (Use @kbd{C-u l} to restore windows.)
+
+@item x j
+Join this difference with the following one.
+(@kbd{C-u x j} joins this difference with the previous one.)
+
+@item x s
+Split this difference into two differences.  Before you use this
+command, position point in each of the three buffers at the place where
+you want to split the difference.
+
+@item x t
+Trim identical lines off the top and bottom of the difference.
+Such lines occur when the A and B versions are
+identical but differ from the ancestor version.
+@end table
+
+@node Exiting Emerge
+@subsection Exiting Emerge
+
+  The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
+the results into the output file if you specified one.  It restores the
+A and B buffers to their proper contents, or kills them if they were
+created by Emerge and you haven't changed them.  It also disables the
+Emerge commands in the merge buffer, since executing them later could
+damage the contents of the various buffers.
+
+  @kbd{C-]} aborts the merge.  This means exiting without writing the
+output file.  If you didn't specify an output file, then there is no
+real difference between aborting and finishing the merge.
+
+  If the Emerge command was called from another Lisp program, then its
+return value is @code{t} for successful completion, or @code{nil} if you
+abort.
+
+@node Combining in Emerge
+@subsection Combining the Two Versions
+
+  Sometimes you want to keep @emph{both} alternatives for a particular
+difference.  To do this, use @kbd{x c}, which edits the merge buffer
+like this:
+
+@example
+@group
+#ifdef NEW
+@var{version from A buffer}
+#else /* not NEW */
+@var{version from B buffer}
+#endif /* not NEW */
+@end group
+@end example
+
+@noindent
+@vindex emerge-combine-versions-template
+While this example shows C preprocessor conditionals delimiting the two
+alternative versions, you can specify the strings to use by setting
+the variable @code{emerge-combine-versions-template} to a string of your
+choice.  In the string, @samp{%a} says where to put version A, and
+@samp{%b} says where to put version B.  The default setting, which
+produces the results shown above, looks like this:
+
+@example
+@group
+"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
+@end group
+@end example
+
+@node Fine Points of Emerge
+@subsection Fine Points of Emerge
+
+  During the merge, you mustn't try to edit the A and B buffers yourself.
+Emerge modifies them temporarily, but ultimately puts them back the way
+they were.
+
+  You can have any number of merges going at once---just don't use any one
+buffer as input to more than one merge at once, since the temporary
+changes made in these buffers would get in each other's way.
+
+  Starting Emerge can take a long time because it needs to compare the
+files fully.  Emacs can't do anything else until @code{diff} finishes.
+Perhaps in the future someone will change Emerge to do the comparison in
+the background when the input files are large---then you could keep on
+doing other things with Emacs until Emerge is ready to accept
+commands.
+
+@vindex emerge-startup-hook
+  After setting up the merge, Emerge runs the hook
+@code{emerge-startup-hook} (@pxref{Hooks}).
+