This is ../info/emacs, produced by makeinfo version 4.0f from
emacs.texi.
This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.2.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs). The extensible self-documenting text editor.
END-INFO-DIR-ENTRY
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C)
1985,1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU
GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU
Manual," and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License."
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: emacs, Node: Lisp Eval, Next: External Lisp, Prev: Lisp Interaction, Up: Building
Evaluating Emacs-Lisp Expressions
=================================
Lisp programs intended to be run in Emacs should be edited in
Emacs-Lisp mode; this happens automatically for file names ending in
`.el'. By contrast, Lisp mode itself is used for editing Lisp programs
intended for other Lisp systems. To switch to Emacs-Lisp mode
explicitly, use the command `M-x emacs-lisp-mode'.
For testing of Lisp programs to run in Emacs, it is often useful to
evaluate part of the program as it is found in the Emacs buffer. For
example, after changing the text of a Lisp function definition,
evaluating the definition installs the change for future calls to the
function. Evaluation of Lisp expressions is also useful in any kind of
editing, for invoking noninteractive functions (functions that are not
commands).
`M-:'
Read a single Lisp expression in the minibuffer, evaluate it, and
print the value in the echo area (`eval-expression').
`C-x C-e'
Evaluate the Lisp expression before point, and print the value in
the echo area (`eval-last-sexp').
`C-M-x'
Evaluate the defun containing or after point, and print the value
in the echo area (`eval-defun').
`M-x eval-region'
Evaluate all the Lisp expressions in the region.
`M-x eval-current-buffer'
Evaluate all the Lisp expressions in the buffer.
`M-:' (`eval-expression') is the most basic command for evaluating a
Lisp expression interactively. It reads the expression using the
minibuffer, so you can execute any expression on a buffer regardless of
what the buffer contains. When the expression is evaluated, the current
buffer is once again the buffer that was current when `M-:' was typed.
In Emacs-Lisp mode, the key `C-M-x' is bound to the command
`eval-defun', which parses the defun containing or following point as a
Lisp expression and evaluates it. The value is printed in the echo
area. This command is convenient for installing in the Lisp environment
changes that you have just made in the text of a function definition.
`C-M-x' treats `defvar' expressions specially. Normally, evaluating
a `defvar' expression does nothing if the variable it defines already
has a value. But `C-M-x' unconditionally resets the variable to the
initial value specified in the `defvar' expression. `defcustom'
expressions are treated similarly. This special feature is convenient
for debugging Lisp programs.
The command `C-x C-e' (`eval-last-sexp') evaluates the Lisp
expression preceding point in the buffer, and displays the value in the
echo area. It is available in all major modes, not just Emacs-Lisp
mode. It does not treat `defvar' specially.
If `C-M-x', `C-x C-e', or `M-:' is given a numeric argument, it
inserts the value into the current buffer at point, rather than
displaying it in the echo area. The argument's value does not matter.
The most general command for evaluating Lisp expressions from a
buffer is `eval-region'. `M-x eval-region' parses the text of the
region as one or more Lisp expressions, evaluating them one by one.
`M-x eval-current-buffer' is similar but evaluates the entire buffer.
This is a reasonable way to install the contents of a file of Lisp code
that you are ready to test. Later, as you find bugs and change
individual functions, use `C-M-x' on each function that you change.
This keeps the Lisp world in step with the source file.
The customizable variables `eval-expression-print-level' and
`eval-expression-print-length' control the maximum depth and length of
lists to print in the result of the evaluation commands before
abbreviating them. `eval-expression-debug-on-error' controls whether
evaluation errors invoke the debugger when these commands are used.
File: emacs, Node: Lisp Interaction, Next: Lisp Eval, Prev: Lisp Libraries, Up: Building
Lisp Interaction Buffers
========================
The buffer `*scratch*' which is selected when Emacs starts up is
provided for evaluating Lisp expressions interactively inside Emacs.
The simplest way to use the `*scratch*' buffer is to insert Lisp
expressions and type `C-j' after each expression. This command reads
the Lisp expression before point, evaluates it, and inserts the value
in printed representation before point. The result is a complete
typescript of the expressions you have evaluated and their values.
The `*scratch*' buffer's major mode is Lisp Interaction mode, which
is the same as Emacs-Lisp mode except for the binding of `C-j'.
The rationale for this feature is that Emacs must have a buffer when
it starts up, but that buffer is not useful for editing files since a
new buffer is made for every file that you visit. The Lisp interpreter
typescript is the most useful thing I can think of for the initial
buffer to do. Type `M-x lisp-interaction-mode' to put the current
buffer in Lisp Interaction mode.
An alternative way of evaluating Emacs Lisp expressions interactively
is to use Inferior Emacs-Lisp mode, which provides an interface rather
like Shell mode (*note Shell Mode::) for evaluating Emacs Lisp
expressions. Type `M-x ielm' to create an `*ielm*' buffer which uses
this mode.
File: emacs, Node: External Lisp, Prev: Lisp Eval, Up: Building
Running an External Lisp
========================
Emacs has facilities for running programs in other Lisp systems.
You can run a Lisp process as an inferior of Emacs, and pass
expressions to it to be evaluated. You can also pass changed function
definitions directly from the Emacs buffers in which you edit the Lisp
programs to the inferior Lisp process.
To run an inferior Lisp process, type `M-x run-lisp'. This runs the
program named `lisp', the same program you would run by typing `lisp'
as a shell command, with both input and output going through an Emacs
buffer named `*lisp*'. That is to say, any "terminal output" from Lisp
will go into the buffer, advancing point, and any "terminal input" for
Lisp comes from text in the buffer. (You can change the name of the
Lisp executable file by setting the variable `inferior-lisp-program'.)
To give input to Lisp, go to the end of the buffer and type the
input, terminated by <RET>. The `*lisp*' buffer is in Inferior Lisp
mode, which combines the special characteristics of Lisp mode with most
of the features of Shell mode (*note Shell Mode::). The definition of
<RET> to send a line to a subprocess is one of the features of Shell
mode.
For the source files of programs to run in external Lisps, use Lisp
mode. This mode can be selected with `M-x lisp-mode', and is used
automatically for files whose names end in `.l', `.lsp', or `.lisp', as
most Lisp systems usually expect.
When you edit a function in a Lisp program you are running, the
easiest way to send the changed definition to the inferior Lisp process
is the key `C-M-x'. In Lisp mode, this runs the function
`lisp-eval-defun', which finds the defun around or following point and
sends it as input to the Lisp process. (Emacs can send input to any
inferior process regardless of what buffer is current.)
Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
programs to be run in Emacs): in both modes it has the effect of
installing the function definition that point is in, but the way of
doing so is different according to where the relevant Lisp environment
is found. *Note Executing Lisp::.
File: emacs, Node: Maintaining, Next: Abbrevs, Prev: Building, Up: Top
Maintaining Programs
********************
This chapter describes Emacs features for maintaining programs. The
version control features (*note Version Control::) are also
particularly useful for this purpose.
* Menu:
* Change Log:: Maintaining a change history for your program.
* 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.
File: emacs, Node: Change Log, Next: Tags, Up: Maintaining
Change Logs
===========
The Emacs command `C-x 4 a' adds a new entry to the change log file
for the file you are editing (`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 `ChangeLog'
in the same directory as the file you are editing, or one of its parent
directories. A single `ChangeLog' file can record changes for all the
files in its directory and all its subdirectories.
You should put a copyright notice and permission notice at the end
of the change log file. Here is an example:
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.
Of course, you should substitute the proper years and copyright holder.
A change log entry starts with a header line that contains the
current date, your name, and your email address (taken from the
variable `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 "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:
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.
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.
`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.
When the option `add-log-keep-changes-together' is non-`nil', `C-x 4
a' adds to any existing entry for the file rather than starting a new
entry.
If the value of the variable `change-log-version-info-enabled' is
non-`nil', `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
`change-log-version-number-regexp-list'.
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.
`C-j' and auto-fill indent each new line like the previous line; this
is convenient for entering the contents of an entry.
You can use the command `M-x change-log-merge' to merge other log
files into a buffer in Change Log Mode, preserving the date ordering of
entries.
Versions of Emacs before 20.1 used a different format for the time of
the change log entry:
Fri May 25 11:23:23 1993 Richard Stallman <rms@gnu.org>
The `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. *Note Log Buffer::.
File: emacs, Node: Tags, Next: Emerge, Prev: Change Log, Up: Maintaining
Tags Tables
===========
A "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 `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 "tags table files". The
conventional name for a tags table file is `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 "tag".
See also the Ebrowse facility, which is tailored for C++. *Note
Ebrowse: (ebrowse)Top.
* Menu:
* Tag Syntax:: Tag syntax for various types of code and text files.
* Create Tags Table:: Creating a tags table with `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.
File: emacs, Node: Tag Syntax, Next: Create Tags Table, Up: Tags
Source File Tag Syntax
----------------------
Here is how tag syntax is defined for the most popular languages:
* In C code, any C function or typedef is a tag, and so are
definitions of `struct', `union' and `enum'. `#define' macro
definitions and `enum' constants are also tags, unless you specify
`--no-defines' when making the tags table. Similarly, global
variables are tags, unless you specify `--no-globals'. Use of
`--no-globals' and `--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 `--declarations'
option to `etags'.
* 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 `--members' option. Tags for variables
and functions in classes are named `CLASS::VARIABLE' and
`CLASS::FUNCTION'. `operator' definitions have tag names like
`operator+'.
* In Java code, tags include all the constructs recognized in C++,
plus the `interface', `extends' and `implements' constructs. Tags
for variables and functions in classes are named `CLASS.VARIABLE'
and `CLASS.FUNCTION'.
* In LaTeX text, the argument of any of the commands `\chapter',
`\section', `\subsection', `\subsubsection', `\eqno', `\label',
`\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
`\index', is a tag.
Other commands can make tags as well, if you specify them in the
environment variable `TEXTAGS' before invoking `etags'. The value
of this environment variable should be a colon-separated list of
command names. For example,
TEXTAGS="def:newcommand:newenvironment"
export TEXTAGS
specifies (using Bourne shell syntax) that the commands `\def',
`\newcommand' and `\newenvironment' also define tags.
* In Lisp code, any function defined with `defun', any variable
defined with `defvar' or `defconst', and in general the first
argument of any expression that starts with `(def' in column zero,
is a tag.
* In Scheme code, tags include anything defined with `def' or with a
construct whose name starts with `def'. They also include
variables set with `set!' at top level in the file.
Several other languages are also supported:
* In Ada code, functions, procedures, packages, tasks, and types are
tags. Use the `--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:
`/b'
package body.
`/f'
function.
`/k'
task.
`/p'
procedure.
`/s'
package spec.
`/t'
type.
Thus, `M-x find-tag <RET> bidule/b <RET>' will go directly to the
body of the package `bidule', while `M-x find-tag <RET> bidule
<RET>' will just search for any tag `bidule'.
* In assembler code, labels appearing at the beginning of a line,
followed by a colon, are tags.
* 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.
* In Cobol code, tags are paragraph names; that is, any word
starting in column 8 and followed by a period.
* In Erlang code, the tags are the functions, records, and macros
defined in the file.
* In Fortran code, functions, subroutines and block data are tags.
* In makefiles, targets are tags.
* In Objective C code, tags include Objective C definitions for
classes, class categories, methods, and protocols.
* In Pascal code, the tags are the functions and procedures defined
in the file.
* In Perl code, the tags are the procedures defined by the `sub',
`my' and `local' keywords. Use `--globals' if you want to tag
global variables.
* In PostScript code, the tags are the functions.
* In Prolog code, a tag name appears at the left margin.
* In Python code, `def' or `class' at the beginning of a line
generate a tag.
You can also generate tags based on regexp matching (*note Etags
Regexps::) to handle other formats and languages.
File: emacs, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags
Creating Tags Tables
--------------------
The `etags' program is used to create a tags table file. It knows
the syntax of several languages, as described in *Note Tag Syntax::.
Here is how to run `etags':
etags INPUTFILES...
The `etags' program reads the specified files, and writes a tags table
named `TAGS' in the current working directory.
If the specified files don't exist, `etags' looks for compressed
versions of them and uncompresses them to read them. Under MS-DOS,
`etags' also looks for file names like `mycode.cgz' if it is given
`mycode.c' on the command line and `mycode.c' does not exist.
`etags' recognizes the language used in an input file based on its
file name and contents. You can specify the language with the
`--language=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 only 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. Even that delay
is hardly noticeable with today's computers.
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 `--include=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
`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 `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
`/', or with `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 `etags' to read the file names from its standard input, by
typing a dash in place of the file names, like this:
find . -name "*.[chCH]" -print | etags -
Use the option `--language=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 `--language=auto' to tell
`etags' to resume guessing the language from the file names and file
contents. Specify `--language=none' to turn off language-specific
processing entirely; then `etags' recognizes tags by regexp matching
alone (*note Etags Regexps::).
`etags --help' prints the list of the languages `etags' knows, and
the file name rules for guessing the language. It also prints a list
of all the available `etags' options, together with a short explanation.
File: emacs, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags
Etags Regexps
-------------
The `--regex' option provides a general way of recognizing tags
based on regexp matching. You can freely intermix it with file names.
Each `--regex' option adds to the preceding ones, and applies only to
the following files. The syntax is:
--regex=/TAGREGEXP[/NAMEREGEXP]/
where TAGREGEXP is used to match the lines to tag. It is always
anchored, that is, it behaves as if preceded by `^'. If you want to
account for indentation, just match any initial number of blanks by
beginning your regular expression with `[ \t]*'. In the regular
expressions, `\' quotes the next character, and `\t' stands for the tab
character. Note that `etags' does not handle the other C escape
sequences for special characters.
The syntax of regular expressions in `etags' is the same as in
Emacs, augmented with the "interval operator", which works as in `grep'
and `ed'. The syntax of an interval operator is `\{M,N\}', and its
meaning is to match the preceding expression at least M times and up to
N times.
You should not match more characters with 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 TAGREGEXP (as will
usually be the case), you should add a 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 `--ignore-case-regex' (or `-c') works like `--regex',
except that matching ignores case. This is appropriate for certain
programming languages.
The `-R' option deletes all the regexps defined with `--regex'
options. It applies to the file names following it, as you can see
from the following example:
etags --regex=/REG1/ voo.doo --regex=/REG2/ \
bar.ber -R --lang=lisp los.er
Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
according to their contents. `etags' also uses REG1 to recognize
additional tags in `voo.doo', and both REG1 and REG2 to recognize
additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
regexp matching, to recognize tags in `los.er'.
You can specify a regular expression for a particular language, by
writing `{lang}' in front of it. Then `etags' will use the regular
expression only for files of that language. (`etags --help' prints the
list of languages recognized by `etags'.) The following example tags
the `DEFVAR' macros in the Emacs source files, for the C language only:
--regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
This feature is particularly useful when you store a list of regular
expressions in a file. The following option syntax instructs `etags'
to read two files of regular expressions. The regular expressions
contained in the second file are matched without regard to case.
--regex=@first-file --ignore-case-regex=@second-file
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 `@', `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 `--',
that line is a comment.
For example, one can create a file called `emacs.tags' with the
following contents:
-- This is for GNU Emacs C source files
{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
and then use it like this:
etags --regex=@emacs.tags *.[ch] */*.[ch]
Here are some more examples. The regexps are quoted to protect them
from shell interpretation.
* Tag Octave files:
etags --language=none \
--regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
--regex='/###key \(.*\)/\1/' \
--regex='/[ \t]*global[ \t].*/' \
*.m
Note that tags are not generated for scripts, so that you have to
add a line by yourself of the form `###key SCRIPTNAME' if you want
to jump to it.
* Tag Tcl files:
etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
* Tag VHDL files:
etags --language=none \
--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
File: emacs, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
Selecting a Tags Table
----------------------
Emacs has at any time one "selected" tags table, and all the commands
for working with tags tables use the selected one. To select a tags
table, type `M-x visit-tags-table', which reads the tags table file
name as an argument. The name `TAGS' in the default directory is used
as the default file name.
All this command does is store the file name in the variable
`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 `visit-tags-table'. The variable's initial value
is `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 `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 _instead_ of others. If you add the new table to the current
list, it is used _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.
You can specify a precise list of tags tables by setting the variable
`tags-table-list' to a list of strings, like this:
(setq tags-table-list
'("~/emacs" "/usr/local/lib/emacs/src"))
This tells the tags commands to look at the `TAGS' files in your
`~/emacs' directory and in the `/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 `tags-file-name' and `tags-table-list'.
File: emacs, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags
Finding a Tag
-------------
The most important thing that a tags table enables you to do is to
find the definition of a specific tag.
`M-. TAG <RET>'
Find first definition of TAG (`find-tag').
`C-u M-.'
Find next alternate definition of last tag specified.
`C-u - M-.'
Go back to previous tag found.
`C-M-. PATTERN <RET>'
Find a tag whose name matches PATTERN (`find-tag-regexp').
`C-u C-M-.'
Find the next tag whose name matches the last pattern used.
`C-x 4 . TAG <RET>'
Find first definition of TAG, but display it in another window
(`find-tag-other-window').
`C-x 5 . TAG <RET>'
Find first definition of TAG, and create a new frame to select the
buffer (`find-tag-other-frame').
`M-*'
Pop back to where you previously invoked `M-.' and friends.
`M-.' (`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 `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 <RET>), the balanced
expression in the buffer before or around point is used as the TAG
argument. *Note Expressions::.
You don't need to give `M-.' the full name of the tag; a part will
do. This is because `M-.' finds tags in the table which contain TAG as
a substring. However, it prefers an exact match to a substring match.
To find other tags that match the same substring, give `find-tag' a
numeric argument, as in `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 <META> key, `M-0 M-.'
is an easier alternative to `C-u M-.'.
Like most commands that can switch buffers, `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 `C-x 4 .', which invokes the command
`find-tag-other-window'. The latter is `C-x 5 .', which invokes
`find-tag-other-frame'.
To move back to places you've found tags recently, use `C-u - M-.';
more generally, `M-.' with a negative numeric argument. This command
can take you to another buffer. `C-x 4 .' with a negative argument
finds the previous tag location in another window.
As well as going back to places you've found tags recently, you can
go back to places _from where_ you found them. Use `M-*', which
invokes the command `pop-tag-mark', for this. Typically you would find
and study the definition of something with `M-.' and then return to
where you were with `M-*'.
Both `C-u - M-.' and `M-*' allow you to retrace your steps to a
depth determined by the variable `find-tag-marker-ring-length'.
The command `C-M-.' (`find-tag-regexp') visits the tags that match a
specified regular expression. It is just like `M-.' except that it
does regexp matching instead of substring matching.
File: emacs, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags
Searching and Replacing with Tags Tables
----------------------------------------
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.
`M-x tags-search <RET> REGEXP <RET>'
Search for REGEXP through the files in the selected tags table.
`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
Perform a `query-replace-regexp' on each file in the selected tags
table.
`M-,'
Restart one of the commands above, from the current location of
point (`tags-loop-continue').
`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, `tags-search'
returns.
Having found one match, you probably want to find all the rest. To
find one more match, type `M-,' (`tags-loop-continue') to resume the
`tags-search'. This searches the rest of the current buffer, followed
by the remaining files of the tags table.
`M-x tags-query-replace' performs a single `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 `M-x
query-replace-regexp'. It searches much like `M-x tags-search', but
repeatedly, processing matches according to your input. *Note
Replace::, for more information on query replace.
You can control the case-sensitivity of tags search commands by
customizing the value of the variable `tags-case-fold-search'. The
default is to use the same setting as the value of `case-fold-search'
(*note Search Case::).
It is possible to get through all the files in the tags table with a
single invocation of `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 `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
`find-tag' family. The `find-tag' commands search only for definitions
of tags that match your substring or regexp. The commands
`tags-search' and `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 `tags-search' is a lot like `grep'. You
can also run `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 `grep' matches works
like finding the compilation errors. *Note Compilation::.
File: emacs, Node: List Tags, Prev: Tags Search, Up: Tags
Tags Table Inquiries
--------------------
`M-x list-tags <RET> FILE <RET>'
Display a list of the tags defined in the program file FILE.
`M-x tags-apropos <RET> REGEXP <RET>'
Display a list of all tags matching REGEXP.
`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.
`M-x tags-apropos' is like `apropos' for tags (*note Apropos::). It
finds all the tags in the selected tags table whose entries match
REGEXP, and displays them. If the variable `tags-apropos-verbose' is
non-`nil', it displays the names of the tags files together with the
tag names.
You can customize the appearance of the output with the face
`tags-tag-face'. You can display additional output with `M-x
tags-apropos' by customizing the variable
`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. *Note Symbol Completion::.
File: emacs, Node: Emerge, Prev: Tags, Up: Maintaining
Merging Files with Emerge
=========================
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 *Note Comparing Files::, for commands to compare in a
more manual fashion, and *Note Ediff: (ediff)Top.
* 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.
File: emacs, Node: Overview of Emerge, Next: Submodes of Emerge, Up: Emerge
Overview of Emerge
------------------
To start Emerge, run one of these four commands:
`M-x emerge-files'
Merge two specified files.
`M-x emerge-files-with-ancestor'
Merge two specified files, with reference to a common ancestor.
`M-x emerge-buffers'
Merge two buffers.
`M-x emerge-buffers-with-ancestor'
Merge two buffers with reference to a common ancestor in a third
buffer.
The Emerge commands compare two files or buffers, and display the
comparison in three buffers: one for each input text (the "A buffer"
and the "B buffer"), and one (the "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 (*note
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
`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
"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 "selected" difference. This
difference is marked off in the three buffers like this:
vvvvvvvvvvvvvvvvvvvv
TEXT THAT DIFFERS
^^^^^^^^^^^^^^^^^^^^
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 `C-x C-w'. If you give a
numeric argument to `emerge-files' or `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 `C-]', the Emerge command does not save
the output buffer, but you can save it yourself if you wish.
File: emacs, Node: Submodes of Emerge, Next: State of Difference, Prev: Overview of Emerge, Up: Emerge
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 `C-c C-c', and the normal Emacs
commands are also available. This allows editing the merge buffer, but
slows down Emerge operations.
Use `e' to switch to Edit mode, and `C-c C-c f' to switch to Fast
mode. The mode line indicates Edit and Fast modes with `E' and `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 `a' and `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 `A'.
If Skip Prefers mode is in effect, the `n' and `p' commands skip
over differences in states prefer-A and prefer-B (*note State of
Difference::). Thus you see only differences for which neither version
is presumed "correct." The mode line indicates Skip Prefers mode with
`S'.
Use the command `s a' (`emerge-auto-advance-mode') to set or clear
Auto Advance mode. Use `s s' (`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.
File: emacs, Node: State of Difference, Next: Merge Commands, Prev: Submodes of Emerge, Up: Emerge
State of a Difference
---------------------
In the merge buffer, a difference is marked with lines of `v' and
`^' characters. Each difference has one of these seven states:
A
The difference is showing the A version. The `a' command always
produces this state; the mode line indicates it with `A'.
B
The difference is showing the B version. The `b' command always
produces this state; the mode line indicates it with `B'.
default-A
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 `d a' chooses default-A as the default state, and `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 `d a' and `d b' between sections.
prefer-A
prefer-B
The difference is showing the A or B state because it is
"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 `A*' and `B*'.
combined
The difference is showing a combination of the A and B states, as a
result of the `x c' or `x C' commands.
Once a difference is in this state, the `a' and `b' commands don't
do anything to it unless you give them a numeric argument.
The mode line displays this state as `comb'.
File: emacs, Node: Merge Commands, Next: Exiting Emerge, Prev: State of Difference, Up: Emerge
Merge Commands
--------------
Here are the Merge commands for Fast mode; in Edit mode, precede them
with `C-c C-c':
`p'
Select the previous difference.
`n'
Select the next difference.
`a'
Choose the A version of this difference.
`b'
Choose the B version of this difference.
`C-u N j'
Select difference number N.
`.'
Select the difference containing point. You can use this command
in the merge buffer or in the A or B buffer.
`q'
Quit--finish the merge.
`C-]'
Abort--exit merging and do not save the output.
`f'
Go into Fast mode. (In Edit mode, this is actually `C-c C-c f'.)
`e'
Go into Edit mode.
`l'
Recenter (like `C-l') all three windows.
`-'
Specify part of a prefix numeric argument.
`DIGIT'
Also specify part of a prefix numeric argument.
`d a'
Choose the A version as the default from here down in the merge
buffer.
`d b'
Choose the B version as the default from here down in the merge
buffer.
`c a'
Copy the A version of this difference into the kill ring.
`c b'
Copy the B version of this difference into the kill ring.
`i a'
Insert the A version of this difference at point.
`i b'
Insert the B version of this difference at point.
`m'
Put point and mark around the difference.
`^'
Scroll all three windows down (like `M-v').
`v'
Scroll all three windows up (like `C-v').
`<'
Scroll all three windows left (like `C-x <').
`>'
Scroll all three windows right (like `C-x >').
`|'
Reset horizontal scroll on all three windows.
`x 1'
Shrink the merge window to one line. (Use `C-u l' to restore it
to full size.)
`x c'
Combine the two versions of this difference (*note Combining in
Emerge::).
`x f'
Show the names of the files/buffers Emerge is operating on, in a
Help window. (Use `C-u l' to restore windows.)
`x j'
Join this difference with the following one. (`C-u x j' joins
this difference with the previous one.)
`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.
`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.
File: emacs, Node: Exiting Emerge, Next: Combining in Emerge, Prev: Merge Commands, Up: Emerge
Exiting Emerge
--------------
The `q' command (`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.
`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 `t' for successful completion, or `nil' if you abort.