mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-24 10:38:38 +00:00
859 lines
34 KiB
Plaintext
859 lines
34 KiB
Plaintext
@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 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}. 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}. You can tag struct members with the @samp{--members}
|
|
option.
|
|
|
|
@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},
|
|
@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. When using the
|
|
@samp{--members} option, vars are tags too.
|
|
|
|
@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}.
|
|
|
|
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
|