This is ../../info/emacs, produced by makeinfo version 4.13 from
emacs.texi.

This is the Sixteenth edition of the `GNU Emacs Manual',
updated for Emacs version 23.4.

   Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
2011, 2012  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.3 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 the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs).       The extensible self-documenting text editor.
END-INFO-DIR-ENTRY


File: emacs,  Node: GDB-UI Layout,  Next: Source Buffers,  Up: GDB Graphical Interface

31.6.5.1 GDB User Interface Layout
..................................

If the variable `gdb-many-windows' is `nil' (the default value) then
`M-x gdb' normally displays only the GUD buffer.  However, if the
variable `gdb-show-main' is also non-`nil', it starts with two windows:
one displaying the GUD buffer, and the other showing the source for the
`main' function of the program you are debugging.

   If `gdb-many-windows' is non-`nil', then `M-x gdb' displays the
following frame layout:

     +--------------------------------+--------------------------------+
     |   GUD buffer (I/O of GDB)      |   Locals/Registers buffer      |
     |--------------------------------+--------------------------------+
     |   Primary Source buffer        |   I/O buffer for debugged pgm  |
     |--------------------------------+--------------------------------+
     |   Stack buffer                 |   Breakpoints/Threads buffer   |
     +--------------------------------+--------------------------------+

   However, if `gdb-use-separate-io-buffer' is `nil', the I/O buffer
does not appear and the primary source buffer occupies the full width
of the frame.

   If you change the window layout, for example, while editing and
re-compiling your program, then you can restore this standard window
layout with the command `gdb-restore-windows'.

   To switch between this standard layout and a simple layout
containing just the GUD buffer and a source file, type `M-x
gdb-many-windows'.

   You may also specify additional GDB-related buffers to display,
either in the same frame or a different one.  Select the buffers you
want with the `GUD->GDB-Windows' and `GUD->GDB-Frames' sub-menus.  If
the menu-bar is unavailable, type `M-x gdb-display-BUFFERTYPE-buffer'
or `M-x gdb-frame-BUFFERTYPE-buffer' respectively, where BUFFERTYPE is
the relevant buffer type, such as `breakpoints'.  Most of these buffers
are read-only, and typing `q' in them kills them.

   When you finish debugging, kill the GUD buffer with `C-x k', which
will also kill all the buffers associated with the session.  However
you need not do this if, after editing and re-compiling your source
code within Emacs, you wish continue debugging.  When you restart
execution, GDB will automatically find your new executable.  Keeping
the GUD buffer has the advantage of keeping the shell history as well
as GDB's breakpoints.  You do need to check that the breakpoints in
recently edited source files are still in the right places.


File: emacs,  Node: Source Buffers,  Next: Breakpoints Buffer,  Prev: GDB-UI Layout,  Up: GDB Graphical Interface

31.6.5.2 Source Buffers
.......................

Many GDB commands can be entered using key bindings or the tool bar but
sometimes it is quicker to use the fringe.  These commands either
manipulate breakpoints or control program execution.  When there is no
fringe, you can use the margin but this is only present when the source
file already has a breakpoint.

   You can click `Mouse-1' in the fringe or display margin of a source
buffer to set a breakpoint there and, on a graphical display, a red
bullet will appear on that line.  If a breakpoint already exists on
that line, the same click will remove it.  You can also enable or
disable a breakpoint by clicking `C-Mouse-1' on the bullet.

   A solid arrow in the left fringe of a source buffer indicates the
line of the innermost frame where the debugged program has stopped. A
hollow arrow indicates the current execution line of higher level
frames.

   If you drag the arrow in the fringe with `Mouse-1'
(`gdb-mouse-until'), execution will continue to the line where you
release the button, provided it is still in the same frame.
Alternatively, you can click `Mouse-3' at some point in the fringe of
this buffer and execution will advance to there.  A similar command
(`gdb-mouse-jump') allows you to jump to a source line without
executing the intermediate lines by clicking `C-Mouse-3'.  This command
allows you to go backwards which can be useful for running through code
that has already executed, in order to examine its execution in more
detail.

`Mouse-1'
     Set or clear a breakpoint.

`C-Mouse-1'
     Enable or disable a breakpoint.

`Mouse-3'
     Continue execution to here.

`C-Mouse-3'
     Jump to here.

   If the variable `gdb-find-source-frame' is non-`nil' and execution
stops in a frame for which there is no source code e.g after an
interrupt, then Emacs finds and displays the first frame further up
stack for which there is source.  If it is `nil' then the source buffer
continues to display the last frame which maybe more useful, for
example, when re-setting a breakpoint.


File: emacs,  Node: Breakpoints Buffer,  Next: Stack Buffer,  Prev: Source Buffers,  Up: GDB Graphical Interface

31.6.5.3 Breakpoints Buffer
...........................

The breakpoints buffer shows the existing breakpoints, watchpoints and
catchpoints (*note Breakpoints: (gdb)Breakpoints.).  It has these
special commands, which mostly apply to the "current breakpoint", the
breakpoint which point is on.

`<SPC>'
     Enable/disable current breakpoint (`gdb-toggle-breakpoint').  On a
     graphical display, this changes the color of a bullet in the
     margin of a source buffer at the relevant line.  This is red when
     the breakpoint is enabled and grey when it is disabled.  Text-only
     terminals correspondingly display a `B' or `b'.

`D'
     Delete the current breakpoint (`gdb-delete-breakpoint').

`<RET>'
     Visit the source line for the current breakpoint
     (`gdb-goto-breakpoint').

`Mouse-2'
     Visit the source line for the breakpoint you click on.

   When `gdb-many-windows' is non-`nil', the breakpoints buffer shares
its window with the threads buffer.  To switch from one to the other
click with `Mouse-1' on the relevant button in the header line.


File: emacs,  Node: Stack Buffer,  Next: Other GDB-UI Buffers,  Prev: Breakpoints Buffer,  Up: GDB Graphical Interface

31.6.5.4 Stack Buffer
.....................

The stack buffer displays a "call stack", with one line for each of the
nested subroutine calls ("stack frames") now active in the program.
*Note Backtraces: (gdb)Backtrace.

   An arrow in the fringe points to the selected frame or, if the
fringe is not present, the number of the selected frame is displayed in
reverse contrast.  To select a frame in GDB, move point in the stack
buffer to that stack frame and type <RET> (`gdb-frames-select'), or
click `Mouse-2' on a stack frame.  If the locals buffer is visible,
selecting a stack frame updates it to display the local variables of the
new frame.


File: emacs,  Node: Other GDB-UI Buffers,  Next: Watch Expressions,  Prev: Stack Buffer,  Up: GDB Graphical Interface

31.6.5.5 Other Buffers
......................

Input/Output Buffer
     If the variable `gdb-use-separate-io-buffer' is non-`nil', the
     program being debugged takes its input and displays its output
     here.  Otherwise it uses the GUD buffer for that.  To toggle
     whether GUD mode uses this buffer, do `M-x
     gdb-use-separate-io-buffer'.  This takes effect when you next
     restart the program you are debugging.

     The history and replay commands from Shell mode are available here,
     as are the commands to send signals to the debugged program.
     *Note Shell Mode::.

Locals Buffer
     The locals buffer displays the values of local variables of the
     current frame for simple data types (*note Frame Info: (gdb)Frame
     Info.).  Press <RET> or click `Mouse-2' on the value if you want
     to edit it.

     Arrays and structures display their type only.  With GDB 6.4 or
     later, move point to their name and press <RET>, or alternatively
     click `Mouse-2' there, to examine their values.  With earlier
     versions of GDB, use `Mouse-2' or <RET> on the type description
     (`[struct/union]' or `[array]').  *Note Watch Expressions::.

Registers Buffer
     The registers buffer displays the values held by the registers
     (*note Registers: (gdb)Registers.).  Press <RET> or click
     `Mouse-2' on a register if you want to edit its value.  With GDB
     6.4 or later, recently changed register values display with
     `font-lock-warning-face'.  With earlier versions of GDB, you can
     press <SPC> to toggle the display of floating point registers
     (`toggle-gdb-all-registers').

Assembler Buffer
     The assembler buffer displays the current frame as machine code.
     An arrow points to the current instruction, and you can set and
     remove breakpoints as in a source buffer.  Breakpoint icons also
     appear in the fringe or margin.

Threads Buffer
     The threads buffer displays a summary of all threads currently in
     your program (*note Threads: (gdb)Threads.).  Move point to any
     thread in the list and press <RET> to select it
     (`gdb-threads-select') and display the associated source in the
     primary source buffer.  Alternatively, click `Mouse-2' on a thread
     to select it.  If the locals buffer is visible, its contents
     update to display the variables that are local in the new thread.

     When there is more than one main thread and the threads buffer is
     present, Emacs displays the selected thread number in the mode
     line of many of the GDB-UI Buffers.

Memory Buffer
     The memory buffer lets you examine sections of program memory
     (*note Memory: (gdb)Memory.).  Click `Mouse-1' on the appropriate
     part of the header line to change the starting address or number
     of data items that the buffer displays.  Alternatively, use `S' or
     `N' respectively.  Click `Mouse-3' on the header line to select
     the display format or unit size for these data items.

   When `gdb-many-windows' is non-`nil', the threads buffer shares its
window with the breakpoints buffer, and the locals buffer with the
registers buffer.  To switch from one to the other click with `Mouse-1'
on the relevant button in the header line.


File: emacs,  Node: Watch Expressions,  Next: Reverse Debugging,  Prev: Other GDB-UI Buffers,  Up: GDB Graphical Interface

31.6.5.6 Watch Expressions
..........................

If you want to see how a variable changes each time your program stops,
move point into the variable name and click on the watch icon in the
tool bar (`gud-watch') or type `C-x C-a C-w'.  If you specify a prefix
argument, you can enter the variable name in the minibuffer.

   Each watch expression is displayed in the speedbar.  Complex data
types, such as arrays, structures and unions are represented in a tree
format.  Leaves and simple data types show the name of the expression
and its value and, when the speedbar frame is selected, display the
type as a tooltip.  Higher levels show the name, type and address value
for pointers and just the name and type otherwise.  Root expressions
also display the frame address as a tooltip to help identify the frame
in which they were defined.

   To expand or contract a complex data type, click `Mouse-2' or press
<SPC> on the tag to the left of the expression.  Emacs asks for
confirmation before expanding the expression if its number of immediate
children exceeds the value of the variable `gdb-max-children'.

   To delete a complex watch expression, move point to the root
expression in the speedbar and type `D' (`gdb-var-delete').

   To edit a variable with a simple data type, or a simple element of a
complex data type, move point there in the speedbar and type <RET>
(`gdb-edit-value').  Or you can click `Mouse-2' on a value to edit it.
Either way, this reads the new value using the minibuffer.

   If you set the variable `gdb-show-changed-values' to non-`nil' (the
default value), Emacs uses `font-lock-warning-face' to highlight values
that have recently changed and `shadow' face to make variables which
have gone out of scope less noticeable.  When a variable goes out of
scope you can't edit its value.

   If the variable `gdb-delete-out-of-scope' is non-`nil' (the default
value), Emacs automatically deletes watch expressions which go out of
scope.  Sometimes, when re-entering the same function, it may be useful
to set this value to `nil' so that you don't need to recreate the watch
expression.

   If the variable `gdb-use-colon-colon-notation' is non-`nil', Emacs
uses the `FUNCTION::VARIABLE' format.  This allows the user to display
watch expressions which share the same variable name.  The default
value is `nil'.

   To automatically raise the speedbar every time the display of watch
expressions updates, set `gdb-speedbar-auto-raise' to non-`nil'.  This
can be useful if you are debugging with a full screen Emacs frame.


File: emacs,  Node: Reverse Debugging,  Prev: Watch Expressions,  Up: GDB Graphical Interface

31.6.5.7 Reverse Debugging
..........................

The GDB tool bar shares many buttons with the other GUD debuggers for
tasks like stepping and printing expressions.  It also has a further
set of buttons that allow reverse debugging (*note Process Record and
Replay: (gdb)Process Record and Replay.).  This is useful when it takes
a long time to reproduce the conditions where your program fails or for
transient problems, like race conditions in multi-threaded programs,
where a failure might otherwise be hard to reproduce.

   To use reverse debugging, set a breakpoint slightly before the
location of interest and run your program to that point.  Enable
process recording by clicking on the record button.  At this point, a
new set of buttons appear.  These buttons allow program execution in
the reverse direction.  Run your program over the code where the
problem occurs, and then use the new set of buttons to retrace your
steps, examine values, and analyze the problem.  When analysis is
complete, turn off process recording by clicking on the record button
again.


File: emacs,  Node: Executing Lisp,  Next: Lisp Libraries,  Prev: Debuggers,  Up: Building

31.7 Executing Lisp Expressions
===============================

Emacs has several different major modes for Lisp and Scheme.  They are
the same in terms of editing commands, but differ in the commands for
executing Lisp expressions.  Each mode has its own purpose.

Emacs-Lisp mode
     The mode for editing source files of programs to run in Emacs Lisp.
     This mode defines `C-M-x' to evaluate the current defun.  *Note
     Lisp Libraries::.

Lisp Interaction mode
     The mode for an interactive session with Emacs Lisp.  It defines
     `C-j' to evaluate the sexp before point and insert its value in the
     buffer.  *Note Lisp Interaction::.

Lisp mode
     The mode for editing source files of programs that run in Lisps
     other than Emacs Lisp.  This mode defines `C-M-x' to send the
     current defun to an inferior Lisp process.  *Note External Lisp::.

Inferior Lisp mode
     The mode for an interactive session with an inferior Lisp process.
     This mode combines the special features of Lisp mode and Shell mode
     (*note Shell Mode::).

Scheme mode
     Like Lisp mode but for Scheme programs.

Inferior Scheme mode
     The mode for an interactive session with an inferior Scheme
     process.

   Most editing commands for working with Lisp programs are in fact
available globally.  *Note Programs::.


File: emacs,  Node: Lisp Libraries,  Next: Lisp Eval,  Prev: Executing Lisp,  Up: Building

31.8 Libraries of Lisp Code for Emacs
=====================================

Lisp code for Emacs editing commands is stored in files whose names
conventionally end in `.el'.  This ending tells Emacs to edit them in
Emacs-Lisp mode (*note Executing Lisp::).

   Emacs Lisp code can be compiled into byte-code, which loads faster,
takes up less space, and executes faster.  *Note Byte Compilation:
(elisp)Byte Compilation.  By convention, the compiled code for a
library goes in a separate file whose name ends in `.elc'.  Thus, the
compiled code for `foo.el' goes in `foo.elc'.

   To execute a file of Emacs Lisp code, use `M-x load-file'.  This
command reads a file name using the minibuffer and then executes the
contents of that file as Lisp code.  It is not necessary to visit the
file first; in any case, this command reads the file as found on disk,
not text in an Emacs buffer.

   Once a file of Lisp code is installed in the Emacs Lisp library
directories, users can load it using `M-x load-library'.  Programs can
load it by calling `load', a more primitive function that is similar
but accepts some additional arguments.

   `M-x load-library' differs from `M-x load-file' in that it searches
a sequence of directories and tries three file names in each directory.
Suppose your argument is LIB; the three names are `LIB.elc', `LIB.el',
and lastly just `LIB'.  If `LIB.elc' exists, it is by convention the
result of compiling `LIB.el'; it is better to load the compiled file,
since it will load and run faster.

   If `load-library' finds that `LIB.el' is newer than `LIB.elc' file,
it issues a warning, because it's likely that somebody made changes to
the `.el' file and forgot to recompile it.  Nonetheless, it loads
`LIB.elc'.  This is because people often leave unfinished edits the
source file, and don't recompile it until they think it is ready to use.

   The variable `load-path' specifies the sequence of directories
searched by `M-x load-library'.  Its value should be a list of strings
that are directory names; in addition, `nil' in this list stands for
the current default directory.  (Generally, it is not a good idea to
put `nil' in the list; if you find yourself wishing that `nil' were in
the list, most likely what you really want is to do `M-x load-file'
this once.)

   The default value of `load-path' is a list of directories where the
Lisp code for Emacs itself is stored.  If you have libraries of your
own, put them in a single directory and add that directory to
`load-path', by adding a line like this to your init file (*note Init
File::):

     (add-to-list 'load-path "/path/to/lisp/libraries")

   Some commands are "autoloaded": when you run them, Emacs will
automatically load the associated library first.  For instance, the
`compile' and `compilation-mode' commands (*note Compilation::) are
autoloaded; if you call either command, Emacs automatically loads the
`compile' library.  In contrast, the command `recompile' is not
autoloaded, so it is unavailable until you load the `compile' library.

   By default, Emacs refuses to load compiled Lisp files which were
compiled with XEmacs, a modified versions of Emacs--they can cause
Emacs to crash.  Set the variable `load-dangerous-libraries' to `t' if
you want to try loading them.


File: emacs,  Node: Lisp Eval,  Next: Lisp Interaction,  Prev: Lisp Libraries,  Up: Building

31.9 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-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.  Typing `C-M-x' on a `defface' expression
reinitializes the face according to the `defface' specification.

   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.

   When the result of an evaluation is an integer, you can type `C-x
C-e' a second time to display the value of the integer result in
additional formats (octal, hexadecimal, and character).

   If `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.  `C-M-x' with a
numeric argument instruments the function definition for Edebug (*note
Instrumenting for Edebug: (elisp)Instrumenting.).

   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-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 two 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; its
default is `t'.


File: emacs,  Node: Lisp Interaction,  Next: External Lisp,  Prev: Lisp Eval,  Up: Building

31.10 Lisp Interaction Buffers
==============================

When Emacs starts up, it contains a buffer named `*scratch*', which is
provided for evaluating Lisp expressions interactively inside Emacs.
Its major mode is Lisp Interaction mode.

   The simplest way to use the `*scratch*' buffer is to insert Lisp
expressions and type `C-j' (`eval-print-last-sexp') 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.

   At startup, the `*scratch*' buffer contains a short message, in the
form of a Lisp comment, that explains what it is for.  This message is
controlled by the variable `initial-scratch-message', which should be
either a string or `nil'.  If you set it to the empty string, or `nil',
the initial message is suppressed.

   All other commands in Lisp Interaction mode are the same as in Emacs
Lisp mode.  You can enable Lisp Interaction mode by typing `M-x
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.  For more information see that command's documentation.


File: emacs,  Node: External Lisp,  Prev: Lisp Interaction,  Up: Building

31.11 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.  You can switch to this mode with `M-x lisp-mode', and it is used
automatically for files whose names end in `.l', `.lsp', or `.lisp'.

   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; see *note Lisp Eval::): 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.


File: emacs,  Node: Maintaining,  Next: Abbrevs,  Prev: Building,  Up: Top

32 Maintaining Large Programs
*****************************

This chapter describes Emacs features for maintaining large programs.

* Menu:

* Version Control::     Using version control systems.
* Change Log::          Maintaining a change history for your program.
* Tags::                Go directly to any function in your program in one
                          command.  Tags remembers which file it is in.
* EDE::                 An integrated development environment for Emacs.

* Emerge::              A convenient way of merging two versions of a program.


File: emacs,  Node: Version Control,  Next: Change Log,  Up: Maintaining

32.1 Version Control
====================

A "version control system" is a program that can record multiple
versions of a source file, storing information such as the creation
time of each version, who made it, and a description of what was
changed.

   The Emacs version control interface is called "VC".  VC commands
work with several different version control systems; currently, it
supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
SCCS/CSSC, and Subversion.  Of these, the GNU project distributes CVS,
Arch, RCS, and Bazaar.

   VC is enabled automatically whenever you visit a file governed by a
version control system.  To disable VC entirely, set the customizable
variable `vc-handled-backends' to `nil' (*note Customizing VC::).

* Menu:

* Introduction to VC::  How version control works in general.
* VC Mode Line::        How the mode line shows version control status.
* Basic VC Editing::    How to edit a file under version control.
* Log Buffer::          Features available in log entry buffers.
* Old Revisions::       Examining and comparing old versions.
* Secondary VC Commands::    The commands used a little less frequently.
* VC Directory Mode::   Listing files managed by version control.
* Branches::            Multiple lines of development.

* Remote Repositories:: Efficient access to remote CVS servers.
* Revision Tags::       Symbolic names for revisions.
* Miscellaneous VC::    Various other commands and features of VC.
* Customizing VC::      Variables that change VC's behavior.


File: emacs,  Node: Introduction to VC,  Next: VC Mode Line,  Up: Version Control

32.1.1 Introduction to Version Control
--------------------------------------

VC allows you to use a version control system from within Emacs,
integrating the version control operations smoothly with editing.  It
provides a uniform interface for common operations in many version
control operations.

   Some uncommon or intricate version control operations, such as
altering repository settings, are not supported in VC.  You should
perform such tasks outside Emacs, e.g. via the command line.

   This section provides a general overview of version control, and
describes the version control systems that VC supports.  You can skip
this section if you are already familiar with the version control system
you want to use.

* Menu:

* Why Version Control?::    Understanding the problems it addresses.
* Version Control Systems:: Supported version control back-end systems.
* VCS Concepts::            Words and concepts related to version control.
* VCS Merging::             How file conflicts are handled.
* VCS Changesets::          How changes are grouped.
* VCS Repositories::        Where version control repositories are stored.
* Types of Log File::       The VCS log in contrast to the ChangeLog.


File: emacs,  Node: Why Version Control?,  Next: Version Control Systems,  Up: Introduction to VC

32.1.1.1 Understanding the problems it addresses
................................................

Version control systems provide you with three important capabilities:

   * "Reversibility": the ability to back up to a previous state if you
     discover that some modification you did was a mistake or a bad
     idea.

   * "Concurrency": the ability to have many people modifying the same
     collection of files knowing that conflicting modifications can be
     detected and resolved.

   * "History": the ability to attach historical data to your data,
     such as explanatory comments about the intention behind each
     change to it.  Even for a programmer working solo, change
     histories are an important aid to memory; for a multi-person
     project, they are a vitally important form of communication among
     developers.


File: emacs,  Node: Version Control Systems,  Next: VCS Concepts,  Prev: Why Version Control?,  Up: Introduction to VC

32.1.1.2 Supported Version Control Systems
..........................................

VC currently works with many different version control systems, which
it refers to as "back ends":

   * SCCS was the first version control system ever built, and was long
     ago superseded by more advanced ones.  VC compensates for certain
     features missing in SCCS (e.g., tag names for releases) by
     implementing them itself.  Other VC features, such as multiple
     branches, are simply unavailable.  Since SCCS is non-free, we
     recommend avoiding it.

   * CSSC is a free replacement for SCCS.  You should use CSSC only if,
     for some reason, you cannot use a more recent and better-designed
     version control system.

   * RCS is the free version control system around which VC was
     initially built.  It is relatively primitive: it cannot be used
     over the network, and works at the level of individual files.
     Almost everything you can do with RCS can be done through VC.

   * CVS is the free version control system that was, until recently
     (circa 2008), used by the majority of free software projects.
     Nowadays, it is slowly being superseded by newer systems.  CVS
     allows concurrent multi-user development either locally or over
     the network.  Unlike newer systems, it lacks support for atomic
     commits and file moving/renaming.  VC supports all basic editing
     operations under CVS.

   * Subversion (SVN) is a free version control system designed to be
     similar to CVS but without its problems (e.g., it supports atomic
     commits of filesets, and versioning of directories, symbolic links,
     meta-data, renames, copies, and deletes).

   * GNU Arch is one of the earliest "distributed" version control
     systems (the other being Monotone).  *Note VCS Concepts::, for a
     description of distributed version control systems.  It is no
     longer under active development, and has been deprecated in favor
     of Bazaar.

   * Git is a distributed version control system originally invented by
     Linus Torvalds to support development of Linux (his kernel).  VC
     supports many common git operations, but others, such as repository
     syncing, must be done from the command line.

   * Mercurial (hg) is a distributed version control system broadly
     resembling git.  VC supports most Mercurial commands, with the
     exception of repository sync operations.

   * Bazaar (bzr) is a distributed version control system that supports
     both repository-based and distributed versioning.  VC supports most
     basic editing operations under Bazaar.

   Previous versions of VC supported a version control system known as
Meta-CVS.  This support was dropped due to limited interest from users
and developers.


File: emacs,  Node: VCS Concepts,  Next: VCS Merging,  Prev: Version Control Systems,  Up: Introduction to VC

32.1.1.3 Concepts of Version Control
....................................

When a file is under version control, we say that it is "registered" in
the version control system.  The system has a "repository" which stores
both the file's present state and its change history--enough to
reconstruct the current version or any earlier version.  The repository
also contains other information, such as "log entries" that describe
the changes made to each file.

   The copy of a version-controlled file that you actually edit is
called the "work file".  You can change each work file as you would an
ordinary file.  After you are done with a set of changes, you "commit"
(or "check in") the changes; this records the changes in the
repository, along with a descriptive log entry.

   A copy of a file stored in a repository is called a "revision".  The
history of a file is a sequence of revisions.  Each revision is named
by a "revision ID".  The format of the revision ID depends on the
version control system; in the simplest case, it is just an integer.

   To go beyond these basic concepts, you will need to understand three
aspects in which version control systems differ.  As explained in the
next three sections, they can be lock-based or merge-based; file-based
or changeset-based; and centralized or decentralized.  VC handles all
these modes of operation, but it cannot hide the differences.


File: emacs,  Node: VCS Merging,  Next: VCS Changesets,  Prev: VCS Concepts,  Up: Introduction to VC

32.1.1.4 Merge-based vs lock-based Version Control
..................................................

A version control system typically has some mechanism to coordinate
between users who want to change the same file.  There are two ways to
do this: merging and locking.

   In a version control system that uses merging, each user may check
out and modify a work file at any time.  The system lets you "merge"
your work file, which may contain changes that have not been committed,
with the latest changes that others have committed.

   Older version control systems use a "locking" scheme instead.  Here,
work files are normally read-only.  To edit a file, you ask the version
control system to make it writable for you by "locking" it; only one
user can lock a given file at any given time.  This procedure is
analogous to, but different from, the locking that Emacs uses to detect
simultaneous editing of ordinary files (*note Interlocking::).  When
you commit your changes, that unlocks the file, and the work file
becomes read-only again.  Other users may then lock the file to make
their own changes.

   Both locking and merging systems can have problems when multiple
users try to modify the same file at the same time.  Locking systems
have "lock conflicts"; a user may try to check a file out and be unable
to because it is locked.  In merging systems, "merge conflicts" happen
when you commit a change to a file that conflicts with a change
committed by someone else after your checkout.  Both kinds of conflict
have to be resolved by human judgment and communication.  Experience
has shown that merging is superior to locking, both in convenience to
developers and in minimizing the number and severity of conflicts that
actually occur.

   SCCS always uses locking.  RCS is lock-based by default but can be
told to operate in a merging style.  CVS and Subversion are merge-based
by default but can be told to operate in a locking mode.  Distributed
version control systems, such as GNU Arch, git, and Mercurial, are
exclusively merging-based.

   VC mode supports both locking and merging version control.  The
terms "commit" and "update" are used in newer version control systems;
older lock-based systems use the terms "check in" and "check out".  VC
hides the differences between them as much as possible.


File: emacs,  Node: VCS Changesets,  Next: VCS Repositories,  Prev: VCS Merging,  Up: Introduction to VC

32.1.1.5 Changeset-based vs File-based Version Control
......................................................

On SCCS, RCS, CVS, and other early version control systems, version
control operations are "file-based": each file has its own comment and
revision history separate from that of all other files.  Newer systems,
beginning with Subversion, are "changeset-based": a checkin may include
changes to several files, and the entire set of changes is handled as a
unit.  Any comment associated with the change does not belong to a
single file, but to the changeset itself.

   Changeset-based version control is more flexible and powerful than
file-based version control; usually, when a change to multiple files
has to be reversed, it's good to be able to easily identify and remove
all of it.


File: emacs,  Node: VCS Repositories,  Next: Types of Log File,  Prev: VCS Changesets,  Up: Introduction to VC

32.1.1.6 Decentralized vs Centralized Repositories
..................................................

Early version control systems were designed around a "centralized"
model in which each project has only one repository used by all
developers.  SCCS, RCS, CVS, and Subversion share this kind of model.
One of its drawbacks is that the repository is a choke point for
reliability and efficiency.

   GNU Arch pioneered the concept of "decentralized" version control,
later implemented in git, Mercurial, and Bazaar.  A project may have
several different repositories, and these systems support a sort of
super-merge between repositories that tries to reconcile their change
histories.  In effect, there is one repository for each developer, and
repository merges take the place of commit operations.

   VC helps you manage the traffic between your personal workfiles and
a repository.  Whether the repository is a single master, or one of a
network of peer repositories, is not something VC has to care about.


File: emacs,  Node: Types of Log File,  Prev: VCS Repositories,  Up: Introduction to VC

32.1.1.7 Types of Log File
..........................

Projects that use a version control system can have two types of log
for changes.  One is the log maintained by the version control system:
each time you commit a change, you fill out a "log entry" for the
change (*note Log Buffer::).  This is called the "version control log".

   The other kind of log is the file `ChangeLog' (*note Change Log::).
It provides a chronological record of all changes to a large portion of
a program--typically one directory and its subdirectories.  A small
program would use one `ChangeLog' file; a large program may have a
`ChangeLog' file in each major directory.  *Note Change Log::.
Programmers have used change logs since long before version control
systems.

   Changeset-based version systems typically maintain a changeset-based
modification log for the entire system, which makes change log files
somewhat redundant.  One advantage that they retain is that it is
sometimes useful to be able to view the transaction history of a single
directory separately from those of other directories.

   A project maintained with version control can use just the version
control log, or it can use both kinds of logs.  It can handle some
files one way and some files the other way.  Each project has its
policy, which you should follow.

   When the policy is to use both, you typically want to write an entry
for each change just once, then put it into both logs.  You can write
the entry in `ChangeLog', then copy it to the log buffer with `C-c C-a'
when checking in the change (*note Log Buffer::).  Or you can write the
entry in the log buffer while checking in the change, and later use the
`C-x v a' command to copy it to `ChangeLog' (*note Change Logs and
VC::).


File: emacs,  Node: VC Mode Line,  Next: Basic VC Editing,  Prev: Introduction to VC,  Up: Version Control

32.1.2 Version Control and the Mode Line
----------------------------------------

When you visit a file that is under version control, Emacs indicates
this on the mode line.  For example, `Bzr-1223' says that Bazaar is
used for that file, and the current revision ID is 1223.

   The character between the back-end name and the revision ID
indicates the status of the work file.  In a merge-based version
control system, a `-' character indicates that the work file is
unmodified, and `:' indicates that it has been modified.  In a
lock-based system, `-' indicates an unlocked file, and `:' a locked
file; if the file is locked by another user (for instance, `jim'), that
is displayed as `RCS:jim:1.3'.

   On a graphical display, you can move the mouse over this mode line
indicator to pop up a "tool-tip", which displays a more verbose
description of the version control status.  Pressing `Mouse-1' over the
indicator pops up a menu of VC commands, identical to `Tools / Version
Control' on the menu bar.

   When Auto Revert mode (*note Reverting::) reverts a buffer that is
under version control, it updates the version control information in
the mode line.  However, Auto Revert mode may not properly update this
information if the version control status changes without changes to
the work file, from outside the current Emacs session.  If you set
`auto-revert-check-vc-info' to `t', Auto Revert mode updates the
version control status information every `auto-revert-interval'
seconds, even if the work file itself is unchanged.  The resulting CPU
usage depends on the version control system, but is usually not
excessive.


File: emacs,  Node: Basic VC Editing,  Next: Log Buffer,  Prev: VC Mode Line,  Up: Version Control

32.1.3 Basic Editing under Version Control
------------------------------------------

Most VC commands operate on "VC filesets".  A VC fileset is a
collection of one or more files that a VC operation acts on.  When you
type VC commands in a buffer visiting a version-controlled file, the VC
fileset is simply that one file.  When you type them in a VC Directory
buffer, and some files in it are marked, the VC fileset consists of the
marked files (*note VC Directory Mode::).

   The principal VC command is an all-purpose command, `C-x v v'
(`vc-next-action'), that performs either registration, locking, merging
or a check-in (depending on the situation) on the current VC fileset.
You can use `C-x v v' in a file-visiting buffer or in a VC Directory
buffer.

`C-x v v'
     Perform the appropriate next version control operation on the VC
     fileset.

   The precise action of `C-x v v' depends on the state of the VC
fileset, and whether the version control system uses locking or
merging.  This is described in detail in the subsequent sections.

   VC filesets are the way that VC mode bridges the gap between
file-based and changeset-based version control systems.  They are,
essentially, a way to pass multiple file arguments as a group to
version control commands.  For example, on Subversion, a checkin with a
multi-file VC fileset becomes a joint commit, as though you had typed
`svn commit' with those file arguments at the shell command line.  All
files in a VC fileset must be under the same version control system; if
they are not, Emacs signals an error when you attempt to execute a
command on the fileset.

   VC filesets are distinct from the "named filesets" used for viewing
and visiting files in functional groups (*note Filesets::).  Unlike
named filesets, VC filesets are not named and don't persist across
sessions.

* Menu:

* VC With A Merging VCS::  Without locking: default mode for CVS.
* VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
* Advanced C-x v v::       Advanced features available with a prefix argument.


File: emacs,  Node: VC With A Merging VCS,  Next: VC With A Locking VCS,  Up: Basic VC Editing

32.1.3.1 Basic Version Control with Merging
...........................................

When your version control system is merging-based (the default for CVS
and all newer version control systems), work files are always writable;
you need not do anything special to begin editing a file.  The status
indicator on the mode line is `-' if the file is unmodified; it flips
to `:' as soon as you save any changes (*note VC Mode Line::).

   Here is what `C-x v v' does when using a merging-based system:

   * If the work file is in a directory that is not controlled by any
     version control system, prompt for a repository type.  Then,
     create a version control repository of that type and register the
     file with it.

   * If the work file is in a directory that is controlled by a version
     control system but not registered with it, register the file.

   * If the work file is the same as in the repository, do nothing.

   * If you have not changed the work file, but some other user has
     checked in changes to the repository, merge those changes into the
     work file.

   * If you have made modifications to the work file, attempt to commit
     the changes.  To do this, Emacs first reads the log entry for the
     new revision (*note Log Buffer::).  If some other user has
     committed changes to the repository since you last checked it out,
     the checkin fails.  In that case, type `C-x v v' again to merge
     those changes into your own work file; this puts the work file
     into a "conflicted" state.  Type `C-x v v' to clear the
     "conflicted" state; VC then regards the file as up-to-date and
     modified, and you can try to check it in again.

     To pick up any recent changes from the repository _without_ trying
     to commit your own changes, type `C-x v m <RET>'.  *Note Merging::.

   These rules also apply when you use RCS in its "non-locking" mode,
except that changes are not automatically merged from the repository.
Nothing informs you if another user has committed changes in the same
file since you began editing it; when you commit your revision, his
changes are removed (however, they remain in the repository and are
thus not irrevocably lost).  Therefore, you must verify that the
current revision is unchanged before checking in your changes.  In
addition, locking is possible with RCS even in this mode: `C-x v v'
with an unmodified file locks the file, just as it does with RCS in its
normal locking mode (*note VC With A Locking VCS::).


File: emacs,  Node: VC With A Locking VCS,  Next: Advanced C-x v v,  Prev: VC With A Merging VCS,  Up: Basic VC Editing

32.1.3.2 Basic Version Control with Locking
...........................................

Under a locking-based version control system (such as SCCS, and RCS in
its default mode), `C-x v v' does the following:

   * If the file is not locked, lock it and make it writable, so that
     you can change it.

   * If the file is locked by you, and contains changes, commit the
     changes.  In order to do this, Emacs first reads the log entry for
     the new revision.  *Note Log Buffer::.

   * If the file is locked by you, but you have not changed it since you
     locked it, release the lock and makes the file read-only again.

   * If the file is locked by some other user, ask whether you want to
     "steal the lock" from that user.  If you say yes, the file becomes
     locked by you, but a message is sent to the person who had formerly
     locked the file, to inform him of what has happened.

   These rules also apply when you use CVS in locking mode, except that
CVS does not support stealing a lock.


File: emacs,  Node: Advanced C-x v v,  Prev: VC With A Locking VCS,  Up: Basic VC Editing

32.1.3.3 Advanced Control in `C-x v v'
......................................

When you give a prefix argument to `vc-next-action' (`C-u C-x v v'), it
still performs the next logical version control operation, but accepts
additional arguments to specify precisely how to do the operation.

   * If the file is modified (or locked), you can specify the revision
     ID to use for the new version that you commit.  This is one way to
     create a new branch (*note Branches::).

   * If the file is not modified (and unlocked), you can specify the
     revision to select; this lets you start working from an older
     revision, or on another branch.  If you do not enter any revision,
     that takes you to the highest ("head") revision on the current
     branch; therefore `C-u C-x v v <RET>' is a convenient way to get
     the latest version of a file from the repository.

   * Instead of the revision ID, you can also specify the name of a
     version control system.  This is useful when one file is being
     managed with two version control systems at the same time (*note
     Local Version Control::).



File: emacs,  Node: Log Buffer,  Next: Old Revisions,  Prev: Basic VC Editing,  Up: Version Control

32.1.4 Features of the Log Entry Buffer
---------------------------------------

When you tell VC to commit a change, it pops up a buffer called
`*VC-Log*'.  In this buffer, you should write a "log entry" describing
the changes you have made (*note Why Version Control?::).  After you
are done, type `C-c C-c'; this exits the buffer and commits the change,
together with your log entry.

   While in the `*VC-Log*' buffer, you can write one or more "header
lines", specifying additional information to be supplied to the version
control system.  Each header line must occupy a single line at the top
of the buffer; the first line that is not a header line is treated as
the start of the log entry.  For example, the following header line
states that the present change was not written by you, but by another
developer:

     Author: J. R. Hacker <jrh@example.com>

Apart from the `Author' header, Emacs recognizes the headers `Date' (a
manually-specified commit time) and `Fixes' (a reference to a bug fixed
by the change).  Not all version control systems recognize all headers:
Bazaar recognizes all three headers, while git, Mercurial, and Monotone
recognizes only `Author' and `Summary'.  If you specify a header for a
version control that does not support it, the header is treated as part
of the log entry.

   Type `C-c C-f' (`log-edit-show-files') to display a list of files in
the current VC fileset.  If you called `C-x v v' directly from a work
file, the fileset consists of that single file; if you called `C-x v v'
from a VC directory buffer (*note VC Directory Mode::), the fileset may
consist of multiple files.

   Type `C-c C-d' (`log-edit-show-diff') to show a "diff" of the
changes you have made (i.e., the differences between the work file and
the repository revision from which you started editing).  *Note Old
Revisions::.

   If the current VC fileset includes one or more `ChangeLog' files
(*note Change Log::), type `C-c C-a' (`log-edit-insert-changelog') to
pull the relevant entries into the `*VC-Log*' buffer.  If the topmost
item in each `ChangeLog' was made under your user name on the current
date, this command searches that item for entries that match the
file(s) to be committed; if found, these entries are inserted.  *Note
Change Logs and VC::, for the opposite way of working--generating
ChangeLog entries from the revision control log.

   To abort a check-in, just *don't* type `C-c C-c' in that buffer.
You can switch buffers and do other editing.  As long as you don't try
to commit another file, the entry you were editing remains in the
`*VC-Log*' buffer, and you can go back to that buffer at any time to
complete the check-in.

   If you change several source files for the same reason, it is often
convenient to specify the same log entry for many of the files.  (This
is the normal way to do things on a changeset-oriented system, where
comments are attached to changesets rather than the history of
individual files.)  The most convenient way to do this is to mark all
the files in VC Directory Mode and commit from there; the log buffer
will carry the fileset information with it and do a group commit when
you type `C-c C-c'.

   You can also browse the history of previous log entries to duplicate
a checkin comment. This can be useful when you want several files to
have checkin comments that vary only slightly from each other. The
commands `M-n', `M-p', `M-s' and `M-r' for doing this work just like
the minibuffer history commands (except that these versions are used
outside the minibuffer).

   Each time you commit a change, the log entry buffer is put into VC
Log Edit mode, which involves running two hooks: `text-mode-hook' and
`vc-log-mode-hook'.  *Note Hooks::.


File: emacs,  Node: Old Revisions,  Next: Secondary VC Commands,  Prev: Log Buffer,  Up: Version Control

32.1.5 Examining And Comparing Old Revisions
--------------------------------------------

One of the convenient features of version control is the ability to
examine any revision of a file, or compare two revisions.

`C-x v ~'
     Prompt for a revision of the current file, and visit it in a
     buffer of its own (`vc-revision-other-window').

`C-x v ='
     Compare the files in the current fileset with the working
     revision(s) you started from (`vc-diff').  With a prefix argument,
     prompt for two revisions of the current fileset and compare them.
     You can call this command from a Dired buffer (*note Dired::).

`C-x v D'
     Compare the entire tree corresponding to the current fileset with
     the tree you started from (`vc-root-diff').  With a prefix
     argument, prompt for two revisions and compare their trees.

`C-x v g'
     Display an annotated version of the file: for each line, show the
     latest revision in which it was modified (`vc-annotate').

   To examine an old revision, visit the work file and type `C-x v ~
REVISION <RET>' (`vc-revision-other-window').  Here, REVISION is either
the desired revision ID (*note VCS Concepts::), or the name of a tag or
branch (*note Tags::).  This command puts the text of the old revision
in a file named `FILENAME.~REVISION~', and visits it in its own buffer
in a separate window.

   `C-x v =' (`vc-diff') compares each file in the current VC fileset
(saving them if necessary) with the repository revision(s) from which
you started editing.  Note that the latter may or may not be the latest
revision of the file(s).

   The diff is displayed in another window, in a Diff mode buffer
(*note Diff Mode::) named `*vc-diff*'.  In this buffer, the `g'
(`revert-buffer') command performs the file comparison again,
generating a new diff.

   To compare two arbitrary revisions of the current VC fileset, call
`vc-diff' with a prefix argument: `C-u C-x v ='.  This prompts for two
revision IDs, using the minibuffer, and displays the diff in a special
buffer in another window.  Instead of providing a revision ID, you can
give an empty input, which specifies the current contents of the work
file; or a tag or branch name (*note Tags::).  If your version control
system is file-based (e.g. CVS) rather than changeset-based
(Subversion, GNU Arch, git, Mercurial), supplying a revision ID for a
multi-file fileset (as opposed to a symbolic tag name) is unlikely to
return diffs that are connected in any meaningful way.

   The command `C-x v D' (`vc-root-diff') is similar to `C-x v =', but
it compares the entire tree associated with the current VC fileset with
the tree you started with.  This means all the files controlled by the
current version control repository, even those that are not part of the
current VC fileset.

   If you invoke `C-x v =' or `C-u C-x v =' from a buffer that is
neither visiting a version-controlled file nor a VC directory buffer,
these commands generate a diff of all registered files in the current
directory and its subdirectories.

   `C-x v =' works by running a variant of the `diff' utility designed
to work with the version control system in use.  The options to pass to
the `diff' command are taken from the first non-`nil' value of
`vc-BACKEND-diff-switches', `vc-diff-switches', and `diff-switches'
(*note Comparing Files::), in that order.  Since `nil' means to check
the next variable in the sequence, either of the first two may use the
value `t' to mean no switches at all.  Most of the `vc...diff-switches'
variables default to `nil', but some default to `t'.  These are for
those version control systems (e.g. SVN) whose `diff' implementations
do not accept common options (e.g. `-c') likely to be in
`diff-switches'.

   The buffer produced by `C-x v =' supports the commands of
Compilation mode (*note Compilation Mode::), such as `C-x `' and `C-c
C-c', in both the "old" and "new" text, and they always find the
corresponding locations in the current work file.  (Older revisions are
not, in general, present as files on your disk.)

   For some back ends, you can display the file "annotated" with
per-line revision information, by typing `C-x v g' (`vc-annotate').
This creates a new buffer (the "annotate buffer") displaying the file's
text, with each part colored to show how old it is.  Text colored red
is new, blue means old, and intermediate colors indicate intermediate
ages.  By default, the color is scaled over the full range of ages,
such that the oldest changes are blue, and the newest changes are red.

   When you give a prefix argument to this command, Emacs reads two
arguments using the minibuffer: the ID of which revision to display and
annotate (instead of the current file contents), and the time span in
days the color range should cover.

   From the annotate buffer, these and other color scaling options are
available from the `VC-Annotate' menu.  In this buffer, you can also
use the following keys to browse the annotations of past revisions,
view diffs, or view log entries:

`p'
     Annotate the previous revision, that is to say, the revision before
     the one currently annotated.  A numeric prefix argument is a repeat
     count, so `C-u 10 p' would take you back 10 revisions.

`n'
     Annotate the next revision--the one after the revision currently
     annotated.  A numeric prefix argument is a repeat count.

`j'
     Annotate the revision indicated by the current line.

`a'
     Annotate the revision before the one indicated by the current line.
     This is useful to see the state the file was in before the change
     on the current line was made.

`f'
     Show in a buffer the file revision indicated by the current line.

`d'
     Display the diff between the current line's revision and the
     previous revision.  This is useful to see what the current line's
     revision actually changed in the file.

`D'
     Display the diff between the current line's revision and the
     previous revision for all files in the changeset (for VC systems
     that support changesets).  This is useful to see what the current
     line's revision actually changed in the tree.

`l'
     Show the log of the current line's revision.  This is useful to see
     the author's description of the changes in the revision on the
     current line.

`w'
     Annotate the working revision-the one you are editing.  If you used
     `p' and `n' to browse to other revisions, use this key to return
     to your working revision.

`v'
     Toggle the annotation visibility.  This is useful for looking just
     at the file contents without distraction from the annotations.


File: emacs,  Node: Secondary VC Commands,  Next: VC Directory Mode,  Prev: Old Revisions,  Up: Version Control

32.1.6 The Secondary Commands of VC
-----------------------------------

This section explains the secondary commands of VC.

* Menu:

* Registering::         Putting a file under version control.
* VC Change Log::       Viewing the VC Change Log.
* VC Undo::             Canceling changes before or after check-in.


File: emacs,  Node: Registering,  Next: VC Change Log,  Up: Secondary VC Commands

32.1.6.1 Registering a File for Version Control
...............................................

You can put any file under version control by simply visiting it, and
then typing `C-x v i' (`vc-register').

`C-x v i'
     Register the visited file for version control.

   To register the file, Emacs must choose which version control system
to use for it.  If the file's directory already contains files
registered in a version control system, Emacs uses that system.  If
there is more than one system in use for a directory, Emacs uses the
one that appears first in `vc-handled-backends' (*note Customizing
VC::).  On the other hand, if there are no files already registered,
Emacs uses the first system from `vc-handled-backends' that could
register the file (for example, you cannot register a file under CVS if
its directory is not already part of a CVS tree); with the default value
of `vc-handled-backends', this means that Emacs uses RCS in this
situation.

   If locking is in use, `C-x v i' leaves the file unlocked and
read-only.  Type `C-x v v' if you wish to start editing it.  After
registering a file with CVS, you must subsequently commit the initial
revision by typing `C-x v v'.  Until you do that, the revision ID
appears as `@@' in the mode line.

   The default initial revision ID for a newly registered file varies
by what VCS you are using; normally it will be 1.1 on VCSes that use
dot-pair revision IDs and 1 on VCSes that use monotonic IDs.  You can
specify a different default by setting the variable
`vc-default-init-revision', or you can give `C-x v i' a numeric
argument; then it reads the initial revision ID for this particular
file using the minibuffer.

   If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
comment to describe the purpose of this source file.  Reading the
initial comment works like reading a log entry (*note Log Buffer::).


File: emacs,  Node: VC Change Log,  Next: VC Undo,  Prev: Registering,  Up: Secondary VC Commands

32.1.6.2 VC Change Log
......................

`C-x v l'
     Display revision control state and change history (`vc-print-log').

`C-x v L'
     Display the change history for the current repository
     (`vc-print-root-log').

`C-x v I'
     Display the changes that will be received with a pull operation
     (`vc-log-incoming').

`C-x v O'
     Display the changes that will be sent by the next push operation
     (`vc-log-outgoing').

   The command `C-x v l' (`vc-print-log') displays a buffer named
`*vc-change-log*' in a new window.  This buffer lists the changes to
the current file, including the associated log entries.  (These are the
log entries associated with the version control system, i.e. the ones
you enter via the `*VC-Log*' buffer.  *Note Log Buffer::.)  Point is
centered at the revision of the file currently being visited.  With a
prefix argument, the command prompts for the revision to center on, and
the maximum number of revisions to display.  You can call this command
from a Dired buffer (*note Dired::).

   Type `C-x v L' (`vc-print-root-log') to display a `*vc-change-log*'
buffer showing the history of the version-controlled directory tree as
a whole.  With a prefix argument, the command prompts for the maximum
number of revisions to display.  RCS, SCCS, and CVS do not support this
feature.

   On a distributed version control system, the `C-x v I'
(`vc-log-incoming') command displays a log buffer showing the changes
that will be applied, the next time you run the version control
system's "pull" command to get new revisions from another repository.
This other repository is the default one from which changes are pulled,
as defined by the version control system; with a prefix argument,
`vc-log-incoming' prompts for a specific repository from which changes
would be pulled, and lists the changes accordingly.  Similarly, `C-x v
O' (`vc-log-outgoing') shows the changes that will be sent to another
repository, the next time you run the "push" command; with a prefix
argument, it prompts for a specific repository to which changes would
be pushed.

   In the `*vc-change-log*' buffer, you can use the following keys to
move between the logs of revisions and of files, to view past
revisions, to modify change comments, to view annotations and to view
diffs:

`p'
     Move to the previous revision-item in the buffer.  (Revision
     entries in the log buffer are usually in reverse-chronological
     order, so the previous revision-item usually corresponds to a
     newer revision.)  A numeric prefix argument is a repeat count.

`n'
     Move to the next revision-item (which most often corresponds to the
     previous revision of the file).  A numeric prefix argument is a
     repeat count.

`P'
     Move to the log of the previous file, when the logs of multiple
     files are in the log buffer (*note VC Directory Mode::).
     Otherwise, just move to the beginning of the log.  A numeric
     prefix argument is a repeat count, so `C-u 10 P' would move
     backward 10 files.

`N'
     Move to the log of the next file, when the logs of multiple files
     are in the log buffer (*note VC Directory Mode::).  It also takes a
     numeric prefix argument as a repeat count.

`a'
     Annotate the revision indicated by the current line.

`e'
     Modify the change comment displayed at point.  Note that not all VC
     systems support modifying change comments.

`f'
     Visit the revision indicated at the current line, like typing `C-x
     v ~' and specifying this revision's ID (*note Old Revisions::).

`d'
     Display the diff (*note Comparing Files::) between the revision
     indicated at the current line and the next earlier revision.  This
     is useful to see what actually changed in the file when the
     revision indicated on the current line was committed.

`D'
     Display the changeset diff (*note Comparing Files::) between the
     revision indicated at the current line and the next earlier
     revision.  This is useful to see all the changes to all files that
     the revision indicated on the current line did when it was
     committed.

   Because fetching many log entries can be slow, the `*vc-change-log*'
buffer displays no more than 2000 revisions by default.  The variable
`vc-log-show-limit' specifies this limit; if you set the value to zero,
that removes the limit.  You can also increase the number of revisions
shown in an existing `*vc-change-log*' buffer by clicking on the `Show
2X entries' or `Show unlimited entries' buttons at the end of the
buffer.  However, RCS, SCCS, and CVS do not support this feature.


File: emacs,  Node: VC Undo,  Prev: VC Change Log,  Up: Secondary VC Commands

32.1.6.3 Undoing Version Control Actions
........................................

`C-x v u'
     Revert the buffer and the file to the working revision from which
     you started editing the file.

`C-x v c'
     Remove the last-entered change from the master for the visited
     file.  This undoes your last check-in.

   If you want to discard your current set of changes and revert to the
working revision from which you started editing the file, use `C-x v u'
(`vc-revert-buffer').  If the version control system is locking-based,
this leaves the file unlocked, and you must lock it again before making
new changes.  `C-x v u' requires confirmation, unless it sees that you
haven't made any changes with respect to the master copy of the working
revision.

   `C-x v u' is also the command to unlock a file if you lock it and
then decide not to change it.

   To cancel a change that you already committed, use `C-x v c'
(`vc-rollback').  This command discards all record of the most recent
checked-in revision, but only if your work file corresponds to that
revision--you cannot use `C-x v c' to cancel a revision that is not the
latest on its branch.  Note that many version control systems do not
support rollback at all; this command is something of a historical
relic.


File: emacs,  Node: VC Directory Mode,  Next: Branches,  Prev: Secondary VC Commands,  Up: Version Control

32.1.7 VC Directory Mode
------------------------

When you are working on a large program, it is often useful to find out
which files have changed within an entire directory tree, or to view
the status of all files under version control at once, and to perform
version control operations on collections of files.  You can use the
command `C-x v d' (`vc-dir') to make a directory listing that includes
only files relevant for version control.  This creates a "VC Directory
buffer" and displays it in a separate window.

   The VC Directory buffer works with all the version control systems
that VC supports.  For CVS, Emacs also offers a more powerful facility
called PCL-CVS.  *Note About PCL-CVS: (pcl-cvs)Top.

* Menu:

* Buffer: VC Directory Buffer.      What the buffer looks like and means.
* Commands: VC Directory Commands.  Commands to use in a VC directory buffer.


File: emacs,  Node: VC Directory Buffer,  Next: VC Directory Commands,  Up: VC Directory Mode

32.1.7.1 The VC Directory Buffer
................................

The VC Directory buffer contains a list of version-controlled files in
the current directory and its subdirectories.  Files which are
up-to-date (have no local differences from the repository copy) are
usually hidden; if all files in a subdirectory are up-to-date, the
subdirectory is hidden as well.  There is an exception to this rule: if
VC mode detects that a file has changed to an up-to-date state since
you last looked at it, that file and its state are shown.

   If a directory uses more that one version control system, you can
select which system to use for the `vc-dir' command by invoking
`vc-dir' with a prefix argument: `C-u C-x v d'.

   The line for an individual file shows the version control state of
the file.  Under RCS and SCCS, the name of the user locking the file is
shown; under CVS, an abbreviated version of the `cvs status' output is
used.  Here is an example using CVS:

                            ./
         modified           file1.c
         needs-update       file2.c
         needs-merge        file3.c

In this example, `file1.c' is modified with respect to the repository,
and `file2.c' is not.  `file3.c' is modified, but other changes have
also been committed--you need to merge them with the work file before
you can check it in.

   In the above, if the repository were on a remote machine, VC only
contacts it when the variable `vc-stay-local' (or `vc-cvs-stay-local')
is `nil' (*note CVS Options::).  This is because access to the
repository may be slow, or you may be working offline and not have
access to the repository at all.  As a consequence, VC would not be
able to tell you that `file3.c' is in the "merge" state; you would
learn that only when you try to check-in your modified copy of the
file, or use a command such as `C-x v m'.

   In practice, this is not a problem because CVS handles this case
consistently whenever it arises.  In VC, you'll simply get prompted to
merge the remote changes into your work file first.  The benefits of
less network communication usually outweigh the disadvantage of not
seeing remote changes immediately.

   When a VC directory displays subdirectories it omits some that
should never contain any files under version control.  By default, this
includes Version Control subdirectories such as `RCS' and `CVS'; you
can customize this by setting the variable
`vc-directory-exclusion-list'.


File: emacs,  Node: VC Directory Commands,  Prev: VC Directory Buffer,  Up: VC Directory Mode

32.1.7.2 VC Directory Commands
..............................

VC Directory mode has a full set of navigation and marking commands for
picking out filesets.  Some of these are also available in a context
menu invoked by `mouse-2'.

   Up- and down-arrow keys move in the buffer; `n' and `p'  also move
vertically as in other list-browsing modes.  <SPC> and <TAB> behave
like down-arrow, and <BackTab> behaves like up-arrow.

   Both `C-m' and `f' visit the file on the current line.  `o' visits
that file in another window.  `q' dismisses the directory buffer.

   `x' hides up-to-date files.

   `m' marks the file or directory on the current line.  If the region
is active, `m' marks all the files in the region.  There are some
restrictions when marking: a file cannot be marked if any of its parent
directories are marked, and a directory cannot be marked if any files
in it or in its child directories are marked.

   `M' marks all the files with the same VC state as the current file
if the cursor is on a file.  If the cursor is on a directory, it marks
all child files.  With a prefix argument: marks all files and
directories.

   `u' unmarks the file or directory on the current line.  If the
region is active, it unmarks all the files in the region.

   `U' marks all the files with the same VC state as the current file
if the cursor is on a file.  If the cursor is on a directory, it
unmarks all child files.  With a prefix argument: unmarks all marked
files and directories.

   It is possible to do search, search and replace, incremental search,
and incremental regexp search on multiple files.  These commands will
work on all the marked files or the current file if nothing is marked.
If a directory is marked, the files in that directory shown in the VC
directory buffer will be used.

   `S' searches the marked files.

   `Q' does a query replace on the marked files.

   `M-s a C-s' does an incremental search on the marked files.

   `M-s a C-M-s' does an incremental regular expression search on the
marked files.

   Commands are also accessible from the VC-dir menu.  Note that some
VC backends use the VC-dir menu to make available extra,
backend-specific, commands.  For example, Git and Bazaar allow you to
manipulate "stashes" and "shelves".  (These provide a mechanism to
temporarily store uncommitted changes somewhere out of the way, and
bring them back at a later time.)

   Normal VC commands with the `C-x v' prefix work in VC directory
buffers.  Some single-key shortcuts are available as well; `=', `+',
`l', `i', and `v' behave as through prefixed with `C-x v'.

   The command `C-x v v' (`vc-next-action') operates on all the marked
files, so that you can commit several files at once.  If the underlying
VC supports atomic commits of multiple-file changesets, `C-x v v' with
a selected set of modified but not committed files will commit all of
them at once as a single changeset.

   When `C-x v v' (`vc-next-action') operates on multiple files, all of
those files must be either in the same state or in compatible states
(added, modified and removed states are considered compatible).
Otherwise it signals an error.  This differs from the behavior of older
versions of VC, which did not have fileset operations and simply did
`vc-next-action' on each file individually.

   If any files are in a state that calls for commit, `C-x v v' reads a
single log entry and uses it for the changeset as a whole.  If the
underling VCS is file- rather than changeset-oriented, the log entry
will be replicated into the history of each file.


File: emacs,  Node: Branches,  Next: Remote Repositories,  Prev: VC Directory Mode,  Up: Version Control

32.1.8 Multiple Branches of a File
----------------------------------

One use of version control is to maintain multiple "current" revisions
of a file.  For example, you might have different revisions of a
program in which you are gradually adding various unfinished new
features.  Each such independent line of development is called a
"branch".  VC allows you to create branches, switch between different
branches, and merge changes from one branch to another.  Please note,
however, that branches are not supported for SCCS.

   A file's main line of development is usually called the "trunk".
You can create multiple branches from the trunk.  How the difference
between trunk and branch is made visible is dependent on whether the
VCS uses dot-pair or monotonic version IDs.

   In VCSes with dot-pair revision IDs, the revisions on the trunk are
normally IDed 1.1, 1.2, 1.3, etc.  At any such revision, you can start
an independent branch.  A branch starting at revision 1.2 would have
revision ID 1.2.1.1, and consecutive revisions on this branch would
have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on.  If there is a second
branch also starting at revision 1.2, it would consist of revisions
1.2.2.1, 1.2.2.2, 1.2.2.3, etc.

   In VCSes with monotonic revision IDs, trunk revisions are IDed as 1,
2, 3, etc.  A branch from (say) revision 2 might start with 2.1 and
continue through 2.2, 2.3, etc.  But naming conventions for branches
and subbranches vary widely on these systems, and some (like Mercurial)
never depart from the monotonic integer sequence at all.  Consult the
documentation of the VCS you are using.

   If you omit the final component of a dot-pair revision ID, that is
called a "branch ID".  It refers to the highest existing revision on
that branch--the "head revision" of that branch.  The branches in the
dot-pair example above have branch IDs 1.2.1 and 1.2.2.

* Menu:

* Switching Branches::    How to get to another existing branch.
* Creating Branches::     How to start a new branch.
* Merging::               Transferring changes between branches.
* Multi-User Branching::  Multiple users working at multiple branches
                            in parallel.


File: emacs,  Node: Switching Branches,  Next: Creating Branches,  Up: Branches

32.1.8.1 Switching between Branches
...................................

To switch between branches, type `C-u C-x v v' and specify the revision
ID you want to select.  On a locking-based system, this version is then
visited _unlocked_ (write-protected), so you can examine it before
locking it.  Switching branches in this way is allowed only when the
file is not locked.

   On a VCS with dot-pair IDs, you can omit the minor part, thus giving
only the branch ID; this takes you to the head version on the chosen
branch.  If you only type <RET>, Emacs goes to the highest version on
the trunk.

   After you have switched to any branch (including the main branch),
you stay on it for subsequent VC commands, until you explicitly select
some other branch.


File: emacs,  Node: Creating Branches,  Next: Merging,  Prev: Switching Branches,  Up: Branches

32.1.8.2 Creating New Branches
..............................

To create a new branch from a head revision (one that is the latest in
the branch that contains it), first select that revision if necessary,
lock it with `C-x v v', and make whatever changes you want.  Then, when
you commit the changes, use `C-u C-x v v'.  This lets you specify the
revision ID for the new revision.  You should specify a suitable branch
ID for a branch starting at the current revision.  For example, if the
current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, and so
on, depending on the number of existing branches at that point.

   To create a new branch at an older revision (one that is no longer
the head of a branch), first select that revision (*note Switching
Branches::).  Your procedure will then differ depending on whether you
are using a locking or merging-based VCS.

   On a locking VCS, you will need to lock the old revision branch with
`C-x v v'.  You'll be asked to confirm, when you lock the old revision,
that you really mean to create a new branch--if you say no, you'll be
offered a chance to lock the latest revision instead.  On a
merging-based VCS you will skip this step.

   Then make your changes and type `C-x v v' again to commit a new
revision.  This automatically creates a new branch starting from the
selected revision.  You need not specially request a new branch,
because that's the only way to add a new revision at a point that is
not the head of a branch.

   After the branch is created, you "stay" on it.  That means that
subsequent check-ins create new revisions on that branch.  To leave the
branch, you must explicitly select a different revision with `C-u C-x v
v'.  To transfer changes from one branch to another, use the merge
command, described in the next section.


File: emacs,  Node: Merging,  Next: Multi-User Branching,  Prev: Creating Branches,  Up: Branches

32.1.8.3 Merging Branches
.........................

When you have finished the changes on a certain branch, you will often
want to incorporate them into the file's main line of development (the
trunk).  This is not a trivial operation, because development might
also have proceeded on the trunk, so that you must "merge" the changes
into a file that has already been changed otherwise.  VC allows you to
do this (and other things) with the `vc-merge' command.

`C-x v m (vc-merge)'
     Merge changes into the work file.

   `C-x v m' (`vc-merge') takes a set of changes and merges it into the
current version of the work file.  It firsts asks you in the minibuffer
where the changes should come from.  If you just type <RET>, Emacs
merges any changes that were made on the same branch since you checked
the file out (we call this "merging the news").  This is the common way
to pick up recent changes from the repository, regardless of whether
you have already changed the file yourself.

   You can also enter a branch ID or a pair of revision IDs in the
minibuffer.  Then `C-x v m' finds the changes from that branch, or the
differences between the two revisions you specified, and merges them
into the current revision of the current file.

   As an example, suppose that you have finished a certain feature on
branch 1.3.1.  In the meantime, development on the trunk has proceeded
to revision 1.5.  To merge the changes from the branch to the trunk,
first go to the head revision of the trunk, by typing `C-u C-x v v
<RET>'.  Revision 1.5 is now current.  If locking is used for the file,
type `C-x v v' to lock revision 1.5 so that you can change it.  Next,
type `C-x v m 1.3.1 <RET>'.  This takes the entire set of changes on
branch 1.3.1 (relative to revision 1.3, where the branch started, up to
the last revision on the branch) and merges it into the current revision
of the work file.  You can now commit the changed file, thus creating
revision 1.6 containing the changes from the branch.

   It is possible to do further editing after merging the branch, before
the next check-in.  But it is usually wiser to commit the merged
revision, then lock it and make the further changes.  This will keep a
better record of the history of changes.

   When you merge changes into a file that has itself been modified, the
changes might overlap.  We call this situation a "conflict", and
reconciling the conflicting changes is called "resolving a conflict".

   Whenever conflicts occur during merging, VC detects them, tells you
about them in the echo area, and asks whether you want help in merging.
If you say yes, it starts an Ediff session (*note Ediff: (ediff)Top.).

   If you say no, the conflicting changes are both inserted into the
file, surrounded by "conflict markers".  The example below shows how a
conflict region looks; the file is called `name' and the current master
file revision with user B's changes in it is 1.11.

     <<<<<<< name
       USER A'S VERSION
     =======
       USER B'S VERSION
     >>>>>>> 1.11

   Then you can resolve the conflicts by editing the file manually.  Or
you can type `M-x vc-resolve-conflicts' after visiting the file.  This
starts an Ediff session, as described above.  Don't forget to commit
the merged version afterwards.

   If there is more than one conflicted file in a merge, type `M-x
vc-find-conflicted-file' after resolving the conflicts in each file.
This command visits the next conflicted file, and moves point to the
first conflict marker in that file.


File: emacs,  Node: Multi-User Branching,  Prev: Merging,  Up: Branches

32.1.8.4 Multi-User Branching
.............................

It is often useful for multiple developers to work simultaneously on
different branches of a file.  CVS and later systems allow this by
default; for RCS, it is possible if you create multiple source
directories.  Each source directory should have a link named `RCS'
which points to a common directory of RCS master files.  Then each
source directory can have its own choice of selected revisions, but all
share the same common RCS records.

   This technique works reliably and automatically, provided that the
source files contain RCS version headers (*note Version Headers::).
The headers enable Emacs to be sure, at all times, which revision ID is
present in the work file.

   If the files do not have version headers, you must instead tell Emacs
explicitly in each session which branch you are working on.  To do this,
first find the file, then type `C-u C-x v v' and specify the correct
branch ID.  This ensures that Emacs knows which branch it is using
during this particular editing session.


File: emacs,  Node: Remote Repositories,  Next: Revision Tags,  Prev: Branches,  Up: Version Control

32.1.9 Remote Repositories
--------------------------

A common way of using CVS and other more advanced VCSes is to set up a
central repository on some Internet host, then have each developer
check out a personal working copy of the files on his local machine.
Committing changes to the repository, and picking up changes from other
users into one's own working area, then works by direct interactions
with the repository server.

   One difficulty is that access to a repository server is often slow,
and that developers might need to work off-line as well.  While only
third-generation decentralized VCses such as GNU Arch or Mercurial
really solve this problem, VC is designed to reduce the amount of
network interaction necessary.

   If you are using a truly decentralized VCS you can skip the rest of
this section. It describes backup and local-repository techniques that
are only useful for Subversion and earlier VCSes.

* Menu:

* Version Backups::        Keeping local copies of repository versions.
* Local Version Control::  Using another version system for local editing.


File: emacs,  Node: Version Backups,  Next: Local Version Control,  Up: Remote Repositories

32.1.9.1 Version Backups
........................

When VC sees that the repository for a file is on a remote machine, it
automatically makes local backups of unmodified versions of the
file--"automatic version backups".  This means that you can compare the
file to the repository version (`C-x v ='), or revert to that version
(`C-x v u'), without any network interactions.

   The local copy of the unmodified file is called a "version backup"
to indicate that it corresponds exactly to a version that is stored in
the repository.  Note that version backups are not the same as ordinary
Emacs backup files (*note Backup::).  But they follow a similar naming
convention.

   For a file that comes from a remote repository, VC makes a version
backup whenever you save the first changes to the file, and removes it
after you have committed your modified version to the repository. You
can disable the making of automatic version backups by setting
`vc-cvs-stay-local' to `nil' (*note CVS Options::).

   The name of the automatic version backup for version VERSION of file
FILE is `FILE.~VERSION.~'.  This is almost the same as the name used by
`C-x v ~' (*note Old Revisions::), the only difference being the
additional dot (`.')  after the version number.  This similarity is
intentional, because both kinds of files store the same kind of
information.  The file made by `C-x v ~' acts as a "manual version
backup".

   All the VC commands that operate on old versions of a file can use
both kinds of version backups.  For instance, `C-x v ~' uses either an
automatic or a manual version backup, if possible, to get the contents
of the version you request.  Likewise, `C-x v =' and `C-x v u' use
either an automatic or a manual version backup, if one of them exists,
to get the contents of a version to compare or revert to.  If you
changed a file outside of Emacs, so that no automatic version backup
was created for the previous text, you can create a manual backup of
that version using `C-x v ~', and thus obtain the benefit of the local
copy for Emacs commands.

   The only difference in Emacs's handling of manual and automatic
version backups, once they exist, is that Emacs deletes automatic
version backups when you commit to the repository.  By contrast, manual
version backups remain until you delete them.


File: emacs,  Node: Local Version Control,  Prev: Version Backups,  Up: Remote Repositories

32.1.9.2 Local Version Control
..............................

When you make many changes to a file that comes from a remote
repository, it can be convenient to have version control on your local
machine as well.  You can then record intermediate versions, revert to
a previous state, etc., before you actually commit your changes to the
remote server.

   VC lets you do this by putting a file under a second, local version
control system, so that the file is effectively registered in two
systems at the same time.  For the description here, we will assume
that the remote system is CVS, and you use RCS locally, although the
mechanism works with any combination of version control systems ("back
ends").

   To make it work with other back ends, you must make sure that the
"more local" back end comes before the "more remote" back end in the
setting of `vc-handled-backends' (*note Customizing VC::).  By default,
this variable is set up so that you can use remote CVS and local RCS as
described here.

   To start using local RCS for a file that comes from a remote CVS
server, you must _register the file in RCS_, by typing `C-u C-x v v rcs
<RET>'.  (In other words, use `vc-next-action' with a prefix argument,
and specify RCS as the back end.)

   You can do this at any time; it does not matter whether you have
already modified the file with respect to the version in the CVS
repository.  If possible, VC tries to make the RCS master start with
the unmodified repository version, then checks in any local changes as
a new version.  This works if you have not made any changes yet, or if
the unmodified repository version exists locally as a version backup
(*note Version Backups::).  If the unmodified version is not available
locally, the RCS master starts with the modified version; the only
drawback to this is that you cannot compare your changes locally to
what is stored in the repository.

   The version number of the RCS master is derived from the current CVS
version, starting a branch from it.  For example, if the current CVS
version is 1.23, the local RCS branch will be 1.23.1.  Version 1.23 in
the RCS master will be identical to version 1.23 under CVS; your first
changes are checked in as 1.23.1.1.  (If the unmodified file is not
available locally, VC will check in the modified file twice, both as
1.23 and 1.23.1.1, to make the revision numbers consistent.)

   If you do not use locking under CVS (the default), locking is also
disabled for RCS, so that editing under RCS works exactly as under CVS.

   When you are done with local editing, you can commit the final
version back to the CVS repository by typing `C-u C-x v v cvs <RET>'.
This initializes the log entry buffer (*note Log Buffer::) to contain
all the log entries you have recorded in the RCS master; you can edit
them as you wish, and then commit in CVS by typing `C-c C-c'.  If the
commit is successful, VC removes the RCS master, so that the file is
once again registered under CVS only.  (The RCS master is not actually
deleted, just renamed by appending `~' to the name, so that you can
refer to it later if you wish.)

   While using local RCS, you can pick up recent changes from the CVS
repository into your local file, or commit some of your changes back to
CVS, without terminating local RCS version control.  To do this, switch
to the CVS back end temporarily, with the `C-x v b' command:

`C-x v b'
     Switch to another back end that the current file is registered
     under (`vc-switch-backend').

`C-u C-x v b BACKEND <RET>'
     Switch to BACKEND for the current file.

   `C-x v b' does not change the buffer contents, or any files; it only
changes VC's perspective on how to handle the file.  Any subsequent VC
commands for that file will operate on the back end that is currently
selected.

   If the current file is registered in more than one back end, typing
`C-x v b' "cycles" through all of these back ends.  With a prefix
argument, it asks for the back end to use in the minibuffer.

   Thus, if you are using local RCS, and you want to pick up some recent
changes in the file from remote CVS, first visit the file, then type
`C-x v b' to switch to CVS, and finally use `C-x v m <RET>' to merge
the news (*note Merging::).  You can then switch back to RCS by typing
`C-x v b' again, and continue to edit locally.

   But if you do this, the revision numbers in the RCS master no longer
correspond to those of CVS.  Technically, this is not a problem, but it
can become difficult to keep track of what is in the CVS repository and
what is not.  So we suggest that you return from time to time to
CVS-only operation, by committing your local changes back to the
repository using `C-u C-x v v cvs <RET>'.


File: emacs,  Node: Revision Tags,  Next: Miscellaneous VC,  Prev: Remote Repositories,  Up: Version Control

32.1.10 Revision Tags
---------------------

In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS)
"tag" is a named set of file versions (one for each registered file)
that you can treat as a unit.  In a VCS with per-repository version
numbers (Subversion and most later ones) a tag is simply a symbolic
name for a revision.

   One important kind of tag is a "release", a (theoretically) stable
version of the system that is ready for distribution to users.

* Menu:

* Making Revision Tags::  The tag facilities.
* Revision Tag Caveats::  Things to be careful of when using tags.


File: emacs,  Node: Making Revision Tags,  Next: Revision Tag Caveats,  Up: Revision Tags

32.1.10.1 Making and Using Revision Tags
........................................

There are two basic commands for tags; one makes a tag with a given
name, the other retrieves a named tag.

`C-x v s NAME <RET>'
     Define the working revision of every registered file in or under
     the current directory as a tag named NAME (`vc-create-tag').

`C-x v r NAME <RET>'
     For all registered files at or below the current directory level,
     retrieve the tagged revision NAME. This command will switch to a
     branch if NAME is a branch name and your VCS distinguishes
     branches from tags.  (`vc-retrieve-tag').

     This command reports an error if any files are locked at or below
     the current directory, without changing anything; this is to avoid
     overwriting work in progress.

   Tags are inexpensive, so you need not hesitate to create them
whenever they are useful.  Branches vary in cost depending on your VCS;
in older ones they may be expensive.

   You can give a tag or branch name as an argument to `C-x v =' or
`C-x v ~' (*note Old Revisions::).  Thus, you can use it to compare a
tagged version against the current files, or two tagged versions
against each other.


File: emacs,  Node: Revision Tag Caveats,  Prev: Making Revision Tags,  Up: Revision Tags

32.1.10.2 Revision Tag Caveats
..............................

For SCCS, VC implements tags itself; these tags are visible only
through VC.  Most later systems (including CVS, Subversion, bzr, git,
and hg) have a native tag facility, and VC uses it where available;
those tags will be visible even when you bypass VC.

   There is no support for VC tags using GNU Arch yet.

   Under older VCSes (SCCS, RCS, CVS, early versions of Subversion),
renaming and deletion could create some difficulties with tags.  This is
not a VC-specific problem, but a general design issue in version
control systems that was not solved effectively until the earliest
third-generation systems.

   In a file-oriented VCS, when you rename a registered file you need
to rename its master along with it; the command `vc-rename-file' will
do this automatically.  If you are using SCCS, you must also update the
records of the tag, to mention the file by its new name
(`vc-rename-file' does this, too).  An old tag that refers to a master
file that no longer exists under the recorded name is invalid; VC can
no longer retrieve it.  It would be beyond the scope of this manual to
explain enough about RCS and SCCS to explain how to update the tags by
hand.

   Using `vc-rename-file' makes the tag remain valid for retrieval, but
it does not solve all problems.  For example, some of the files in your
program probably refer to others by name.  At the very least, the
makefile probably mentions the file that you renamed.  If you retrieve
an old tag, the renamed file is retrieved under its new name, which is
not the name that the makefile expects.  So the program won't really
work as retrieved.


File: emacs,  Node: Miscellaneous VC,  Next: Customizing VC,  Prev: Revision Tags,  Up: Version Control

32.1.11 Miscellaneous Commands and Features of VC
-------------------------------------------------

This section explains the less-frequently-used features of VC.

* Menu:

* Change Logs and VC::  Generating a change log file from log entries.
* Renaming and VC::     A command to rename both the source and master
                          file correctly.
* Version Headers::     Inserting version control headers into working files.


File: emacs,  Node: Change Logs and VC,  Next: Renaming and VC,  Up: Miscellaneous VC

32.1.11.1 Change Logs and VC
............................

If you use RCS or CVS for a program and also maintain a change log file
for it (*note Change Log::), you can generate change log entries
automatically from the version control log entries:

`C-x v a'
     Visit the current directory's change log file and, for registered
     files in that directory, create new entries for versions checked
     in since the most recent entry in the change log file.
     (`vc-update-change-log').

     This command works with RCS or CVS only, not with any of the other
     back ends.

`C-u C-x v a'
     As above, but only find entries for the current buffer's file.

`M-1 C-x v a'
     As above, but find entries for all the currently visited files
     that are maintained with version control.  This works only with
     RCS, and it puts all entries in the log for the default directory,
     which may not be appropriate.

   For example, suppose the first line of `ChangeLog' is dated
1999-04-10, and that the only check-in since then was by Nathaniel
Bowditch to `rcs2log' on 1999-05-22 with log text `Ignore log messages
that start with `#'.'.  Then `C-x v a' visits `ChangeLog' and inserts
text like this:

     1999-05-22  Nathaniel Bowditch  <nat@apn.org>

             * rcs2log: Ignore log messages that start with `#'.

You can then edit the new change log entry further as you wish.

   Some of the new change log entries may duplicate what's already in
ChangeLog.  You will have to remove these duplicates by hand.

   Normally, the log entry for file `foo' is displayed as `* foo: TEXT
OF LOG ENTRY'.  The `:' after `foo' is omitted if the text of the log
entry starts with `(FUNCTIONNAME): '.  For example, if the log entry
for `vc.el' is `(vc-do-command): Check call-process status.', then the
text in `ChangeLog' looks like this:

     1999-05-06  Nathaniel Bowditch  <nat@apn.org>

             * vc.el (vc-do-command): Check call-process status.

   When `C-x v a' adds several change log entries at once, it groups
related log entries together if they all are checked in by the same
author at nearly the same time.  If the log entries for several such
files all have the same text, it coalesces them into a single entry.
For example, suppose the most recent check-ins have the following log
entries:

* For `vc.texinfo': `Fix expansion typos.'
* For `vc.el': `Don't call expand-file-name.'
* For `vc-hooks.el': `Don't call expand-file-name.'

They appear like this in `ChangeLog':

     1999-04-01  Nathaniel Bowditch  <nat@apn.org>

             * vc.texinfo: Fix expansion typos.

             * vc.el, vc-hooks.el: Don't call expand-file-name.

   Normally, `C-x v a' separates log entries by a blank line, but you
can mark several related log entries to be clumped together (without an
intervening blank line) by starting the text of each related log entry
with a label of the form `{CLUMPNAME} '.  The label itself is not
copied to `ChangeLog'.  For example, suppose the log entries are:

* For `vc.texinfo': `{expand} Fix expansion typos.'
* For `vc.el': `{expand} Don't call expand-file-name.'
* For `vc-hooks.el': `{expand} Don't call expand-file-name.'

Then the text in `ChangeLog' looks like this:

     1999-04-01  Nathaniel Bowditch  <nat@apn.org>

             * vc.texinfo: Fix expansion typos.
             * vc.el, vc-hooks.el: Don't call expand-file-name.

   A log entry whose text begins with `#' is not copied to `ChangeLog'.
For example, if you merely fix some misspellings in comments, you can
log the change with an entry beginning with `#' to avoid putting such
trivia into `ChangeLog'.


File: emacs,  Node: Renaming and VC,  Next: Version Headers,  Prev: Change Logs and VC,  Up: Miscellaneous VC

32.1.11.2 Renaming VC Work Files and Master Files
.................................................

When you rename a registered file, you must also rename its master file
correspondingly to get proper results.  Use `vc-rename-file' to rename
the source file as you specify, and rename its master file accordingly.
It also updates any tags (*note Revision Tags::) that mention the file,
so that they use the new name; despite this, the tag thus modified may
not completely work (*note Revision Tag Caveats::).

   Some back ends do not provide an explicit rename operation to their
repositories.  After issuing `vc-rename-file', use `C-x v v' on the
original and renamed buffers and provide the necessary edit log.

   You cannot use `vc-rename-file' on a file that is locked by someone
else.


File: emacs,  Node: Version Headers,  Prev: Renaming and VC,  Up: Miscellaneous VC

32.1.11.3 Inserting Version Control Headers
...........................................

Sometimes it is convenient to put version identification strings
directly into working files.  Certain special strings called "version
headers" are replaced in each successive version by the number of that
version, the name of the user who created it, and other relevant
information.  All of the back ends that VC supports have such a
mechanism, except GNU Arch.

   VC does not normally use the information contained in these headers.
The exception is RCS--with RCS, version headers are sometimes more
reliable than the master file to determine which version of the file
you are editing.  Note that in a multi-branch environment, version
headers are necessary to make VC behave correctly (*note Multi-User
Branching::).

   Searching for RCS version headers is controlled by the variable
`vc-consult-headers'.  If it is non-`nil' (the default), Emacs searches
for headers to determine the version number you are editing.  Setting
it to `nil' disables this feature.

   Note that although CVS uses the same kind of version headers as RCS
does, VC never searches for these headers if you are using CVS,
regardless of the above setting.

   You can use the `C-x v h' command (`vc-insert-headers') to insert a
suitable header string.

`C-x v h'
     Insert headers in a file for use with your version-control system.

   The default header string is `$Id$' for RCS and `%W%' for SCCS.  You
can specify other headers to insert by setting the variables
`vc-BACKEND-header' where BACKEND is `rcs' or `sccs'.

   Instead of a single string, you can specify a list of strings; then
each string in the list is inserted as a separate header on a line of
its own.

   It may be necessary to use apparently-superfluous backslashes when
writing the strings that you put in this variable.  For instance, you
might write `"$Id\$"' rather than `"$Id$"'.  The extra backslash
prevents the string constant from being interpreted as a header, if the
Emacs Lisp file containing it is maintained with version control.

   Each header is inserted surrounded by tabs, inside comment
delimiters, on a new line at point.  Normally the ordinary comment
start and comment end strings of the current mode are used, but for
certain modes, there are special comment delimiters for this purpose;
the variable `vc-comment-alist' specifies them.  Each element of this
list has the form `(MODE STARTER ENDER)'.

   The variable `vc-static-header-alist' specifies further strings to
add based on the name of the buffer.  Its value should be a list of
elements of the form `(REGEXP . FORMAT)'.  Whenever REGEXP matches the
buffer name, FORMAT is inserted as part of the header.  A header line
is inserted for each element that matches the buffer name, and for each
string specified by `vc-BACKEND-header'.  The header line is made by
processing the string from `vc-BACKEND-header' with the format taken
from the element.  The default value for `vc-static-header-alist' is as
follows:

     (("\\.c$" .
       "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
     #endif /* lint */\n"))

It specifies insertion of text of this form:


     #ifndef lint
     static char vcid[] = "STRING";
     #endif /* lint */

Note that the text above starts with a blank line.

   If you use more than one version header in a file, put them close
together in the file.  The mechanism in `revert-buffer' that preserves
markers may not handle markers positioned between two version headers.


File: emacs,  Node: Customizing VC,  Prev: Miscellaneous VC,  Up: Version Control

32.1.12 Customizing VC
----------------------

The variable `vc-handled-backends' determines which version control
systems VC should handle.  The default value is `(RCS CVS SVN SCCS Bzr
Git Hg Mtn Arch)', so it contains all the version systems that are
currently supported.  If you want VC to ignore one or more of these
systems, exclude its name from the list.  To disable VC entirely, set
this variable to `nil'.

   The order of systems in the list is significant: when you visit a
file registered in more than one system (*note Local Version
Control::), VC uses the system that comes first in
`vc-handled-backends' by default.  The order is also significant when
you register a file for the first time, see *note Registering::, for
details.

* Menu:

* General VC Options::  Options that apply to multiple back ends.
* RCS and SCCS::        Options for RCS and SCCS.
* CVS Options::         Options for CVS.


File: emacs,  Node: General VC Options,  Next: RCS and SCCS,  Up: Customizing VC

32.1.12.1 General Options
.........................

Emacs normally does not save backup files for source files that are
maintained with version control.  If you want to make backup files even
for files that use version control, set the variable
`vc-make-backup-files' to a non-`nil' value.

   Normally the work file exists all the time, whether it is locked or
not.  If you set `vc-keep-workfiles' to `nil', then checking in a new
version with `C-x v v' deletes the work file; but any attempt to visit
the file with Emacs creates it again.  (With CVS, work files are always
kept.)

   Editing a version-controlled file through a symbolic link can be
dangerous.  It bypasses the version control system--you can edit the
file without locking it, and fail to check your changes in.  Also, your
changes might overwrite those of another user.  To protect against
this, VC checks each symbolic link that you visit, to see if it points
to a file under version control.

   The variable `vc-follow-symlinks' controls what to do when a
symbolic link points to a version-controlled file.  If it is `nil', VC
only displays a warning message.  If it is `t', VC automatically
follows the link, and visits the real file instead, telling you about
this in the echo area.  If the value is `ask' (the default), VC asks
you each time whether to follow the link.

   If `vc-suppress-confirm' is non-`nil', then `C-x v v' and `C-x v i'
can save the current buffer without asking, and `C-x v u' also operates
without asking for confirmation.  (This variable does not affect `C-x v
c'; that operation is so drastic that it should always ask for
confirmation.)

   VC mode does much of its work by running the shell commands for the
appropriate backend.  If `vc-command-messages' is non-`nil', VC
displays messages to indicate which shell commands it runs, and
additional messages when the commands finish.

   You can specify additional directories to search for version control
programs by setting the variable `vc-path'.  These directories are
searched before the usual search path.  It is rarely necessary to set
this variable, because VC normally finds the proper files automatically.


File: emacs,  Node: RCS and SCCS,  Next: CVS Options,  Prev: General VC Options,  Up: Customizing VC

32.1.12.2 Options for RCS and SCCS
..................................

By default, RCS uses locking to coordinate the activities of several
users, but there is a mode called "non-strict locking" in which you can
check-in changes without locking the file first.  Use `rcs -U' to
switch to non-strict locking for a particular file, see the `rcs'
manual page for details.

   When deducing the version control state of an RCS file, VC first
looks for an RCS version header string in the file (*note Version
Headers::).  If there is no header string, VC normally looks at the
file permissions of the work file; this is fast.  But there might be
situations when the file permissions cannot be trusted.  In this case
the master file has to be consulted, which is rather expensive.  Also
the master file can only tell you _if_ there's any lock on the file,
but not whether your work file really contains that locked version.

   You can tell VC not to use version headers to determine the file
status by setting `vc-consult-headers' to `nil'.  VC then always uses
the file permissions (if it is supposed to trust them), or else checks
the master file.

   You can specify the criterion for whether to trust the file
permissions by setting the variable `vc-mistrust-permissions'.  Its
value can be `t' (always mistrust the file permissions and check the
master file), `nil' (always trust the file permissions), or a function
of one argument which makes the decision.  The argument is the
directory name of the `RCS' subdirectory.  A non-`nil' value from the
function says to mistrust the file permissions.  If you find that the
file permissions of work files are changed erroneously, set
`vc-mistrust-permissions' to `t'.  Then VC always checks the master
file to determine the file's status.

   VC determines the version control state of files under SCCS much as
with RCS.  It does not consider SCCS version headers, though.  Thus,
the variable `vc-mistrust-permissions' affects SCCS use, but
`vc-consult-headers' does not.


File: emacs,  Node: CVS Options,  Prev: RCS and SCCS,  Up: Customizing VC

32.1.12.3 Options specific for CVS
..................................

By default, CVS does not use locking to coordinate the activities of
several users; anyone can change a work file at any time.  However,
there are ways to restrict this, resulting in behavior that resembles
locking.

   For one thing, you can set the `CVSREAD' environment variable (the
value you use makes no difference).  If this variable is defined, CVS
makes your work files read-only by default.  In Emacs, you must type
`C-x v v' to make the file writable, so that editing works in fact
similar as if locking was used.  Note however, that no actual locking
is performed, so several users can make their files writable at the
same time.  When setting `CVSREAD' for the first time, make sure to
check out all your modules anew, so that the file protections are set
correctly.

   Another way to achieve something similar to locking is to use the
"watch" feature of CVS.  If a file is being watched, CVS makes it
read-only by default, and you must also use `C-x v v' in Emacs to make
it writable.  VC calls `cvs edit' to make the file writable, and CVS
takes care to notify other developers of the fact that you intend to
change the file.  See the CVS documentation for details on using the
watch feature.

   When a file's repository is on a remote machine, VC tries to keep
network interactions to a minimum.  This is controlled by the variable
`vc-cvs-stay-local'.  There is another variable, `vc-stay-local', which
enables the feature also for other back ends that support it, including
CVS.  In the following, we will talk only about `vc-cvs-stay-local',
but everything applies to `vc-stay-local' as well.

   If `vc-cvs-stay-local' is `t' (the default), then VC uses only the
entry in the local CVS subdirectory to determine the file's state (and
possibly information returned by previous CVS commands).  One
consequence of this is that when you have modified a file, and somebody
else has already checked in other changes to the file, you are not
notified of it until you actually try to commit.  (But you can try to
pick up any recent changes from the repository first, using `C-x v m
<RET>', *note Merging::).

   When `vc-cvs-stay-local' is `t', VC also makes local version
backups, so that simple diff and revert operations are completely local
(*note Version Backups::).

   On the other hand, if you set `vc-cvs-stay-local' to `nil', then VC
queries the remote repository _before_ it decides what to do in
`vc-next-action' (`C-x v v'), just as it does for local repositories.
It also does not make any version backups.

   You can also set `vc-cvs-stay-local' to a regular expression that is
matched against the repository host name; VC then stays local only for
repositories from hosts that match the pattern.

   You can specify additional command line options to pass to all CVS
operations in the variable `vc-cvs-global-switches'.  These switches
are inserted immediately after the `cvs' command, before the name of
the operation to invoke.


File: emacs,  Node: Change Log,  Next: Tags,  Prev: Version Control,  Up: Maintaining

32.2 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 `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.

* Menu:

* Change Log Commands:: Commands for editing change log files.
* Format of ChangeLog:: What the change log file looks like.


File: emacs,  Node: Change Log Commands,  Next: Format of ChangeLog,  Up: Change Log

32.2.1 Change Log Commands
--------------------------

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.

   `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 variable `add-log-keep-changes-together' is non-`nil', `C-x
4 a' adds to any existing item for the file rather than starting a new
item.

   If `add-log-always-start-new-record' is non-`nil', `C-x 4 a' always
makes a new entry, even if the last entry was made by you and on the
same date.

   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 `next-error' command (by default bound to `C-x `')
to move between entries in the Change Log, when Change Log mode is on.
You will jump to the actual site in the file that was changed, not just
to the next Change Log entry.  You can also use `previous-error' to
move back in the same list.

   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.

   Version control systems are another way to keep track of changes in
your program and keep a change log.  In the VC log buffer, typing `C-c
C-a' (`log-edit-insert-changelog') inserts the relevant Change Log
entry, if one exists (*note Log Buffer::).  You can also insert a VC
log entry into a Change Log buffer by typing `C-x v a'
(`vc-update-change-log') in the Change Log buffer (*note Change Logs
and VC::).


File: emacs,  Node: Format of ChangeLog,  Prev: Change Log Commands,  Up: Change Log

32.2.2 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
`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 "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.

     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, 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:

     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.


File: emacs,  Node: Tags,  Next: EDE,  Prev: Change Log,  Up: Maintaining

32.3 Tags Tables
================

A "tag" is a reference to a subunit in a program or in a document.  In
program source code, tags reference syntactic elements of the program:
functions, subroutines, data types, macros, etc.  In a document, tags
reference chapters, sections, appendices, etc.  Each tag specifies the
name of the file where the corresponding subunit is defined, and the
position of the subunit's definition in that file.

   A "tags table" records the tags extracted by scanning the source
code of a certain program or a certain document.  Tags extracted from
generated files reference the original files, rather than the generated
files that were scanned during tag extraction.  Examples of generated
files include C files generated from Cweb source files, from a Yacc
parser, or from Lex scanner definitions; `.i' preprocessed C files; and
Fortran files produced by preprocessing `.fpp' source files.

   To produce a tags table, you use the `etags' command, submitting it
a document or the source code of a program.  `etags' writes the tags to
a "tags table file", or "tags file" in short.  The conventional name
for a tags file is `TAGS'.

   Emacs uses the information recorded in tags tables in commands that
search or replace through multiple source files: these commands use the
names of the source files recorded in the tags table to know which
files to search.  Other commands, such as `M-.', which finds the
definition of a function, use the recorded information about the
function names and positions to find the source file and the position
within that file where the function is defined.

   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

32.3.1 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, `#undef' 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', and
     so are struct members, unless you specify `--no-members'.  Use of
     `--no-globals', `--no-defines' and `--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 `--declarations'
     option to `etags'.

   * 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 `--no-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',
     `\index', `\def', `\newcommand', `\renewcommand',
     `\newenvironment' or `\renewenvironment' 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="mycommand:myothercommand"
          export TEXTAGS

     specifies (using Bourne shell syntax) that the commands
     `\mycommand' and `\myothercommand' 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 HTML input files, the tags are the `title' and the `h1', `h2',
     `h3' headers.  Also, tags are `name=' in anchors and all
     occurrences of `id='.

   * In Lua input files, all functions are tags.

   * In makefiles, targets are tags; additionally, variables are tags
     unless you specify `--no-globals'.

   * 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 `CLASS::VARIABLE' and
     `CLASS::FUNCTION'.

   * In Pascal code, the tags are the functions and procedures defined
     in the file.

   * In Perl code, the tags are the packages, subroutines and variables
     defined by the `package', `sub', `my' and `local' keywords.  Use
     `--globals' if you want to tag global variables.  Tags for
     subroutines are named `PACKAGE::SUB'.  The name for subroutines
     defined in the default package is `main::SUB'.

   * In PHP code, tags are functions, classes and defines.  Vars are
     tags too, unless you use the `--no-members' option.

   * In PostScript code, the tags are the functions.

   * In Prolog code, tags are predicates and rules at the beginning of
     line.

   * 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

32.3.2 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.  You can optionally
specify a different file name for the tags table by using the
`--output=FILE' option; specifying `-' as a file name prints the tags
table to standard output.

   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 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 `--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 the tags file is `-' or is in the `/dev' directory, however,
the file names are made relative to the current working directory.
This is useful, for example, when writing the tags to `/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 `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::).

   The option `--parse-stdin=FILE' is mostly useful when calling
`etags' from programs.  It can be used (only once) in place of a file
name on the command line.  `Etags' will read from standard input and
mark the produced tags as belonging to the file FILE.

   `etags --help' outputs 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.  If followed by one or more `--language=LANG' options, it
outputs detailed information about how tags are generated for LANG.


File: emacs,  Node: Etags Regexps,  Next: Select Tags Table,  Prev: Create Tags Table,  Up: Tags

32.3.3 Etags Regexps
--------------------

The `--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 `--regex' options, all of them are used in parallel.
The syntax is:

     --regex=[{LANGUAGE}]/TAGREGEXP/[NAMEREGEXP/]MODIFIERS

   The essential part of the option value is 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 `[ \t]*'.

   In these regular expressions, `\' quotes the next character, and all
the GCC character escape sequences are supported (`\a' for bell, `\b'
for back space, `\d' for delete, `\e' for escape, `\f' for formfeed,
`\n' for newline, `\r' for carriage return, `\t' for tab, and `\v' for
vertical tab).

   Ideally, TAGREGEXP should not match more characters than are needed
to recognize what you want to tag.  If the syntax requires you to write
TAGREGEXP so it matches more characters beyond the tag itself, 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 MODIFIERS are a sequence of zero or more characters that modify
the way `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:

`i'
     Ignore case when matching this regexp.

`m'
     Match this regular expression against the whole file, so that
     multi-line matches are possible.

`s'
     Match this regular expression against the whole file, and allow
     `.' in TAGREGEXP to match newlines.

   The `-R' option cancels all the regexps defined by preceding
`--regex' options.  It too applies to the file names following it.
Here's an example:

     etags --regex=/REG1/i voo.doo --regex=/REG2/m \
         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'.  REG1 is checked against each line of
`voo.doo' and `bar.ber', in a case-insensitive way, while REG2 is
checked against the whole `bar.ber' file, permitting multi-line
matches, in a case-sensitive way.  `etags' uses only the Lisp tags
rules, with no user-specified regexp matching, to recognize tags in
`los.er'.

   You can restrict a `--regex' option to match only files of a given
language by using the optional prefix {LANGUAGE}.  (`etags --help'
prints the list of languages recognized by `etags'.)  This is
particularly useful when storing many predefined regular expressions
for `etags' in a file.  The following example tags the `DEFVAR' macros
in the Emacs source files, for the C language only:

     --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'

When you have complex regular expressions, you can store the list of
them 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=@CASE-SENSITIVE-FILE --ignore-case-regex=@IGNORE-CASE-FILE

A regex file for `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 `@', `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 `--', that line is a comment.

   For example, we 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

32.3.4 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, with `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 `visit-tags-table' does is store the file name in
the variable `tags-file-name', and setting the variable yourself is
just as good.  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.

   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

32.3.5 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

32.3.6 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.  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.

`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.  For instance, to skip the rest of the
current file, you can type `M-> M-,'.

   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.  *Note Grep Searching::.


File: emacs,  Node: List Tags,  Prev: Tags Search,  Up: Tags

32.3.7 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 by setting the
variable `tags-tag-face' to a 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: EDE,  Next: Emerge,  Prev: Tags,  Up: Maintaining

32.4 Emacs Development Environment
==================================

EDE ("Emacs Development Environment") is a package that simplifies the
task of creating, building, and debugging large programs with Emacs.
It provides some of the features of an IDE, or "Integrated Development
Environment", in Emacs.

   This section provides a brief description of EDE usage.  For full
details, see *note EDE: (ede)Top.

   EDE is implemented as a global minor mode (*note Minor Modes::).  To
enable it, type `M-x global-ede-mode' or click on the `Project Support
(EDE)' item in the `Tools' menu.  You can also enable EDE each time you
start Emacs, by adding the following line to your initialization file:

     (global-ede-mode t)

Activating EDE adds a menu named `Development' to the menu bar.  Many
EDE commands, including the ones described below, can be invoked from
this menu.

   EDE organizes files into "projects", which correspond to directory
trees.  The "project root" is the topmost directory of a project.  To
define a new project, visit a file in the desired project root and type
`M-x ede-new'.  This command prompts for a "project type", which refers
to the underlying method that EDE will use to manage the project (*note
EDE: (ede)Creating a Project.).  The most common project types are
`Make', which uses Makefiles, and `Automake', which uses GNU Automake
(*note Automake: (automake)Top.).  In both cases, EDE also creates a
file named `Project.ede', which stores information about the project.

   A project may contain one or more "targets".  A target can be an
object file, executable program, or some other type of file, which is
"built" from one or more of the files in the project.

   To add a new "target" to a project, type `C-c . t' (`M-x
ede-new-target').  This command also asks if you wish to "add" the
current file to that target, which means that the target is to be built
from that file.  After you have defined a target, you can add more
files to it by typing `C-c . a' (`ede-add-file').

   To build a target, type `C-c . c' (`ede-compile-target').  To build
all the targets in the project, type `C-c . C' (`ede-compile-project').
EDE uses the file types to guess how the target should be built.


File: emacs,  Node: Emerge,  Prev: EDE,  Up: Maintaining

32.5 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.  For other ways to compare files, see *note Comparing Files::,
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::  Miscellaneous issues.


File: emacs,  Node: Overview of Emerge,  Next: Submodes of Emerge,  Up: Emerge

32.5.1 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 (*note Merge Commands::).  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

32.5.2 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'.  This mode is only relevant when there is an ancestor.

   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, turn 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

32.5.3 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 that you have never 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

32.5.4 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.

`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.  With an argument,
     reestablish the default three-window display.

`-'
     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

32.5.5 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.


File: emacs,  Node: Combining in Emerge,  Next: Fine Points of Emerge,  Prev: Exiting Emerge,  Up: Emerge

32.5.6 Combining the Two Versions
---------------------------------

Sometimes you want to keep _both_ alternatives for a particular
difference.  To do this, use `x c', which edits the merge buffer like
this:

     #ifdef NEW
     VERSION FROM A BUFFER
     #else /* not NEW */
     VERSION FROM B BUFFER
     #endif /* not NEW */

While this example shows C preprocessor conditionals delimiting the two
alternative versions, you can specify the strings to use by setting the
variable `emerge-combine-versions-template' to a string of your choice.
In the string, `%a' says where to put version A, and `%b' says where to
put version B.  The default setting, which produces the results shown
above, looks like this:

     "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"


File: emacs,  Node: Fine Points of Emerge,  Prev: Combining in Emerge,  Up: Emerge

32.5.7 Fine Points of Emerge
----------------------------

During the merge, you mustn't try to edit the A and B buffers yourself.
Emerge modifies them temporarily, but ultimately puts them back the way
they were.

   You can have any number of merges going at once--just don't use any
one buffer as input to more than one merge at once, since the temporary
changes made in these buffers would get in each other's way.

   Starting Emerge can take a long time because it needs to compare the
files fully.  Emacs can't do anything else until `diff' finishes.
Perhaps in the future someone will change Emerge to do the comparison in
the background when the input files are large--then you could keep on
doing other things with Emacs until Emerge is ready to accept commands.

   After setting up the merge, Emerge runs the hook
`emerge-startup-hook'.  *Note Hooks::.


File: emacs,  Node: Abbrevs,  Next: Picture Mode,  Prev: Maintaining,  Up: Top

33 Abbrevs
**********

A defined "abbrev" is a word which "expands", if you insert it, into
some different text.  Abbrevs are defined by the user to expand in
specific ways.  For example, you might define `foo' as an abbrev
expanding to `find outer otter'.  Then you could insert `find outer
otter ' into the buffer by typing `f o o <SPC>'.

   A second kind of abbreviation facility is called "dynamic abbrev
expansion".  You use dynamic abbrev expansion with an explicit command
to expand the letters in the buffer before point by looking for other
words in the buffer that start with those letters.  *Note Dynamic
Abbrevs::.

   "Hippie" expansion generalizes abbreviation expansion.  *Note Hippie
Expansion: (autotype)Hippie Expand.

* Menu:

* Abbrev Concepts::   Fundamentals of defined abbrevs.
* Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
* Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
* Saving Abbrevs::    Saving the entire list of abbrevs for another session.
* Dynamic Abbrevs::   Abbreviations for words already in the buffer.
* Dabbrev Customization:: What is a word, for dynamic abbrevs.  Case handling.


File: emacs,  Node: Abbrev Concepts,  Next: Defining Abbrevs,  Up: Abbrevs

33.1 Abbrev Concepts
====================

An "abbrev" is a word which has been defined to "expand" into a
specified "expansion".  When you insert a word-separator character
following the abbrev, that expands the abbrev--replacing the abbrev
with its expansion.  For example, if `foo' is defined as an abbrev
expanding to `find outer otter', then you can insert `find outer
otter.' into the buffer by typing `f o o .'.

   Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
but they do not expand until Abbrev mode is enabled again.  The command
`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
turns Abbrev mode on if the argument is positive, off otherwise.  *Note
Minor Modes::.  `abbrev-mode' is also a variable; Abbrev mode is on
when the variable is non-`nil'.  The variable `abbrev-mode'
automatically becomes local to the current buffer when it is set.

   Abbrevs can have "mode-specific" definitions, active only in one
major mode.  Abbrevs can also have "global" definitions that are active
in all major modes.  The same abbrev can have a global definition and
various mode-specific definitions for different major modes.  A
mode-specific definition for the current major mode overrides a global
definition.

   You can define abbrevs interactively during the editing session.  You
can also save lists of abbrev definitions in files for use in later
sessions.  Some users keep extensive lists of abbrevs that they load in
every session.


File: emacs,  Node: Defining Abbrevs,  Next: Expanding Abbrevs,  Prev: Abbrev Concepts,  Up: Abbrevs

33.2 Defining Abbrevs
=====================

`C-x a g'
     Define an abbrev, using one or more words before point as its
     expansion (`add-global-abbrev').

`C-x a l'
     Similar, but define an abbrev specific to the current major mode
     (`add-mode-abbrev').

`C-x a i g'
     Define a word in the buffer as an abbrev
     (`inverse-add-global-abbrev').

`C-x a i l'
     Define a word in the buffer as a mode-specific abbrev
     (`inverse-add-mode-abbrev').

`M-x define-global-abbrev <RET> ABBREV <RET> EXP <RET>'
     Define ABBREV as an abbrev expanding into EXP.

`M-x define-mode-abbrev <RET> ABBREV <RET> EXP <RET>'
     Define ABBREV as a mode-specific abbrev expanding into EXP.

`M-x kill-all-abbrevs'
     Discard all abbrev definitions, leaving a blank slate.

   The usual way to define an abbrev is to enter the text you want the
abbrev to expand to, position point after it, and type `C-x a g'
(`add-global-abbrev').  This reads the abbrev itself using the
minibuffer, and then defines it as an abbrev for one or more words
before point.  Use a numeric argument to say how many words before
point should be taken as the expansion.  For example, to define the
abbrev `foo' as mentioned above, insert the text `find outer otter' and
then type `C-u 3 C-x a g f o o <RET>'.

   An argument of zero to `C-x a g' means to use the contents of the
region as the expansion of the abbrev being defined.

   The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
mode-specific abbrev.  Mode-specific abbrevs are active only in a
particular major mode.  `C-x a l' defines an abbrev for the major mode
in effect at the time `C-x a l' is typed.  The arguments work the same
as for `C-x a g'.

   If the abbrev text itself is already in the buffer, you can use the
commands `C-x a i g' (`inverse-add-global-abbrev') and `C-x a i l'
(`inverse-add-mode-abbrev') to define it as an abbrev by specify the
expansion in the minibuffer.  These commands are called "inverse"
because they invert the meaning of the two text strings they use (one
from the buffer and one read with the minibuffer).

   You can define an abbrev without inserting either the abbrev or its
expansion in the buffer using the command `define-global-abbrev'.  It
reads two arguments--the abbrev, and its expansion.  The command
`define-mode-abbrev' does likewise for a mode-specific abbrev.

   To change the definition of an abbrev, just define a new definition.
When the abbrev has a prior definition, the abbrev definition commands
ask for confirmation before replacing it.

   To remove an abbrev definition, give a negative argument to the
abbrev definition command: `C-u - C-x a g' or `C-u - C-x a l'.  The
former removes a global definition, while the latter removes a
mode-specific definition.  `M-x kill-all-abbrevs' removes all abbrev
definitions, both global and local.


File: emacs,  Node: Expanding Abbrevs,  Next: Editing Abbrevs,  Prev: Defining Abbrevs,  Up: Abbrevs

33.3 Controlling Abbrev Expansion
=================================

When Abbrev mode is enabled, an abbrev expands whenever it is present
in the buffer just before point and you type a self-inserting
whitespace or punctuation character (<SPC>, comma, etc.).  More
precisely, any character that is not a word constituent expands an
abbrev, and any word-constituent character can be part of an abbrev.
The most common way to use an abbrev is to insert it and then insert a
punctuation or whitespace character to expand it.

   Abbrev expansion preserves case; thus, `foo' expands into `find
outer otter'; `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
OTTER' or `Find Outer Otter' according to the variable
`abbrev-all-caps' (setting it non-`nil' specifies `FIND OUTER OTTER').

   These commands are used to control abbrev expansion:

`M-''
     Separate a prefix from a following abbrev to be expanded
     (`abbrev-prefix-mark').

`C-x a e'
     Expand the abbrev before point (`expand-abbrev').  This is
     effective even when Abbrev mode is not enabled.

`M-x expand-region-abbrevs'
     Expand some or all abbrevs found in the region.

   You may wish to expand an abbrev and attach a prefix to the
expansion; for example, if `cnst' expands into `construction', you
might want to use it to enter `reconstruction'.  It does not work to
type `recnst', because that is not necessarily a defined abbrev.  What
you can do is use the command `M-'' (`abbrev-prefix-mark') in between
the prefix `re' and the abbrev `cnst'.  First, insert `re'.  Then type
`M-''; this inserts a hyphen in the buffer to indicate that it has done
its work.  Then insert the abbrev `cnst'; the buffer now contains
`re-cnst'.  Now insert a non-word character to expand the abbrev `cnst'
into `construction'.  This expansion step also deletes the hyphen that
indicated `M-'' had been used.  The result is the desired
`reconstruction'.

   If you actually want the text of the abbrev in the buffer, rather
than its expansion, you can accomplish this by inserting the following
punctuation with `C-q'.  Thus, `foo C-q ,' leaves `foo,' in the buffer,
not expanding it.

   If you expand an abbrev by mistake, you can undo the expansion and
bring back the abbrev itself by typing `C-_' to undo (*note Undo::).
This also undoes the insertion of the non-word character that expanded
the abbrev.  If the result you want is the terminating non-word
character plus the unexpanded abbrev, you must reinsert the terminating
character, quoting it with `C-q'.  You can also use the command `M-x
unexpand-abbrev' to cancel the last expansion without deleting the
terminating character.

   `M-x expand-region-abbrevs' searches through the region for defined
abbrevs, and for each one found offers to replace it with its expansion.
This command is useful if you have typed in text using abbrevs but
forgot to turn on Abbrev mode first.  It may also be useful together
with a special set of abbrev definitions for making several global
replacements at once.  This command is effective even if Abbrev mode is
not enabled.

   Expanding any abbrev runs `abbrev-expand-functions', a special hook.
Functions in this special hook can make arbitrary changes to the abbrev
expansion.  *Note Abbrev Expansion: (elisp)Abbrev Expansion.


File: emacs,  Node: Editing Abbrevs,  Next: Saving Abbrevs,  Prev: Expanding Abbrevs,  Up: Abbrevs

33.4 Examining and Editing Abbrevs
==================================

`M-x list-abbrevs'
     Display a list of all abbrev definitions.  With a numeric
     argument, list only local abbrevs.

`M-x edit-abbrevs'
     Edit a list of abbrevs; you can add, alter or remove definitions.

   The output from `M-x list-abbrevs' looks like this:

     VARIOUS OTHER TABLES...
     (lisp-mode-abbrev-table)
     "dk"          0    "define-key"
     (global-abbrev-table)
     "dfn"         0    "definition"

(Some blank lines of no semantic significance, and some other abbrev
tables, have been omitted.)

   A line containing a name in parentheses is the header for abbrevs in
a particular abbrev table; `global-abbrev-table' contains all the global
abbrevs, and the other abbrev tables that are named after major modes
contain the mode-specific abbrevs.

   Within each abbrev table, each nonblank line defines one abbrev.  The
word at the beginning of the line is the abbrev.  The number that
follows is the number of times the abbrev has been expanded.  Emacs
keeps track of this to help you see which abbrevs you actually use, so
that you can eliminate those that you don't use often.  The string at
the end of the line is the expansion.

   Some abbrevs are marked with `(sys)'.  These "system" abbrevs (*note
Abbrevs: (elisp)Abbrevs.) are pre-defined by various modes, and are not
saved to your abbrev file.  To disable a "system" abbrev, define an
abbrev of the same name that expands to itself, and save it to your
abbrev file.

   `M-x edit-abbrevs' allows you to add, change or kill abbrev
definitions by editing a list of them in an Emacs buffer.  The list has
the same format described above.  The buffer of abbrevs is called
`*Abbrevs*', and is in Edit-Abbrevs mode.  Type `C-c C-c' in this
buffer to install the abbrev definitions as specified in the
buffer--and delete any abbrev definitions not listed.

   The command `edit-abbrevs' is actually the same as `list-abbrevs'
except that it selects the buffer `*Abbrevs*' whereas `list-abbrevs'
merely displays it in another window.


File: emacs,  Node: Saving Abbrevs,  Next: Dynamic Abbrevs,  Prev: Editing Abbrevs,  Up: Abbrevs

33.5 Saving Abbrevs
===================

These commands allow you to keep abbrev definitions between editing
sessions.

`M-x write-abbrev-file <RET> FILE <RET>'
     Write a file FILE describing all defined abbrevs.

`M-x read-abbrev-file <RET> FILE <RET>'
     Read the file FILE and define abbrevs as specified therein.

`M-x quietly-read-abbrev-file <RET> FILE <RET>'
     Similar but do not display a message about what is going on.

`M-x define-abbrevs'
     Define abbrevs from definitions in current buffer.

`M-x insert-abbrevs'
     Insert all abbrevs and their expansions into current buffer.

   `M-x write-abbrev-file' reads a file name using the minibuffer and
then writes a description of all current abbrev definitions into that
file.  This is used to save abbrev definitions for use in a later
session.  The text stored in the file is a series of Lisp expressions
that, when executed, define the same abbrevs that you currently have.

   `M-x read-abbrev-file' reads a file name using the minibuffer and
then reads the file, defining abbrevs according to the contents of the
file.  The function `quietly-read-abbrev-file' is similar except that
it does not display a message in the echo area; you cannot invoke it
interactively, and it is used primarily in your init file (*note Init
File::).  If either of these functions is called with `nil' as the
argument, it uses the file given by the variable `abbrev-file-name',
which is `~/.emacs.d/abbrev_defs' by default.  This is your standard
abbrev definition file, and Emacs loads abbrevs from it automatically
when it starts up.  (As an exception, Emacs does not load the abbrev
file when it is started in batch mode.  *Note Initial Options::, for a
description of batch mode.)

   Emacs will offer to save abbrevs automatically if you have changed
any of them, whenever it offers to save all files (for `C-x s' or `C-x
C-c').  It saves them in the file specified by `abbrev-file-name'.
This feature can be inhibited by setting the variable `save-abbrevs' to
`nil'.

   The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
similar to the previous commands but work on text in an Emacs buffer.
`M-x insert-abbrevs' inserts text into the current buffer after point,
describing all current abbrev definitions; `M-x define-abbrevs' parses
the entire current buffer and defines abbrevs accordingly.


File: emacs,  Node: Dynamic Abbrevs,  Next: Dabbrev Customization,  Prev: Saving Abbrevs,  Up: Abbrevs

33.6 Dynamic Abbrev Expansion
=============================

The abbrev facility described above operates automatically as you
insert text, but all abbrevs must be defined explicitly.  By contrast,
"dynamic abbrevs" allow the meanings of abbreviations to be determined
automatically from the contents of the buffer, but dynamic abbrev
expansion happens only when you request it explicitly.

`M-/'
     Expand the word in the buffer before point as a "dynamic abbrev",
     by searching in the buffer for words starting with that
     abbreviation (`dabbrev-expand').

`C-M-/'
     Complete the word before point as a dynamic abbrev
     (`dabbrev-completion').

   For example, if the buffer contains `does this follow ' and you type
`f o M-/', the effect is to insert `follow' because that is the last
word in the buffer that starts with `fo'.  A numeric argument to `M-/'
says to take the second, third, etc. distinct expansion found looking
backward from point.  Repeating `M-/' searches for an alternative
expansion by looking farther back.  After scanning all the text before
point, it searches the text after point.  The variable `dabbrev-limit',
if non-`nil', specifies how far away in the buffer to search for an
expansion.

   After scanning the current buffer, `M-/' normally searches other
buffers, unless you have set `dabbrev-check-all-buffers' to `nil'.

   For finer control over which buffers to scan, customize the variable
`dabbrev-ignored-buffer-regexps'.  Its value is a list of regular
expressions.  If a buffer's name matches any of these regular
expressions, dynamic abbrev expansion skips that buffer.

   A negative argument to `M-/', as in `C-u - M-/', says to search
first for expansions after point, then other buffers, and consider
expansions before point only as a last resort.  If you repeat the `M-/'
to look for another expansion, do not specify an argument.  Repeating
`M-/' cycles through all the expansions after point and then the
expansions before point.

   After you have expanded a dynamic abbrev, you can copy additional
words that follow the expansion in its original context.  Simply type
`<SPC> M-/' for each additional word you want to copy.  The spacing and
punctuation between words is copied along with the words.

   The command `C-M-/' (`dabbrev-completion') performs completion of a
dynamic abbrev.  Instead of trying the possible expansions one by one,
it finds all of them, then inserts the text that they have in common.
If they have nothing in common, `C-M-/' displays a list of completions,
from which you can select a choice in the usual manner.  *Note
Completion::.

   Dynamic abbrev expansion is completely independent of Abbrev mode;
the expansion of a word with `M-/' is completely independent of whether
it has a definition as an ordinary abbrev.


File: emacs,  Node: Dabbrev Customization,  Prev: Dynamic Abbrevs,  Up: Abbrevs

33.7 Customizing Dynamic Abbreviation
=====================================

Normally, dynamic abbrev expansion ignores case when searching for
expansions.  That is, the expansion need not agree in case with the word
you are expanding.

   This feature is controlled by the variable
`dabbrev-case-fold-search'.  If it is `t', case is ignored in this
search; if it is `nil', the word and the expansion must match in case.
If the value of `dabbrev-case-fold-search' is `case-fold-search', which
is true by default, then the variable `case-fold-search' controls
whether to ignore case while searching for expansions.

   Normally, dynamic abbrev expansion preserves the case pattern _of
the dynamic abbrev you are expanding_, by converting the expansion to
that case pattern.

   The variable `dabbrev-case-replace' controls whether to preserve the
case pattern of the dynamic abbrev.  If it is `t', the dynamic abbrev's
case pattern is preserved in most cases; if it is `nil', the expansion
is always copied verbatim.  If the value of `dabbrev-case-replace' is
`case-replace', which is true by default, then the variable
`case-replace' controls whether to copy the expansion verbatim.

   However, if the expansion contains a complex mixed case pattern, and
the dynamic abbrev matches this pattern as far as it goes, then the
expansion is always copied verbatim, regardless of those variables.
Thus, for example, if the buffer contains
`variableWithSillyCasePattern', and you type `v a M-/', it copies the
expansion verbatim including its case pattern.

   The variable `dabbrev-abbrev-char-regexp', if non-`nil', controls
which characters are considered part of a word, for dynamic expansion
purposes.  The regular expression must match just one character, never
two or more.  The same regular expression also determines which
characters are part of an expansion.  The value `nil' has a special
meaning: dynamic abbrevs are made of word characters, but expansions are
made of word and symbol characters.

   In shell scripts and makefiles, a variable name is sometimes prefixed
with `$' and sometimes not.  Major modes for this kind of text can
customize dynamic abbrev expansion to handle optional prefixes by
setting the variable `dabbrev-abbrev-skip-leading-regexp'.  Its value
should be a regular expression that matches the optional prefix that
dynamic abbrev expression should ignore.


File: emacs,  Node: Picture Mode,  Next: Sending Mail,  Prev: Abbrevs,  Up: Top

34 Editing Pictures
*******************

To edit a picture made out of text characters (for example, a picture
of the division of a register into fields, as a comment in a program),
use the command `M-x picture-mode' to enter Picture mode.

   In Picture mode, editing is based on the "quarter-plane" model of
text, according to which the text characters lie studded on an area that
stretches infinitely far to the right and downward.  The concept of the
end of a line does not exist in this model; the most you can say is
where the last nonblank character on the line is found.

   Of course, Emacs really always considers text as a sequence of
characters, and lines really do have ends.  But Picture mode replaces
the most frequently-used commands with variants that simulate the
quarter-plane model of text.  They do this by inserting spaces or by
converting tabs to spaces.

   Most of the basic editing commands of Emacs are redefined by Picture
mode to do essentially the same thing but in a quarter-plane way.  In
addition, Picture mode defines various keys starting with the `C-c'
prefix to run special picture editing commands.

   One of these keys, `C-c C-c', is particularly important.  Often a
picture is part of a larger file that is usually edited in some other
major mode.  Picture mode records the name of the previous major mode
so you can use the `C-c C-c' command (`picture-mode-exit') later to go
back to that mode.  `C-c C-c' also deletes spaces from the ends of
lines, unless given a numeric argument.

   The special commands of Picture mode all work in other modes
(provided the `picture' library is loaded), but are not bound to keys
except in Picture mode.  The descriptions below talk of moving "one
column" and so on, but all the picture mode commands handle numeric
arguments as their normal equivalents do.

   Turning on Picture mode runs the hook `picture-mode-hook'.
Additional extensions to Picture mode can be found in `artist.el'.

* Menu:

* Basic Picture::         Basic concepts and simple commands of Picture Mode.
* Insert in Picture::     Controlling direction of cursor motion
                            after "self-inserting" characters.
* Tabs in Picture::       Various features for tab stops and indentation.
* Rectangles in Picture:: Clearing and superimposing rectangles.


File: emacs,  Node: Basic Picture,  Next: Insert in Picture,  Up: Picture Mode

34.1 Basic Editing in Picture Mode
==================================

Most keys do the same thing in Picture mode that they usually do, but
do it in a quarter-plane style.  For example, `C-f' is rebound to run
`picture-forward-column', a command which moves point one column to the
right, inserting a space if necessary so that the actual end of the
line makes no difference.  `C-b' is rebound to run
`picture-backward-column', which always moves point left one column,
converting a tab to multiple spaces if necessary.  `C-n' and `C-p' are
rebound to run `picture-move-down' and `picture-move-up', which can
either insert spaces or convert tabs as necessary to make sure that
point stays in exactly the same column.  `C-e' runs
`picture-end-of-line', which moves to after the last nonblank character
on the line.  There is no need to change `C-a', as the choice of screen
model does not affect beginnings of lines.

   Insertion of text is adapted to the quarter-plane screen model
through the use of Overwrite mode (*note Minor Modes::.)
Self-inserting characters replace existing text, column by column,
rather than pushing existing text to the right.  <RET> runs
`picture-newline', which just moves to the beginning of the following
line so that new text will replace that line.

   In Picture mode, the commands that normally delete or kill text,
instead erase text (replacing it with spaces).  <DEL>
(`picture-backward-clear-column') replaces the preceding character with
a space rather than removing it; this moves point backwards.  `C-d'
(`picture-clear-column') replaces the next character or characters with
spaces, but does not move point.  (If you want to clear characters to
spaces and move forward over them, use <SPC>.)  `C-k'
(`picture-clear-line') really kills the contents of lines, but does not
delete the newlines from the buffer.

   To do actual insertion, you must use special commands.  `C-o'
(`picture-open-line') creates a blank line after the current line; it
never splits a line.  `C-M-o' (`split-line') makes sense in Picture
mode, so it is not changed.  `C-j' (`picture-duplicate-line') inserts
another line with the same contents below the current line.

   To do actual deletion in Picture mode, use `C-w', `C-c C-d' (which
is defined as `delete-char', as `C-d' is in other modes), or one of the
picture rectangle commands (*note Rectangles in Picture::).


File: emacs,  Node: Insert in Picture,  Next: Tabs in Picture,  Prev: Basic Picture,  Up: Picture Mode

34.2 Controlling Motion after Insert
====================================

Since "self-inserting" characters in Picture mode overwrite and move
point, there is no essential restriction on how point should be moved.
Normally point moves right, but you can specify any of the eight
orthogonal or diagonal directions for motion after a "self-inserting"
character.  This is useful for drawing lines in the buffer.

`C-c <'
`C-c <LEFT>'
     Move left after insertion (`picture-movement-left').

`C-c >'
`C-c <RIGHT>'
     Move right after insertion (`picture-movement-right').

`C-c ^'
`C-c <UP>'
     Move up after insertion (`picture-movement-up').

`C-c .'
`C-c <DOWN>'
     Move down after insertion (`picture-movement-down').

`C-c `'
`C-c <HOME>'
     Move up and left ("northwest") after insertion
     (`picture-movement-nw').

`C-c ''
`C-c <prior>'
     Move up and right ("northeast") after insertion
     (`picture-movement-ne').

`C-c /'
`C-c <END>'
     Move down and left ("southwest") after insertion
     (`picture-movement-sw').

`C-c \'
`C-c <next>'
     Move down and right ("southeast") after insertion
     (`picture-movement-se').

   Two motion commands move based on the current Picture insertion
direction.  The command `C-c C-f' (`picture-motion') moves in the same
direction as motion after "insertion" currently does, while `C-c C-b'
(`picture-motion-reverse') moves in the opposite direction.


File: emacs,  Node: Tabs in Picture,  Next: Rectangles in Picture,  Prev: Insert in Picture,  Up: Picture Mode

34.3 Picture Mode Tabs
======================

Two kinds of tab-like action are provided in Picture mode.  Use
`M-<TAB>' (`picture-tab-search') for context-based tabbing.  With no
argument, it moves to a point underneath the next "interesting"
character that follows whitespace in the previous nonblank line.
"Next" here means "appearing at a horizontal position greater than the
one point starts out at."  With an argument, as in `C-u M-<TAB>', this
command moves to the next such interesting character in the current
line.  `M-<TAB>' does not change the text; it only moves point.
"Interesting" characters are defined by the variable
`picture-tab-chars', which should define a set of characters.  The
syntax for this variable is like the syntax used inside of `[...]' in a
regular expression--but without the `[' and the `]'.  Its default value
is `"!-~"'.

   <TAB> itself runs `picture-tab', which operates based on the current
tab stop settings; it is the Picture mode equivalent of
`tab-to-tab-stop'.  Normally it just moves point, but with a numeric
argument it clears the text that it moves over.

   The context-based and tab-stop-based forms of tabbing are brought
together by the command `C-c <TAB>' (`picture-set-tab-stops').  This
command sets the tab stops to the positions which `M-<TAB>' would
consider significant in the current line.  The use of this command,
together with <TAB>, can get the effect of context-based tabbing.  But
`M-<TAB>' is more convenient in the cases where it is sufficient.

   It may be convenient to prevent use of actual tab characters in
pictures.  For example, this prevents `C-x <TAB>' from messing up the
picture.  You can do this by setting the variable `indent-tabs-mode' to
`nil'.


File: emacs,  Node: Rectangles in Picture,  Prev: Tabs in Picture,  Up: Picture Mode

34.4 Picture Mode Rectangle Commands
====================================

Picture mode defines commands for working on rectangular pieces of the
text in ways that fit with the quarter-plane model.  The standard
rectangle commands may also be useful.  *Note Rectangles::.

`C-c C-k'
     Clear out the region-rectangle with spaces
     (`picture-clear-rectangle').  With argument, delete the text.

`C-c C-w R'
     Similar, but save rectangle contents in register R first
     (`picture-clear-rectangle-to-register').

`C-c C-y'
     Copy last killed rectangle into the buffer by overwriting, with
     upper left corner at point (`picture-yank-rectangle').  With
     argument, insert instead.

`C-c C-x R'
     Similar, but use the rectangle in register R
     (`picture-yank-rectangle-from-register').

   The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
standard rectangle commands in that they normally clear the rectangle
instead of deleting it; this is analogous with the way `C-d' is changed
in Picture mode.

   However, deletion of rectangles can be useful in Picture mode, so
these commands delete the rectangle if given a numeric argument.  `C-c
C-k' either with or without a numeric argument saves the rectangle for
`C-c C-y'.

   The Picture mode commands for yanking rectangles differ from the
standard ones in that they overwrite instead of inserting.  This is the
same way that Picture mode insertion of other text differs from other
modes.  `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
the rectangle that was most recently killed, while `C-c C-x'
(`picture-yank-rectangle-from-register') does likewise for the
rectangle found in a specified register.


File: emacs,  Node: Sending Mail,  Next: Rmail,  Prev: Picture Mode,  Up: Top

35 Sending Mail
***************

To send an "e-mail" message in Emacs, type `C-x m'.  This selects and
initializes a buffer named `*mail*', where you can edit the text and
headers of the message.  Finally, type `C-c C-s' or `C-c C-c' to send
the message.

`C-x m'
     Begin composing mail (`compose-mail').

`C-x 4 m'
     Likewise, in another window (`compose-mail-other-window').

`C-x 5 m'
     Likewise, but in a new frame (`compose-mail-other-frame').

`C-c C-s'
     In the mail buffer, send the message (`message-send').

`C-c C-c'
     In the mail buffer, send the message and bury the buffer
     (`message-send-and-exit').

The command `C-x 4 m' (`compose-mail-other-window') does the same as
`C-x m', except it displays the mail buffer in a different window.  The
command `C-x 5 m' (`compose-mail-other-frame') creates a new frame for
the mail buffer.

   Because the mail buffer is an ordinary Emacs buffer, you can switch
to other buffers while in the middle of composing mail, and switch back
later (or never).  If you type `C-x m' again when you have been
composing another message but have not sent it, Emacs asks for
confirmation before erasing the old message.  If you answer `n', Emacs
selects the mail buffer with its old contents, so you can finish the
old message and send it.  `C-u C-x m' is another way to do this.
Sending the message marks the mail buffer "unmodified," which avoids
the need for confirmation when `C-x m' is next used.

   If you want to send another message before finishing the current
message, use the command `M-x rename-uniquely' to rename the current
mail buffer (*note Misc Buffer::).  Then you can use `C-x m' to make a
new mail buffer, and work with each mail buffer independently.

   Before using Emacs to send mail, you may need to customize the
variable `send-mail-function' if your system is not set up to deliver
mail directly via SMTP (*note Mail Sending::).  In addition, you may
need to customize `user-mail-address' if the system cannot receive mail
via SMTP (*note Mail Headers::).

* Menu:

* Format: Mail Format.        Format of a mail message.
* Headers: Mail Headers.      Details of some standard mail header fields.
* Aliases: Mail Aliases.      Abbreviating and grouping mail addresses.
* Commands: Mail Commands.    Special commands for editing mail being composed.
* Signature: Mail Signature.  Adding a signature to every message.
* Amuse: Mail Amusements.     Distracting the NSA; adding fortune messages.
* Methods: Mail Methods.      Using alternative mail-composition methods.


File: emacs,  Node: Mail Format,  Next: Mail Headers,  Up: Sending Mail

35.1 The Format of the Mail Buffer
==================================

An email message must contain certain pieces of information, called
"headers", which specify the message's sender, recipient(s), and so on.

   At the top of the mail buffer is a set of "header fields", where you
can enter this information.  You can insert and edit header fields
using ordinary editing commands.  *Note Header Editing::, for commands
specific to editing header fields.

   Some header fields are automatically pre-initialized in the buffer,
when appropriate; other headers, such as `Date' and `Message-Id', are
normally omitted from the mail buffer and created automatically when
the message is sent.

   The line in the buffer that says

     --text follows this line--

separates the header fields from the "body" (or "text") of the message.
Everything above this line is treated as part of the headers;
everything below it is treated as the body.  The delimiter line itself
does not appear in the message actually sent.  The text used for the
delimiter line is controlled by the variable `mail-header-separator'.

   Here is an example of what the headers and text in the mail buffer
might look like.

     To: gnu@example.org
     CC: lungfish@example.com, byob@example.net
     Subject: The Emacs Manual
     --text follows this line--
     Please ignore this message.


File: emacs,  Node: Mail Headers,  Next: Mail Aliases,  Prev: Mail Format,  Up: Sending Mail

35.2 Mail Header Fields
=======================

A header field in the mail buffer starts with a field name at the
beginning of a line, terminated by a colon.  Upper and lower case are
equivalent in field names (and in mailing addresses also).  After the
colon and optional whitespace comes the contents of the field.

   You can use any name you like for a header field, but normally
people use only standard field names with accepted meanings.  Here is a
table of commonly-used fields.  Emacs pre-initializes some of these,
depending on various options you can set.  You can delete or alter any
header field before you send the message, if you wish.

`From'
     The address of the sender (you).  This should be a valid mailing
     address, as replies will normally go there.  Emacs initializes this
     field using the variables `user-full-name' and
     `user-mail-address'; see below.

`To'
     The mailing address(es) to which the message is addressed.  To list
     more than one address, use commas (not spaces) to separate them.

`Subject'
     A piece of text saying what the message is about.  Most
     mail-reading programs can display a summary of messages, listing
     the subject of each message but not its text.

`CC'
     Additional mailing address(es) to send the message to.  This is
     like `To', except that these readers should not regard the message
     as directed at them.

`BCC'
     Additional mailing address(es) to send the message to, which should
     not appear in the header of the message actually sent.  "BCC"
     stands for "blind carbon copies".

`FCC'
     The name of one file, to which a copy of the sent message should be
     appended.  Emacs writes the message in mbox format, unless the
     file is in Babyl format (used by Rmail before Emacs 23), in which
     case Emacs writes Babyl.  If an Rmail buffer is visiting the file,
     Emacs updates it accordingly.  To specify more than one file, use
     several `FCC' fields, with one file name in each field.

`Reply-to'
     An address to which replies should be sent, instead of `From'.
     You can use this header if, for some reason, your `From' address
     is unable to receive replies.

`Mail-reply-to'
     This field takes precedence over `Reply-to'.  It is used because
     some mailing lists set the `Reply-to' field for their own purposes
     (a somewhat controversial practice).

`Mail-followup-to'
     This field contains one or more addresses.  It is typically used
     when you reply to a message from a mailing list that you are
     subscribed to.  It usually indicates that you want replies to go
     to the list, and that you do not need an extra copy sent directly
     to you.

`In-reply-to'
     A piece of text describing the message you are replying to.  Some
     mail systems can use this information to correlate related pieces
     of mail.  Normally, you never need to think about this, because it
     is filled in automatically when you reply to a message in Rmail
     (or any other mail program built into Emacs).

`References'
     The Message-Ids of previous related messages (a Message-Id is a
     unique identifier generated when a message is sent).  Like
     `In-reply-to', this is normally set up automatically for you.

The `To', `CC', and `BCC' fields can appear any number of times, and
each such header field can contain multiple addresses, separated by
commas.  This way, you can specify any number of places to send the
message.  These fields can also have continuation lines: one or more
lines starting with whitespace, following the starting line of the
field, are considered part of the field.  Here's an example of a `To'
field with a continuation line:

     To: foo@example.net, this@example.net,
       bob@example.com

   The default contents of the `From' header field are computed from
the variables `user-full-name' and `user-mail-address'.  On some
operating systems, Emacs initializes these two variables using
environment variables (*note General Variables::).  If this information
is unavailable or wrong, you can customize the variables yourself
(*note Easy Customization::).

   The value of the variable `mail-from-style' specifies how to format
the address in the `From' field:

`nil'
     Use just the address, as in `king@grassland.com'.

`parens'
     Use both address and full name, as in:
     `king@grassland.com (Elvis Parsley)'.

`angles'
     Use both address and full name, as in:
     `Elvis Parsley <king@grassland.com>'.

any other value
     Use `angles' for most addresses.  However, if the address must be
     "quoted" to remain syntactically-valid under the `angles' format
     but not under the `parens' format, use `parens' instead.  This is
     the default.

   You can direct Emacs to insert certain default headers into the mail
buffer by setting the variable `mail-default-headers' to a string.
Then `C-x m' inserts this string into the message headers.  For
example, here is how to add a `Reply-to' and `FCC' header to each
message:

     (setq mail-default-headers
           "Reply-to: foo@example.com\nFCC: ~/Mail/sent")

If the default header fields are not appropriate for a particular
message, edit them as necessary before sending the message.


File: emacs,  Node: Mail Aliases,  Next: Mail Commands,  Prev: Mail Headers,  Up: Sending Mail

35.3 Mail Aliases
=================

You can define "mail aliases", which are short mnemonic names that
stand for mail addresses or groups of mail addresses.  By default, mail
aliases are defined in the file `~/.mailrc'.  You can specify a
different file name to use, by setting the variable
`mail-personal-alias-file'.

   To define an alias in `.mailrc', write a line in the following
format:

     alias NICK FULLADDRESSES

This means that NICK should expand into FULLADDRESSES, where
FULLADDRESSES can be either a single address, or multiple addresses
separated with spaces.  For instance, to make `maingnu' stand for
`gnu@gnu.org' plus a local address of your own, put in this line:

     alias maingnu gnu@gnu.org local-gnu

If an address contains a space, quote the whole address with a pair of
double quotes, like this:

     alias jsmith "John Q. Smith <none@example.com>"

Note that you need not include double quotes around individual parts of
the address, such as the person's full name.  Emacs puts them in if
they are needed.  For instance, it inserts the above address as `"John
Q. Smith" <none@example.com>'.

   Emacs also recognizes "include" commands in `.mailrc'.  They look
like this:

     source FILENAME

The `.mailrc' file is not unique to Emacs; many other mail-reading
programs use it for mail aliases, and it can contain various other
commands.  However, Emacs ignores everything except alias definitions
and include commands.

   Mail aliases expand as abbrevs--that is to say, as soon as you type
a word-separator character after an alias (*note Abbrevs::).  This
expansion takes place only within the `To', `From', `CC', `BCC', and
`Reply-to' header fields (plus their `Resent-' variants); it does not
take place in other header fields, such as `Subject'.

   You can also insert an aliased address directly, using the command
`M-x mail-abbrev-insert-alias'.  This reads an alias name, with
completion, and inserts its definition at point.


File: emacs,  Node: Mail Commands,  Next: Mail Signature,  Prev: Mail Aliases,  Up: Sending Mail

35.4 Mail Commands
==================

The default major mode for the `*mail*' buffer is called Message mode.
It behaves like Text mode in many ways, but provides several additional
commands on the `C-c' prefix, which make editing a message more
convenient.

   In this section, we will describe some of the most commonly-used
commands available in Message mode.  Message mode also has its own
manual, where its features are described in greater detail.  *Note
Message: (message)Top.

* Menu:

* Mail Sending::        Commands to send the message.
* Header Editing::      Commands to move to header fields and edit them.
* Citing Mail::         Quoting a message you are replying to.
* Mail Misc::           Attachments, spell checking, etc.


File: emacs,  Node: Mail Sending,  Next: Header Editing,  Up: Mail Commands

35.4.1 Mail Sending
-------------------

There are two commands to send a message you have been editing:

`C-c C-c'
     Send the message, and deselect the mail buffer
     (`message-send-and-exit').

`C-c C-s'
     Send the message, and leave the mail buffer selected
     (`message-send').

   If you want to send a message and be done with it, type `C-c C-c'
(`mail-send-and-exit').  This sends the message and then either deletes
the window or switches to another buffer.  It also "buries" the mail
buffer, putting it at the lowest priority for reselection.  This is the
usual command for sending a message.

   The command `C-c C-s' (`message-send') sends the message and marks
the mail buffer unmodified, but leaves the buffer selected.  Use this
command if you want to modify the message (perhaps with new recipients)
and send it again.

   Sending a message runs the hook `message-send-hook'.

   In a file-visiting buffer, sending the message does not clear the
modified flag, because only saving the file should do that.  Also, you
don't get a warning if you try to send the same message twice.

   When you send a message containing non-ASCII characters, they need
to be encoded with a coding system (*note Coding Systems::).  Usually
the coding system is specified automatically by your chosen language
environment (*note Language Environments::).  You can explicitly
specify the coding system for outgoing mail by setting the variable
`sendmail-coding-system' (*note Recognize Coding::).  If the coding
system thus determined does not handle the characters in a particular
message, Emacs asks you to select the coding system to use, showing a
list of possible coding systems.

   The variable `send-mail-function' controls how the default mail user
agent sends mail.  Its value should be a function, which can be one of
the following:

`sendmail-send-it'
     Send mail using the system's default `sendmail' (or
     `sendmail'-compatible) program.  This is the default on Unix and
     GNU, and works provided the system is a valid "mail host" (that
     is, provided it can deliver mail via SMTP).

`mailclient-send-it'
     Pass the mail buffer on to the system's designated mail client (see
     `mailclient.el').  This is the default on Mac OS X and MS-Windows.

`smtpmail-send-it'
     Send mail through an external mail host (e.g., your Internet
     service provider's SMTP server).  You will need to tell Emacs how
     to contact the SMTP server, by customizing the variables
     `smtpmail-smtp-server' and `smtpmail-auth-credentials'.  *Note
     Emacs SMTP Library: (smtpmail)Top.

`feedmail-send-it'
     This is similar to `sendmail-send-it', but allows you to queue
     messages for later sending.  See the commentary section in the file
     `feedmail.el' for more information.


File: emacs,  Node: Header Editing,  Next: Citing Mail,  Prev: Mail Sending,  Up: Mail Commands

35.4.2 Mail Header Editing
--------------------------

Message mode provides the following special commands to move to
particular header fields and to complete addresses in headers.

`C-c C-f C-t'
     Move to the `To' header (`message-goto-to').

`C-c C-f C-s'
     Move to the `Subject' header (`message-goto-subject').

`C-c C-f C-c'
     Move to the `CC' header (`message-goto-cc').

`C-c C-f C-b'
     Move to the `BCC' header (`message-goto-bcc').

`C-c C-f C-r'
     Move to the `Reply-To' header (`message-goto-reply-to').

`C-c C-f C-f'
     Move to the `Mail-Followup-To' header field
     (`message-goto-followup-to').

`C-c C-f C-w'
     Add a new `FCC' header field, with file-name completion
     (`message-goto-fcc').

`C-c C-b'
     Move to the start of the message body (`message-goto-body').

`<TAB>'
     Complete a mailing address (`message-tab').

   The commands to move point to particular header fields are all based
on the prefix `C-c C-f' (`C-f' is for "field").  If the field in
question does not exist, the command creates one (the exception is
`mail-fcc', which creates a new field each time).

   The command `C-c C-b' (`message-goto-body') moves point to just
after the header separator line--that is, to the beginning of the body.

   While editing a header field that contains addresses, such as `To:',
`CC:' and `BCC:', you can complete an address by typing <TAB>
(`message-tab').  This attempts to insert the full name corresponding
to the address based on a couple of methods, including EUDC, a library
that recognizes a number of directory server protocols (*note EUDC:
(eudc)Top.).  Failing that, it attempts to expand the address as a mail
alias (*note Mail Aliases::).  If point is on a header field that does
not take addresses, or if it is in the message body, then <TAB> just
inserts a tab character.


File: emacs,  Node: Citing Mail,  Next: Mail Misc,  Prev: Header Editing,  Up: Mail Commands

35.4.3 Citing Mail
------------------

`C-c C-y'
     Yank the selected message from Rmail (`message-yank-original').

`C-c C-q'
     Fill each paragraph cited from another message
     (`message-fill-yanked-message').

   You can use the command `C-c C-y' (`message-yank-original') to
"cite" a message that you are replying to.  This inserts the text of
that message into the mail buffer.  This command is active only when
the mail buffer is invoked from a mail program running in Emacs, such
as Rmail.

   By default, Emacs inserts the string `>' in front of each line of
the cited text; this prefix string is specified by the variable
`message-yank-prefix'.  If you call `message-yank-original' with a
prefix argument, the citation prefix is not inserted.

   After using `C-c C-y', you can type `C-c C-q'
(`message-fill-yanked-message') to fill the paragraphs of the cited
message.  One use of `C-c C-q' fills all such paragraphs, each one
individually.  To fill a single paragraph of the quoted message, use
`M-q'.  If filling does not automatically handle the type of citation
prefix you use, try setting the fill prefix explicitly.  *Note
Filling::.

   You can customize mail citation through the hook
`mail-citation-hook'.  For example, you can use the Supercite package,
which provides more flexible citation (*note Introduction:
(sc)Introduction.).


File: emacs,  Node: Mail Misc,  Prev: Citing Mail,  Up: Mail Commands

35.4.4 Mail Miscellany
----------------------

You can "attach" a file to an outgoing message by typing `C-c C-a'
(`mml-attach-file') in the mail buffer.  Attaching is done using the
MIME (Multipurpose Internet Mail Extensions) standard.

   The `mml-attach-file' command prompts for the name of the file, and
for the attachment's "content type", "description", and "disposition".
The content type is normally detected automatically; just type <RET> to
accept the default.  The description is a single line of text that the
recipient will see next to the attachment; you may also choose to leave
this empty.  The disposition is either `inline' (the default), which
means the recipient will see a link to the attachment within the
message body, or `attachment', which means the link will be separate
from the body.

   The actual contents of the attached file are not inserted into the
mail buffer.  Instead, some placeholder text is inserted into the mail
buffer, like this:

     <#part type="text/plain" filename="~/foo.txt" disposition=inline>
     <#/part>

When you type `C-c C-c' or `C-c C-s' to send the message, the attached
file will be delivered with it.

   While composing a message, you can do spelling correction on the
message text by typing `M-x ispell-message'.  If you have yanked an
incoming message into the outgoing draft, this command skips what was
yanked, but it checks the text that you yourself inserted (it looks for
indentation or `mail-yank-prefix' to distinguish the cited lines from
your input).  *Note Spelling::.

   Turning on Message mode (which `C-x m' does automatically) runs the
normal hooks `text-mode-hook' and `message-mode-hook'.  Initializing a
new outgoing message runs the normal hook `message-setup-hook'; you can
use this hook if you want to make changes to the appearance of the mail
buffer.  *Note Hooks::.

   The main difference between these hooks is just when they are
invoked.  Whenever you type `C-x m', `message-mode-hook' runs as soon
as the mail buffer is created.  Then the `message-setup' function
inserts the default contents of the buffer.  After these default
contents are inserted, `message-setup-hook' runs.

   If you use `C-x m' to continue an existing composition,
`message-mode-hook' runs immediately after switching to the mail
buffer.  If the buffer is unmodified, or if you decide to erase it and
start again, `message-setup-hook' runs after the default contents are
inserted.


File: emacs,  Node: Mail Signature,  Next: Mail Amusements,  Prev: Mail Commands,  Up: Sending Mail

35.5 Mail Signature
===================

You can add a standard piece of text--your "mail signature"--to the end
of every message.  This signature may contain information such as your
telephone number or your physical location.  The variable
`mail-signature' determines how Emacs handles the mail signature.

   The default value of `mail-signature' is `t'; this means to look for
your mail signature in the file `~/.signature'.  If this file exists,
its contents are automatically inserted into the end of the mail
buffer.  You can change the signature file via the variable
`mail-signature-file'.

   If you change `mail-signature' to a string, that specifies the text
of the signature directly.

   If you change `mail-signature' to `nil', Emacs will not insert your
mail signature automatically.  You can insert your mail signature by
typing `C-c C-w' (`message-insert-signature') in the mail buffer.
Emacs will look for your signature in the signature file.

   By convention, a mail signature should be marked by a line whose
contents are `-- '.  If your signature lacks this prefix, it is added
for you.  The remainder of your signature should be no more than four
lines.


File: emacs,  Node: Mail Amusements,  Next: Mail Methods,  Prev: Mail Signature,  Up: Sending Mail

35.6 Mail Amusements
====================

`M-x spook' adds a line of randomly chosen keywords to an outgoing mail
message.  The keywords are chosen from a list of words that suggest you
are discussing something subversive.

   The idea behind this feature is the suspicion that the NSA(1) and
other intelligence agencies snoop on all electronic mail messages that
contain keywords suggesting they might find them interesting.  (The
agencies say that they don't, but that's what they _would_ say.)  The
idea is that if lots of people add suspicious words to their messages,
the agencies will get so busy with spurious input that they will have
to give up reading it all.  Whether or not this is true, it at least
amuses some people.

   You can use the `fortune' program to put a "fortune cookie" message
into outgoing mail.  To do this, add `fortune-to-signature' to
`mail-setup-hook':

     (add-hook 'mail-setup-hook 'fortune-to-signature)

You will probably need to set the variable `fortune-file' before using
this.

   ---------- Footnotes ----------

   (1) The US National Security Agency.


File: emacs,  Node: Mail Methods,  Prev: Mail Amusements,  Up: Sending Mail

35.7 Mail-Composition Methods
=============================

In this chapter we have described the usual Emacs mode for editing and
sending mail--Message mode.  This is only one of several available
modes.  Prior to Emacs 23.2, the default mode was Mail mode, which is
similar to Message mode in many respects but lacks features such as
MIME support.  Another available mode is MH-E (*note MH-E: (mh-e)Top.).

   You can choose any of these "mail user agents" as your preferred
method for editing and sending mail.  The commands `C-x m', `C-x 4 m'
and `C-x 5 m' use whichever agent you have specified; so do various
other parts of Emacs that send mail, such as the bug reporter (*note
Bugs::).  To specify a mail user agent, customize the variable
`mail-user-agent'.  Currently, legitimate values include
`message-user-agent' (Message mode) `sendmail-user-agent' (Mail mode),
`gnus-user-agent', and `mh-e-user-agent'.

   If you select a different mail-composition method, the information
in this chapter about the mail buffer and Message mode does not apply;
the other methods use a different format of text in a different buffer,
and their commands are different as well.

   Similarly, to specify your preferred method for reading mail,
customize the variable `read-mail-command'.  The default is `rmail'
(*note Rmail::).


File: emacs,  Node: Rmail,  Next: Dired,  Prev: Sending Mail,  Up: Top

36 Reading Mail with Rmail
**************************

Rmail is an Emacs subsystem for reading and disposing of mail that you
receive.  Rmail stores mail messages in files called Rmail files.
Reading the messages in an Rmail file is done in a special major mode,
Rmail mode, which redefines most letters to run commands for managing
mail.

* Menu:

* Basic: Rmail Basics.       Basic concepts of Rmail, and simple use.
* Scroll: Rmail Scrolling.   Scrolling through a message.
* Motion: Rmail Motion.      Moving to another message.
* Deletion: Rmail Deletion.  Deleting and expunging messages.
* Inbox: Rmail Inbox.        How mail gets into the Rmail file.
* Files: Rmail Files.        Using multiple Rmail files.
* Output: Rmail Output.      Copying messages out to files.
* Labels: Rmail Labels.      Classifying messages by labeling them.
* Attrs: Rmail Attributes.   Certain standard labels, called attributes.
* Reply: Rmail Reply.        Sending replies to messages you are viewing.
* Summary: Rmail Summary.    Summaries show brief info on many messages.
* Sort: Rmail Sorting.       Sorting messages in Rmail.
* Display: Rmail Display.    How Rmail displays a message; customization.
* Coding: Rmail Coding.      How Rmail handles decoding character sets.
* Editing: Rmail Editing.    Editing message text and headers in Rmail.
* Digest: Rmail Digest.      Extracting the messages from a digest message.
* Rot13: Rmail Rot13.        Reading messages encoded in the rot13 code.
* Movemail::                 More details of fetching new mail.
* Remote Mailboxes::         Retrieving mail from remote mailboxes.
* Other Mailbox Formats::    Retrieving mail from local mailboxes in
                             various formats.


File: emacs,  Node: Rmail Basics,  Next: Rmail Scrolling,  Up: Rmail

36.1 Basic Concepts of Rmail
============================

Using Rmail in the simplest fashion, you have one Rmail file `~/RMAIL'
in which all of your mail is saved.  It is called your "primary Rmail
file".  The command `M-x rmail' reads your primary Rmail file, merges
new mail in from your inboxes, displays the first message you haven't
read yet, and lets you begin reading.  The variable `rmail-file-name'
specifies the name of the primary Rmail file.

   Rmail displays only one message in the Rmail file at a time.  The
message that is shown is called the "current message".  Rmail mode's
special commands can do such things as delete the current message, copy
it into another file, send a reply, or move to another message.  You
can also create multiple Rmail files and use Rmail to move messages
between them.

   Within the Rmail file, messages are normally arranged sequentially in
order of receipt; you can specify other ways to sort them (*note Rmail
Sorting::).  Messages are identified by consecutive integers which are
their "message numbers".  The number of the current message is
displayed in Rmail's mode line, followed by the total number of messages
in the file.  You can move to a message by specifying its message number
with the `j' key (*note Rmail Motion::).

   Following the usual conventions of Emacs, changes in an Rmail file
become permanent only when you save the file.  You can save it with `s'
(`rmail-expunge-and-save'), which also expunges deleted messages from
the file first (*note Rmail Deletion::).  To save the file without
expunging, use `C-x C-s'.  Rmail also saves the Rmail file after
merging new mail from an inbox file (*note Rmail Inbox::).

   You can exit Rmail with `q' (`rmail-quit'); this expunges and saves
the Rmail file, then buries the Rmail buffer as well as its summary
buffer, if present (*note Rmail Summary::).  But there is no need to
"exit" formally.  If you switch from Rmail to editing in other buffers,
and never switch back, you have exited.  Just make sure to save the
Rmail file eventually (like any other file you have changed).  `C-x s'
is a suitable way to do this (*note Save Commands::).  The Rmail
command `b', `rmail-bury', buries the Rmail buffer and its summary
buffer without expunging and saving the Rmail file.


File: emacs,  Node: Rmail Scrolling,  Next: Rmail Motion,  Prev: Rmail Basics,  Up: Rmail

36.2 Scrolling Within a Message
===============================

When Rmail displays a message that does not fit on the screen, you must
scroll through it to read the rest.  You could do this with `C-v',
`M-v' and `M-<', but in Rmail scrolling is so frequent that it deserves
to be easier.

`<SPC>'
     Scroll forward (`scroll-up').

`<DEL>'
     Scroll backward (`scroll-down').

`.'
     Scroll to start of message (`rmail-beginning-of-message').

`/'
     Scroll to end of message (`rmail-end-of-message').

   Since the most common thing to do while reading a message is to
scroll through it by screenfuls, Rmail makes <SPC> and <DEL> synonyms of
`C-v' (`scroll-up') and `M-v' (`scroll-down')

   The command `.' (`rmail-beginning-of-message') scrolls back to the
beginning of the selected message.  This is not quite the same as `M-<':
for one thing, it does not set the mark; for another, it resets the
buffer boundaries of the current message if you have changed them.
Similarly, the command `/' (`rmail-end-of-message') scrolls forward to
the end of the selected message.


File: emacs,  Node: Rmail Motion,  Next: Rmail Deletion,  Prev: Rmail Scrolling,  Up: Rmail

36.3 Moving Among Messages
==========================

The most basic thing to do with a message is to read it.  The way to do
this in Rmail is to make the message current.  The usual practice is to
move sequentially through the file, since this is the order of receipt
of messages.  When you enter Rmail, you are positioned at the first
message that you have not yet made current (that is, the first one that
has the `unseen' attribute; *note Rmail Attributes::).  Move forward to
see the other new messages; move backward to re-examine old messages.

`n'
     Move to the next nondeleted message, skipping any intervening
     deleted messages (`rmail-next-undeleted-message').

`p'
     Move to the previous nondeleted message
     (`rmail-previous-undeleted-message').

`M-n'
     Move to the next message, including deleted messages
     (`rmail-next-message').

`M-p'
     Move to the previous message, including deleted messages
     (`rmail-previous-message').

`C-c C-n'
     Move to the next message with the same subject as the current one
     (`rmail-next-same-subject').

`C-c C-p'
     Move to the previous message with the same subject as the current
     one (`rmail-previous-same-subject').

`j'
     Move to the first message.  With argument N, move to message
     number N (`rmail-show-message').

`>'
     Move to the last message (`rmail-last-message').

`<'
     Move to the first message (`rmail-first-message').

`M-s REGEXP <RET>'
     Move to the next message containing a match for REGEXP
     (`rmail-search').

`- M-s REGEXP <RET>'
     Move to the previous message containing a match for REGEXP.

   `n' and `p' are the usual way of moving among messages in Rmail.
They move through the messages sequentially, but skip over deleted
messages, which is usually what you want to do.  Their command
definitions are named `rmail-next-undeleted-message' and
`rmail-previous-undeleted-message'.  If you do not want to skip deleted
messages--for example, if you want to move to a message to undelete
it--use the variants `M-n' and `M-p' (`rmail-next-message' and
`rmail-previous-message').  A numeric argument to any of these commands
serves as a repeat count.

   In Rmail, you can specify a numeric argument by typing just the
digits.  You don't need to type `C-u' first.

   The `M-s' (`rmail-search') command is Rmail's version of search.
The usual incremental search command `C-s' works in Rmail, but it
searches only within the current message.  The purpose of `M-s' is to
search for another message.  It reads a regular expression (*note
Regexps::) nonincrementally, then searches starting at the beginning of
the following message for a match.  It then selects that message.  If
REGEXP is empty, `M-s' reuses the regexp used the previous time.

   To search backward in the file for another message, give `M-s' a
negative argument.  In Rmail you can do this with `- M-s'.  This begins
searching from the end of the previous message.

   It is also possible to search for a message based on labels.  *Note
Rmail Labels::.

   The `C-c C-n' (`rmail-next-same-subject') command moves to the next
message with the same subject as the current one.  A prefix argument
serves as a repeat count.  With a negative argument, this command moves
backward, acting like `C-c C-p' (`rmail-previous-same-subject').  When
comparing subjects, these commands ignore the prefixes typically added
to the subjects of replies.

   To move to a message specified by absolute message number, use `j'
(`rmail-show-message') with the message number as argument.  With no
argument, `j' selects the first message.  `<' (`rmail-first-message')
also selects the first message.  `>' (`rmail-last-message') selects the
last message.


File: emacs,  Node: Rmail Deletion,  Next: Rmail Inbox,  Prev: Rmail Motion,  Up: Rmail

36.4 Deleting Messages
======================

When you no longer need to keep a message, you can "delete" it.  This
flags it as ignorable, and some Rmail commands pretend it is no longer
present; but it still has its place in the Rmail file, and still has its
message number.

   "Expunging" the Rmail file actually removes the deleted messages.
The remaining messages are renumbered consecutively.

`d'
     Delete the current message, and move to the next nondeleted message
     (`rmail-delete-forward').

`C-d'
     Delete the current message, and move to the previous nondeleted
     message (`rmail-delete-backward').

`u'
     Undelete the current message, or move back to the previous deleted
     message and undelete it (`rmail-undelete-previous-message').

`x'
     Expunge the Rmail file (`rmail-expunge').

   There are two Rmail commands for deleting messages.  Both delete the
current message and select another message.  `d'
(`rmail-delete-forward') moves to the following message, skipping
messages already deleted, while `C-d' (`rmail-delete-backward') moves
to the previous nondeleted message.  If there is no nondeleted message
to move to in the specified direction, the message that was just
deleted remains current.  `d' with a prefix argument is equivalent to
`C-d'.  Note that the Rmail summary versions of these commands behave
slightly differently (*note Rmail Summary Edit::).

   Whenever Rmail deletes a message, it runs the hook
`rmail-delete-message-hook'.  When the hook functions are invoked, the
message has been marked deleted, but it is still the current message in
the Rmail buffer.

   To make all the deleted messages finally vanish from the Rmail file,
type `x' (`rmail-expunge').  Until you do this, you can still
"undelete" the deleted messages.  The undeletion command, `u'
(`rmail-undelete-previous-message'), is designed to cancel the effect
of a `d' command in most cases.  It undeletes the current message if
the current message is deleted.  Otherwise it moves backward to
previous messages until a deleted message is found, and undeletes that
message.

   You can usually undo a `d' with a `u' because the `u' moves back to
and undeletes the message that the `d' deleted.  But this does not work
when the `d' skips a few already-deleted messages that follow the
message being deleted; then the `u' command undeletes the last of the
messages that were skipped.  There is no clean way to avoid this
problem.  However, by repeating the `u' command, you can eventually get
back to the message that you intend to undelete.  You can also select a
particular deleted message with the `M-p' command, then type `u' to
undelete it.

   A deleted message has the `deleted' attribute, and as a result
`deleted' appears in the mode line when the current message is deleted.
In fact, deleting or undeleting a message is nothing more than adding
or removing this attribute.  *Note Rmail Attributes::.


File: emacs,  Node: Rmail Inbox,  Next: Rmail Files,  Prev: Rmail Deletion,  Up: Rmail

36.5 Rmail Files and Inboxes
============================

When you receive mail locally, the operating system places incoming
mail for you in a file that we call your "inbox".  When you start up
Rmail, it runs a C program called `movemail' to copy the new messages
from your local inbox into your primary Rmail file, which also contains
other messages saved from previous Rmail sessions.  It is in this file
that you actually read the mail with Rmail.  This operation is called
"getting new mail".  You can get new mail at any time in Rmail by
typing `g'.

   The variable `rmail-primary-inbox-list' contains a list of the files
which are inboxes for your primary Rmail file.  If you don't set this
variable explicitly, Rmail uses the `MAIL' environment variable, or, as
a last resort, a default inbox based on `rmail-spool-directory'.  The
default inbox file depends on your operating system; often it is
`/var/mail/USERNAME', `/var/spool/mail/USERNAME', or
`/usr/spool/mail/USERNAME'.

   You can specify the inbox file(s) for any Rmail file for the current
session with the command `set-rmail-inbox-list'; see *note Rmail
Files::.

   There are two reasons for having separate Rmail files and inboxes.

  1. The inbox file format varies between operating systems and
     according to the other mail software in use.  Only one part of
     Rmail needs to know about the alternatives, and it need only
     understand how to convert all of them to Rmail's own format.

  2. It is very cumbersome to access an inbox file without danger of
     losing mail, because it is necessary to interlock with mail
     delivery.  Moreover, different operating systems use different
     interlocking techniques.  The strategy of moving mail out of the
     inbox once and for all into a separate Rmail file avoids the need
     for interlocking in all the rest of Rmail, since only Rmail
     operates on the Rmail file.

   Rmail was originally written to use the Babyl format as its internal
format.  Since then, we have recognized that the usual inbox format
(`mbox') on Unix and GNU systems is adequate for the job, and so since
Emacs 23 Rmail uses that as its internal format.  The Rmail file is
still separate from the inbox file, even though their format is the
same.

   When getting new mail, Rmail first copies the new mail from the
inbox file to the Rmail file; then it saves the Rmail file; then it
clears out the inbox file.  This way, a system crash may cause
duplication of mail between the inbox and the Rmail file, but cannot
lose mail.  If `rmail-preserve-inbox' is non-`nil', then Rmail does not
clear out the inbox file when it gets new mail.  You may wish to set
this, for example, on a portable computer you use to check your mail
via POP while traveling, so that your mail will remain on the server
and you can save it later on your workstation.

   In some cases, Rmail copies the new mail from the inbox file
indirectly.  First it runs the `movemail' program to move the mail from
the inbox to an intermediate file called `.newmail-INBOXNAME', in the
same directory as the Rmail file.  Then Rmail merges the new mail from
that file, saves the Rmail file, and only then deletes the intermediate
file.  If there is a crash at the wrong time, this file continues to
exist, and Rmail will use it again the next time it gets new mail from
that inbox.

   If Rmail is unable to convert the data in `.newmail-INBOXNAME' into
mbox format, it renames the file to `RMAILOSE.N' (N is an integer
chosen to make the name unique) so that Rmail will not have trouble
with the data again.  You should look at the file, find whatever
message confuses Rmail (probably one that includes the
control-underscore character, octal code 037), and delete it.  Then you
can use `1 g' to get new mail from the corrected file.


File: emacs,  Node: Rmail Files,  Next: Rmail Output,  Prev: Rmail Inbox,  Up: Rmail

36.6 Multiple Rmail Files
=========================

Rmail operates by default on your "primary Rmail file", which is named
`~/RMAIL' and receives your incoming mail from your system inbox file.
But you can also have other Rmail files and edit them with Rmail.  These
files can receive mail through their own inboxes, or you can move
messages into them with explicit Rmail commands (*note Rmail Output::).

`i FILE <RET>'
     Read FILE into Emacs and run Rmail on it (`rmail-input').

`M-x set-rmail-inbox-list <RET> FILES <RET>'
     Specify inbox file names for current Rmail file to get mail from.

`g'
     Merge new mail from current Rmail file's inboxes
     (`rmail-get-new-mail').

`C-u g FILE <RET>'
     Merge new mail from inbox file FILE.

   To run Rmail on a file other than your primary Rmail file, you can
use the `i' (`rmail-input') command in Rmail.  This visits the file in
Rmail mode.  You can use `M-x rmail-input' even when not in Rmail, but
it is easier to type `C-u M-x rmail', which does the same thing.

   The file you read with `i' should normally be a valid mbox file.  If
it is not, Rmail tries to convert its text to mbox format, and visits
the converted text in the buffer.  If you save the buffer, that
converts the file.

   If you specify a file name that doesn't exist, `i' initializes a new
buffer for creating a new Rmail file.

   You can also select an Rmail file from a menu.  In the Classify menu,
choose the Input Rmail File item; then choose the Rmail file you want.
The variables `rmail-secondary-file-directory' and
`rmail-secondary-file-regexp' specify which files to offer in the menu:
the first variable says which directory to find them in; the second
says which files in that directory to offer (all those that match the
regular expression).  If no files match, you cannot select this menu
item.  These variables also apply to choosing a file for output (*note
Rmail Output::).

   The inbox files to use are specified by the variable
`rmail-inbox-list', which is buffer-local in Rmail mode.  As a special
exception, if you have specified no inbox files for your primary Rmail
file, it uses the `MAIL' environment variable, or your standard system
inbox.

   The `g' command (`rmail-get-new-mail') merges mail into the current
Rmail file from its inboxes.  If the Rmail file has no inboxes, `g'
does nothing.  The command `M-x rmail' also merges new mail into your
primary Rmail file.

   To merge mail from a file that is not the usual inbox, give the `g'
key a numeric argument, as in `C-u g'.  Then it reads a file name and
merges mail from that file.  The inbox file is not deleted or changed
in any way when `g' with an argument is used.  This is, therefore, a
general way of merging one file of messages into another.


File: emacs,  Node: Rmail Output,  Next: Rmail Labels,  Prev: Rmail Files,  Up: Rmail

36.7 Copying Messages Out to Files
==================================

These commands copy messages from an Rmail file into another file.

`o FILE <RET>'
     Append a full copy of the current message to the file FILE
     (`rmail-output').

`C-o FILE <RET>'
     Append a copy of the current message, as displayed, to the file
     FILE (`rmail-output-as-seen').

`w FILE <RET>'
     Output just the message body to the file FILE, taking the default
     file name from the message `Subject' header.

   The commands `o' and `C-o' copy the current message into a specified
file, adding it at the end.  The two commands differ mainly in how much
to copy: `o' copies the full message headers, even if they are not all
visible, while `C-o' copies exactly the headers currently displayed and
no more.  *Note Rmail Display::.  In addition, `o' converts the message
to Babyl format (used by Rmail in Emacs version 22 and before) if the
file is in Babyl format; `C-o' cannot output to Babyl files at all.

   If the output file is currently visited in an Emacs buffer, the
output commands append the message to that buffer.  It is up to you to
save the buffer eventually in its file.

   Sometimes you may receive a message whose body holds the contents of
a file.  You can save the body to a file (excluding the message header)
with the `w' command (`rmail-output-body-to-file').  Often these
messages contain the intended file name in the `Subject' field, so the
`w' command uses the `Subject' field as the default for the output file
name.  However, the file name is read using the minibuffer, so you can
specify a different name if you wish.

   You can also output a message to an Rmail file chosen with a menu.
In the Classify menu, choose the Output Rmail File menu item; then
choose the Rmail file you want.  This outputs the current message to
that file, like the `o' command.  The variables
`rmail-secondary-file-directory' and `rmail-secondary-file-regexp'
specify which files to offer in the menu: the first variable says which
directory to find them in; the second says which files in that
directory to offer (all those that match the regular expression).  If
no files match, you cannot select this menu item.

   Copying a message with `o' or `C-o' gives the original copy of the
message the `filed' attribute, so that `filed' appears in the mode line
when such a message is current.

   If you like to keep just a single copy of every mail message, set
the variable `rmail-delete-after-output' to `t'; then the `o', `C-o'
and `w' commands delete the original message after copying it.  (You
can undelete it afterward if you wish.)

   The variable `rmail-output-file-alist' lets you specify intelligent
defaults for the output file, based on the contents of the current
message.  The value should be a list whose elements have this form:

     (REGEXP . NAME-EXP)

If there's a match for REGEXP in the current message, then the default
file name for output is NAME-EXP.  If multiple elements match the
message, the first matching element decides the default file name.  The
subexpression NAME-EXP may be a string constant giving the file name to
use, or more generally it may be any Lisp expression that returns a
file name as a string.  `rmail-output-file-alist' applies to both `o'
and `C-o'.


File: emacs,  Node: Rmail Labels,  Next: Rmail Attributes,  Prev: Rmail Output,  Up: Rmail

36.8 Labels
===========

Each message can have various "labels" assigned to it as a means of
classification.  Each label has a name; different names are different
labels.  Any given label is either present or absent on a particular
message.  A few label names have standard meanings and are given to
messages automatically by Rmail when appropriate; these special labels
are called "attributes".  (*Note Rmail Attributes::.)  All other labels
are assigned only by users.

`a LABEL <RET>'
     Assign the label LABEL to the current message (`rmail-add-label').

`k LABEL <RET>'
     Remove the label LABEL from the current message
     (`rmail-kill-label').

`C-M-n LABELS <RET>'
     Move to the next message that has one of the labels LABELS
     (`rmail-next-labeled-message').

`C-M-p LABELS <RET>'
     Move to the previous message that has one of the labels LABELS
     (`rmail-previous-labeled-message').

`l LABELS <RET>'
`C-M-l LABELS <RET>'
     Make a summary of all messages containing any of the labels LABELS
     (`rmail-summary-by-labels').

   The `a' (`rmail-add-label') and `k' (`rmail-kill-label') commands
allow you to assign or remove any label on the current message.  If the
LABEL argument is empty, it means to assign or remove the same label
most recently assigned or removed.

   Once you have given messages labels to classify them as you wish,
there are three ways to use the labels: in moving, in summaries, and in
sorting.

   `C-M-n LABELS <RET>' (`rmail-next-labeled-message') moves to the
next message that has one of the labels LABELS.  The argument LABELS
specifies one or more label names, separated by commas.  `C-M-p'
(`rmail-previous-labeled-message') is similar, but moves backwards to
previous messages.  A numeric argument to either command serves as a
repeat count.

   The command `C-M-l LABELS <RET>' (`rmail-summary-by-labels')
displays a summary containing only the messages that have at least one
of a specified set of labels.  The argument LABELS is one or more label
names, separated by commas.  *Note Rmail Summary::, for information on
summaries.

   If the LABELS argument to `C-M-n', `C-M-p' or `C-M-l' is empty, it
means to use the last set of labels specified for any of these commands.

   *Note Rmail Sorting::, for information on sorting messages with
labels.


File: emacs,  Node: Rmail Attributes,  Next: Rmail Reply,  Prev: Rmail Labels,  Up: Rmail

36.9 Rmail Attributes
=====================

Some labels such as `deleted' and `filed' have built-in meanings, and
Rmail assigns them to messages automatically at appropriate times;
these labels are called "attributes".  Here is a list of Rmail
attributes:

`unseen'
     Means the message has never been current.  Assigned to messages
     when they come from an inbox file, and removed when a message is
     made current.  When you start Rmail, it initially shows the first
     message that has this attribute.

`deleted'
     Means the message is deleted.  Assigned by deletion commands and
     removed by undeletion commands (*note Rmail Deletion::).

`filed'
     Means the message has been copied to some other file.  Assigned by
     the `o' and `C-o' file output commands (*note Rmail Output::).

`answered'
     Means you have mailed an answer to the message.  Assigned by the
     `r' command (`rmail-reply').  *Note Rmail Reply::.

`forwarded'
     Means you have forwarded the message.  Assigned by the `f' command
     (`rmail-forward').  *Note Rmail Reply::.

`edited'
     Means you have edited the text of the message within Rmail.  *Note
     Rmail Editing::.

`resent'
     Means you have resent the message.  Assigned by the command `M-x
     rmail-resend'.  *Note Rmail Reply::.

`retried'
     Means you have retried a failed outgoing message.  Assigned by the
     command `M-x rmail-retry-failure'.  *Note Rmail Reply::.

   All other labels are assigned or removed only by users, and have no
standard meaning.


File: emacs,  Node: Rmail Reply,  Next: Rmail Summary,  Prev: Rmail Attributes,  Up: Rmail

36.10 Sending Replies
=====================

Rmail has several commands to send outgoing mail.  *Note Sending
Mail::, for information on using Message mode, including certain
features meant to work with Rmail.  What this section documents are the
special commands of Rmail for entering the mail buffer.  Note that the
usual keys for sending mail--`C-x m', `C-x 4 m', and `C-x 5 m'--also
work normally in Rmail mode.

`m'
     Send a message (`rmail-mail').

`c'
     Continue editing the already started outgoing message
     (`rmail-continue').

`r'
     Send a reply to the current Rmail message (`rmail-reply').

`f'
     Forward the current message to other users (`rmail-forward').

`C-u f'
     Resend the current message to other users (`rmail-resend').

`M-m'
     Try sending a bounced message a second time
     (`rmail-retry-failure').

   The most common reason to send a message while in Rmail is to reply
to the message you are reading.  To do this, type `r' (`rmail-reply').
This displays the `*mail*' buffer in another window, much like `C-x 4
m', but preinitializes the `Subject', `To', `CC', `In-reply-to' and
`References' header fields based on the message you are replying to.
The `To' field starts out as the address of the person who sent the
message you received, and the `CC' field starts out with all the other
recipients of that message.

   You can exclude certain recipients from being included automatically
in replies, using the variable `rmail-dont-reply-to-names'.  Its value
should be a regular expression; any recipients that match are excluded
from the `CC' field.  They are also excluded from the `To' field,
unless this would leave the field empty.  If this variable is nil, then
the first time you compose a reply it is initialized to a default value
that matches your own address, and any name starting with `info-'.
(Those names are excluded because there is a convention of using them
for large mailing lists to broadcast announcements.)

   To omit the `CC' field completely for a particular reply, enter the
reply command with a numeric argument: `C-u r' or `1 r'.  This means to
reply only to the sender of the original message.

   Once the `*mail*' buffer has been initialized, editing and sending
the mail goes as usual (*note Sending Mail::).  You can edit the
presupplied header fields if they are not what you want.  You can also
use commands such as `C-c C-y', which yanks in the message that you are
replying to (*note Mail Commands::).  You can also switch to the Rmail
buffer, select a different message there, switch back, and yank the new
current message.

   Sometimes a message does not reach its destination.  Mailers usually
send the failed message back to you, enclosed in a "failure message".
The Rmail command `M-m' (`rmail-retry-failure') prepares to send the
same message a second time: it sets up a `*mail*' buffer with the same
text and header fields as before.  If you type `C-c C-c' right away,
you send the message again exactly the same as the first time.
Alternatively, you can edit the text or headers and then send it.  The
variable `rmail-retry-ignored-headers', in the same format as
`rmail-ignored-headers' (*note Rmail Display::), controls which headers
are stripped from the failed message when retrying it.

   Another frequent reason to send mail in Rmail is to "forward" the
current message to other users.  `f' (`rmail-forward') makes this easy
by preinitializing the `*mail*' buffer with the current message as the
text, and a subject designating a forwarded message.  All you have to
do is fill in the recipients and send.  When you forward a message,
recipients get a message which is "from" you, and which has the
original message in its contents.

   Forwarding a message encloses it between two delimiter lines.  It
also modifies every line that starts with a dash, by inserting `- ' at
the start of the line.  When you receive a forwarded message, if it
contains something besides ordinary text--for example, program source
code--you might find it useful to undo that transformation.  You can do
this by selecting the forwarded message and typing `M-x
unforward-rmail-message'.  This command extracts the original forwarded
message, deleting the inserted `- ' strings, and inserts it into the
Rmail file as a separate message immediately following the current one.

   "Resending" is an alternative similar to forwarding; the difference
is that resending sends a message that is "from" the original sender,
just as it reached you--with a few added header fields (`Resent-From'
and `Resent-To') to indicate that it came via you.  To resend a message
in Rmail, use `C-u f'.  (`f' runs `rmail-forward', which invokes
`rmail-resend' if you provide a numeric argument.)

   Use the `m' (`rmail-mail') command to start editing an outgoing
message that is not a reply.  It leaves the header fields empty.  Its
only difference from `C-x 4 m' is that it makes the Rmail buffer
accessible for `C-c C-y', just as `r' does.  Thus, `m' can be used to
reply to or forward a message; it can do anything `r' or `f' can do.

   The `c' (`rmail-continue') command resumes editing the `*mail*'
buffer, to finish editing an outgoing message you were already
composing, or to alter a message you have sent.

   If you set the variable `rmail-mail-new-frame' to a non-`nil' value,
then all the Rmail commands to start sending a message create a new
frame to edit it in.  This frame is deleted when you send the message,
or when you use the `Cancel' item in the `Mail' menu.

   All the Rmail commands to send a message use the mail-composition
method that you have chosen (*note Mail Methods::).


File: emacs,  Node: Rmail Summary,  Next: Rmail Sorting,  Prev: Rmail Reply,  Up: Rmail

36.11 Summaries
===============

A "summary" is a buffer containing one line per message to give you an
overview of the mail in an Rmail file.  Each line shows the message
number and date, the sender, the line count, the labels, and the
subject.  Moving point in the summary buffer selects messages as you
move to their summary lines.  Almost all Rmail commands are valid in
the summary buffer also; when used there, they apply to the message
described by the current line of the summary.

   A summary buffer applies to a single Rmail file only; if you are
editing multiple Rmail files, each one can have its own summary buffer.
The summary buffer name is made by appending `-summary' to the Rmail
buffer's name.  Normally only one summary buffer is displayed at a time.

* Menu:

* Rmail Make Summary::       Making various sorts of summaries.
* Rmail Summary Edit::       Manipulating messages from the summary.


File: emacs,  Node: Rmail Make Summary,  Next: Rmail Summary Edit,  Up: Rmail Summary

36.11.1 Making Summaries
------------------------

Here are the commands to create a summary for the current Rmail buffer.
Once the Rmail buffer has a summary, changes in the Rmail buffer (such
as deleting or expunging messages, and getting new mail) automatically
update the summary.

`h'
`C-M-h'
     Summarize all messages (`rmail-summary').

`l LABELS <RET>'
`C-M-l LABELS <RET>'
     Summarize messages that have one or more of the specified labels
     (`rmail-summary-by-labels').

`C-M-r RCPTS <RET>'
     Summarize messages that match the specified recipients
     (`rmail-summary-by-recipients').

`C-M-t TOPIC <RET>'
     Summarize messages that have a match for the specified regexp
     TOPIC in their subjects (`rmail-summary-by-topic').

`C-M-s REGEXP <RET>'
     Summarize messages whose headers match the specified regular
     expression REGEXP (`rmail-summary-by-regexp').

`C-M-f SENDERS <RET>'
     Summarize messages that match the specified senders.
     (`rmail-summary-by-senders').

   The `h' or `C-M-h' (`rmail-summary') command fills the summary buffer
for the current Rmail buffer with a summary of all the messages in the
buffer.  It then displays and selects the summary buffer in another
window.

   `C-M-l LABELS <RET>' (`rmail-summary-by-labels') makes a partial
summary mentioning only the messages that have one or more of the
labels LABELS.  LABELS should contain label names separated by commas.

   `C-M-r RCPTS <RET>' (`rmail-summary-by-recipients') makes a partial
summary mentioning only the messages that have one or more recipients
matching the regular expression RCPTS.  You can use commas to separate
multiple regular expressions.  These are matched against the `To',
`From', and `CC' headers (with a prefix argument, this header is not
included).

   `C-M-t TOPIC <RET>' (`rmail-summary-by-topic') makes a partial
summary mentioning only the messages whose subjects have a match for
the regular expression TOPIC.  You can use commas to separate multiple
regular expressions.  With a prefix argument, the match is against the
whole message, not just the subject.

   `C-M-s REGEXP <RET>' (`rmail-summary-by-regexp') makes a partial
summary that mentions only the messages whose headers (including the
date and the subject lines) match the regular expression REGEXP.

   `C-M-f SENDERS <RET>' (`rmail-summary-by-senders') makes a partial
summary that mentions only the messages whose `From' fields match the
regular expression SENDERS.  You can use commas to separate multiple
regular expressions.

   Note that there is only one summary buffer for any Rmail buffer;
making any kind of summary discards any previous summary.

   The variable `rmail-summary-window-size' says how many lines to use
for the summary window.  The variable `rmail-summary-line-count-flag'
controls whether the summary line for a message should include the line
count of the message.  Setting this option to nil might speed up the
generation of summaries.


File: emacs,  Node: Rmail Summary Edit,  Prev: Rmail Make Summary,  Up: Rmail Summary

36.11.2 Editing in Summaries
----------------------------

You can use the Rmail summary buffer to do almost anything you can do
in the Rmail buffer itself.  In fact, once you have a summary buffer,
there's no need to switch back to the Rmail buffer.

   You can select and display various messages in the Rmail buffer, from
the summary buffer, just by moving point in the summary buffer to
different lines.  It doesn't matter what Emacs command you use to move
point; whichever line point is on at the end of the command, that
message is selected in the Rmail buffer.

   Almost all Rmail commands work in the summary buffer as well as in
the Rmail buffer.  Thus, `d' in the summary buffer deletes the current
message, `u' undeletes, and `x' expunges.  (However, in the summary
buffer, a numeric argument to `d', `C-d' and `u' serves as a repeat
count.  A negative argument reverses the meaning of `d' and `C-d'.
Also, if there are no more undeleted messages in the relevant
direction, the delete commands go to the first or last message, rather
than staying on the current message.)  `o' and `C-o' output the current
message to a FILE; `r' starts a reply to it; etc.  You can scroll the
current message while remaining in the summary buffer using <SPC> and
<DEL>.

   `M-u' (`rmail-summary-undelete-many') undeletes all deleted messages
in the summary.  A prefix argument means to undelete that many of the
previous deleted messages.

   The Rmail commands to move between messages also work in the summary
buffer, but with a twist: they move through the set of messages included
in the summary.  They also ensure the Rmail buffer appears on the screen
(unlike cursor motion commands, which update the contents of the Rmail
buffer but don't display it in a window unless it already appears).
Here is a list of these commands:

`n'
     Move to next line, skipping lines saying `deleted', and select its
     message (`rmail-summary-next-msg').

`p'
     Move to previous line, skipping lines saying `deleted', and select
     its message (`rmail-summary-previous-msg').

`M-n'
     Move to next line and select its message
     (`rmail-summary-next-all').

`M-p'
     Move to previous line and select its message
     (`rmail-summary-previous-all').

`>'
     Move to the last line, and select its message
     (`rmail-summary-last-message').

`<'
     Move to the first line, and select its message
     (`rmail-summary-first-message').

`j'
`<RET>'
     Select the message on the current line (ensuring that the Rmail
     buffer appears on the screen; `rmail-summary-goto-msg').  With
     argument N, select message number N and move to its line in the
     summary buffer; this signals an error if the message is not listed
     in the summary buffer.

`M-s PATTERN <RET>'
     Search through messages for PATTERN starting with the current
     message; select the message found, and move point in the summary
     buffer to that message's line (`rmail-summary-search').  A prefix
     argument acts as a repeat count; a negative argument means search
     backward (equivalent to `rmail-summary-search-backward'.)

`C-M-n LABELS <RET>'
     Move to the next message with at least one of the specified labels
     (`rmail-summary-next-labeled-message').  LABELS is a
     comma-separated list of labels.  A prefix argument acts as a repeat
     count.

`C-M-p LABELS <RET>'
     Move to the previous message with at least one of the specified
     labels (`rmail-summary-previous-labeled-message').

`C-c C-n <RET>'
     Move to the next message with the same subject as the current
     message (`rmail-summary-next-same-subject').  A prefix argument
     acts as a repeat count.

`C-c C-p <RET>'
     Move to the previous message with the same subject as the current
     message (`rmail-summary-previous-same-subject').

   Deletion, undeletion, and getting new mail, and even selection of a
different message all update the summary buffer when you do them in the
Rmail buffer.  If the variable `rmail-redisplay-summary' is non-`nil',
these actions also bring the summary buffer back onto the screen.

   When you are finished using the summary, type `Q'
(`rmail-summary-wipe') to delete the summary buffer's window.  You can
also exit Rmail while in the summary: `q' (`rmail-summary-quit')
deletes the summary window, then exits from Rmail by saving the Rmail
file and switching to another buffer.  Alternatively, `b'
(`rmail-summary-bury') simply buries the Rmail summary and buffer.


File: emacs,  Node: Rmail Sorting,  Next: Rmail Display,  Prev: Rmail Summary,  Up: Rmail

36.12 Sorting the Rmail File
============================

`C-c C-s C-d'
`M-x rmail-sort-by-date'
     Sort messages of current Rmail buffer by date.

`C-c C-s C-s'
`M-x rmail-sort-by-subject'
     Sort messages of current Rmail buffer by subject.

`C-c C-s C-a'
`M-x rmail-sort-by-author'
     Sort messages of current Rmail buffer by author's name.

`C-c C-s C-r'
`M-x rmail-sort-by-recipient'
     Sort messages of current Rmail buffer by recipient's names.

`C-c C-s C-c'
`M-x rmail-sort-by-correspondent'
     Sort messages of current Rmail buffer by the name of the other
     correspondent.

`C-c C-s C-l'
`M-x rmail-sort-by-lines'
     Sort messages of current Rmail buffer by number of lines.

`C-c C-s C-k <RET> LABELS <RET>'
`M-x rmail-sort-by-labels <RET> LABELS <RET>'
     Sort messages of current Rmail buffer by labels.  The argument
     LABELS should be a comma-separated list of labels.  The order of
     these labels specifies the order of messages; messages with the
     first label come first, messages with the second label come
     second, and so on.  Messages that have none of these labels come
     last.

   The Rmail sort commands perform a _stable sort_: if there is no
reason to prefer either one of two messages, their order remains
unchanged.  You can use this to sort by more than one criterion.  For
example, if you use `rmail-sort-by-date' and then
`rmail-sort-by-author', messages from the same author appear in order
by date.

   With a prefix argument, all these commands reverse the order of
comparison.  This means they sort messages from newest to oldest, from
biggest to smallest, or in reverse alphabetical order.

   The same keys in the summary buffer run similar functions; for
example, `C-c C-s C-l' runs `rmail-summary-sort-by-lines'.  Note that
these commands always sort the whole Rmail buffer, even if the summary
is only showing a subset of messages.

   Note that you cannot undo a sort, so you may wish to save the Rmail
buffer before sorting it.


File: emacs,  Node: Rmail Display,  Next: Rmail Coding,  Prev: Rmail Sorting,  Up: Rmail

36.13 Display of Messages
=========================

This section describes how Rmail displays mail headers, MIME sections
and attachments, and URLs.

`t'
     Toggle display of complete header (`rmail-toggle-header').

   Before displaying each message for the first time, Rmail reformats
its header, hiding uninteresting header fields to reduce clutter.  The
`t' (`rmail-toggle-header') command toggles this, switching between
showing the reformatted header fields and showing the complete,
original header.  With a positive prefix argument, the command shows
the reformatted header; with a zero or negative prefix argument, it
shows the full header.  Selecting the message again also reformats it
if necessary.

   The variable `rmail-ignored-headers' holds a regular expression
specifying the header fields to hide; any matching header line will be
hidden.  The variable `rmail-nonignored-headers' overrides this: any
header field matching that regular expression is shown even if it
matches `rmail-ignored-headers' too.  The variable
`rmail-displayed-headers' is an alternative to these two variables; if
non-`nil', this should be a regular expression specifying which headers
to display (the default is `nil').

   Rmail highlights certain header fields that are especially
interesting--by default, the `From' and `Subject' fields.  This
highlighting uses the `rmail-highlight' face.  The variable
`rmail-highlighted-headers' holds a regular expression specifying the
header fields to highlight; if it matches the beginning of a header
field, that whole field is highlighted.  To disable this feature, set
`rmail-highlighted-headers' to `nil'.

   If a message is in MIME (Multipurpose Internet Mail Extensions)
format and contains multiple parts (MIME entities), Rmail displays each
part with a "tagline".  The tagline summarizes the part's index, size,
and content type.  Depending on the content type, it may also contain
one or more buttons; these perform actions such as saving the part into
a file.

`<RET>'
     Hide or show the MIME part at point (`rmail-mime-toggle-hidden').

`<TAB>'
     Move point to the next MIME tagline button.
     (`rmail-mime-next-item').

`<BackTab>'
     Move point to the previous MIME part (`rmail-mime-previous-item').

`v'
     Toggle between MIME display and raw message (`rmail-mime').

   Each plain-text MIME part is initially displayed immediately after
its tagline, as part of the Rmail buffer, while MIME parts of other
types are represented only by their taglines, with their actual
contents hidden.  In either case, you can toggle a MIME part between
its "displayed" and "hidden" states by typing <RET> anywhere in the
part--or anywhere in its tagline, apart from a tagline button for some
other action.  Type <RET> (or click with the mouse) to activate a
tagline button, and <TAB> to cycle point between tagline buttons.

   The `v' (`rmail-mime') command toggles between the default MIME
display described above, and a "raw" display showing the undecoded MIME
data.  With a prefix argument, this command toggles the display of only
an entity at point.

   To prevent Rmail from handling MIME decoded messages, change the
variable `rmail-enable-mime' to `nil'.  When this is the case, the `v'
(`rmail-mime') command instead creates a temporary buffer to display
the current MIME message.

   You can highlight and activate URLs in the Rmail buffer using Goto
Address mode:

     (add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1)))

Then you can browse these URLs by clicking on them with `Mouse-2' (or
`Mouse-1' quickly) or by moving to one and typing `C-c <RET>'.  *Note
Activating URLs: Goto Address mode.


File: emacs,  Node: Rmail Coding,  Next: Rmail Editing,  Prev: Rmail Display,  Up: Rmail

36.14 Rmail and Coding Systems
==============================

Rmail automatically decodes messages which contain non-ASCII
characters, just as Emacs does with files you visit and with subprocess
output.  Rmail uses the standard `charset=CHARSET' header in the
message, if any, to determine how the message was encoded by the
sender.  It maps CHARSET into the corresponding Emacs coding system
(*note Coding Systems::), and uses that coding system to decode message
text.  If the message header doesn't have the `charset' specification,
or if CHARSET is not recognized, Rmail chooses the coding system with
the usual Emacs heuristics and defaults (*note Recognize Coding::).

   Occasionally, a message is decoded incorrectly, either because Emacs
guessed the wrong coding system in the absence of the `charset'
specification, or because the specification was inaccurate.  For
example, a misconfigured mailer could send a message with a
`charset=iso-8859-1' header when the message is actually encoded in
`koi8-r'.  When you see the message text garbled, or some of its
characters displayed as empty boxes, this may have happened.

   You can correct the problem by decoding the message again using the
right coding system, if you can figure out or guess which one is right.
To do this, invoke the `M-x rmail-redecode-body' command.  It reads the
name of a coding system, and then redecodes the message using the
coding system you specified.  If you specified the right coding system,
the result should be readable.


File: emacs,  Node: Rmail Editing,  Next: Rmail Digest,  Prev: Rmail Coding,  Up: Rmail

36.15 Editing Within a Message
==============================

Most of the usual Emacs keybindings are available in Rmail mode, though
a few, such as `C-M-n' and `C-M-h', are redefined by Rmail for other
purposes.  However, the Rmail buffer is normally read only, and most of
the letters are redefined as Rmail commands.  If you want to edit the
text of a message, you must use the Rmail command `e'.

`e'
     Edit the current message as ordinary text.

   The `e' command (`rmail-edit-current-message') switches from Rmail
mode into Rmail Edit mode, another major mode which is nearly the same
as Text mode.  The mode line indicates this change.

   In Rmail Edit mode, letters insert themselves as usual and the Rmail
commands are not available.  You can edit the message body and header
fields.  When you are finished editing the message, type `C-c C-c' to
switch back to Rmail mode.  Alternatively, you can return to Rmail mode
but cancel any editing that you have done, by typing `C-c C-]'.

   Entering Rmail Edit mode runs the hook `text-mode-hook'; then it
runs the hook `rmail-edit-mode-hook' (*note Hooks::).  Returning to
ordinary Rmail mode adds the attribute `edited' to the message, if you
have made any changes in it.


File: emacs,  Node: Rmail Digest,  Next: Rmail Rot13,  Prev: Rmail Editing,  Up: Rmail

36.16 Digest Messages
=====================

A "digest message" is a message which exists to contain and carry
several other messages.  Digests are used on some moderated mailing
lists; all the messages that arrive for the list during a period of time
such as one day are put inside a single digest which is then sent to the
subscribers.  Transmitting the single digest uses much less computer
time than transmitting the individual messages even though the total
size is the same, because the per-message overhead in network mail
transmission is considerable.

   When you receive a digest message, the most convenient way to read
it is to "undigestify" it: to turn it back into many individual
messages.  Then you can read and delete the individual messages as it
suits you.  To do this, select the digest message and type the command
`M-x undigestify-rmail-message'.  This extracts the submessages as
separate Rmail messages, and inserts them following the digest.  The
digest message itself is flagged as deleted.


File: emacs,  Node: Rmail Rot13,  Next: Movemail,  Prev: Rmail Digest,  Up: Rmail

36.17 Reading Rot13 Messages
============================

Mailing list messages that might offend some readers are sometimes
encoded in a simple code called "rot13"--so named because it rotates
the alphabet by 13 letters.  This code is not for secrecy, as it
provides none; rather, it enables those who might be offended to avoid
seeing the real text of the message.

   To view a buffer which uses the rot13 code, use the command `M-x
rot13-other-window'.  This displays the current buffer in another window
which applies the code when displaying the text.


File: emacs,  Node: Movemail,  Next: Remote Mailboxes,  Prev: Rmail Rot13,  Up: Rmail

36.18 `movemail' program
========================

Rmail uses the `movemail' program to move mail from your inbox to your
Rmail file (*note Rmail Inbox::).  When loaded for the first time,
Rmail attempts to locate the `movemail' program and determine its
version.  There are two versions of the `movemail' program: the native
one, shipped with GNU Emacs (the "emacs version") and the one included
in GNU mailutils (the "mailutils version," *note movemail:
(mailutils)movemail.).  They support the same command line syntax and
the same basic subset of options.  However, the Mailutils version
offers additional features.

   The Emacs version of `movemail' is able to retrieve mail from the
usual UNIX mailbox formats and from remote mailboxes using the POP3
protocol.

   The Mailutils version is able to handle a wide set of mailbox
formats, such as plain UNIX mailboxes, `maildir' and `MH' mailboxes,
etc.  It is able to access remote mailboxes using the POP3 or IMAP4
protocol, and can retrieve mail from them using a TLS encrypted
channel.  It also accepts mailbox arguments in URL form.  The detailed
description of mailbox URLs can be found in *note URL: (mailutils)URL.
In short, a URL is:

     PROTO://[USER[:PASSWORD]@]HOST-OR-FILE-NAME

where square brackets denote optional elements.

PROTO
     Specifies the "mailbox protocol", or "format" to use.  The exact
     semantics of the rest of URL elements depends on the actual value
     of PROTO (see below).

USER
     User name to access the remote mailbox.

PASSWORD
     User password to access the remote mailbox.

HOST-OR-FILE-NAME
     Hostname of the remote server for remote mailboxes or file name of
     a local mailbox.

PROTO can be one of:

`mbox'
     Usual UNIX mailbox format.  In this case, neither USER nor PASS
     are used, and HOST-OR-FILE-NAME denotes the file name of the
     mailbox file, e.g., `mbox://var/spool/mail/smith'.

`mh'
     A local mailbox in the MH format.  USER and PASS are not used.
     HOST-OR-FILE-NAME denotes the name of MH folder, e.g.,
     `mh://Mail/inbox'.

`maildir'
     A local mailbox in the maildir format.  USER and PASS are not
     used, and HOST-OR-FILE-NAME denotes the name of `maildir' mailbox,
     e.g., `maildir://mail/inbox'.

`file'
     Any local mailbox format.  Its actual format is detected
     automatically by `movemail'.

`pop'
     A remote mailbox to be accessed via POP3 protocol.  USER specifies
     the remote user name to use, PASS may be used to specify the user
     password, HOST-OR-FILE-NAME is the name or IP address of the
     remote mail server to connect to; e.g.,
     `pop://smith:guessme@remote.server.net'.

`imap'
     A remote mailbox to be accessed via IMAP4 protocol.  USER
     specifies the remote user name to use, PASS may be used to specify
     the user password, HOST-OR-FILE-NAME is the name or IP address of
     the remote mail server to connect to; e.g.,
     `imap://smith:guessme@remote.server.net'.

   Alternatively, you can specify the file name of the mailbox to use.
This is equivalent to specifying the `file' protocol:

     /var/spool/mail/USER == file://var/spool/mail/USER

   The variable `rmail-movemail-program' controls which version of
`movemail' to use.  If that is a string, it specifies the absolute file
name of the `movemail' executable.  If it is `nil', Rmail searches for
`movemail' in the directories listed in `rmail-movemail-search-path'
and `exec-path', then in `exec-directory'.


File: emacs,  Node: Remote Mailboxes,  Next: Other Mailbox Formats,  Prev: Movemail,  Up: Rmail

36.19 Retrieving Mail from Remote Mailboxes
===========================================

Some sites use a method called POP for accessing users' inbox data
instead of storing the data in inbox files.  By default, the `Emacs
movemail' can work with POP (unless the Emacs `configure' script was
run with the option `--without-pop').

   Similarly, the Mailutils `movemail' by default supports POP, unless
it was configured with the `--disable-pop' option.

   Both versions of `movemail' only work with POP3, not with older
versions of POP.

   No matter which flavor of `movemail' you use, you can specify a POP
inbox by using a POP "URL" (*note Movemail::).  A POP URL is a "file
name" of the form `pop://USERNAME@HOSTNAME', where HOSTNAME is the host
name or IP address of the remote mail server and USERNAME is the user
name on that server.  Additionally, you may specify the password in the
mailbox URL: `pop://USERNAME:PASSWORD@HOSTNAME'.  In this case,
PASSWORD takes preference over the one set by `rmail-remote-password'
(see below).  This is especially useful if you have several remote
mailboxes with different passwords.

   For backward compatibility, Rmail also supports an alternative way of
specifying remote POP mailboxes.  Specifying an inbox name in the form
`po:USERNAME:HOSTNAME' is equivalent to `pop://USERNAME@HOSTNAME'.  If
you omit the :HOSTNAME part, the `MAILHOST' environment variable
specifies the machine on which to look for the POP server.

   Another method for accessing remote mailboxes is IMAP.  This method
is supported only by the Mailutils `movemail'.  To specify an IMAP
mailbox in the inbox list, use the following mailbox URL:
`imap://USERNAME[:PASSWORD]@HOSTNAME'.  The PASSWORD part is optional,
as described above.

   Accessing a remote mailbox may require a password.  Rmail uses the
following algorithm to retrieve it:

  1. If a PASSWORD is present in the mailbox URL (see above), it is
     used.

  2. If the variable `rmail-remote-password-required' is `nil', Rmail
     assumes no password is required.

  3. If the variable `rmail-remote-password' is non-`nil', its value is
     used.

  4. Otherwise, Rmail will ask you for the password to use.

   If you need to pass additional command-line flags to `movemail', set
the variable `rmail-movemail-flags' a list of the flags you wish to
use.  Do not use this variable to pass the `-p' flag to preserve your
inbox contents; use `rmail-preserve-inbox' instead.

   The `movemail' program installed at your site may support Kerberos
authentication (the Emacs `movemail' does so if Emacs was configured
with the option `--with-kerberos' or `--with-kerberos5').  If it is
supported, it is used by default whenever you attempt to retrieve POP
mail when `rmail-remote-password' and `rmail-remote-password-required'
are unset.

   Some POP servers store messages in reverse order.  If your server
does this, and you would rather read your mail in the order in which it
was received, you can tell `movemail' to reverse the order of
downloaded messages by adding the `-r' flag to `rmail-movemail-flags'.

   Mailutils `movemail' supports TLS encryption.  If you wish to use
it, add the `--tls' flag to `rmail-movemail-flags'.


File: emacs,  Node: Other Mailbox Formats,  Prev: Remote Mailboxes,  Up: Rmail

36.20 Retrieving Mail from Local Mailboxes in Various Formats
=============================================================

If your incoming mail is stored on a local machine in a format other
than UNIX mailbox, you will need the Mailutils `movemail' to retrieve
it.  *Note Movemail::, for the detailed description of `movemail'
versions.  For example, to access mail from a inbox in `maildir' format
located in `/var/spool/mail/in', you would include the following in the
Rmail inbox list:

     maildir://var/spool/mail/in


File: emacs,  Node: Dired,  Next: Calendar/Diary,  Prev: Rmail,  Up: Top

37 Dired, the Directory Editor
******************************

Dired makes an Emacs buffer containing a listing of a directory, and
optionally some of its subdirectories as well.  You can use the normal
Emacs commands to move around in this buffer, and special Dired
commands to operate on the listed files.

   The Dired buffer is "read-only," and inserting text in it is not
allowed.  Ordinary printing characters such as `d' and `x' are
redefined for special Dired commands.  Some Dired commands "mark" or
"flag" the "current file" (that is, the file on the current line);
other commands operate on the marked files or on the flagged files.
You first mark certain files in order to operate on all of them with
one command.

   The Dired-X package provides various extra features for Dired mode.
*Note Dired-X: (dired-x)Top.

   You can also view a list of files in a directory with `C-x C-d'
(`list-directory').  Unlike Dired, this command does not allow you to
operate on the listed files.  *Note Directories::.

* Menu:

* Enter: Dired Enter.         How to invoke Dired.
* Navigation: Dired Navigation.   Special motion commands in the Dired buffer.
* Deletion: Dired Deletion.   Deleting files with Dired.
* Flagging Many Files::       Flagging files based on their names.
* Visit: Dired Visiting.      Other file operations through Dired.
* Marks vs Flags::            Flagging for deletion vs marking.
* Operating on Files::        How to copy, rename, print, compress, etc.
                                either one file or several files.
* Shell Commands in Dired::   Running a shell command on the marked files.
* Transforming File Names::   Using patterns to rename multiple files.
* Comparison in Dired::       Running `diff' by way of Dired.
* Subdirectories in Dired::   Adding subdirectories to the Dired buffer.

* Subdir Switches::           Subdirectory switches in Dired.
* Subdirectory Motion::       Moving across subdirectories, and up and down.
* Hiding Subdirectories::     Making subdirectories visible or invisible.
* Updating: Dired Updating.   Discarding lines for files of no interest.
* Find: Dired and Find.       Using `find' to choose the files for Dired.
* Wdired::                    Operating on files by editing the Dired buffer.
* Image-Dired::               Viewing image thumbnails in Dired.
* Misc: Misc Dired Features.  Various other features.


File: emacs,  Node: Dired Enter,  Next: Dired Navigation,  Up: Dired

37.1 Entering Dired
===================

To invoke Dired, type `C-x d' (`dired').  This reads a directory name
using the minibuffer, and opens a "Dired buffer" listing the files in
that directory.  You can also supply a wildcard file name pattern as
the minibuffer argument, in which case the Dired buffer lists all files
matching that pattern.  The usual history and completion commands can
be used in the minibuffer; in particular, `M-n' puts the name of the
visited file (if any) in the minibuffer (*note Minibuffer History::).

   You can also invoke Dired by giving `C-x C-f' (`find-file') a
directory name.

   The variable `dired-listing-switches' specifies the options to give
to `ls' for listing the directory; this string _must_ contain `-l'.  If
you use a prefix argument with the `dired' command, you can specify the
`ls' switches with the minibuffer before you enter the directory
specification.  No matter how they are specified, the `ls' switches can
include short options (that is, single characters) requiring no
arguments, and long options (starting with `--') whose arguments are
specified with `='.

   On MS-Windows and MS-DOS systems, Emacs _emulates_ `ls'; see *note
ls in Lisp::, for options and peculiarities of that emulation.

   To display the Dired buffer in another window rather than in the
selected window, use `C-x 4 d' (`dired-other-window') instead of `C-x
d'.  `C-x 5 d' (`dired-other-frame') uses a separate frame to display
the Dired buffer.


File: emacs,  Node: Dired Navigation,  Next: Dired Deletion,  Prev: Dired Enter,  Up: Dired

37.2 Navigation in the Dired Buffer
===================================

All the usual Emacs cursor motion commands are available in Dired
buffers.  The keys `C-n' and `C-p' are redefined to put the cursor at
the beginning of the file name on the line, rather than at the
beginning of the line.

   For extra convenience, <SPC> and `n' in Dired are equivalent to
`C-n'.  `p' is equivalent to `C-p'.  (Moving by lines is so common in
Dired that it deserves to be easy to type.)  <DEL> (move up and unflag)
is also often useful simply for moving up (*note Dired Deletion::).

   `j' (`dired-goto-file') prompts for a file name using the
minibuffer, and moves point to the line in the Dired buffer describing
that file.

   `M-s f C-s' (`dired-isearch-filenames') performs a forward
incremental search in the Dired buffer, looking for matches only
amongst the file names and ignoring the rest of the text in the buffer.
`M-s f M-C-s' (`dired-isearch-filenames-regexp') does the same, using a
regular expression search.  If you change the variable
`dired-isearch-filenames' to `t', then the usual search commands also
limit themselves to the file names; for instance, `C-s' behaves like
`M-s f C-s'.  If the value is `dwim', then search commands match the
file names only when point was on a file name initially.  *Note
Search::, for information about incremental search.

   Some additional navigation commands are available when the Dired
buffer includes several directories.  *Note Subdirectory Motion::.


File: emacs,  Node: Dired Deletion,  Next: Flagging Many Files,  Prev: Dired Navigation,  Up: Dired

37.3 Deleting Files with Dired
==============================

One of the most frequent uses of Dired is to first "flag" files for
deletion, then delete the files that were flagged.

`d'
     Flag this file for deletion.

`u'
     Remove deletion flag on this line.

`<DEL>'
     Move point to previous line and remove the deletion flag on that
     line.

`x'
     Delete the files that are flagged for deletion.

   You can flag a file for deletion by moving to the line describing
the file and typing `d' (`dired-flag-file-deletion').  The deletion
flag is visible as a `D' at the beginning of the line.  This command
moves point to the next line, so that repeated `d' commands flag
successive files.  A numeric argument serves as a repeat count.

   The reason for flagging files for deletion, rather than deleting
files immediately, is to reduce the danger of deleting a file
accidentally.  Until you direct Dired to delete the flagged files, you
can remove deletion flags using the commands `u' and <DEL>.  `u'
(`dired-unmark') works just like `d', but removes flags rather than
making flags.  <DEL> (`dired-unmark-backward') moves upward, removing
flags; it is like `u' with argument -1.

   To delete the flagged files, type `x' (`dired-do-flagged-delete').
This command first displays a list of all the file names flagged for
deletion, and requests confirmation with `yes'.  If you confirm, Dired
deletes the flagged files, then deletes their lines from the text of
the Dired buffer.  The Dired buffer, with somewhat fewer lines, remains
selected.

   If you answer `no' or quit with `C-g' when asked to confirm, you
return immediately to Dired, with the deletion flags still present in
the buffer, and no files actually deleted.

   You can delete empty directories just like other files, but normally
Dired cannot delete directories that are nonempty.  If the variable
`dired-recursive-deletes' is non-`nil', then Dired can delete nonempty
directories including all their contents.  That can be somewhat risky.

   On some systems, there is a facility called the "Trash" or "Recycle
Bin", but Emacs does _not_ use it by default.  Thus, when you delete a
file in Dired, it is gone forever.  However, you can tell Emacs to use
the Trash for file deletion, by changing the variable
`delete-by-moving-to-trash' to `t'.  *Note Misc File Ops::, for more
information about the Trash.


File: emacs,  Node: Flagging Many Files,  Next: Dired Visiting,  Prev: Dired Deletion,  Up: Dired

37.4 Flagging Many Files at Once
================================

The `#', `~', `.', `% &', and `% d' commands flag many files for
deletion, based on their file names:

`#'
     Flag all auto-save files (files whose names start and end with `#')
     for deletion (*note Auto Save::).

`~'
     Flag all backup files (files whose names end with `~') for deletion
     (*note Backup::).

`. (Period)'
     Flag excess numeric backup files for deletion.  The oldest and
     newest few backup files of any one file are exempt; the middle
     ones are flagged.

`% &'
     Flag for deletion all files with certain kinds of names which
     suggest you could easily create those files again.

`% d REGEXP <RET>'
     Flag for deletion all files whose names match the regular
     expression REGEXP.

   `#' (`dired-flag-auto-save-files') flags all files whose names look
like auto-save files--that is, files whose names begin and end with
`#'.  *Note Auto Save::.

   `~' (`dired-flag-backup-files') flags all files whose names say they
are backup files--that is, files whose names end in `~'.  *Note
Backup::.

   `.' (period, `dired-clean-directory') flags just some of the backup
files for deletion: all but the oldest few and newest few backups of
any one file.  Normally, the number of newest versions kept for each
file is given by the variable `dired-kept-versions' (*not*
`kept-new-versions'; that applies only when saving).  The number of
oldest versions to keep is given by the variable `kept-old-versions'.

   Period with a positive numeric argument, as in `C-u 3 .', specifies
the number of newest versions to keep, overriding
`dired-kept-versions'.  A negative numeric argument overrides
`kept-old-versions', using minus the value of the argument to specify
the number of oldest versions of each file to keep.

   `% &' (`dired-flag-garbage-files') flags files whose names match the
regular expression specified by the variable
`dired-garbage-files-regexp'.  By default, this matches certain files
produced by TeX, `.bak' files, and the `.orig' and `.rej' files
produced by `patch'.

   `% d' flags all files whose names match a specified regular
expression (`dired-flag-files-regexp').  Only the non-directory part of
the file name is used in matching.  You can use `^' and `$' to anchor
matches.  You can exclude certain subdirectories from marking by hiding
them while you use `% d'.  *Note Hiding Subdirectories::.


File: emacs,  Node: Dired Visiting,  Next: Marks vs Flags,  Prev: Flagging Many Files,  Up: Dired

37.5 Visiting Files in Dired
============================

There are several Dired commands for visiting or examining the files
listed in the Dired buffer.  All of them apply to the current line's
file; if that file is really a directory, these commands invoke Dired on
that subdirectory (making a separate Dired buffer).

`f'
     Visit the file described on the current line, like typing `C-x C-f'
     and supplying that file name (`dired-find-file').  *Note
     Visiting::.

`<RET>'
`e'
     Equivalent to `f'.

`o'
     Like `f', but uses another window to display the file's buffer
     (`dired-find-file-other-window').  The Dired buffer remains visible
     in the first window.  This is like using `C-x 4 C-f' to visit the
     file.  *Note Windows::.

`C-o'
     Visit the file described on the current line, and display the
     buffer in another window, but do not select that window
     (`dired-display-file').

`Mouse-1'
`Mouse-2'
     Visit the file named by the line you click on
     (`dired-mouse-find-file-other-window').  This uses another window
     to display the file, like the `o' command.

`v'
     View the file described on the current line, using `M-x view-file'
     (`dired-view-file').  Viewing a file with `view-file' is like
     visiting it, but is slanted toward moving around in the file
     conveniently and does not allow changing the file.  *Note View
     File: Misc File Ops.

`^'
     Visit the parent directory of the current directory
     (`dired-up-directory').  This is equivalent to moving to the line
     for `..' and typing `f' there.


File: emacs,  Node: Marks vs Flags,  Next: Operating on Files,  Prev: Dired Visiting,  Up: Dired

37.6 Dired Marks vs. Flags
==========================

Instead of flagging a file with `D', you can "mark" the file with some
other character (usually `*').  Most Dired commands to operate on files
use the files marked with `*'.  The only command that operates on
flagged files is `x', which deletes them.

   Here are some commands for marking with `*', for unmarking, and for
operating on marks.  (*Note Dired Deletion::, for commands to flag and
unflag files.)

`m'
`* m'
     Mark the current file with `*' (`dired-mark').  With a numeric
     argument N, mark the next N files starting with the current file.
     (If N is negative, mark the previous -N files.)

`* *'
     Mark all executable files with `*' (`dired-mark-executables').
     With a numeric argument, unmark all those files.

`* @'
     Mark all symbolic links with `*' (`dired-mark-symlinks').  With a
     numeric argument, unmark all those files.

`* /'
     Mark with `*' all files which are directories, except for `.' and
     `..' (`dired-mark-directories').  With a numeric argument, unmark
     all those files.

`* s'
     Mark all the files in the current subdirectory, aside from `.' and
     `..' (`dired-mark-subdir-files').

`u'
`* u'
     Remove any mark on this line (`dired-unmark').

`<DEL>'
`* <DEL>'
     Move point to previous line and remove any mark on that line
     (`dired-unmark-backward').

`* !'
`U'
     Remove all marks from all the files in this Dired buffer
     (`dired-unmark-all-marks').

`* ? MARKCHAR'
`M-<DEL>'
     Remove all marks that use the character MARKCHAR
     (`dired-unmark-all-files').  The argument is a single
     character--do not use <RET> to terminate it.  See the description
     of the `* c' command below, which lets you replace one mark
     character with another.

     With a numeric argument, this command queries about each marked
     file, asking whether to remove its mark.  You can answer `y'
     meaning yes, `n' meaning no, or `!' to remove the marks from the
     remaining files without asking about them.

`* C-n'
`M-}'
     Move down to the next marked file (`dired-next-marked-file') A
     file is "marked" if it has any kind of mark.

`* C-p'
`M-{'
     Move up to the previous marked file (`dired-prev-marked-file')

`t'
`* t'
     Toggle all marks (`dired-toggle-marks'): files marked with `*'
     become unmarked, and unmarked files are marked with `*'.  Files
     marked in any other way are not affected.

`* c OLD-MARKCHAR NEW-MARKCHAR'
     Replace all marks that use the character OLD-MARKCHAR with marks
     that use the character NEW-MARKCHAR (`dired-change-marks').  This
     command is the primary way to create or use marks other than `*'
     or `D'.  The arguments are single characters--do not use <RET> to
     terminate them.

     You can use almost any character as a mark character by means of
     this command, to distinguish various classes of files.  If
     OLD-MARKCHAR is a space (` '), then the command operates on all
     unmarked files; if NEW-MARKCHAR is a space, then the command
     unmarks the files it acts on.

     To illustrate the power of this command, here is how to put `D'
     flags on all the files that have no marks, while unflagging all
     those that already have `D' flags:

          * c D t  * c SPC D  * c t SPC

     This assumes that no files were already marked with `t'.

`% m REGEXP <RET>'
`* % REGEXP <RET>'
     Mark (with `*') all files whose names match the regular expression
     REGEXP (`dired-mark-files-regexp').  This command is like `% d',
     except that it marks files with `*' instead of flagging with `D'.

     Only the non-directory part of the file name is used in matching.
     Use `^' and `$' to anchor matches.  You can exclude subdirectories
     by temporarily hiding them (*note Hiding Subdirectories::).

`% g REGEXP <RET>'
     Mark (with `*') all files whose _contents_ contain a match for the
     regular expression REGEXP (`dired-mark-files-containing-regexp').
     This command is like `% m', except that it searches the file
     contents instead of the file name.

`C-x u'
`C-_'
`C-/'
     Undo changes in the Dired buffer, such as adding or removing marks
     (`dired-undo').  _This command does not revert the actual file
     operations, nor recover lost files!_  It just undoes changes in
     the buffer itself.

     In some cases, using this after commands that operate on files can
     cause trouble.  For example, after renaming one or more files,
     `dired-undo' restores the original names in the Dired buffer,
     which gets the Dired buffer out of sync with the actual contents of
     the directory.

