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

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

   Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 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 are free to copy and modify
     this GNU Manual. Buying copies from GNU Press supports the FSF 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: Fortran Comments,  Next: Fortran Autofill,  Prev: Fortran Indent,  Up: Fortran

31.13.3 Fortran Comments
------------------------

The usual Emacs comment commands assume that a comment can follow a
line of code.  In Fortran77, the standard comment syntax requires an
entire line to be just a comment.  Therefore, Fortran mode replaces the
standard Emacs comment commands and defines some new variables.

   Fortran mode can also handle the Fortran90 comment syntax where
comments start with `!' and can follow other text.  Because only some
Fortran77 compilers accept this syntax, Fortran mode will not insert
such comments unless you have said in advance to do so.  To do this,
set the variable `fortran-comment-line-start' to `"!"'.

`M-;'
     Align comment or insert new comment (`fortran-indent-comment').

`C-x ;'
     Applies to nonstandard `!' comments only.

`C-c ;'
     Turn all lines of the region into comments, or (with argument)
     turn them back into real code (`fortran-comment-region').

   `M-;' in Fortran mode is redefined as the command
`fortran-indent-comment'.  Like the usual `M-;' command, this
recognizes any kind of existing comment and aligns its text
appropriately; if there is no existing comment, a comment is inserted
and aligned.  But inserting and aligning comments are not the same in
Fortran mode as in other modes.

   When a new comment must be inserted, if the current line is blank, a
full-line comment is inserted.  On a non-blank line, a nonstandard `!'
comment is inserted if you have said you want to use them.  Otherwise a
full-line comment is inserted on a new line before the current line.

   Nonstandard `!' comments are aligned like comments in other
languages, but full-line comments are different.  In a standard
full-line comment, the comment delimiter itself must always appear in
column zero.  What can be aligned is the text within the comment.  You
can choose from three styles of alignment by setting the variable
`fortran-comment-indent-style' to one of these values:

`fixed'
     Align the text at a fixed column, which is the sum of
     `fortran-comment-line-extra-indent' and the minimum statement
     indentation.  This is the default.

     The minimum statement indentation is
     `fortran-minimum-statement-indent-fixed' for fixed format
     continuation line style and `fortran-minimum-statement-indent-tab'
     for tab format style.

`relative'
     Align the text as if it were a line of code, but with an additional
     `fortran-comment-line-extra-indent' columns of indentation.

`nil'
     Don't move text in full-line comments automatically.

   In addition, you can specify the character to be used to indent
within full-line comments by setting the variable
`fortran-comment-indent-char' to the single-character string you want
to use.

   Compiler directive lines, or preprocessor lines, have much the same
appearance as comment lines.  It is important, though, that such lines
never be indented at all, no matter what the value of
`fortran-comment-indent-style'.  The variable `fortran-directive-re' is
a regular expression that specifies which lines are directives.
Matching lines are never indented, and receive distinctive font-locking.

   The normal Emacs comment command `C-x ;' has not been redefined.  If
you use `!' comments, this command can be used with them.  Otherwise it
is useless in Fortran mode.

   The command `C-c ;' (`fortran-comment-region') turns all the lines
of the region into comments by inserting the string `C$$$' at the front
of each one.  With a numeric argument, it turns the region back into
live code by deleting `C$$$' from the front of each line in it.  The
string used for these comments can be controlled by setting the
variable `fortran-comment-region'.  Note that here we have an example
of a command and a variable with the same name; these two uses of the
name never conflict because in Lisp and in Emacs it is always clear
from the context which one is meant.


File: emacs,  Node: Fortran Autofill,  Next: Fortran Columns,  Prev: Fortran Comments,  Up: Fortran

31.13.4 Auto Fill in Fortran Mode
---------------------------------

Fortran mode has specialized support for Auto Fill mode, which is a
minor mode that automatically splits statements as you insert them when
they become too wide.  Splitting a statement involves making
continuation lines using `fortran-continuation-string' (*note ForIndent
Cont::).  This splitting happens when you type <SPC>, <RET>, or <TAB>,
and also in the Fortran indentation commands.  You activate Auto Fill
in Fortran mode in the normal way.  *Note Auto Fill::.

   Auto Fill breaks lines at spaces or delimiters when the lines get
longer than the desired width (the value of `fill-column').  The
delimiters (besides whitespace) that Auto Fill can break at are `+',
`-', `/', `*', `=', `<', `>', and `,'.  The line break comes after the
delimiter if the variable `fortran-break-before-delimiters' is `nil'.
Otherwise (and by default), the break comes before the delimiter.

   To enable Auto Fill in all Fortran buffers, add `turn-on-auto-fill'
to `fortran-mode-hook'.  *Note Hooks::.


File: emacs,  Node: Fortran Columns,  Next: Fortran Abbrev,  Prev: Fortran Autofill,  Up: Fortran

31.13.5 Checking Columns in Fortran
-----------------------------------

`C-c C-r'
     Display a "column ruler" momentarily above the current line
     (`fortran-column-ruler').

`C-c C-w'
     Split the current window horizontally temporarily so that it is 72
     columns wide (`fortran-window-create-momentarily').  This may help
     you avoid making lines longer than the 72-character limit that
     some Fortran compilers impose.

`C-u C-c C-w'
     Split the current window horizontally so that it is 72 columns wide
     (`fortran-window-create').  You can then continue editing.

`M-x fortran-strip-sequence-nos'
     Delete all text in column 72 and beyond.

   The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
momentarily above the current line.  The comment ruler is two lines of
text that show you the locations of columns with special significance in
Fortran programs.  Square brackets show the limits of the columns for
line numbers, and curly brackets show the limits of the columns for the
statement body.  Column numbers appear above them.

   Note that the column numbers count from zero, as always in GNU Emacs.
As a result, the numbers may be one less than those you are familiar
with; but the positions they indicate in the line are standard for
Fortran.

   The text used to display the column ruler depends on the value of the
variable `indent-tabs-mode'.  If `indent-tabs-mode' is `nil', then the
value of the variable `fortran-column-ruler-fixed' is used as the
column ruler.  Otherwise, the value of the variable
`fortran-column-ruler-tab' is displayed.  By changing these variables,
you can change the column ruler display.

   `C-c C-w' (`fortran-window-create-momentarily') temporarily splits
the current window horizontally, making a window 72 columns wide, so
you can see any lines that are too long.  Type a space to restore the
normal width.

   You can also split the window horizontally and continue editing with
the split in place.  To do this, use `C-u C-c C-w' (`M-x
fortran-window-create').  By editing in this window you can immediately
see when you make a line too wide to be correct Fortran.

   The command `M-x fortran-strip-sequence-nos' deletes all text in
column 72 and beyond, on all lines in the current buffer.  This is the
easiest way to get rid of old sequence numbers.


File: emacs,  Node: Fortran Abbrev,  Prev: Fortran Columns,  Up: Fortran

31.13.6 Fortran Keyword Abbrevs
-------------------------------

Fortran mode provides many built-in abbrevs for common keywords and
declarations.  These are the same sort of abbrev that you can define
yourself.  To use them, you must turn on Abbrev mode.  *Note Abbrevs::.

   The built-in abbrevs are unusual in one way: they all start with a
semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
mode makes this possible by changing the syntax of semicolon to "word
constituent."

   For example, one built-in Fortran abbrev is `;c' for `continue'.  If
you insert `;c' and then insert a punctuation character such as a space
or a newline, the `;c' expands automatically to `continue', provided
Abbrev mode is enabled.

   Type `;?' or `;C-h' to display a list of all the built-in Fortran
abbrevs and what they stand for.


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

32 Compiling and Testing Programs
*********************************

The previous chapter discusses the Emacs commands that are useful for
making changes in programs.  This chapter deals with commands that
assist in the larger process of compiling and testing programs.

* Menu:

* Compilation::         Compiling programs in languages other
                          than Lisp (C, Pascal, etc.).
* Compilation Mode::    The mode for visiting compiler errors.
* Compilation Shell::   Customizing your shell properly
                          for use in the compilation buffer.
* Grep Searching::      Searching with grep.
* Flymake::             Finding syntax errors on the fly.
* Debuggers::	        Running symbolic debuggers for non-Lisp programs.
* Executing Lisp::      Various modes for editing Lisp programs,
                          with different facilities for running
                          the Lisp programs.
* Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
* Eval: Lisp Eval.      Executing a single Lisp expression in Emacs.
* Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
* External Lisp::         Communicating through Emacs with a separate Lisp.


File: emacs,  Node: Compilation,  Next: Compilation Mode,  Up: Building

32.1 Running Compilations under Emacs
=====================================

Emacs can run compilers for noninteractive languages such as C and
Fortran as inferior processes, feeding the error log into an Emacs
buffer.  It can also parse the error messages and show you the source
lines where compilation errors occurred.

`M-x compile'
     Run a compiler asynchronously under Emacs, with error messages
     going to the `*compilation*' buffer.

`M-x recompile'
     Invoke a compiler with the same command as in the last invocation
     of `M-x compile'.

`M-x kill-compilation'
     Kill the running compilation subprocess.

   To run `make' or another compilation command, do `M-x compile'.
This command reads a shell command line using the minibuffer, and then
executes the command in an inferior shell, putting output in the buffer
named `*compilation*'.  The current buffer's default directory is used
as the working directory for the execution of the command; normally,
therefore, the compilation happens in this directory.

   The default for the compilation command is normally `make -k', which
is correct most of the time for nontrivial programs.  (*Note Make:
(make)Top.)  If you have done `M-x compile' before, the default each
time is the command you used the previous time.  `compile' stores this
command in the variable `compile-command', so setting that variable
specifies the default for the next use of `M-x compile'.  If a file
specifies a file local value for `compile-command', that provides the
default when you type `M-x compile' in that file's buffer.  *Note File
Variables::.

   Starting a compilation displays the buffer `*compilation*' in
another window but does not select it.  The buffer's mode line tells
you whether compilation is finished, with the word `run', `signal' or
`exit' inside the parentheses.  You do not have to keep this buffer
visible; compilation continues in any case.  While a compilation is
going on, the string `Compiling' appears in the mode lines of all
windows.  When this string disappears, the compilation is finished.

   If you want to watch the compilation transcript as it appears, switch
to the `*compilation*' buffer and move point to the end of the buffer.
When point is at the end, new compilation output is inserted above
point, which remains at the end.  If point is not at the end of the
buffer, it remains fixed while more compilation output is added at the
end of the buffer.

   If you set the variable `compilation-scroll-output' to a non-`nil'
value, then the compilation buffer always scrolls to follow output as
it comes in.

   To rerun the last compilation with the same command, type `M-x
recompile'.  This automatically reuses the compilation command from the
last invocation of `M-x compile'.  It also reuses the `*compilation*'
buffer and starts the compilation in its default directory, which is
the directory in which the previous compilation was started.

   When the compiler process terminates, for whatever reason, the mode
line of the `*compilation*' buffer changes to say `exit' (followed by
the exit code, `[0]' for a normal exit), or `signal' (if a signal
terminated the process), instead of `run'.

   Starting a new compilation also kills any compilation already
running in `*compilation*', as the buffer can only handle one
compilation at any time.  However, `M-x compile' asks for confirmation
before actually killing a compilation that is running.  You can also
kill the compilation process with `M-x kill-compilation'.

   If you want to run two compilations at once, you should start the
first one, then rename the `*compilation*' buffer (perhaps using
`rename-uniquely'; *note Misc Buffer::), and start the other
compilation.  That will create a new `*compilation*' buffer.

   Emacs does not expect a compiler process to launch asynchronous
subprocesses; if it does, and they keep running after the main compiler
process has terminated, Emacs may kill them or their output may not
arrive in Emacs.  To avoid this problem, make the main process wait for
its subprocesses to finish.  In a shell script, you can do this using
`$!' and `wait', like this:

     (sleep 10; echo 2nd)& pid=$!  # Record pid of subprocess
     echo first message
     wait $pid                     # Wait for subprocess

   If the background process does not output to the compilation buffer,
so you only need to prevent it from being killed when the main
compilation process terminates, this is sufficient:

     nohup COMMAND; sleep 1

   You can control the environment passed to the compilation command
with the variable `compilation-environment'.  Its value is a list of
environment variable settings; each element should be a string of the
form `"ENVVARNAME=VALUE"'.  These environment variable settings
override the usual ones.


File: emacs,  Node: Compilation Mode,  Next: Compilation Shell,  Prev: Compilation,  Up: Building

32.2 Compilation Mode
=====================

The `*compilation*' buffer uses a special major mode, Compilation mode,
whose main feature is to provide a convenient way to visit the source
line corresponding to an error message.  These commands are also
available in other special buffers that list locations in files,
including those made by `M-x grep' and `M-x occur'.

`M-g M-n'
`M-g n'
`C-x `'
     Visit the locus of the next error message or match.

`M-g M-p'
`M-g p'
     Visit the locus of the previous error message or match.

`<RET>'
     Visit the locus of the error message that point is on.  This
     command is used in the compilation buffer.

`Mouse-2'
     Visit the locus of the error message that you click on.

`M-n'
     Find and highlight the locus of the next error message, without
     selecting the source buffer.

`M-p'
     Find and highlight the locus of the previous error message, without
     selecting the source buffer.

`M-}'
     Move point to the next error for a different file than the current
     one.

`M-{'
     Move point to the previous error for a different file than the
     current one.

`C-c C-f'
     Toggle Next Error Follow minor mode, which makes cursor motion in
     the compilation buffer produce automatic source display.

   You can visit the source for any particular error message by moving
point in the `*compilation*' buffer to that error message and typing
<RET> (`compile-goto-error').  Alternatively, you can click `Mouse-2'
on the error message; you need not switch to the `*compilation*' buffer
first.

   To parse the compiler error messages sequentially, type `C-x `'
(`next-error').  The character following the `C-x' is the backquote or
"grave accent," not the single-quote.  This command is available in all
buffers, not just in `*compilation*'; it displays the next error
message at the top of one window and source location of the error in
another window.  It also temporarily highlights the relevant source
line, for a period controlled by the variable `next-error-highlight'.

   The first time `C-x `' is used after the start of a compilation, it
moves to the first error's location.  Subsequent uses of `C-x `'
advance down to subsequent errors.  If you visit a specific error
message with <RET> or `Mouse-2', subsequent `C-x `' commands advance
from there.  When `C-x `' gets to the end of the buffer and finds no
more error messages to visit, it fails and signals an Emacs error.
`C-u C-x `' starts scanning from the beginning of the compilation
buffer, and goes to the first error's location.

   By default, `C-x `' skips less important messages.  The variable
`compilation-skip-threshold' controls this.  If its value is 2, `C-x `'
skips anything less than error, 1 skips anything less than warning, and
0 doesn't skip any messages.  The default is 1.

   When the window has a left fringe, an arrow in the fringe points to
the current message in the compilation buffer. The variable
`compilation-context-lines' controls the number of lines of leading
context to display before the current message.  Going to an error
message location scrolls the `*compilation*' buffer to put the message
that far down from the top.  The value `nil' is special: if there's a
left fringe, the window doesn't scroll at all if the message is already
visible.  If there is no left fringe, `nil' means display the message
at the top of the window.

   If you're not in the compilation buffer when you run `next-error',
Emacs will look for a buffer that contains error messages.  First, it
looks for one displayed in the selected frame, then for one that
previously had `next-error' called on it, and then at the current
buffer.  Finally, Emacs looks at all the remaining buffers.
`next-error' signals an error if it can't find any such buffer.

   To parse messages from the compiler, Compilation mode uses the
variable `compilation-error-regexp-alist' which lists various formats
of error messages and tells Emacs how to extract the source file and
the line number from the text of a message.  If your compiler isn't
supported, you can tailor Compilation mode to it by adding elements to
that list.  A similar variable `grep-regexp-alist' tells Emacs how to
parse output of a `grep' command.

   Compilation mode also redefines the keys <SPC> and <DEL> to scroll
by screenfuls, and `M-n' (`compilation-next-error') and `M-p'
(`compilation-previous-error') to move to the next or previous error
message.  You can also use `M-{' (`compilation-next-file' and `M-}'
(`compilation-previous-file') to move up or down to an error message
for a different source file.

   You can type `C-c C-f' to toggle Next Error Follow mode.  In this
minor mode, ordinary cursor motion in the compilation buffer
automatically updates the source buffer.  For instance, moving the
cursor to the next error message causes the location of that error to
be displayed immediately.

   The features of Compilation mode are also available in a minor mode
called Compilation Minor mode.  This lets you parse error messages in
any buffer, not just a normal compilation output buffer.  Type `M-x
compilation-minor-mode' to enable the minor mode.  This defines the keys
<RET> and `Mouse-2', as in the Compilation major mode.

   Compilation minor mode works in any buffer, as long as the contents
are in a format that it understands.  In an Rlogin buffer (*note Remote
Host::), Compilation minor mode automatically accesses remote source
files by FTP (*note File Names::).


File: emacs,  Node: Compilation Shell,  Next: Grep Searching,  Prev: Compilation Mode,  Up: Building

32.3 Subshells for Compilation
==============================

Emacs uses a shell to run the compilation command, but specifies the
option for a noninteractive shell.  This means, in particular, that the
shell should start with no prompt.  If you find your usual shell prompt
making an unsightly appearance in the `*compilation*' buffer, it means
you have made a mistake in your shell's init file by setting the prompt
unconditionally.  (This init file's name may be `.bashrc', `.profile',
`.cshrc', `.shrc', or various other things, depending on the shell you
use.)  The shell init file should set the prompt only if there already
is a prompt.  Here's how to do it in bash:

     if [ "${PS1+set}" = set ]
     then PS1=...
     fi

And here's how to do it in csh:

     if ($?prompt) set prompt = ...

   There may well be other things that your shell's init file ought to
do only for an interactive shell.  You can use the same method to
conditionalize them.

   The MS-DOS "operating system" does not support asynchronous
subprocesses; to work around this lack, `M-x compile' runs the
compilation command synchronously on MS-DOS.  As a consequence, you must
wait until the command finishes before you can do anything else in
Emacs.  *Note MS-DOS::.


File: emacs,  Node: Grep Searching,  Next: Flymake,  Prev: Compilation Shell,  Up: Building

32.4 Searching with Grep under Emacs
====================================

Just as you can run a compiler from Emacs and then visit the lines with
compilation errors, you can also run `grep' and then visit the lines on
which matches were found.  This works by treating the matches reported
by `grep' as if they were "errors."  The buffer of matches uses Grep
mode, which is a variant of Compilation mode (*note Compilation Mode::).

`M-x grep'

`M-x lgrep'
     Run `grep' asynchronously under Emacs, with matching lines listed
     in the buffer named `*grep*'.

`M-x grep-find'
`M-x find-grep'
`M-x rgrep'
     Run `grep' via `find', with user-specified arguments, and collect
     output in the buffer named `*grep*'.

`M-x kill-grep'
     Kill the running `grep' subprocess.

   To run `grep', type `M-x grep', then enter a command line that
specifies how to run `grep'.  Use the same arguments you would give
`grep' when running it normally: a `grep'-style regexp (usually in
single-quotes to quote the shell's special characters) followed by file
names, which may use wildcards.  If you specify a prefix argument for
`M-x grep', it finds the tag (*note Tags::) in the buffer around point,
and puts that into the default `grep' command.

   Your command need not simply run `grep'; you can use any shell
command that produces output in the same format.  For instance, you can
chain `grep' commands, like this:

     grep -nH -e foo *.el | grep bar | grep toto

   The output from `grep' goes in the `*grep*' buffer.  You can find
the corresponding lines in the original files using `C-x `', <RET>, and
so forth, just like compilation errors.

   Some grep programs accept a `--color' option to output special
markers around matches for the purpose of highlighting.  You can make
use of this feature by setting `grep-highlight-matches' to `t'.  When
displaying a match in the source buffer, the exact match will be
highlighted, instead of the entire source line.

   The command `M-x grep-find' (also available as `M-x find-grep') is
similar to `M-x grep', but it supplies a different initial default for
the command--one that runs both `find' and `grep', so as to search
every file in a directory tree.  See also the `find-grep-dired'
command, in *note Dired and Find::.

   The commands `M-x lgrep' (local grep) and `M-x rgrep' (recursive
grep) are more user-friendly versions of `grep' and `grep-find', which
prompt separately for the regular expression to match, the files to
search, and the base directory for the search.  Case sensitivity of the
search is controlled by the current value of `case-fold-search'.

   These commands build the shell commands based on the variables
`grep-template' (for `lgrep') and `grep-find-template' (for `rgrep').

   The files to search can use aliases defined in the variable
`grep-files-aliases'.

   Subdirectories listed in the variable
`grep-find-ignored-directories' such as those typically used by various
version control systems, like CVS and arch, are automatically skipped
by `rgrep'.


File: emacs,  Node: Flymake,  Next: Debuggers,  Prev: Grep Searching,  Up: Building

32.5 Finding Syntax Errors On The Fly
=====================================

Flymake mode is a minor mode that performs on-the-fly syntax checking
for many programming and markup languages, including C, C++, Perl,
HTML, and TeX/LaTeX.  It is somewhat analogous to Flyspell mode, which
performs spell checking for ordinary human languages in a similar
fashion (*note Spelling::).  As you edit a file, Flymake mode runs an
appropriate syntax checking tool in the background, using a temporary
copy of the buffer.  It then parses the error and warning messages, and
highlights the erroneous lines in the buffer.  The syntax checking tool
used depends on the language; for example, for C/C++ files this is
usually the C compiler.  Flymake can also use build tools such as
`make' for checking complicated projects.

   To activate Flymake mode, type `M-x flymake-mode'.  You can move to
the errors spotted by Flymake mode with `M-x flymake-goto-next-error'
and `M-x flymake-goto-prev-error'.  To display any error messages
associated with the current line, use `M-x
flymake-display-err-menu-for-current-line'.

   For more details about using Flymake, see *note Flymake:
(flymake)Top.


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

32.6 Running Debuggers Under Emacs
==================================

The GUD (Grand Unified Debugger) library provides an interface to
various symbolic debuggers from within Emacs.  We recommend the
debugger GDB, which is free software, but GUD can also run DBX, SDB or
XDB.  GUD can also serve as an interface to Perl's debugging mode, the
Python debugger PDB, and to JDB, the Java Debugger.  *Note The Lisp
Debugger: (elisp)Debugging, for information on debugging Emacs Lisp
programs.

* Menu:

* Starting GUD::	How to start a debugger subprocess.
* Debugger Operation::	Connection between the debugger and source buffers.
* Commands of GUD::	Key bindings for common commands.
* GUD Customization::	Defining your own commands for GUD.
* GDB Graphical Interface::  An enhanced mode that uses GDB features to
                        implement a graphical debugging environment through
                        Emacs.


File: emacs,  Node: Starting GUD,  Next: Debugger Operation,  Up: Debuggers

32.6.1 Starting GUD
-------------------

There are several commands for starting a debugger, each corresponding
to a particular debugger program.

`M-x gdb <RET> FILE <RET>'
     Run GDB as a subprocess of Emacs.  By default, this uses an
     IDE-like graphical interface; see *note GDB Graphical Interface::.
     Only GDB works with the graphical interface.

`M-x dbx <RET> FILE <RET>'
     Run DBX as a subprocess of Emacs.  Since Emacs does not implement a
     graphical interface for DBX, communication with DBX works by typing
     commands in the GUD interaction buffer.  The same is true for all
     the other supported debuggers.

`M-x xdb <RET> FILE <RET>'
     Similar, but run XDB.  Use the variable `gud-xdb-directories' to
     specify directories to search for source files.

`M-x sdb <RET> FILE <RET>'
     Similar, but run SDB.

     Some versions of SDB do not mention source file names in their
     messages.  When you use them, you need to have a valid tags table
     (*note Tags::) in order for GUD to find functions in the source
     code.  If you have not visited a tags table or the tags table
     doesn't list one of the functions, you get a message saying `The
     sdb support requires a valid tags table to work'.  If this
     happens, generate a valid tags table in the working directory and
     try again.

`M-x perldb <RET> FILE <RET>'
     Run the Perl interpreter in debug mode to debug FILE, a Perl
     program.

`M-x jdb <RET> FILE <RET>'
     Run the Java debugger to debug FILE.

`M-x pdb <RET> FILE <RET>'
     Run the Python debugger to debug FILE.

   Each of these commands takes one argument: a command line to invoke
the debugger.  In the simplest case, specify just the name of the
executable file you want to debug.  You may also use options that the
debugger supports.  However, shell wildcards and variables are not
allowed.  GUD assumes that the first argument not starting with a `-'
is the executable file name.


File: emacs,  Node: Debugger Operation,  Next: Commands of GUD,  Prev: Starting GUD,  Up: Debuggers

32.6.2 Debugger Operation
-------------------------

Generally when you run a debugger with GUD, the debugger uses an Emacs
buffer for its ordinary input and output.  This is called the GUD
buffer.  Input and output from the program you are debugging also use
this buffer.  We call this "text command mode".  The GDB Graphical
Interface can use further buffers (*note GDB Graphical Interface::).

   The debugger displays the source files of the program by visiting
them in Emacs buffers.  An arrow in the left fringe indicates the
current execution line.(1)  Moving point in this buffer does not move
the arrow.  The arrow is not part of the file's text; it appears only
on the screen.

   You can start editing these source files at any time in the buffers
that display them.  If you do modify a source file, keep in mind that
inserting or deleting lines will throw off the arrow's positioning; GUD
has no way of figuring out which line corresponded before your changes
to the line number in a debugger message.  Also, you'll typically have
to recompile and restart the program for your changes to be reflected
in the debugger's tables.

   The Tooltip facility (*note Tooltips::) provides support for GUD.
You activate this feature by turning on the minor mode
`gud-tooltip-mode'.  Then you can display a variable's value in a
tooltip simply by pointing at it with the mouse.  This operates in the
GUD buffer and in source buffers with major modes in the list
`gud-tooltip-modes'.  If the variable `gud-tooltip-echo-area' is
non-`nil' then the variable's value is displayed in the echo area.
When debugging a C program using the GDB Graphical Interface, you can
also display macro definitions associated with an identifier when the
program is not executing.

   GUD tooltips are disabled when you use GDB in text command mode
(*note GDB Graphical Interface::), because displaying an expression's
value in GDB can sometimes expand a macro and result in a side effect
that interferes with the program's operation.  The GDB graphical
interface supports GUD tooltips and assures they will not cause side
effects.

   ---------- Footnotes ----------

   (1) On a text-only terminal, the arrow appears as `=>' and overlays
the first two text columns.


File: emacs,  Node: Commands of GUD,  Next: GUD Customization,  Prev: Debugger Operation,  Up: Debuggers

32.6.3 Commands of GUD
----------------------

The GUD interaction buffer uses a variant of Shell mode, so the Emacs
commands of Shell mode are available (*note Shell Mode::).  All the
usual commands for your debugger are available, and you can use the
Shell mode history commands to repeat them.  If you wish, you can
control your debugger process entirely through this buffer.

   GUD mode also provides commands for setting and clearing
breakpoints, for selecting stack frames, and for stepping through the
program.  These commands are available both in the GUD buffer and
globally, but with different key bindings.  It also has its own tool
bar from which you can invoke the more common commands by clicking on
the appropriate icon.  This is particularly useful for repetitive
commands like `gud-next' and `gud-step', and allows you to keep the GUD
buffer hidden.

   The breakpoint commands are normally used in source file buffers,
because that is the easiest way to specify where to set or clear the
breakpoint.  Here's the global command to set a breakpoint:

`C-x <SPC>'
     Set a breakpoint on the source line that point is on.

   Here are the other special commands provided by GUD.  The keys
starting with `C-c' are available only in the GUD interaction buffer.
The key bindings that start with `C-x C-a' are available in the GUD
interaction buffer and also in source files.  Some of these commands
are not available to all the supported debuggers.

`C-c C-l'
`C-x C-a C-l'
     Display in another window the last line referred to in the GUD
     buffer (that is, the line indicated in the last location message).
     This runs the command `gud-refresh'.

`C-c C-s'
`C-x C-a C-s'
     Execute a single line of code (`gud-step').  If the line contains
     a function call, execution stops after entering the called
     function.

`C-c C-n'
`C-x C-a C-n'
     Execute a single line of code, stepping across entire function
     calls at full speed (`gud-next').

`C-c C-i'
`C-x C-a C-i'
     Execute a single machine instruction (`gud-stepi').

`C-c C-p'
`C-x C-a C-p'
     Evaluate the expression at point (`gud-print').  If Emacs does not
     print the exact expression that you want, mark it as a region
     first.

`C-c C-r'
`C-x C-a C-r'
     Continue execution without specifying any stopping point.  The
     program will run until it hits a breakpoint, terminates, or gets a
     signal that the debugger is checking for (`gud-cont').

`C-c C-d'
`C-x C-a C-d'
     Delete the breakpoint(s) on the current source line, if any
     (`gud-remove').  If you use this command in the GUD interaction
     buffer, it applies to the line where the program last stopped.

`C-c C-t'
`C-x C-a C-t'
     Set a temporary breakpoint on the current source line, if any
     (`gud-tbreak').  If you use this command in the GUD interaction
     buffer, it applies to the line where the program last stopped.

`C-c <'
`C-x C-a <'
     Select the next enclosing stack frame (`gud-up').  This is
     equivalent to the GDB command `up'.

`C-c >'
`C-x C-a >'
     Select the next inner stack frame (`gud-down').  This is
     equivalent to the GDB command `down'.

`C-c C-u'
`C-x C-a C-u'
     Continue execution to the current line (`gud-until').  The program
     will run until it hits a breakpoint, terminates, gets a signal
     that the debugger is checking for, or reaches the line on which the
     cursor currently sits.

`C-c C-f'
`C-x C-a C-f'
     Run the program until the selected stack frame returns or stops
     for some other reason (`gud-finish').

   If you are using GDB, these additional key bindings are available:

`C-x C-a C-j'
     Only useful in a source buffer, `gud-jump' transfers the program's
     execution point to the current line.  In other words, the next
     line that the program executes will be the one where you gave the
     command.  If the new execution line is in a different function from
     the previously one, GDB prompts for confirmation since the results
     may be bizarre.  See the GDB manual entry regarding `jump' for
     details.

`<TAB>'
     With GDB, complete a symbol name (`gud-gdb-complete-command').
     This key is available only in the GUD interaction buffer.

   These commands interpret a numeric argument as a repeat count, when
that makes sense.

   Because <TAB> serves as a completion command, you can't use it to
enter a tab as input to the program you are debugging with GDB.
Instead, type `C-q <TAB>' to enter a tab.


File: emacs,  Node: GUD Customization,  Next: GDB Graphical Interface,  Prev: Commands of GUD,  Up: Debuggers

32.6.4 GUD Customization
------------------------

On startup, GUD runs one of the following hooks: `gdb-mode-hook', if
you are using GDB; `dbx-mode-hook', if you are using DBX;
`sdb-mode-hook', if you are using SDB; `xdb-mode-hook', if you are
using XDB; `perldb-mode-hook', for Perl debugging mode;
`pdb-mode-hook', for PDB; `jdb-mode-hook', for JDB.  You can use these
hooks to define custom key bindings for the debugger interaction
buffer.  *Note Hooks::.

   Here is a convenient way to define a command that sends a particular
command string to the debugger, and set up a key binding for it in the
debugger interaction buffer:

     (gud-def FUNCTION CMDSTRING BINDING DOCSTRING)

   This defines a command named FUNCTION which sends CMDSTRING to the
debugger process, and gives it the documentation string DOCSTRING.  You
can then use the command FUNCTION in any buffer.  If BINDING is
non-`nil', `gud-def' also binds the command to `C-c BINDING' in the GUD
buffer's mode and to `C-x C-a BINDING' generally.

   The command string CMDSTRING may contain certain `%'-sequences that
stand for data to be filled in at the time FUNCTION is called:

`%f'
     The name of the current source file.  If the current buffer is the
     GUD buffer, then the "current source file" is the file that the
     program stopped in.

`%l'
     The number of the current source line.  If the current buffer is
     the GUD buffer, then the "current source line" is the line that
     the program stopped in.

`%e'
     In transient-mark-mode the text in the region, if it is active.
     Otherwise the text of the C lvalue or function-call expression at
     or adjacent to point.

`%a'
     The text of the hexadecimal address at or adjacent to point.

`%p'
     The numeric argument of the called function, as a decimal number.
     If the command is used without a numeric argument, `%p' stands for
     the empty string.

     If you don't use `%p' in the command string, the command you define
     ignores any numeric argument.

`%d'
     The name of the directory of the current source file.

`%c'
     Fully qualified class name derived from the expression surrounding
     point (jdb only).


File: emacs,  Node: GDB Graphical Interface,  Prev: GUD Customization,  Up: Debuggers

32.6.5 GDB Graphical Interface
------------------------------

By default, the command `gdb' starts GDB using a graphical interface,
using Emacs windows for display program state information.  In effect,
this makes Emacs into an IDE (interactive development environment).
With it, you do not need to use textual GDB commands; you can control
the debugging session with the mouse.  For example, you can click in
the fringe of a source buffer to set a breakpoint there, or on a stack
frame in the stack buffer to select that frame.

   This mode requires telling GDB that its "screen size" is unlimited,
so it sets the height and width accordingly.  For correct operation you
must not change these values during the GDB session.

   You can also run GDB in text command mode, like the other debuggers
in Emacs.  To do this, replace the GDB `"--annotate=3"' option with
`"--fullname"' either in the minibuffer for the current Emacs session,
or the custom variable `gud-gdb-command-name' for all future sessions.
You need to use text command mode to debug multiple programs within one
Emacs session.  You can also use `M-x gud-gdb' to invoke GDB in text
command mode if you have problems before execution has started.

* Menu:

* GDB-UI Layout::               Control the number of displayed buffers.
* Source Buffers::              Use the mouse in the fringe/margin to
                                control your program.
* Breakpoints Buffer::          A breakpoint control panel.
* Stack Buffer::                Select a frame from the call stack.
* Other GDB-UI Buffers::        Input/output, locals, registers,
                                assembler, threads and memory buffers.
* Watch Expressions::           Monitor variable values in the speedbar.


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

32.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 buffer                |
     |--------------------------------+--------------------------------+
     |   Primary Source buffer        |   I/O buffer for debugged pgm  |
     |--------------------------------+--------------------------------+
     |   Stack buffer                 |   Breakpoints 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

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

32.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 the 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.


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

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

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

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.  Click `Mouse-3' on the
     header line to select the display format or unit size for these
     data items.


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

32.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: Executing Lisp,  Next: Lisp Libraries,  Prev: Debuggers,  Up: Building

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

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

   Because the argument to `load-library' is usually not in itself a
valid file name, file name completion is not available.  Indeed, when
using this command, you usually do not know exactly what file name will
be used.

   The sequence of directories searched by `M-x load-library' is
specified by the variable `load-path', a list of strings that are
directory names.  The default value of the list contains the
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'.  `nil' in this list stands for the current
default directory, but it is probably 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 to do is use `M-x load-file' this once.

   Often you do not have to give any command to load a library, because
the commands defined in the library are set up to "autoload" that
library.  Trying to run any of those commands calls `load' to load the
library; this replaces the autoload definitions with the real ones from
the 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

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

32.10 Lisp Interaction Buffers
==============================

The buffer `*scratch*' which is selected when Emacs starts up is
provided for evaluating Lisp expressions interactively inside Emacs.

   The simplest way to use the `*scratch*' buffer is to insert Lisp
expressions and type `C-j' after each expression.  This command reads
the Lisp expression before point, evaluates it, and inserts the value
in printed representation before point.  The result is a complete
typescript of the expressions you have evaluated and their values.

   The `*scratch*' buffer's major mode is Lisp Interaction mode, which
is the same as Emacs-Lisp mode except for the binding of `C-j'.

   The rationale for this feature is that Emacs must have a buffer when
it starts up, but that buffer is not useful for editing files since a
new buffer is made for every file that you visit.  The Lisp interpreter
typescript is the most useful thing I can think of for the initial
buffer to do.  Type `M-x lisp-interaction-mode' to put the current
buffer in Lisp Interaction mode.

   An alternative way of evaluating Emacs Lisp expressions interactively
is to use Inferior Emacs-Lisp mode, which provides an interface rather
like Shell mode (*note Shell Mode::) for evaluating Emacs Lisp
expressions.  Type `M-x ielm' to create an `*ielm*' buffer which uses
this mode.  For more information see that command's documentation.


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

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

33 Maintaining Large Programs
*****************************

This chapter describes Emacs features for maintaining large programs.
The version control features (*note Version Control::) are also
particularly useful for this purpose.

* Menu:

* Change Log::	        Maintaining a change history for your program.
* Format of ChangeLog:: What the change log file looks like.
* Tags::	        Go directly to any function in your program in one
			  command.  Tags remembers which file it is in.

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


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

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

   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 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.  *Note Log Buffer::.


File: emacs,  Node: Format of ChangeLog,  Next: Tags,  Prev: Change Log,  Up: Maintaining

33.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: Emerge,  Prev: Format of ChangeLog,  Up: Maintaining

33.3 Tags Tables
================

A "tags table" is a description of how a multi-file program is broken
up into files.  It lists the names of the component files and the names
and positions of the functions (or other named subunits) in each file.
Grouping the related files makes it possible to search or replace
through all the files with one command.  Recording the function names
and positions makes possible the `M-.' command which finds the
definition of a function by looking up which of the files it is in.

   Tags tables are stored in files called "tags table files".  The
conventional name for a tags table file is `TAGS'.

   Each entry in the tags table records the name of one tag, the name
of the file that the tag is defined in (implicitly), and the position
in that file of the tag's definition.  When a file parsed by `etags' is
generated from a different source file, like a C file generated from a
Cweb source file, the tags of the parsed file reference the source file.

   Just what names from the described files are recorded in the tags
table depends on the programming language of the described file.  They
normally include all file names, functions and subroutines, and may
also include global variables, data types, and anything else
convenient.  Each name recorded is called a "tag".

   See also the Ebrowse facility, which is tailored for C++.  *Note
Ebrowse: (ebrowse)Top.

* Menu:

* Tag Syntax::		Tag syntax for various types of code and text files.
* Create Tags Table::	Creating a tags table with `etags'.
* Etags Regexps::       Create arbitrary tags using regular expressions.
* Select Tags Table::	How to visit a tags table.
* Find Tag::		Commands to find the definition of a specific tag.
* Tags Search::		Using a tags table for searching and replacing.
* List Tags::		Listing and finding tags defined in a file.


File: emacs,  Node: Tag Syntax,  Next: Create Tags Table,  Up: Tags

33.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'.  Use
     of `--no-globals' and `--no-defines' can make the tags table file
     much smaller.

     You can tag function declarations and external variables in
     addition to function definitions by giving the `--declarations'
     option to `etags'.  You can tag struct members with the `--members'
     option.

   * In C++ code, in addition to all the tag constructs of C code,
     member functions are also recognized, and optionally member
     variables if you use the `--members' option.  Tags for variables
     and functions in classes are named `CLASS::VARIABLE' and
     `CLASS::FUNCTION'.  `operator' definitions have tag names like
     `operator+'.

   * In Java code, tags include all the constructs recognized in C++,
     plus the `interface', `extends' and `implements' constructs.  Tags
     for variables and functions in classes are named `CLASS.VARIABLE'
     and `CLASS.FUNCTION'.

   * In LaTeX text, the argument of any of the commands `\chapter',
     `\section', `\subsection', `\subsubsection', `\eqno', `\label',
     `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry',
     `\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.  When using
     the `--members' option, vars are tags too.

   * 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

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

   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 in `/dev', 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

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

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

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

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

33.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: Emerge,  Prev: Tags,  Up: Maintaining

33.4 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::   Misc.


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

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

33.4.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'.

   Use the command `s a' (`emerge-auto-advance-mode') to set or clear
Auto Advance mode.  Use `s s' (`emerge-skip-prefers-mode') to set or
clear Skip Prefers mode.  These commands turn on the mode with a
positive argument, turns it off with a negative or zero argument, and
toggle the mode with no argument.


File: emacs,  Node: State of Difference,  Next: Merge Commands,  Prev: Submodes of Emerge,  Up: Emerge

33.4.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 which you haven't ever selected and for which no
     alternative is preferred.  If you are moving through the merge
     sequentially, the differences you haven't selected are those
     following the selected one.  Thus, while moving sequentially, you
     can effectively make the A version the default for some sections
     of the merge buffer and the B version the default for others by
     using `d a' and `d b' between sections.

prefer-A
prefer-B
     The difference is showing the A or B state because it is
     "preferred".  This means that you haven't made an explicit choice,
     but one alternative seems likely to be right because the other
     alternative agrees with the common ancestor.  Thus, where the A
     buffer agrees with the common ancestor, the B version is
     preferred, because chances are it is the one that was actually
     changed.

     These two states are displayed in the mode line as `A*' and `B*'.

combined
     The difference is showing a combination of the A and B states, as a
     result of the `x c' or `x C' commands.

     Once a difference is in this state, the `a' and `b' commands don't
     do anything to it unless you give them a numeric argument.

     The mode line displays this state as `comb'.


File: emacs,  Node: Merge Commands,  Next: Exiting Emerge,  Prev: State of Difference,  Up: Emerge

33.4.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.  You can use this command
     in the merge buffer or in the A or B buffer.

`q'
     Quit--finish the merge.

`C-]'
     Abort--exit merging and do not save the output.

`f'
     Go into Fast mode.  (In Edit mode, this is actually `C-c C-c f'.)

`e'
     Go into Edit mode.

`l'
     Recenter (like `C-l') all three windows.

`-'
     Specify part of a prefix numeric argument.

`DIGIT'
     Also specify part of a prefix numeric argument.

`d a'
     Choose the A version as the default from here down in the merge
     buffer.

`d b'
     Choose the B version as the default from here down in the merge
     buffer.

`c a'
     Copy the A version of this difference into the kill ring.

`c b'
     Copy the B version of this difference into the kill ring.

`i a'
     Insert the A version of this difference at point.

`i b'
     Insert the B version of this difference at point.

`m'
     Put point and mark around the difference.

`^'
     Scroll all three windows down (like `M-v').

`v'
     Scroll all three windows up (like `C-v').

`<'
     Scroll all three windows left (like `C-x <').

`>'
     Scroll all three windows right (like `C-x >').

`|'
     Reset horizontal scroll on all three windows.

`x 1'
     Shrink the merge window to one line.  (Use `C-u l' to restore it
     to full size.)

`x c'
     Combine the two versions of this difference (*note Combining in
     Emerge::).

`x f'
     Show the names of the files/buffers Emerge is operating on, in a
     Help window.  (Use `C-u l' to restore windows.)

`x j'
     Join this difference with the following one.  (`C-u x j' joins
     this difference with the previous one.)

`x s'
     Split this difference into two differences.  Before you use this
     command, position point in each of the three buffers at the place
     where you want to split the difference.

`x t'
     Trim identical lines off the top and bottom of the difference.
     Such lines occur when the A and B versions are identical but
     differ from the ancestor version.


File: emacs,  Node: Exiting Emerge,  Next: Combining in Emerge,  Prev: Merge Commands,  Up: Emerge

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

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

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

34 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

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

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

34.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 first runs the hook `pre-abbrev-expand-hook'
(*note Hooks::).


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

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

34.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 the `.emacs' file.  If
either of these functions is called with `nil' as the argument, it uses
the file name specified in the variable `abbrev-file-name', which is by
default `"~/.abbrev_defs"'.  That file is your standard abbrev
definition file, and Emacs loads abbrevs from it automatically when it
starts up.

   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

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

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

35 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 edit-picture' 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.  `M-x edit-picture' 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

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

35.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 <PAGEUP>'
     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 <PAGEDOWN>'
     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

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

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

36 Sending Mail
***************

To send a message in Emacs, you start by typing a command (`C-x m') to
select and initialize the `*mail*' buffer.  Then you edit the text and
headers of the message in this buffer, and type another command (`C-c
C-s' or `C-c C-c') to send the message.

`C-x m'
     Begin composing a message to send (`compose-mail').

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

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

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

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

   The command `C-x m' (`compose-mail') selects a buffer named `*mail*'
and initializes it with the skeleton of an outgoing message.  `C-x 4 m'
(`compose-mail-other-window') selects the `*mail*' buffer in a
different window, leaving the previous current buffer visible.  `C-x 5
m' (`compose-mail-other-frame') creates a new frame to select the
`*mail*' buffer.

   Because the mail-composition 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 use the `C-x m' command again
when you have been composing another message but have not sent it, you
are asked to confirm before the old message is erased.  If you answer
`n', the `*mail*' buffer remains selected 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 are composing a message in the `*mail*' buffer and want to
send another message before finishing the first, rename the `*mail*'
buffer using `M-x rename-uniquely' (*note Misc Buffer::).  Then you can
use `C-x m' or its variants described above to make a new `*mail*'
buffer.  Once you've done that, you can work with each mail buffer
independently.

   The variable `mail-default-directory' controls the default directory
for mail buffers, and also says where to put their auto-save files.

* Menu:

* Format: Mail Format.	     Format of the mail being composed.
* Headers: Mail Headers.     Details of permitted mail header fields.
* Aliases: Mail Aliases.     Abbreviating and grouping mail addresses.
* Mode: Mail Mode.	     Special commands for editing mail being composed.
* 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

36.1 The Format of the Mail Buffer
==================================

In addition to the "text" or "body", a message has "header fields"
which say who sent it, when, to whom, why, and so on.  Some header
fields, such as `Date' and `Sender', are created automatically when you
send the message.  Others, such as the recipient names, must be
specified by you in order to send the message properly.

   In the mail buffer, you can insert and edit header fields using
ordinary editing commands.  Mail mode provides a commands to help you
edit some header fields, and some are preinitialized in the buffer
automatically when appropriate.

   The line in the buffer that says

     --text follows this line--

is a special delimiter that separates the headers you have specified
from the text.  Whatever follows this line is the text of the message;
the headers precede it.  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@gnu.org
     CC: lungfish@spam.org, byob@spam.org
     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

36.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 fields commonly used in outgoing messages.

`To'
     This field contains the mailing addresses to which the message is
     addressed.  If you list more than one address, use commas, not
     spaces, to separate them.

`Subject'
     The contents of the `Subject' field should be a piece of text that
     says what the message is about.  The reason `Subject' fields are
     useful is that most mail-reading programs can provide a summary of
     messages, listing the subject of each message but not its text.

`CC'
     This field contains additional mailing addresses to send the
     message to, like `To' except that these readers should not regard
     the message as directed at them.

`BCC'
     This field contains additional mailing addresses to send the
     message to, which should not appear in the header of the message
     actually sent.  Copies sent this way are called "blind carbon
     copies".

     To send a blind carbon copy of every outgoing message to yourself,
     set the variable `mail-self-blind' to `t'.  To send a blind carbon
     copy of every message to some other ADDRESS, set the variable
     `mail-default-headers' to `"Bcc: ADDRESS\n"'.

`FCC'
     This field contains the name of one file and directs Emacs to
     append a copy of the message to that file when you send the
     message.  If the file is in Rmail format, Emacs writes the message
     in Rmail format; otherwise, Emacs writes the message in system
     mail file format.  To specify more than one file, use several
     `FCC' fields, with one file name in each field.

     To put a fixed file name in the `FCC' field each time you start
     editing an outgoing message, set the variable
     `mail-archive-file-name' to that file name.  Unless you remove the
     `FCC' field before sending, the message will be written into that
     file when it is sent.

`From'
     Use the `From' field to say who you are, when the account you are
     using to send the mail is not your own.  The contents of the `From'
     field should be a valid mailing address, since replies will
     normally go there.  If you don't specify the `From' field
     yourself, Emacs uses the value of `user-mail-address' as the
     default.

`Reply-to'
     Use this field to direct replies to a different address.  Most
     mail-reading programs (including Rmail) automatically send replies
     to the `Reply-to' address in preference to the `From' address.  By
     adding a `Reply-to' field to your header, you can work around any
     problems your `From' address may cause for replies.

     To put a fixed `Reply-to' address into every outgoing message, set
     the variable `mail-default-reply-to' to that address (as a string).
     Then `mail' initializes the message with a `Reply-to' field as
     specified.  You can delete or alter that header field before you
     send the message, if you wish.  When Emacs starts up, if the
     environment variable `REPLYTO' is set, `mail-default-reply-to' is
     initialized from that environment variable.

`In-reply-to'
     This field contains 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 this field is filled
     in by Rmail when you reply to a message in Rmail, and you never
     need to think about it (*note Rmail::).

`References'
     This field lists the message IDs of related previous messages.
     Rmail sets up this field automatically when you reply to a message.

   The `To', `CC', and `BCC' header 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@here.net, this@there.net,
       me@gnu.cambridge.mass.usa.earth.spiral3281

   When you send the message, if you didn't write a `From' field
yourself, Emacs puts in one for you.  The variable `mail-from-style'
controls the format:

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

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

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

`system-default'
     Allow the system to insert the `From' field.

   You can direct Emacs to insert certain default headers into the
outgoing message by setting the variable `mail-default-headers' to a
string.  Then `C-x m' inserts this string into the message headers.  If
the default header fields are not appropriate for a particular message,
edit them as appropriate before sending the message.


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

36.3 Mail Aliases
=================

You can define "mail aliases" in a file named `~/.mailrc'.  These are
short mnemonic names which stand for mail addresses or groups of mail
addresses.  Like many other mail programs, Emacs expands aliases when
they occur in the `To', `From', `CC', `BCC', and `Reply-to' fields,
plus their `Resent-' variants.

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

     alias SHORTADDRESS FULLADDRESSES

Here FULLADDRESSES stands for one or more mail addresses for
SHORTADDRESS to expand into.  Separate multiple addresses with spaces;
if an address contains a space, quote the whole address with a pair of
double-quotes.

   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

Addresses specified in this way should use doublequotes around an
entire address when the address contains spaces.  But you need not
include doublequotes around parts of the address, such as the person's
full name.  Emacs puts them in if they are needed.  For example,

     alias chief-torturer "George W. Bush <bush@whitehouse.gov>"

is correct in `.mailrc'.  Emacs will insert the address as `"George W.
Bush" <bush@whitehouse.gov>'.

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

     source FILENAME

The file `~/.mailrc' is used primarily by other mail-reading programs;
it can contain various other commands.  Emacs ignores everything in it
except for alias definitions and include commands.

   Another way to define a mail alias, within Emacs alone, is with the
`define-mail-alias' command.  It prompts for the alias and then the
full address.  You can use it to define aliases in your `.emacs' file,
like this:

     (define-mail-alias "maingnu" "gnu@gnu.org")

   `define-mail-alias' records aliases by adding them to a variable
named `mail-aliases'.  If you are comfortable with manipulating Lisp
lists, you can set `mail-aliases' directly.  The initial value of
`mail-aliases' is `t', which means that Emacs should read `.mailrc' to
get the proper value.

   You can specify a different file name to use instead of `~/.mailrc'
by setting the variable `mail-personal-alias-file'.

   Normally, Emacs expands aliases when you send the message.  You do
not need to expand mail aliases before sending the message, but you can
expand them if you want to see where the mail will actually go.  To do
this, use the command `M-x expand-mail-aliases'; it expands all mail
aliases currently present in the mail headers that hold addresses.

   If you like, you can have mail aliases expand as abbrevs, as soon as
you type them in (*note Abbrevs::).  To enable this feature, execute the
following:

     (add-hook 'mail-mode-hook 'mail-abbrevs-setup)

This can go in your `.emacs' file.  *Note Hooks::.  If you use this
feature, you must use `define-mail-abbrev' instead of
`define-mail-alias'; the latter does not work with this package.  Note
that the mail abbreviation package uses the variable `mail-abbrevs'
instead of `mail-aliases', and that all alias names are converted to
lower case.

   The mail abbreviation package also provides the `C-c C-a'
(`mail-interactive-insert-alias') command, which reads an alias name
(with completion) and inserts its definition at point.  This is useful
when editing the message text itself or a header field such as
`Subject' in which Emacs does not normally expand aliases.

   Note that abbrevs expand only if you insert a word-separator
character afterward.  However, you can rebind `C-n' and `M->' to cause
expansion as well.  Here's how to do that:

     (add-hook 'mail-mode-hook
         (lambda ()
           (define-key
             mail-mode-map [remap next-line] 'mail-abbrev-next-line)
           (define-key
             mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer)))


File: emacs,  Node: Mail Mode,  Next: Mail Amusements,  Prev: Mail Aliases,  Up: Sending Mail

36.4 Mail Mode
==============

The major mode used in the mail buffer is Mail mode, which is much like
Text mode except that various special commands are provided on the
`C-c' prefix.  These commands all have to do specifically with editing
or sending the message.  In addition, Mail mode defines the character
`%' as a word separator; this is helpful for using the word commands to
edit mail addresses.

   Mail mode is normally used in buffers set up automatically by the
`mail' command and related commands.  However, you can also switch to
Mail mode in a file-visiting buffer.  This is a useful thing to do if
you have saved the text of a draft message in a file.

* Menu:

* Mail Sending::        Commands to send the message.
* Header Editing::      Commands to move to header fields and edit them.
* Citing Mail::         Copying all or part of a message you are replying to.
* Mail Mode Misc::      Spell checking, signatures, etc.


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

36.4.1 Mail Sending
-------------------

Mail mode has two commands for sending the message you have been
editing:

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

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

   `C-c C-s' (`mail-send') sends the message and marks the mail buffer
unmodified, but leaves that buffer selected so that you can modify the
message (perhaps with new recipients) and send it again.  `C-c C-c'
(`mail-send-and-exit') sends and then deletes the window or switches to
another buffer.  It puts the mail buffer at the lowest priority for
reselection by default, since you are finished with using it.  This is
the usual way to send the message.

   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 that contains 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.  It should be set to a function.  The default is
`sendmail-send-it', which delivers mail using the Sendmail installation
on the local host.  To send mail through a SMTP server, set it to
`smtpmail-send-it' and set up the Emacs SMTP library (*note Emacs SMTP
Library: (smtpmail)Top.).  A third option is `feedmail-send-it', see
the commentary section of the `feedmail.el' package for more
information.


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

36.4.2 Mail Header Editing
--------------------------

Mail mode provides 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 field, creating one if there is none
     (`mail-to').

`C-c C-f C-s'
     Move to the `Subject' header field, creating one if there is none
     (`mail-subject').

`C-c C-f C-c'
     Move to the `CC' header field, creating one if there is none
     (`mail-cc').

`C-c C-f C-b'
     Move to the `BCC' header field, creating one if there is none
     (`mail-bcc').

`C-c C-f C-f'
     Move to the `FCC' header field, creating one if there is none
     (`mail-fcc').

`M-<TAB>'
     Complete a mailing address (`mail-complete').

   There are five commands to move point to particular header fields,
all based on the prefix `C-c C-f' (`C-f' is for "field").  They are
listed in the table above.  If the field in question does not exist,
these commands create one.  We provide special motion commands for these
particular fields because they are the fields users most often want to
edit.

   While editing a header field that contains mailing addresses, such
as `To:', `CC:' and `BCC:', you can complete a mailing address by
typing `M-<TAB>' (`mail-complete').  It inserts the full name
corresponding to the address, if it can determine the full name.  The
variable `mail-complete-style' controls whether to insert the full
name, and what style to use, as in `mail-from-style' (*note Mail
Headers::).  (If your window manager defines `M-<TAB>' to switch
windows, you can type `<ESC> <TAB>' or `C-M-i'.)

   For completion purposes, the valid mailing addresses are taken to be
the local users' names plus your personal mail aliases.  You can
specify additional sources of valid addresses; see the customization
group `mailalias' to see the variables for customizing this feature
(*note Customization Groups::).

   If you type `M-<TAB>' in the body of the message, `mail-complete'
invokes `ispell-complete-word', as in Text mode.


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

36.4.3 Citing Mail
------------------

Mail mode also has commands for yanking or "citing" all or part of a
message that you are replying to.  These commands are active only when
you started sending a message using an Rmail command.

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

`C-c C-r'
     Yank the region from the Rmail buffer (`mail-yank-region').

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

   When mail sending is invoked from the Rmail mail reader using an
Rmail command, `C-c C-y' can be used inside the mail buffer to insert
the text of the message you are replying to.  Normally it indents each
line of that message three spaces and eliminates most header fields.  A
numeric argument specifies the number of spaces to indent.  An argument
of just `C-u' says not to indent at all and not to eliminate anything.
`C-c C-y' always uses the current message from the Rmail buffer, so you
can insert several old messages by selecting one in Rmail, switching to
`*mail*' and yanking it, then switching back to Rmail to select another.

   You can specify the text for `C-c C-y' to insert at the beginning of
each line: set `mail-yank-prefix' to the desired string.  (A value of
`nil' means to use indentation; this is the default.)  However, `C-u
C-c C-y' never adds anything at the beginning of the inserted lines,
regardless of the value of `mail-yank-prefix'.

   To yank just a part of an incoming message, set the region in Rmail
to the part you want; then go to the `*Mail*' message and type `C-c
C-r' (`mail-yank-region').  Each line that is copied is indented or
prefixed according to `mail-yank-prefix'.

   After using `C-c C-y' or `C-c C-r', you can type `C-c C-q'
(`mail-fill-yanked-message') to fill the paragraphs of the yanked old
message or messages.  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::.


File: emacs,  Node: Mail Mode Misc,  Prev: Citing Mail,  Up: Mail Mode

36.4.4 Mail Mode Miscellany
---------------------------

`C-c C-t'
     Move to the beginning of the message body text (`mail-text').

`C-c C-w'
     Insert the file `~/.signature' at the end of the message text
     (`mail-signature').

`C-c C-i FILE <RET>'
     Insert the contents of FILE at the end of the outgoing message
     (`mail-attach-file').

`M-x ispell-message'
     Perform spelling correction on the message text, but not on
     citations from other messages.

   `C-c C-t' (`mail-text') moves point to just after the header
separator line--that is, to the beginning of the message body text.

   `C-c C-w' (`mail-signature') adds a standard piece of text at the
end of the message to say more about who you are.  The text comes from
the file `~/.signature' in your home directory.  To insert your
signature automatically, set the variable `mail-signature' to `t';
after that, starting a mail message automatically inserts the contents
of your `~/.signature' file.  If you want to omit your signature from a
particular message, delete it from the buffer before you send the
message.

   You can also set `mail-signature' to a string; then that string is
inserted automatically as your signature when you start editing a
message to send.  If you set it to some other Lisp expression, the
expression is evaluated each time, and its value (which should be a
string) specifies the signature.

   You can do spelling correction on the message text you have written
with the command `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::.

   To include a file in the outgoing message, you can use `C-x i', the
usual command to insert a file in the current buffer.  But it is often
more convenient to use a special command, `C-c C-i'
(`mail-attach-file').  This command inserts the file contents at the
end of the buffer, after your signature if any, with a delimiter line
that includes the file name.  Note that this is not a MIME attachment.

   Turning on Mail mode (which `C-x m' does automatically) runs the
normal hooks `text-mode-hook' and `mail-mode-hook'.  Initializing a new
outgoing message runs the normal hook `mail-setup-hook'; if you want to
add special fields to your mail header or make other changes to the
appearance of the mail buffer, use that hook.  *Note Hooks::.

   The main difference between these hooks is just when they are
invoked.  Whenever you type `M-x mail', `mail-mode-hook' runs as soon
as the `*mail*' buffer is created.  Then the `mail-setup' function
inserts the default contents of the buffer.  After these default
contents are inserted, `mail-setup-hook' runs.


File: emacs,  Node: Mail Amusements,  Next: Mail Methods,  Prev: Mail Mode,  Up: Sending Mail

36.5 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) snoops
on all electronic mail messages that contain keywords suggesting they
might find them interesting.  (The NSA says 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 NSA will get so busy with spurious input
that they will have to give up reading it all.

   Here's how to insert spook keywords automatically whenever you start
entering an outgoing message:

     (add-hook 'mail-setup-hook 'spook)

   Whether or not this confuses the NSA, it at least amuses 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)

   ---------- Footnotes ----------

   (1) The US National Security Agency.


File: emacs,  Node: Mail Methods,  Prev: Mail Amusements,  Up: Sending Mail

36.6 Mail-Composition Methods
=============================

In this chapter we have described the usual Emacs mode for editing and
sending mail--Mail mode.  Emacs has alternative facilities for editing
and sending mail, including MH-E and Message mode, not documented in
this manual.  *Note MH-E: (mh-e)Top.  *Note Message: (message)Top.  You
can choose any of them as your preferred method.  The commands `C-x m',
`C-x 4 m' and `C-x 5 m' use whichever agent you have specified, as do
various other Emacs commands and facilities that send mail.

   To specify your mail-composition method, customize the variable
`mail-user-agent'.  Currently legitimate values include
`sendmail-user-agent' (Mail mode), `mh-e-user-agent',
`message-user-agent' and `gnus-user-agent'.

   If you select a different mail-composition method, the information
in this chapter about the `*mail*' buffer and Mail mode does not apply;
the other methods use a different format of text in a different buffer,
and their commands are different as well.


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

37 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 which
use a special format.  Reading the message 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 message 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.
* Out of Rmail::	     Converting an Rmail file to mailbox format.
* 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

37.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 uses narrowing to hide all but one message in the Rmail file.
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.  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

37.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 to 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

37.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').

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

   It is also possible to search for a message based on labels.  *Note
Rmail Labels::.

   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

37.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.  Expunging is the
only action that changes the message number of any message, except for
undigestifying (*note Rmail Digest::).

`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 a 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 numeric argument is equivalent to
`C-d'.

   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

37.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, it is initialized from the `MAIL' environment
variable, or, as a last resort, set to `nil', which means to use the
default inbox.  The default inbox file depends on your operating
system; often it is `/var/mail/USERNAME', `/usr/spool/mail/USERNAME', or
`/usr/mail/USERNAME'.

   You can specify the inbox file(s) for any Rmail file 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 written to use Babyl format as its internal format.  Since
then, we have recognized that the usual inbox format on Unix and GNU
systems is adequate for the job, and we plan to change Rmail to use that
as its internal format.  However, the Rmail file will still be separate
from the inbox file, even when 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'.  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 Babyl 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

37.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 Rmail file.
If it is not, Rmail tries to decompose it into a stream of messages in
various known formats.  If it succeeds, it converts the whole file to an
Rmail 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).  These variables also apply to choosing a file for
output (*note Rmail Output::).

   Each Rmail file can contain a list of inbox file names; you can
specify this list with `M-x set-rmail-inbox-list <RET> FILES <RET>'.
The argument can contain any number of file names, separated by commas.
It can also be empty, which specifies that this file should have no
inboxes.  Once you specify a list of inboxes in an Rmail file, the
Rmail file remembers it permanently until you specify a different list.

   As a special exception, if your primary Rmail file does not specify
any inbox files, it uses 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

37.7 Copying Messages Out to Files
==================================

These commands copy messages from an Rmail file into another file.

`o FILE <RET>'
     Append a copy of the current message to the file FILE, using Rmail
     file format by default (`rmail-output-to-rmail-file').

`C-o FILE <RET>'
     Append a copy of the current message to the file FILE, using
     system inbox file format by default (`rmail-output').

`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.  This file may be an Rmail file or it may be in system inbox
format; the output commands ascertain the file's format and write the
copied message in that format.

   The `o' and `C-o' commands differ in two ways: each has its own
separate default file name, and each specifies a choice of format to
use when the file does not already exist.  The `o' command uses Rmail
format when it creates a new file, while `C-o' uses system inbox format
for a new file.  The default file name for `o' is the file name used
last with `o', and the default file name for `C-o' is the file name
used last with `C-o'.

   If the output file is an Rmail file currently visited in an Emacs
buffer, the output commands copy the message into 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).

   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.  `w' gives it the `stored' attribute.
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 the original afterward if you wish.)

   Copying messages into files in system inbox format uses the header
fields that are displayed in Rmail at the time.  Thus, if you use the
`t' command to view the entire header and then copy the message, the
entire header is copied.  *Note Rmail Display::.

   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

37.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 two ways to use the labels: in moving and in summaries.

   The command `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.


File: emacs,  Node: Rmail Attributes,  Next: Rmail Reply,  Prev: Rmail Labels,  Up: Rmail

37.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::).

`stored'
     Assigned by the `w' file output command (*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::.

   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

37.10 Sending Replies
=====================

Rmail has several commands that use Mail mode to send outgoing mail.
*Note Sending Mail::, for information on using Mail mode, including
certain features meant to work with Rmail.  What this section documents
are the special commands of Rmail for entering Mail mode.  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 placed automatically in
the `CC', using the variable `rmail-dont-reply-to-names'.  Its value
should be a regular expression (as a string); any recipient that the
regular expression matches, is excluded from the `CC' field.  The
default value matches your own name, 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 the commands of Mail mode (*note Mail Mode::), including `C-c C-y'
which yanks in the message that you are replying to.  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 is programmed
to invoke `rmail-resend' if you provide a numeric argument.)

   The `m' (`rmail-mail') command is used 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

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

37.11.1 Making Summaries
------------------------

Here are the commands to create a summary for the current Rmail file.
Once the Rmail file has a summary buffer, changes in the Rmail file
(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 have one or more of 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'
     Summarize messages whose headers and the subject line match the
     specified regular expression REGEXP (`rmail-summary-by-regexp').

   The `h' or `C-M-h' (`rmail-summary') command fills the summary buffer
for the current Rmail file with a summary of all the messages in the
file.  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 of the
recipients RCPTS.  RCPTS should contain mailing addresses separated by
commas.

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

   `C-M-s REGEXP <RET>' (`rmail-summary-by-regexp') makes a partial
summary which mentions only the messages whose headers (including the
date and the subject lines) match the regular expression REGEXP.

   Note that there is only one summary buffer for any Rmail file;
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.


File: emacs,  Node: Rmail Summary Edit,  Prev: Rmail Make Summary,  Up: Rmail Summary

37.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'.)
`o' and `C-o' output the current message to a file; `r' starts a reply
to it.  You can scroll the current message while remaining in the
summary buffer using <SPC> and <DEL>.

   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.

`p'
     Move to previous line, skipping lines saying `deleted', and select
     its message.

`M-n'
     Move to next line and select its message.

`M-p'
     Move to previous line and select its message.

`>'
     Move to the last line, and select its message.

`<'
     Move to the first line, and select its message.

`j'
`<RET>'
     Select the message on the current line (ensuring that the RMAIL
     buffer appears on the screen).  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.

   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.


File: emacs,  Node: Rmail Sorting,  Next: Rmail Display,  Prev: Rmail Summary,  Up: Rmail

37.12 Sorting the Rmail File
============================

`M-x rmail-sort-by-date'
     Sort messages of current Rmail file by date.

`M-x rmail-sort-by-subject'
     Sort messages of current Rmail file by subject.

`M-x rmail-sort-by-author'
     Sort messages of current Rmail file by author's name.

`M-x rmail-sort-by-recipient'
     Sort messages of current Rmail file by recipient's names.

`M-x rmail-sort-by-correspondent'
     Sort messages of current Rmail file by the name of the other
     correspondent.

`M-x rmail-sort-by-lines'
     Sort messages of current Rmail file by size (number of lines).

`M-x rmail-sort-by-keywords <RET> LABELS <RET>'
     Sort messages of current Rmail file 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 which 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 numeric 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.


File: emacs,  Node: Rmail Display,  Next: Rmail Coding,  Prev: Rmail Sorting,  Up: Rmail

37.13 Display of Messages
=========================

Rmail reformats the header of each message before displaying it for the
first time.  Reformatting hides uninteresting header fields to reduce
clutter.  You can use the `t' command to show the entire header or to
repeat the header reformatting operation.

`t'
     Toggle display of complete header (`rmail-toggle-header').

   Reformatting the header involves deleting most header fields, on the
grounds that they are not interesting.  The variable
`rmail-ignored-headers' holds a regular expression that specifies which
header fields to hide in this way--if it matches the beginning of a
header field, that whole field is hidden.  However, the variable
`rmail-nonignored-headers' provides a further override: a header
matching that regular expression is shown even if it matches
`rmail-ignored-headers' too.

   Rmail saves the complete original header before reformatting; to see
it, use the `t' command (`rmail-toggle-header').  This discards the
reformatted headers of the current message and displays it with the
original header.  Repeating `t' reformats the message again, which
shows only the interesting headers according to the current values of
those variable.  Selecting the message again also reformats it if
necessary.

   One consequence of this is that if you edit the reformatted header
(using `e'; *note Rmail Editing::), subsequent use of `t' will discard
your edits.  On the other hand, if you use `e' after `t', to edit the
original (unreformatted) header, those changes are permanent.

   When the `t' command has a prefix argument, a positive argument
means to show the reformatted header, and a zero or negative argument
means to show the full header.

   When the terminal supports multiple fonts or colors, Rmail
highlights certain header fields that are especially interesting--by
default, the `From' and `Subject' fields.  The variable
`rmail-highlighted-headers' holds a regular expression that specifies
the header fields to highlight; if it matches the beginning of a header
field, that whole field is highlighted.

   If you specify unusual colors for your text foreground and
background, the colors used for highlighting may not go well with them.
If so, specify different colors by setting the variable
`rmail-highlight-face' to a suitable face.  To turn off highlighting
entirely in Rmail, set `rmail-highlighted-headers' to `nil'.

   You can highlight and activate URLs in incoming messages by adding
the function `goto-address' to the hook `rmail-show-message-hook'.
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.


File: emacs,  Node: Rmail Coding,  Next: Rmail Editing,  Prev: Rmail Display,  Up: Rmail

37.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, encodes the message body using whichever
coding system was used to decode it before, then redecodes it using the
coding system you specified.  If you specified the right coding system,
the result should be readable.

   Decoding and encoding using the wrong coding system is lossless for
most encodings, in particular with 8-bit encodings such as iso-8859 or
koi8.  So, if the initial attempt to redecode the message didn't result
in a legible text, you can try other coding systems until you succeed.

   With some coding systems, notably those from the iso-2022 family,
information can be lost in decoding, so that encoding the message again
won't bring back the original incoming text.  In such a case,
`rmail-redecode-body' cannot work.  However, the problems that call for
use of `rmail-redecode-body' rarely occur with those coding systems.
So in practice the command works when you need it.


File: emacs,  Node: Rmail Editing,  Next: Rmail Digest,  Prev: Rmail Coding,  Up: Rmail

37.15 Editing Within a Message
==============================

Most of the usual Emacs commands 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.  When you are finished editing the message
and are ready to go back to Rmail, type `C-c C-c', which switches back
to Rmail mode.  Alternatively, you can return to Rmail mode but cancel
all the 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::).  It adds the
attribute `edited' to the message.  It also displays the full headers
of the message, so that you can edit the headers as well as the body of
the message, and your changes in the headers will be permanent.


File: emacs,  Node: Rmail Digest,  Next: Out of Rmail,  Prev: Rmail Editing,  Up: Rmail

37.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: Out of Rmail,  Next: Rmail Rot13,  Prev: Rmail Digest,  Up: Rmail

37.17 Converting an Rmail File to Inbox Format
==============================================

The command `M-x unrmail' converts a file in Rmail format to inbox
format (also known as the system mailbox, or mbox, format), so that you
can use it with other mail-editing tools.  You must specify two
arguments, the name of the Rmail file and the name to use for the
converted file.  `M-x unrmail' does not alter the Rmail file itself.

   `M-x unrmail' is useful if you can run Emacs on the machine where
the Rmail file resides, or can access the Rmail file remotely (*note
Remote Files::) from a machine where Emacs is installed.  If accessing
Rmail files from Emacs is impossible, you can use the `b2m' program
instead.  `b2m' is part of the Emacs distribution, it is installed into
the same directory where all the other auxiliary programs (`etags'
etc.) are installed, and its source is available in the Emacs source
distribution, so that you could copy the source to the target machine
and compile it there.

   To convert a file `BABYL-FILE' into `MBOX-FILE', invoke `b2m' like
this:

      b2m < BABYL-FILE > MBOX-FILE


File: emacs,  Node: Rmail Rot13,  Next: Movemail,  Prev: Out of Rmail,  Up: Rmail

37.18 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

37.19 `movemail' program
========================

When invoked for the first time, Rmail attempts to locate the
`movemail' program and determine its version.  There are two versions
of `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 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 retrieve remote mail using POP3 or IMAP4 protocol,
and can retrieve mail from them using a TLS encrypted channel.  It also
accepts mailbox argument in the 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

37.20 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.  The `Emacs movemail' can
work with POP if you compile it with the macro `MAIL_USE_POP' defined.
(You can achieve that by specifying `--with-pop' when you run
`configure' during the installation of Emacs.)

   The Mailutils `movemail' by default supports POP, unless it was
configured with `--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 POP
inbox by using 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'.
This is especially useful if you have several remote mailboxes with
different passwords.

   For backward compatibility, Rmail also supports two alternative ways
of specifying remote POP mailboxes.  First, specifying an inbox name in
the form `po:USERNAME:HOSTNAME' is equivalent to
`pop://USERNAME@HOSTNAME'.  Alternatively, you may set a "file name" of
`po:USERNAME' in the inbox list of an Rmail file.  `movemail' will
handle such a name by opening a connection to the POP server.  In this
case, 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 the PASSWORD is present in mailbox URL (see above), it is used.

  2. If the variable `rmail-remote-password' is non-`nil', its value is
     used.

  3. Otherwise, if `rmail-remote-password-required' is non-`nil', then
     Rmail will ask you for the password to use.

  4. Otherwise, Rmail assumes no password is required.

   For compatibility with previous versions, the variables
`rmail-pop-password' and `rmail-pop-password-required' may be used
instead of `rmail-remote-password' and `rmail-remote-password-required'.

   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.  If it is supported, it is used by default whenever you
attempt to retrieve POP mail when `rmail-pop-password' and
`rmail-pop-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

37.21 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

38 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 files listed.

   The Dired buffer is "read-only," and inserting text in it is not
useful, so 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 on
command.

   The Dired-X package provides various extra features for Dired mode.
*Note Dired-X: (dired-x)Top.

* 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

38.1 Entering Dired
===================

To invoke Dired, do `C-x d' or `M-x dired'.  The command reads a
directory name or wildcard file name pattern as a minibuffer argument
to specify the files to list.  `C-x C-f' given a directory name also
invokes Dired.  Where `dired' differs from `list-directory' is that it
puts the buffer into Dired mode, so that the special commands of Dired
are available.

   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 numeric 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

38.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 often useful simply for moving up.

   `j' (`dired-goto-file') moves point to the line that describes a
specified file or directory.

   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

38.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 is also known as "expunging".)  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.


File: emacs,  Node: Flagging Many Files,  Next: Dired Visiting,  Prev: Dired Deletion,  Up: Dired

38.4 Flagging Many Files at Once
================================

`#'
     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::).

`&'
     Flag for deletion all files with certain kinds of names which
     suggest you could easily create those files again.

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

`% d REGEXP <RET>'
     Flag for deletion all files whose names match the regular
     expression REGEXP.

   The `#', `~', `&', and `.' commands flag many files for deletion,
based on their file names.  These commands are useful precisely because
they do not themselves delete any files; you can remove the deletion
flags from any flagged files that you really wish 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'.

   `#' (`dired-flag-auto-save-files') flags for deletion 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 for deletion 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 `dired-kept-versions' (*not*
`kept-new-versions'; that applies only when saving) specifies the
number of newest versions of each file to keep, and `kept-old-versions'
specifies the number of oldest versions to keep.

   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.

   The `% d' command 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

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

38.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 expunges 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.


File: emacs,  Node: Operating on Files,  Next: Shell Commands in Dired,  Prev: Marks vs Flags,  Up: Dired

38.7 Operating on Files
=======================

This section describes the basic Dired commands to operate on one file
or several files.  All of these commands are capital letters; all of
them use the minibuffer, either to read an argument or to ask for
confirmation, before they act.  All of them let you specify the files
to manipulate in these ways:

   * If you give the command a numeric prefix argument N, it operates
     on the next N files, starting with the current file.  (If N is
     negative, the command operates on the -N files preceding the
     current line.)

   * Otherwise, if some files are marked with `*', the command operates
     on all those files.

   * Otherwise, the command operates on the current file only.

Certain other Dired commands, such as `!' and the `%' commands, use the
same conventions to decide which files to work on.

   Commands which ask for a destination directory, such as those which
copy and rename files or create links for them, try to guess the default
target directory for the operation.  Normally, they suggest the Dired
buffer's default directory, but if the variable `dired-dwim-target' is
non-`nil', and if there is another Dired buffer displayed in the next
window, that other buffer's directory is suggested instead.

   Here are the file-manipulating Dired commands that operate on files.

`C NEW <RET>'
     Copy the specified files (`dired-do-copy').  The argument NEW is
     the directory to copy into, or (if copying a single file) the new
     name.  This is like the shell command `cp'.

     If `dired-copy-preserve-time' is non-`nil', then copying with this
     command preserves the modification time of the old file in the
     copy, like `cp -p'.

     The variable `dired-recursive-copies' controls whether to copy
     directories recursively (like `cp -r').  The default is `nil',
     which means that directories cannot be copied.

`D'
     Delete the specified files (`dired-do-delete').  This is like the
     shell command `rm'.

     Like the other commands in this section, this command operates on
     the _marked_ files, or the next N files.  By contrast, `x'
     (`dired-do-flagged-delete') deletes all "flagged" files.

`R NEW <RET>'
     Rename the specified files (`dired-do-rename').  If you rename a
     single file, the argument NEW is the new name of the file.  If you
     rename several files, the argument NEW is the directory into which
     to move the files (this is like the shell command `mv').

     Dired automatically changes the visited file name of buffers
     associated with renamed files so that they refer to the new names.

`H NEW <RET>'
     Make hard links to the specified files (`dired-do-hardlink').
     This is like the shell command `ln'.  The argument NEW is the
     directory to make the links in, or (if making just one link) the
     name to give the link.

`S NEW <RET>'
     Make symbolic links to the specified files (`dired-do-symlink').
     This is like `ln -s'.  The argument NEW is the directory to make
     the links in, or (if making just one link) the name to give the
     link.

`M MODESPEC <RET>'
     Change the mode (also called "permission bits") of the specified
     files (`dired-do-chmod').  This uses the `chmod' program, so
     MODESPEC can be any argument that `chmod' can handle.

`G NEWGROUP <RET>'
     Change the group of the specified files to NEWGROUP
     (`dired-do-chgrp').

`O NEWOWNER <RET>'
     Change the owner of the specified files to NEWOWNER
     (`dired-do-chown').  (On most systems, only the superuser can do
     this.)

     The variable `dired-chown-program' specifies the name of the
     program to use to do the work (different systems put `chown' in
     different places).

`T TIMESTAMP <RET>'
     Touch the specified files (`dired-do-touch').  This means updating
     their modification times to the present time.  This is like the
     shell command `touch'.

`P COMMAND <RET>'
     Print the specified files (`dired-do-print').  You must specify the
     command to print them with, but the minibuffer starts out with a
     suitable guess made using the variables `lpr-command' and
     `lpr-switches' (the same variables that `lpr-buffer' uses; *note
     Printing::).

`Z'
     Compress the specified files (`dired-do-compress').  If the file
     appears to be a compressed file already, uncompress it instead.

`L'
     Load the specified Emacs Lisp files (`dired-do-load').  *Note Lisp
     Libraries::.

`B'
     Byte compile the specified Emacs Lisp files
     (`dired-do-byte-compile').  *Note Byte Compilation: (elisp)Byte
     Compilation.

`A REGEXP <RET>'
     Search all the specified files for the regular expression REGEXP
     (`dired-do-search').

     This command is a variant of `tags-search'.  The search stops at
     the first match it finds; use `M-,' to resume the search and find
     the next match.  *Note Tags Search::.

`Q REGEXP <RET> TO <RET>'
     Perform `query-replace-regexp' on each of the specified files,
     replacing matches for REGEXP with the string TO
     (`dired-do-query-replace-regexp').

     This command is a variant of `tags-query-replace'.  If you exit the
     query replace loop, you can use `M-,' to resume the scan and
     replace more matches.  *Note Tags Search::.


File: emacs,  Node: Shell Commands in Dired,  Next: Transforming File Names,  Prev: Operating on Files,  Up: Dired

38.8 Shell Commands in Dired
============================

The Dired command `!' (`dired-do-shell-command') reads a shell command
string in the minibuffer and runs that shell command on all the
specified files.  (`X' is a synonym for `!'.)  You can specify the
files to operate on in the usual ways for Dired commands (*note
Operating on Files::).

   The working directory for the shell command is the top-level
directory of the Dired buffer.

   There are two ways of applying a shell command to multiple files:

   * If you use `*' surrounded by whitespace in the shell command, then
     the command runs just once, with the list of file names
     substituted for the `*'.  The order of file names is the order of
     appearance in the Dired buffer.

     Thus, `! tar cf foo.tar * <RET>' runs `tar' on the entire list of
     file names, putting them into one tar file `foo.tar'.

     If you want to use `*' as a shell wildcard with whitespace around
     it, write `*""'.  In the shell, this is equivalent to `*'; but
     since the `*' is not surrounded by whitespace, Dired does not
     treat it specially.

   * If the command string doesn't contain `*' surrounded by
     whitespace, then it runs once _for each file_.  Normally the file
     name is added at the end.

     For example, `! uudecode <RET>' runs `uudecode' on each file.

   * However, if the command string contains `?' surrounded by
     whitespace, the current file name is substituted for `?' (rather
     than added at the end).  You can use `?' this way more than once
     in the command, and the same file name replaces each occurrence.

   To iterate over the file names in a more complicated fashion, use an
explicit shell loop.  For example, here is how to uuencode each file,
making the output file name by appending `.uu' to the input file name:

     for file in * ; do uuencode "$file" "$file" >"$file".uu; done

   The `!' command does not attempt to update the Dired buffer to show
new or modified files, because it doesn't understand shell commands,
and does not know what files the shell command changed.  Use the `g'
command to update the Dired buffer (*note Dired Updating::).


File: emacs,  Node: Transforming File Names,  Next: Comparison in Dired,  Prev: Shell Commands in Dired,  Up: Dired

38.9 Transforming File Names in Dired
=====================================

This section describes Dired commands which alter file names in a
systematic way.  Each command operates on some or all of the marked
files, using a new name made by transforming the existing name.

   Like the basic Dired file-manipulation commands (*note Operating on
Files::), the commands described here operate either on the next N
files, or on all files marked with `*', or on the current file.  (To
mark files, use the commands described in *note Marks vs Flags::.)

   All of the commands described in this section work _interactively_:
they ask you to confirm the operation for each candidate file.  Thus,
you can select more files than you actually need to operate on (e.g.,
with a regexp that matches many files), and then filter the selected
names by typing `y' or `n' when the command prompts for confirmation.

`% u'
     Rename each of the selected files to an upper-case name
     (`dired-upcase').  If the old file names are `Foo' and `bar', the
     new names are `FOO' and `BAR'.

`% l'
     Rename each of the selected files to a lower-case name
     (`dired-downcase').  If the old file names are `Foo' and `bar',
     the new names are `foo' and `bar'.

`% R FROM <RET> TO <RET>'
`% C FROM <RET> TO <RET>'
`% H FROM <RET> TO <RET>'
`% S FROM <RET> TO <RET>'
     These four commands rename, copy, make hard links and make soft
     links, in each case computing the new name by regular-expression
     substitution from the name of the old file.

   The four regular-expression substitution commands effectively
perform a search-and-replace on the selected file names.  They read two
arguments: a regular expression FROM, and a substitution pattern TO;
they match each "old" file name against FROM, and then replace the
matching part with TO.  You can use `\&' and `\DIGIT' in TO to refer to
all or part of what the pattern matched in the old file name, as in
`replace-regexp' (*note Regexp Replace::).  If the regular expression
matches more than once in a file name, only the first match is replaced.

   For example, `% R ^.*$ <RET> x-\& <RET>' renames each selected file
by prepending `x-' to its name.  The inverse of this, removing `x-'
from the front of each file name, is also possible: one method is `% R
^x-\(.*\)$ <RET> \1 <RET>'; another is `% R ^x- <RET> <RET>'.  (Use `^'
and `$' to anchor matches that should span the whole file name.)

   Normally, the replacement process does not consider the files'
directory names; it operates on the file name within the directory.  If
you specify a numeric argument of zero, then replacement affects the
entire absolute file name including directory name.  (A non-zero
argument specifies the number of files to operate on.)

   You may want to select the set of files to operate on using the same
regexp FROM that you will use to operate on them.  To do this, mark
those files with `% m FROM <RET>', then use the same regular expression
in the command to operate on the files.  To make this more convenient,
the `%' commands to operate on files use the last regular expression
specified in any `%' command as a default.


File: emacs,  Node: Comparison in Dired,  Next: Subdirectories in Dired,  Prev: Transforming File Names,  Up: Dired

38.10 File Comparison with Dired
================================

Here are two Dired commands that compare specified files using `diff'.
They show the output in a buffer using Diff mode (*note Comparing
Files::).

`='
     Compare the current file (the file at point) with another file (the
     file at the mark) using the `diff' program (`dired-diff').  The
     file at the mark is the first argument of `diff', and the file at
     point is the second argument.  This refers to the ordinary Emacs
     mark, not Dired marks; use `C-<SPC>' (`set-mark-command') to set
     the mark at the first file's line (*note Setting Mark::).

`M-='
     Compare the current file with its latest backup file
     (`dired-backup-diff').  If the current file is itself a backup,
     compare it with the file it is a backup of; this way, you can
     compare a file with any one of its backups.

     The backup file is the first file given to `diff'.


File: emacs,  Node: Subdirectories in Dired,  Next: Subdir Switches,  Prev: Comparison in Dired,  Up: Dired

38.11 Subdirectories in Dired
=============================

A Dired buffer displays just one directory in the normal case; but you
can optionally include its subdirectories as well.

   The simplest way to include multiple directories in one Dired buffer
is to specify the options `-lR' for running `ls'.  (If you give a
numeric argument when you run Dired, then you can specify these options
in the minibuffer.)  That produces a recursive directory listing showing
all subdirectories at all levels.

   More often, you will want to show only specific subdirectories.  You
can do this with the `i' command:

`i'
     Insert the contents of a subdirectory later in the buffer.

   Use the `i' (`dired-maybe-insert-subdir') command on a line that
describes a file which is a directory.  It inserts the contents of that
directory into the same Dired buffer, and moves there.  Inserted
subdirectory contents follow the top-level directory of the Dired
buffer, just as they do in `ls -lR' output.

   If the subdirectory's contents are already present in the buffer, the
`i' command just moves to it.

   In either case, `i' sets the Emacs mark before moving, so `C-u
C-<SPC>' takes you back to the old position in the buffer (the line
describing that subdirectory).

   Use the `l' command (`dired-do-redisplay') to update the
subdirectory's contents.  Use `C-u k' on the subdirectory header line
to delete the subdirectory.  *Note Dired Updating::.


File: emacs,  Node: Subdir Switches,  Next: Subdirectory Motion,  Prev: Subdirectories in Dired,  Up: Dired

38.12 Subdirectory Switches in Dired
====================================

You can insert subdirectories with specified `ls' switches in Dired
buffers, using `C-u i'.  You can change the `ls' switches of an already
inserted subdirectory using `C-u l'.

   In Emacs versions 22.1 and later, Dired remembers the switches, so
that reverting the buffer will not change them back to the main
directory's switches.  Deleting a subdirectory forgets about its
switches.

   Using `dired-undo' (usually bound to `C-_' and `C-x u') to reinsert
or delete subdirectories, that were inserted with explicit switches,
can bypass Dired's machinery for remembering (or forgetting) switches.
Deleting a subdirectory using `dired-undo' does not forget its
switches.  When later reinserted using `i', it will be reinserted using
its old switches.  Using `dired-undo' to reinsert a subdirectory that
was deleted using the regular Dired commands (not `dired-undo') will
originally insert it with its old switches.  However, reverting the
buffer will relist it using the buffer's default switches.  If any of
this yields problems, you can easily correct the situation using `C-u
i' or `C-u l'.

   Dired does not remember the `R' switch.  Inserting a subdirectory
with switches that include the `R' switch is equivalent with inserting
each of its subdirectories using all remaining switches.  For instance,
updating or killing a subdirectory that was inserted with the `R'
switch will not update or kill its subdirectories.

   The buffer's default switches do not affect subdirectories that were
inserted using explicitly specified switches.  In particular, commands
such as `s', that change the buffer's switches do not affect such
subdirectories.  (They do affect subdirectories without explicitly
assigned switches, however.)

   You can make Dired forget about all subdirectory switches and relist
all subdirectories with the buffer's default switches using `M-x
dired-reset-subdir-switches'.  This also reverts the Dired buffer.


File: emacs,  Node: Subdirectory Motion,  Next: Hiding Subdirectories,  Prev: Subdir Switches,  Up: Dired

38.13 Moving Over Subdirectories
================================

When a Dired buffer lists subdirectories, you can use the page motion
commands `C-x [' and `C-x ]' to move by entire directories (*note
Pages::).

   The following commands move across, up and down in the tree of
directories within one Dired buffer.  They move to "directory header
lines", which are the lines that give a directory's name, at the
beginning of the directory's contents.

`C-M-n'
     Go to next subdirectory header line, regardless of level
     (`dired-next-subdir').

`C-M-p'
     Go to previous subdirectory header line, regardless of level
     (`dired-prev-subdir').

`C-M-u'
     Go up to the parent directory's header line (`dired-tree-up').

`C-M-d'
     Go down in the directory tree, to the first subdirectory's header
     line (`dired-tree-down').

`<'
     Move up to the previous directory-file line (`dired-prev-dirline').
     These lines are the ones that describe a directory as a file in its
     parent directory.

`>'
     Move down to the next directory-file line (`dired-prev-dirline').


File: emacs,  Node: Hiding Subdirectories,  Next: Dired Updating,  Prev: Subdirectory Motion,  Up: Dired

38.14 Hiding Subdirectories
===========================

"Hiding" a subdirectory means to make it invisible, except for its
header line.

`$'
     Hide or reveal the subdirectory that point is in, and move point
     to the next subdirectory (`dired-hide-subdir').  A numeric
     argument serves as a repeat count.

`M-$'
     Hide all subdirectories in this Dired buffer, leaving only their
     header lines (`dired-hide-all').  Or, if any subdirectory is
     currently hidden, make all subdirectories visible again.  You can
     use this command to get an overview in very deep directory trees
     or to move quickly to subdirectories far away.

   Ordinary Dired commands never consider files inside a hidden
subdirectory.  For example, the commands to operate on marked files
ignore files in hidden directories even if they are marked.  Thus you
can use hiding to temporarily exclude subdirectories from operations
without having to remove the Dired marks on files in those
subdirectories.


File: emacs,  Node: Dired Updating,  Next: Dired and Find,  Prev: Hiding Subdirectories,  Up: Dired

38.15 Updating the Dired Buffer
===============================

This section describes commands to update the Dired buffer to reflect
outside (non-Dired) changes in the directories and files, and to delete
part of the Dired buffer.

`g'
     Update the entire contents of the Dired buffer (`revert-buffer').

`l'
     Update the specified files (`dired-do-redisplay').  You specify the
     files for `l' in the same way as for file operations.

`k'
     Delete the specified _file lines_--not the files, just the lines
     (`dired-do-kill-lines').

`s'
     Toggle between alphabetical order and date/time order
     (`dired-sort-toggle-or-edit').

`C-u s SWITCHES <RET>'
     Refresh the Dired buffer using SWITCHES as
     `dired-listing-switches'.

   Type `g' (`revert-buffer') to update the contents of the Dired
buffer, based on changes in the files and directories listed.  This
preserves all marks except for those on files that have vanished.
Hidden subdirectories are updated but remain hidden.

   To update only some of the files, type `l' (`dired-do-redisplay').
Like the Dired file-operating commands, this command operates on the
next N files (or previous -N files), or on the marked files if any, or
on the current file.  Updating the files means reading their current
status, then updating their lines in the buffer to indicate that status.

   If you use `l' on a subdirectory header line, it updates the
contents of the corresponding subdirectory.

   To delete the specified _file lines_ from the buffer--not delete the
files--type `k' (`dired-do-kill-lines').  Like the file-operating
commands, this command operates on the next N files, or on the marked
files if any; but it does not operate on the current file as a last
resort.

   If you use `k' with a numeric prefix argument to kill the line for a
file that is a directory, which you have inserted in the Dired buffer
as a subdirectory, it deletes that subdirectory from the buffer as
well.  Typing `C-u k' on the header line for a subdirectory also
deletes the subdirectory from the Dired buffer.

   The `g' command brings back any individual lines that you have
killed in this way, but not subdirectories--you must use `i' to
reinsert a subdirectory.

   The files in a Dired buffers are normally listed in alphabetical
order by file names.  Alternatively Dired can sort them by date/time.
The Dired command `s' (`dired-sort-toggle-or-edit') switches between
these two sorting modes.  The mode line in a Dired buffer indicates
which way it is currently sorted--by name, or by date.

   `C-u s SWITCHES <RET>' lets you specify a new value for
`dired-listing-switches'.


File: emacs,  Node: Dired and Find,  Next: Wdired,  Prev: Dired Updating,  Up: Dired

38.16 Dired and `find'
======================

You can select a set of files for display in a Dired buffer more
flexibly by using the `find' utility to choose the files.

   To search for files with names matching a wildcard pattern use `M-x
find-name-dired'.  It reads arguments DIRECTORY and PATTERN, and
chooses all the files in DIRECTORY or its subdirectories whose
individual names match PATTERN.

   The files thus chosen are displayed in a Dired buffer, in which the
ordinary Dired commands are available.

   If you want to test the contents of files, rather than their names,
use `M-x find-grep-dired'.  This command reads two minibuffer
arguments, DIRECTORY and REGEXP; it chooses all the files in DIRECTORY
or its subdirectories that contain a match for REGEXP.  It works by
running the programs `find' and `grep'.  See also `M-x grep-find', in
*note Grep Searching::.  Remember to write the regular expression for
`grep', not for Emacs.  (An alternative method of showing files whose
contents match a given regexp is the `% g REGEXP' command, see *note
Marks vs Flags::.)

   The most general command in this series is `M-x find-dired', which
lets you specify any condition that `find' can test.  It takes two
minibuffer arguments, DIRECTORY and FIND-ARGS; it runs `find' in
DIRECTORY, passing FIND-ARGS to tell `find' what condition to test.  To
use this command, you need to know how to use `find'.

   The format of listing produced by these commands is controlled by the
variable `find-ls-option', whose default value specifies using options
`-ld' for `ls'.  If your listings are corrupted, you may need to change
the value of this variable.

   The command `M-x locate' provides a similar interface to the
`locate' program.  `M-x locate-with-filter' is similar, but keeps only
files whose names match a given regular expression.

   These buffers don't work entirely like ordinary Dired buffers: file
operations work, but do not always automatically update the buffer.
Reverting the buffer with `g' deletes all inserted subdirectories, and
erases all flags and marks.


File: emacs,  Node: Wdired,  Next: Image-Dired,  Prev: Dired and Find,  Up: Dired

38.17 Editing the Dired Buffer
==============================

Wdired is a special mode that allows you to perform file operations by
editing the Dired buffer directly (the "W" in "Wdired" stands for
"writable.")  To enter Wdired mode, type `M-x
wdired-change-to-wdired-mode' while in a Dired buffer.  Alternatively,
use `Edit File Names' in the `Immediate' menu bar menu.

   While in Wdired mode, you can rename files by editing the file names
displayed in the Dired buffer.  All the ordinary Emacs editing
commands, including rectangle operations and `query-replace', are
available for this.  Once you are done editing, type `C-c C-c'
(`wdired-finish-edit').  This applies your changes and switches back to
ordinary Dired mode.

   Apart from simply renaming files, you can move a file to another
directory by typing in the new file name (either absolute or relative).
To mark a file for deletion, delete the entire file name.  To change
the target of a symbolic link, edit the link target name which appears
next to the link name.

   The rest of the text in the buffer, such as the file sizes and
modification dates, is marked read-only, so you can't edit it.
However, if you set `wdired-allow-to-change-permissions' to `t', you
can edit the file permissions.  For example, you can change
`-rw-r--r--' to `-rw-rw-rw-' to make a file world-writable.  These
changes also take effect when you type `C-c C-c'.


File: emacs,  Node: Image-Dired,  Next: Misc Dired Features,  Prev: Wdired,  Up: Dired

38.18 Viewing Image Thumbnails in Dired
=======================================

Image-Dired is a facility for browsing image files.  It provides viewing
the images either as thumbnails or in full size, either inside Emacs or
through an external viewer.

   To enter Image-Dired, mark the image files you want to look at in
the Dired buffer, using `m' as usual.  Then type `C-t d'
(`image-dired-display-thumbs').  This creates and switches to a buffer
containing image-dired, corresponding to the marked files.

   You can also enter Image-Dired directly by typing `M-x image-dired'.
This prompts for a directory; specify one that has image files.  This
creates thumbnails for all the images in that directory, and displays
them all in the "thumbnail buffer."  This takes a long time if the
directory contains many image files, and it asks for confirmation if
the number of image files exceeds
`image-dired-show-all-from-dir-max-files'.

   With point in the thumbnail buffer, you can type `RET'
(`image-dired-display-thumbnail-original-image') to display a sized
version of it in another window.  This sizes the image to fit the
window.  Use the arrow keys to move around in the buffer.  For easy
browsing, use `SPC' (`image-dired-display-next-thumbnail-original') to
advance and display the next image.  Typing `DEL'
(`image-dired-display-previous-thumbnail-original') backs up to the
previous thumbnail and displays that instead.

   To view and the image in its original size, either provide a prefix
argument (`C-u') before pressing `RET', or type `C-<RET>'
(`image-dired-thumbnail-display-external') to display the image in an
external viewer.  You must first configure
`image-dired-external-viewer'.

   You can delete images through Image-Dired also.  Type `d'
(`image-dired-flag-thumb-original-file') to flag the image file for
deletion in the Dired buffer.  You can also delete the thumbnail image
from the thumbnail buffer with `C-d' (`image-dired-delete-char').

   More advanced features include "image tags", which are metadata used
to categorize image files.  The tags are stored in a plain text file
configured by `image-dired-db-file'.

   To tag image files, mark them in the dired buffer (you can also mark
files in Dired from the thumbnail buffer by typing `m') and type `C-t
t' (`image-dired-tag-files').  You will be prompted for a tag.  To mark
files having a certain tag, type `C-t f'
(`image-dired-mark-tagged-files').  After marking image files with a
certain tag, you can use `C-t d' to view them.

   You can also tag a file directly from the thumbnail buffer by typing
`t t' and you can remove a tag by typing `t r'.  There is also a
special "tag" called "comment" for each file (it is not a tag in the
exact same sense as the other tags, it is handled slightly different).
That is used to enter a comment or description about the image.  You
comment a file from the thumbnail buffer by typing `c'.  You will be
prompted for a comment.  Type `C-t c' to add a comment from Dired
(`image-dired-dired-comment-files').

   Image-Dired also provides simple image manipulation.  In the
thumbnail buffer, type `L' to rotate the original image 90 degrees anti
clockwise, and `R' to rotate it 90 degrees clockwise.  This rotation is
lossless, and uses an external utility called JpegTRAN.


File: emacs,  Node: Misc Dired Features,  Prev: Image-Dired,  Up: Dired

38.19 Other Dired Features
==========================

An unusual Dired file-operation command is `+'
(`dired-create-directory').  This command reads a directory name, and
creates the directory if it does not already exist.

   The `w' command (`dired-copy-filename-as-kill') puts the names of
the marked (or next N) files into the kill ring, as if you had killed
them with `C-w'.  The names are separated by a space.

   With a zero prefix argument, this uses the absolute file name of
each marked file.  With just `C-u' as the prefix argument, it uses file
names relative to the Dired buffer's default directory.  (This can
still contain slashes if in a subdirectory.)  As a special case, if
point is on a directory headerline, `w' gives you the absolute name of
that directory.  Any prefix argument or marked files are ignored in
this case.

   The main purpose of this command is so that you can yank the file
names into arguments for other Emacs commands.  It also displays what
it added to the kill ring, so you can use it to display the list of
currently marked files in the echo area.

   The command `M-x dired-compare-directories' is used to compare the
current Dired buffer with another directory.  It marks all the files
that are "different" between the two directories.  It puts these marks
in all Dired buffers where these files are listed, which of course
includes the current buffer.

   The default comparison method (used if you type <RET> at the prompt)
is to compare just the file names--each file name that does not appear
in the other directory is "different."  You can specify more stringent
comparisons by entering a Lisp expression, which can refer to the
variables `size1' and `size2', the respective file sizes; `mtime1' and
`mtime2', the last modification times in seconds, as floating point
numbers; and `fa1' and `fa2', the respective file attribute lists (as
returned by the function `file-attributes').  This expression is
evaluated for each pair of like-named files, and if the expression's
value is non-`nil', those files are considered "different."

   For instance, the sequence `M-x dired-compare-directories <RET> (>
mtime1 mtime2) <RET>' marks files newer in this directory than in the
other, and marks files older in the other directory than in this one.
It also marks files with no counterpart, in both directories, as always.

   On the X window system, Emacs supports the "drag and drop" protocol.
You can drag a file object from another program, and drop it onto a
Dired buffer; this either moves, copies, or creates a link to the file
in that directory.  Precisely which action is taken is determined by
the originating program.  Dragging files out of a Dired buffer is
currently not supported.


File: emacs,  Node: Calendar/Diary,  Next: Gnus,  Prev: Dired,  Up: Top

39 The Calendar and the Diary
*****************************

Emacs provides the functions of a desk calendar, with a diary of
planned or past events.  It also has facilities for managing your
appointments, and keeping track of how much time you spend working on
certain projects.

   To enter the calendar, type `M-x calendar'; this displays a
three-month calendar centered on the current month, with point on the
current date.  With a numeric argument, as in `C-u M-x calendar', it
prompts you for the month and year to be the center of the three-month
calendar.  The calendar uses its own buffer, whose major mode is
Calendar mode.

   `Mouse-2' in the calendar brings up a menu of operations on a
particular date; `Mouse-3' brings up a menu of commonly used calendar
features that are independent of any particular date.  To exit the
calendar, type `q'.

* Menu:

* Calendar Motion::     Moving through the calendar; selecting a date.
* Scroll Calendar::     Bringing earlier or later months onto the screen.
* Counting Days::       How many days are there between two dates?
* General Calendar::    Exiting or recomputing the calendar.
* Writing Calendar Files:: Writing calendars to files of various formats.
* Holidays::            Displaying dates of holidays.
* Sunrise/Sunset::      Displaying local times of sunrise and sunset.
* Lunar Phases::        Displaying phases of the moon.
* Other Calendars::     Converting dates to other calendar systems.
* Diary::               Displaying events from your diary.
* Appointments::	Reminders when it's time to do something.
* Importing Diary::     Converting diary events to/from other formats.
* Daylight Saving::     How to specify when daylight saving time is active.
* Time Intervals::      Keeping track of time intervals.

* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.


File: emacs,  Node: Calendar Motion,  Next: Scroll Calendar,  Up: Calendar/Diary

39.1 Movement in the Calendar
=============================

Calendar mode provides commands to move through the calendar in logical
units of time such as days, weeks, months, and years.  If you move
outside the three months originally displayed, the calendar display
"scrolls" automatically through time to make the selected date visible.
Moving to a date lets you view its holidays or diary entries, or
convert it to other calendars; moving by long time periods is also
useful simply to scroll the calendar.

* Menu:

* Calendar Unit Motion::      Moving by days, weeks, months, and years.
* Move to Beginning or End::  Moving to start/end of weeks, months, and years.
* Specified Dates::           Moving to the current date or another
                                specific date.


File: emacs,  Node: Calendar Unit Motion,  Next: Move to Beginning or End,  Up: Calendar Motion

39.1.1 Motion by Standard Lengths of Time
-----------------------------------------

The commands for movement in the calendar buffer parallel the commands
for movement in text.  You can move forward and backward by days,
weeks, months, and years.

`C-f'
     Move point one day forward (`calendar-forward-day').

`C-b'
     Move point one day backward (`calendar-backward-day').

`C-n'
     Move point one week forward (`calendar-forward-week').

`C-p'
     Move point one week backward (`calendar-backward-week').

`M-}'
     Move point one month forward (`calendar-forward-month').

`M-{'
     Move point one month backward (`calendar-backward-month').

`C-x ]'
     Move point one year forward (`calendar-forward-year').

`C-x ['
     Move point one year backward (`calendar-backward-year').

   The day and week commands are natural analogues of the usual Emacs
commands for moving by characters and by lines.  Just as `C-n' usually
moves to the same column in the following line, in Calendar mode it
moves to the same day in the following week.  And `C-p' moves to the
same day in the previous week.

   The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just
as they normally are in other modes.

   The commands for motion by months and years work like those for
weeks, but move a larger distance.  The month commands `M-}' and `M-{'
move forward or backward by an entire month.  The year commands `C-x ]'
and `C-x [' move forward or backward a whole year.

   The easiest way to remember these commands is to consider months and
years analogous to paragraphs and pages of text, respectively.  But the
commands themselves are not quite analogous.  The ordinary Emacs
paragraph commands move to the beginning or end of a paragraph, whereas
these month and year commands move by an entire month or an entire
year, keeping the same date within the month or year.

   All these commands accept a numeric argument as a repeat count.  For
convenience, the digit keys and the minus sign specify numeric
arguments in Calendar mode even without the Meta modifier.  For example,
`100 C-f' moves point 100 days forward from its present location.


File: emacs,  Node: Move to Beginning or End,  Next: Specified Dates,  Prev: Calendar Unit Motion,  Up: Calendar Motion

39.1.2 Beginning or End of Week, Month or Year
----------------------------------------------

A week (or month, or year) is not just a quantity of days; we think of
weeks (months, years) as starting on particular dates.  So Calendar mode
provides commands to move to the beginning or end of a week, month or
year:

`C-a'
     Move point to start of week (`calendar-beginning-of-week').  

`C-e'
     Move point to end of week (`calendar-end-of-week').  

`M-a'
     Move point to start of month (`calendar-beginning-of-month').  

`M-e'
     Move point to end of month (`calendar-end-of-month').  

`M-<'
     Move point to start of year (`calendar-beginning-of-year').  

`M->'
     Move point to end of year (`calendar-end-of-year').

   These commands also take numeric arguments as repeat counts, with the
repeat count indicating how many weeks, months, or years to move
backward or forward.

   By default, weeks begin on Sunday.  To make them begin on Monday
instead, set the variable `calendar-week-start-day' to 1.


File: emacs,  Node: Specified Dates,  Prev: Move to Beginning or End,  Up: Calendar Motion

39.1.3 Specified Dates
----------------------

Calendar mode provides commands for moving to a particular date
specified in various ways.

`g d'
     Move point to specified date (`calendar-goto-date').

`g D'
     Move point to specified day of year (`calendar-goto-day-of-year').

`g w'
     Move point to specified week of year (`calendar-goto-iso-week').

`o'
     Center calendar around specified month (`calendar-other-month').

`.'
     Move point to today's date (`calendar-goto-today').

   `g d' (`calendar-goto-date') prompts for a year, a month, and a day
of the month, and then moves to that date.  Because the calendar
includes all dates from the beginning of the current era, you must type
the year in its entirety; that is, type `1990', not `90'.

   `g D' (`calendar-goto-day-of-year') prompts for a year and day
number, and moves to that date.  Negative day numbers count backward
from the end of the year.  `g w' (`calendar-goto-iso-week') prompts for
a year and week number, and moves to that week.

   `o' (`calendar-other-month') prompts for a month and year, then
centers the three-month calendar around that month.

   You can return to today's date with `.' (`calendar-goto-today').


File: emacs,  Node: Scroll Calendar,  Next: Counting Days,  Prev: Calendar Motion,  Up: Calendar/Diary

39.2 Scrolling in the Calendar
==============================

The calendar display scrolls automatically through time when you move
out of the visible portion.  You can also scroll it manually.  Imagine
that the calendar window contains a long strip of paper with the months
on it.  Scrolling the calendar means moving the strip horizontally, so
that new months become visible in the window.

`>'
     Scroll calendar one month forward (`scroll-calendar-left').

`<'
     Scroll calendar one month backward (`scroll-calendar-right').

`C-v'
`<NEXT>'
     Scroll calendar three months forward
     (`scroll-calendar-left-three-months').

`M-v'
`<PRIOR>'
     Scroll calendar three months backward
     (`scroll-calendar-right-three-months').

   The most basic calendar scroll commands scroll by one month at a
time.  This means that there are two months of overlap between the
display before the command and the display after.  `>' scrolls the
calendar contents one month forward in time.  `<' scrolls the contents
one month backwards in time.

   The commands `C-v' and `M-v' scroll the calendar by an entire
"screenful"--three months--in analogy with the usual meaning of these
commands.  `C-v' makes later dates visible and `M-v' makes earlier
dates visible.  These commands take a numeric argument as a repeat
count; in particular, since `C-u' multiplies the next command by four,
typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u
M-v' scrolls the calendar backward by a year.

   The function keys <NEXT> and <PRIOR> are equivalent to `C-v' and
`M-v', just as they are in other modes.


File: emacs,  Node: Counting Days,  Next: General Calendar,  Prev: Scroll Calendar,  Up: Calendar/Diary

39.3 Counting Days
==================

`M-='
     Display the number of days in the current region
     (`calendar-count-days-region').

   To determine the number of days in the region, type `M-='
(`calendar-count-days-region').  The numbers of days shown is
_inclusive_; that is, it includes the days specified by mark and point.


File: emacs,  Node: General Calendar,  Next: Writing Calendar Files,  Prev: Counting Days,  Up: Calendar/Diary

39.4 Miscellaneous Calendar Commands
====================================

`p d'
     Display day-in-year (`calendar-print-day-of-year').

`C-c C-l'
     Regenerate the calendar window (`redraw-calendar').

`SPC'
     Scroll the next window up (`scroll-other-window').

`DEL'
     Scroll the next window down (`scroll-other-window-down').

`q'
     Exit from calendar (`exit-calendar').

   To display the number of days elapsed since the start of the year, or
the number of days remaining in the year, type the `p d' command
(`calendar-print-day-of-year').  This displays both of those numbers in
the echo area.  The count of days elapsed includes the selected date.
The count of days remaining does not include that date.

   If the calendar window text gets corrupted, type `C-c C-l'
(`redraw-calendar') to redraw it.  (This can only happen if you use
non-Calendar-mode editing commands.)

   In Calendar mode, you can use `SPC' (`scroll-other-window') and
`DEL' (`scroll-other-window-down') to scroll the other window up or
down, respectively.  This is handy when you display a list of holidays
or diary entries in another window.

   To exit from the calendar, type `q' (`exit-calendar').  This buries
all buffers related to the calendar, selecting other buffers.  (If a
frame contains a dedicated calendar window, exiting from the calendar
iconifies that frame.)


File: emacs,  Node: Writing Calendar Files,  Next: Holidays,  Prev: General Calendar,  Up: Calendar/Diary

39.5 Writing Calendar Files
===========================

These packages produce files of various formats containing calendar and
diary entries, for display purposes.

   The Calendar HTML commands produce files of HTML code that contain
calendar and diary entries.  Each file applies to one month, and has a
name of the format `YYYY-MM.html', where YYYY and MM are the four-digit
year and two-digit month, respectively.  The variable
`cal-html-directory' specifies the default output directory for the
HTML files.

   Diary entries enclosed by `<' and `>' are interpreted as HTML tags
(for example: this is a diary entry with <font color="red">some red
text</font>).  You can change the overall appearance of the displayed
HTML pages (for example, the color of various page elements, header
styles) via a stylesheet `cal.css' in the directory containing the HTML
files (see the value of the variable `cal-html-css-default' for
relevant style settings).

`H m'
     Generate a one-month calendar (`cal-html-cursor-month').

`H y'
     Generate a calendar file for each month of a year, as well as an
     index page (`cal-html-cursor-year').  By default, this command
     writes files to a YYYY subdirectory - if this is altered some
     hyperlinks between years will not work.

   If the variable `cal-html-print-day-number-flag' is non-`nil', then
the monthly calendars show the day-of-the-year number. The variable
`cal-html-year-index-cols' specifies the number of columns in the
yearly index page.

   The Calendar LaTeX commands produce a buffer of LaTeX code that
prints as a calendar.  Depending on the command you use, the printed
calendar covers the day, week, month or year that point is in.

`t m'
     Generate a one-month calendar (`cal-tex-cursor-month').

`t M'
     Generate a sideways-printing one-month calendar
     (`cal-tex-cursor-month-landscape').

`t d'
     Generate a one-day calendar (`cal-tex-cursor-day').

`t w 1'
     Generate a one-page calendar for one week (`cal-tex-cursor-week').

`t w 2'
     Generate a two-page calendar for one week (`cal-tex-cursor-week2').

`t w 3'
     Generate an ISO-style calendar for one week
     (`cal-tex-cursor-week-iso').

`t w 4'
     Generate a calendar for one Monday-starting week
     (`cal-tex-cursor-week-monday').

`t f w'
     Generate a Filofax-style two-weeks-at-a-glance calendar
     (`cal-tex-cursor-filofax-2week').

`t f W'
     Generate a Filofax-style one-week-at-a-glance calendar
     (`cal-tex-cursor-filofax-week').

`t y'
     Generate a calendar for one year (`cal-tex-cursor-year').

`t Y'
     Generate a sideways-printing calendar for one year
     (`cal-tex-cursor-year-landscape').

`t f y'
     Generate a Filofax-style calendar for one year
     (`cal-tex-cursor-filofax-year').

   Some of these commands print the calendar sideways (in "landscape
mode"), so it can be wider than it is long.  Some of them use Filofax
paper size (3.75in x 6.75in).  All of these commands accept a prefix
argument which specifies how many days, weeks, months or years to print
(starting always with the selected one).

   If the variable `cal-tex-holidays' is non-`nil' (the default), then
the printed calendars show the holidays in `calendar-holidays'.  If the
variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
entries are included also (in monthly, filofax, and iso-week calendars
only).  If the variable `cal-tex-rules' is non-`nil' (the default is
`nil'), the calendar displays ruled pages in styles that have
sufficient room.  Consult the documentation of the individual cal-tex
functions to see which calendars support which features.

   You can use the variable `cal-tex-preamble-extra' to insert extra
LaTeX commands in the preamble of the generated document if you need to.


File: emacs,  Node: Holidays,  Next: Sunrise/Sunset,  Prev: Writing Calendar Files,  Up: Calendar/Diary

39.6 Holidays
=============

The Emacs calendar knows about all major and many minor holidays, and
can display them.

`h'
     Display holidays for the selected date
     (`calendar-cursor-holidays').

`Mouse-2 Holidays'
     Display any holidays for the date you click on.

`x'
     Mark holidays in the calendar window (`mark-calendar-holidays').

`u'
     Unmark calendar window (`calendar-unmark').

`a'
     List all holidays for the displayed three months in another window
     (`list-calendar-holidays').

`M-x holidays'
     List all holidays for three months around today's date in another
     window.

`M-x list-holidays'
     List holidays in another window for a specified range of years.

   To see if any holidays fall on a given date, position point on that
date in the calendar window and use the `h' command.  Alternatively,
click on that date with `Mouse-2' and then choose `Holidays' from the
menu that appears.  Either way, this displays the holidays for that
date, in the echo area if they fit there, otherwise in a separate
window.

   To view the distribution of holidays for all the dates shown in the
calendar, use the `x' command.  This displays the dates that are
holidays in a different face (or places a `*' after these dates, if
display with multiple faces is not available).  *Note
calendar-holiday-marker: Calendar Customizing.    The command applies
both to the currently visible months and to other months that
subsequently become visible by scrolling.  To turn marking off and
erase the current marks, type `u', which also erases any diary marks
(*note Diary::).  If the variable `mark-holidays-in-calendar' is
non-`nil', creating or updating the calendar marks holidays
automatically.

   To get even more detailed information, use the `a' command, which
displays a separate buffer containing a list of all holidays in the
current three-month range.  You can use <SPC> and <DEL> in the calendar
window to scroll that list up and down, respectively.

   The command `M-x holidays' displays the list of holidays for the
current month and the preceding and succeeding months; this works even
if you don't have a calendar window.  If the variable
`view-calendar-holidays-initially' is non-`nil', creating the calendar
displays holidays in this way.  If you want the list of holidays
centered around a different month, use `C-u M-x holidays', which
prompts for the month and year.

   The holidays known to Emacs include United States holidays and the
major Christian, Jewish, and Islamic holidays; also the solstices and
equinoxes.

   The command `M-x list-holidays' displays the list of holidays for a
range of years.  This function asks you for the starting and stopping
years, and allows you to choose all the holidays or one of several
categories of holidays.  You can use this command even if you don't have
a calendar window.

   The dates used by Emacs for holidays are based on _current
practice_, not historical fact.  For example Veteran's Day began in
1919, but is shown in earlier years.


File: emacs,  Node: Sunrise/Sunset,  Next: Lunar Phases,  Prev: Holidays,  Up: Calendar/Diary

39.7 Times of Sunrise and Sunset
================================

Special calendar commands can tell you, to within a minute or two, the
times of sunrise and sunset for any date.

`S'
     Display times of sunrise and sunset for the selected date
     (`calendar-sunrise-sunset').

`Mouse-2 Sunrise/sunset'
     Display times of sunrise and sunset for the date you click on.

`M-x sunrise-sunset'
     Display times of sunrise and sunset for today's date.

`C-u M-x sunrise-sunset'
     Display times of sunrise and sunset for a specified date.

   Within the calendar, to display the _local times_ of sunrise and
sunset in the echo area, move point to the date you want, and type `S'.
Alternatively, click `Mouse-2' on the date, then choose
`Sunrise/sunset' from the menu that appears.  The command `M-x
sunrise-sunset' is available outside the calendar to display this
information for today's date or a specified date.  To specify a date
other than today, use `C-u M-x sunrise-sunset', which prompts for the
year, month, and day.

   You can display the times of sunrise and sunset for any location and
any date with `C-u C-u M-x sunrise-sunset'.  This asks you for a
longitude, latitude, number of minutes difference from Coordinated
Universal Time, and date, and then tells you the times of sunrise and
sunset for that location on that date.

   Because the times of sunrise and sunset depend on the location on
earth, you need to tell Emacs your latitude, longitude, and location
name before using these commands.  Here is an example of what to set:

     (setq calendar-latitude 40.1)
     (setq calendar-longitude -88.2)
     (setq calendar-location-name "Urbana, IL")

Use one decimal place in the values of `calendar-latitude' and
`calendar-longitude'.

   Your time zone also affects the local time of sunrise and sunset.
Emacs usually gets time zone information from the operating system, but
if these values are not what you want (or if the operating system does
not supply them), you must set them yourself.  Here is an example:

     (setq calendar-time-zone -360)
     (setq calendar-standard-time-zone-name "CST")
     (setq calendar-daylight-time-zone-name "CDT")

The value of `calendar-time-zone' is the number of minutes difference
between your local standard time and Coordinated Universal Time
(Greenwich time).  The values of `calendar-standard-time-zone-name' and
`calendar-daylight-time-zone-name' are the abbreviations used in your
time zone.  Emacs displays the times of sunrise and sunset _corrected
for daylight saving time_.  *Note Daylight Saving::, for how daylight
saving time is determined.

   As a user, you might find it convenient to set the calendar location
variables for your usual physical location in your `.emacs' file.  And
when you install Emacs on a machine, you can create a `default.el' file
which sets them properly for the typical location of most users of that
machine.  *Note Init File::.


File: emacs,  Node: Lunar Phases,  Next: Other Calendars,  Prev: Sunrise/Sunset,  Up: Calendar/Diary

39.8 Phases of the Moon
=======================

These calendar commands display the dates and times of the phases of
the moon (new moon, first quarter, full moon, last quarter).  This
feature is useful for debugging problems that "depend on the phase of
the moon."

`M'
     Display the dates and times for all the quarters of the moon for
     the three-month period shown (`calendar-phases-of-moon').

`M-x phases-of-moon'
     Display dates and times of the quarters of the moon for three
     months around today's date.

   Within the calendar, use the `M' command to display a separate
buffer of the phases of the moon for the current three-month range.  The
dates and times listed are accurate to within a few minutes.

   Outside the calendar, use the command `M-x phases-of-moon' to
display the list of the phases of the moon for the current month and the
preceding and succeeding months.  For information about a different
month, use `C-u M-x phases-of-moon', which prompts for the month and
year.

   The dates and times given for the phases of the moon are given in
local time (corrected for daylight saving, when appropriate); but if
the variable `calendar-time-zone' is void, Coordinated Universal Time
(the Greenwich time zone) is used.  *Note Daylight Saving::.


File: emacs,  Node: Other Calendars,  Next: Diary,  Prev: Lunar Phases,  Up: Calendar/Diary

39.9 Conversion To and From Other Calendars
===========================================

The Emacs calendar displayed is _always_ the Gregorian calendar,
sometimes called the "new style" calendar, which is used in most of the
world today.  However, this calendar did not exist before the sixteenth
century and was not widely used before the eighteenth century; it did
not fully displace the Julian calendar and gain universal acceptance
until the early twentieth century.  The Emacs calendar can display any
month since January, year 1 of the current era, but the calendar
displayed is the Gregorian, even for a date at which the Gregorian
calendar did not exist.

   While Emacs cannot display other calendars, it can convert dates to
and from several other calendars.

* Menu:

* Calendar Systems::	   The calendars Emacs understands
			     (aside from Gregorian).
* To Other Calendar::	   Converting the selected date to various calendars.
* From Other Calendar::	   Moving to a date specified in another calendar.
* Mayan Calendar::	   Moving to a date specified in a Mayan calendar.


File: emacs,  Node: Calendar Systems,  Next: To Other Calendar,  Up: Other Calendars

39.9.1 Supported Calendar Systems
---------------------------------

The ISO commercial calendar is used largely in Europe.

   The Julian calendar, named after Julius Caesar, was the one used in
Europe throughout medieval times, and in many countries up until the
nineteenth century.

   Astronomers use a simple counting of days elapsed since noon, Monday,
January 1, 4713 B.C. on the Julian calendar.  The number of days elapsed
is called the "Julian day number" or the "Astronomical day number".

   The Hebrew calendar is used by tradition in the Jewish religion.  The
Emacs calendar program uses the Hebrew calendar to determine the dates
of Jewish holidays.  Hebrew calendar dates begin and end at sunset.

   The Islamic calendar is used in many predominantly Islamic countries.
Emacs uses it to determine the dates of Islamic holidays.  There is no
universal agreement in the Islamic world about the calendar; Emacs uses
a widely accepted version, but the precise dates of Islamic holidays
often depend on proclamation by religious authorities, not on
calculations.  As a consequence, the actual dates of observance can vary
slightly from the dates computed by Emacs.  Islamic calendar dates begin
and end at sunset.

   The French Revolutionary calendar was created by the Jacobins after
the 1789 revolution, to represent a more secular and nature-based view
of the annual cycle, and to install a 10-day week in a rationalization
measure similar to the metric system.  The French government officially
abandoned this calendar at the end of 1805.

   The Maya of Central America used three separate, overlapping calendar
systems, the _long count_, the _tzolkin_, and the _haab_.  Emacs knows
about all three of these calendars.  Experts dispute the exact
correlation between the Mayan calendar and our calendar; Emacs uses the
Goodman-Martinez-Thompson correlation in its calculations.

   The Copts use a calendar based on the ancient Egyptian solar
calendar.  Their calendar consists of twelve 30-day months followed by
an extra five-day period.  Once every fourth year they add a leap day
to this extra period to make it six days.  The Ethiopic calendar is
identical in structure, but has different year numbers and month names.

   The Persians use a solar calendar based on a design of Omar Khayyam.
Their calendar consists of twelve months of which the first six have 31
days, the next five have 30 days, and the last has 29 in ordinary years
and 30 in leap years.  Leap years occur in a complicated pattern every
four or five years.  The calendar implemented here is the arithmetical
Persian calendar championed by Birashk, based on a 2,820-year cycle.
It differs from the astronomical Persian calendar, which is based on
astronomical events.  As of this writing the first future discrepancy
is projected to occur on March 20, 2025.  It is currently not clear
what the official calendar of Iran will be that far into the future.

   The Chinese calendar is a complicated system of lunar months arranged
into solar years.  The years go in cycles of sixty, each year containing
either twelve months in an ordinary year or thirteen months in a leap
year; each month has either 29 or 30 days.  Years, ordinary months, and
days are named by combining one of ten "celestial stems" with one of
twelve "terrestrial branches" for a total of sixty names that are
repeated in a cycle of sixty.


File: emacs,  Node: To Other Calendar,  Next: From Other Calendar,  Prev: Calendar Systems,  Up: Other Calendars

39.9.2 Converting To Other Calendars
------------------------------------

The following commands describe the selected date (the date at point)
in various other calendar systems:

`Mouse-2  Other calendars'
     Display the date that you click on, expressed in various other
     calendars.  

`p c'
     Display ISO commercial calendar equivalent for selected day
     (`calendar-print-iso-date').  

`p j'
     Display Julian date for selected day
     (`calendar-print-julian-date').  

`p a'
     Display astronomical (Julian) day number for selected day
     (`calendar-print-astro-day-number').  

`p h'
     Display Hebrew date for selected day
     (`calendar-print-hebrew-date').  

`p i'
     Display Islamic date for selected day
     (`calendar-print-islamic-date').  

`p f'
     Display French Revolutionary date for selected day
     (`calendar-print-french-date').  

`p C'
     Display Chinese date for selected day
     (`calendar-print-chinese-date').  

`p k'
     Display Coptic date for selected day
     (`calendar-print-coptic-date').  

`p e'
     Display Ethiopic date for selected day
     (`calendar-print-ethiopic-date').  

`p p'
     Display Persian date for selected day
     (`calendar-print-persian-date').  

`p m'
     Display Mayan date for selected day (`calendar-print-mayan-date').

   If you are using X, the easiest way to translate a date into other
calendars is to click on it with `Mouse-2', then choose `Other
calendars' from the menu that appears.  This displays the equivalent
forms of the date in all the calendars Emacs understands, in the form of
a menu.  (Choosing an alternative from this menu doesn't actually do
anything--the menu is used only for display.)

   Otherwise, move point to the date you want to convert, then type the
appropriate command starting with `p' from the table above.  The prefix
`p' is a mnemonic for "print," since Emacs "prints" the equivalent date
in the echo area.

