Mercurial > emacs

--- a/man/maintaining.texi	Thu Sep 06 04:38:00 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,862 +0,0 @@
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c   2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Maintaining, Abbrevs, Building, Top
-@chapter Maintaining Large Programs
-
-  This chapter describes Emacs features for maintaining large
-programs.  The version control features (@pxref{Version Control}) are
-also particularly useful for this purpose.
-
-@menu
-* Change Log::	        Maintaining a change history for your program.
-* Format of ChangeLog:: What the change log file looks like.
-* Tags::	        Go direct to any function in your program in one
-			  command.  Tags remembers which file it is in.
-@ifnottex
-* Emerge::              A convenient way of merging two versions of a program.
-@end ifnottex
-@end menu
-
-@node Change Log
-@section Change Logs
-
-  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.
-
-@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.
-
-  @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 variable @code{add-log-keep-changes-together} is
-non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
-rather than starting a new item.
-
-@vindex add-log-always-start-new-record
-  If @code{add-log-always-start-new-record} is non-@code{nil},
-@kbd{C-x 4 a} always makes a new entry, even if the last entry
-was made by you and on the same date.
-
-@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.
-
-  Version control systems are another way to keep track of changes in your
-program and keep a change log.  @xref{Log Buffer}.
-
-@node Format of ChangeLog
-@section Format of ChangeLog
-
-  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{add-log-mailing-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, with two items and one item respectively.
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-1993-05-25  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.
-
-1993-05-24  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, or its own line in an 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.
-
-  You should put a copyright notice and permission notice at the
-end of the change log file.  Here is an example:
-
-@smallexample
-Copyright 1997, 1998 Free Software Foundation, Inc.
-Copying and distribution of this file, with or without modification, are
-permitted provided the copyright notice and this notice are preserved.
-@end smallexample
-
-@noindent
-Of course, you should substitute the proper years and copyright holder.
-
-@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.  When a file parsed by @code{etags} is
-generated from a different source file, like a C file generated from a
-Cweb source file, the tags of the parsed file reference the source
-file.
-
-  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, @code{#undef} 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}, and so are struct members, unless you specify
-@samp{--no-members}.  Use of @samp{--no-globals}, @samp{--no-defines}
-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}.
-
-@item
-In C++ code, in addition to all the tag constructs of C code, member
-functions are also recognized; member variables are also recognized,
-unless you use the @samp{--no-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},
-@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
-@code{\newenvironment} or @code{\renewenvironment} 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="mycommand:myothercommand"
-export TEXTAGS
-@end example
-
-@noindent
-specifies (using Bourne shell syntax) that the commands
-@samp{\mycommand} and @samp{\myothercommand} 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 block data are tags.
-
-@item
-In HTML input files, the tags are the @code{title} and the @code{h1},
-@code{h2}, @code{h3} headers.  Also, tags are @code{name=} in anchors
-and all occurrences of @code{id=}.
-
-@item
-In Lua input files, all functions are tags.
-
-@item
-In makefiles, targets are tags; additionally, variables are tags
-unless you specify @samp{--no-globals}.
-
-@item
-In Objective C code, tags include Objective C definitions for classes,
-class categories, methods and protocols.  Tags for variables and
-functions in classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}.
-
-@item
-In Pascal code, the tags are the functions and procedures defined in
-the file.
-
-@item
-In Perl code, the tags are the packages, subroutines and variables
-defined by the @code{package}, @code{sub}, @code{my} and @code{local}
-keywords.  Use @samp{--globals} if you want to tag global variables.
-Tags for subroutines are named @samp{@var{package}::@var{sub}}.  The
-name for subroutines defined in the default package is
-@samp{main::@var{sub}}.
-
-@item
-In PHP code, tags are functions, classes and defines.  Vars are tags
-too, unless you use the @samp{--no-members} option.
-
-@item
-In PostScript code, the tags are the functions.
-
-@item
-In Prolog code, tags are predicates and rules at the beginning of
-line.
-
-@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
-@ifnottex
-@ref{Tag Syntax}.
-@end ifnottex
-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.  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.
-
-   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.
-
-  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 the tags file is in @file{/dev}, 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}.
-
-  When using a relative file name, it should not be a symbolic link
-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
-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}).
-
-  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
-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}
-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.  If followed by one or more @samp{--language=@var{lang}}
-options, it outputs detailed information about how tags are generated for
-@var{lang}.
-
-@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:
-
-@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]*}.
-
-  In these regular expressions, @samp{\} quotes the next character, and
-all the GCC character escape sequences are supported (@samp{\a} for
-bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
-escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
-carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
-
-  Ideally, @var{tagregexp} should not match more characters than are
-needed to recognize what you want to tag.  If the syntax requires you
-to write @var{tagregexp} so it matches more characters beyond the tag
-itself, 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 @var{modifiers} are a sequence of zero or more characters that
-modify the way @code{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:
-
-@table @samp
-@item i
-Ignore case when matching this regexp.
-@item m
-Match this regular expression against the whole file, so that
-multi-line matches are possible.
-@item s
-Match this regular expression against the whole file, and allow
-@samp{.} in @var{tagregexp} to match newlines.
-@end table
-
-  The @samp{-R} option cancels all the regexps defined by preceding
-@samp{--regex} options.  It too applies to the file names following
-it.  Here's an example:
-
-@smallexample
-etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
-    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}.  @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}
-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
-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
-When you have complex regular expressions, you can store the list of
-them 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=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
-@end smallexample
-
-@noindent
-A regex file for @code{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
-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
-non-whitespace text on the line is @samp{--}, that line is a comment.
-
-  For example, we 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, with @file{TAGS} in the default
-directory as the default.
-
-  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
-yourself is just as good.  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.
-
-@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 @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}.
-
-  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.
-
-@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.  These
-commands scan the list of tags tables starting 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.
-
-@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.
-@xref{Grep Searching}.
-
-@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 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}.
-
-@ifnottex
-@include emerge-xtra.texi
-@end ifnottex
-
-@ignore
-   arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
-@end ignore