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

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


File: emacs,  Node: Other C Commands,  Next: Comments in C,  Prev: Hungry Delete,  Up: C Mode

19.14.4 Other Commands for C Mode
---------------------------------

`C-M-h'
     Put mark at the end of a function definition, and put point at the
     beginning (`c-mark-function').

`M-q'
     Fill a paragraph, handling C and C++ comments (`c-fill-paragraph').
     If any part of the current line is a comment or within a comment,
     this command fills the comment or the paragraph of it that point
     is in, preserving the comment indentation and comment delimiters.

`C-c C-e'
     Run the C preprocessor on the text in the region, and show the
     result, which includes the expansion of all the macro calls
     (`c-macro-expand').  The buffer text before the region is also
     included in preprocessing, for the sake of macros defined there,
     but the output from this part isn't shown.

     When you are debugging C code that uses macros, sometimes it is
     hard to figure out precisely how the macros expand.  With this
     command, you don't have to figure it out; you can see the
     expansions.

`C-c C-\'
     Insert or align `\' characters at the ends of the lines of the
     region (`c-backslash-region').  This is useful after writing or
     editing a C macro definition.

     If a line already ends in `\', this command adjusts the amount of
     whitespace before it.  Otherwise, it inserts a new `\'.  However,
     the last line in the region is treated specially; no `\' is
     inserted on that line, and any `\' there is deleted.

`M-x cpp-highlight-buffer'
     Highlight parts of the text according to its preprocessor
     conditionals.  This command displays another buffer named `*CPP
     Edit*', which serves as a graphic menu for selecting how to
     display particular kinds of conditionals and their contents.
     After changing various settings, click on `[A]pply these settings'
     (or go to that buffer and type `a') to rehighlight the C mode
     buffer accordingly.

`C-c C-s'
     Display the syntactic information about the current source line
     (`c-show-syntactic-information').  This is the information that
     directs how the line is indented.


File: emacs,  Node: Comments in C,  Prev: Other C Commands,  Up: C Mode

19.14.5 Comments in C Modes
---------------------------

C mode and related modes use a number of variables for controlling
comment format.

`c-block-comments-indent-p'
     This variable specifies how to reindent block comments.  The C
     modes support five styles of block comments:

           style 1:    style 2 (GNU):   style 3:    style 4:    style 5:
           /*          /* Blah          /*          /*          /*
              blah        blah.  */      * blah     ** blah     blah
              blah                       * blah     ** blah     blah
              */                         */         */          */

     For the styles 1 through 4, `c-block-comments-indent-p' should be
     `nil' (the default).  If you want to use style 5, set
     `c-block-comments-indent-p' to `t'.

     This variable has no effect on the indentation of the comment-start
     itself or on insertion of asterisks when auto-filling C comments.
     It does not affect `M-q' either.

`c-comment-only-line-offset'
     Extra offset for line which contains only the start of a comment.
     It can be either an integer or a cons cell of the form
     `(NON-ANCHORED-OFFSET . ANCHORED-OFFSET)', where
     NON-ANCHORED-OFFSET is the amount of offset given to
     non-column-zero anchored comment-only lines, and ANCHORED-OFFSET
     is the amount of offset to give column-zero anchored comment-only
     lines.  Just an integer as value is equivalent to `(VAL . 0)'.

`c-comment-start-regexp'
     This buffer-local variable specifies how to recognize the start of
     a comment.

`c-hanging-comment-ender-p'
     If this variable is `nil', `c-fill-paragraph' leaves the comment
     terminator of a block comment on a line by itself.  The default
     value is `t', which always puts the comment-end delimiter `*/' at
     the end of the last line of the comment text.


File: emacs,  Node: Fortran,  Next: Asm Mode,  Prev: C Mode,  Up: Programs

19.15 Fortran Mode
==================

Fortran mode provides special motion commands for Fortran statements and
subprograms, and indentation commands that understand Fortran
conventions of nesting, line numbers and continuation statements.
Fortran mode has its own Auto Fill mode that breaks long lines into
proper Fortran continuation lines.

   Special commands for comments are provided because Fortran comments
are unlike those of other languages.  Built-in abbrevs optionally save
typing when you insert Fortran keywords.

   Use `M-x fortran-mode' to switch to this major mode.  This command
runs the hook `fortran-mode-hook' (*note Hooks::).

* Menu:

* Motion: Fortran Motion.	 Moving point by statements or subprograms.
* Indent: Fortran Indent.	 Indentation commands for Fortran.
* Comments: Fortran Comments.	 Inserting and aligning comments.
* Autofill: Fortran Autofill.	 Auto fill minor mode for Fortran.
* Columns: Fortran Columns.	 Measuring columns for valid Fortran.
* Abbrev: Fortran Abbrev.	 Built-in abbrevs for Fortran keywords.


File: emacs,  Node: Fortran Motion,  Next: Fortran Indent,  Up: Fortran

19.15.1 Motion Commands
-----------------------

Fortran mode provides special commands to move by subprograms (functions
and subroutines) and by statements.  There is also a command to put the
region around one subprogram, convenient for killing it or moving it.

`C-M-a'
     Move to beginning of subprogram
     (`beginning-of-fortran-subprogram').

`C-M-e'
     Move to end of subprogram (`end-of-fortran-subprogram').

`C-M-h'
     Put point at beginning of subprogram and mark at end
     (`mark-fortran-subprogram').

`C-c C-n'
     Move to beginning of current or next statement
     (`fortran-next-statement').

`C-c C-p'
     Move to beginning of current or previous statement
     (`fortran-previous-statement').


File: emacs,  Node: Fortran Indent,  Next: Fortran Comments,  Prev: Fortran Motion,  Up: Fortran

19.15.2 Fortran Indentation
---------------------------

Special commands and features are needed for indenting Fortran code in
order to make sure various syntactic entities (line numbers, comment
line indicators and continuation line flags) appear in the columns that
are required for standard Fortran.

* Menu:

* Commands: ForIndent Commands.  Commands for indenting Fortran.
* Contline: ForIndent Cont.      How continuation lines indent.
* Numbers:  ForIndent Num.       How line numbers auto-indent.
* Conv:     ForIndent Conv.      Conventions you must obey to avoid trouble.
* Vars:     ForIndent Vars.      Variables controlling Fortran indent style.


File: emacs,  Node: ForIndent Commands,  Next: ForIndent Cont,  Up: Fortran Indent

19.15.2.1 Fortran Indentation Commands
......................................

`<TAB>'
     Indent the current line (`fortran-indent-line').

`<LFD>'
     Indent the current and start a new indented line
     (`fortran-indent-new-line').

`M-<LFD>'
     Break the current line and set up a continuation line.

`C-M-q'
     Indent all the lines of the subprogram point is in
     (`fortran-indent-subprogram').

   Fortran mode redefines <TAB> to reindent the current line for
Fortran (`fortran-indent-line').  This command indents Line numbers and
continuation markers to their required columns, and independently
indents the body of the statement based on its nesting in the program.

   The key `LFD' runs the command `fortran-indent-new-line', which
reindents the current line then makes and indents a new line.  This
command is useful to reindent the closing statement of `do' loops and
other blocks before starting a new line.

   The key `C-M-q' runs `fortran-indent-subprogram', a command to
reindent all the lines of the Fortran subprogram (function or
subroutine) containing point.

   The key `M-<LFD>' runs `fortran-split-line', which splits a line in
the appropriate fashion for Fortran.  In a non-comment line, the second
half becomes a continuation line and is indented accordingly.  In a
comment line, both halves become separate comment lines.


File: emacs,  Node: ForIndent Cont,  Next: ForIndent Num,  Prev: ForIndent Commands,  Up: Fortran Indent

19.15.2.2 Continuation Lines
............................

Most modern Fortran compilers allow two ways of writing continuation
lines.  If the first non-space character on a line is in column 5, then
that line is a continuation of the previous line.  We call this "fixed
format".  (In GNU Emacs we always count columns from 0.)  The variable
`fortran-continuation-string' specifies what character to put on column
5.  A line that starts with a tab character followed by any digit
except `0' is also a continuation line.  We call this style of
continuation "tab format".

   Fortran mode can make either style of continuation line, but you
must specify which one you prefer.  The value of the variable
`indent-tabs-mode' controls the choice: `nil' for fixed format, and
non-`nil' for tab format.  You can tell which style is presently in
effect by the presence or absence of the string `Tab' in the mode line.

   If the text on a line starts with the conventional Fortran
continuation marker `$', or if it begins with any non-whitespace
character in column 5, Fortran mode treats it as a continuation line.
When you indent a continuation line with <TAB>, it converts the line to
the current continuation style.  When you split a Fortran statement
with `M-<LFD>', the continuation marker on the newline is created
according to the continuation style.

   The setting of continuation style affects several other aspects of
editing in Fortran mode.  In fixed format mode, the minimum column
number for the body of a statement is 6.  Lines inside of Fortran
blocks that are indented to larger column numbers always use only the
space character for whitespace.  In tab format mode, the minimum column
number for the statement body is 8, and the whitespace before column 8
must always consist of one tab character.

   When you enter Fortran mode for an existing file, it tries to deduce
the proper continuation style automatically from the file contents.
The first line that begins with either a tab character or six spaces
determines the choice.  The variable `fortran-analyze-depth' specifies
how many lines to consider (at the beginning of the file); if none of
those lines indicates a style, then the variable
`fortran-tab-mode-default' specifies the style.  If it is `nil', that
specifies fixed format, and non-`nil' specifies tab format.


File: emacs,  Node: ForIndent Num,  Next: ForIndent Conv,  Prev: ForIndent Cont,  Up: Fortran Indent

19.15.2.3 Line Numbers
......................

If a number is the first non-whitespace in the line, Fortran
indentation assumes it is a line number and moves it to columns 0
through 4.  (Columns always count from 0 in GNU Emacs.)

   Line numbers of four digits or less are normally indented one space.
The variable `fortran-line-number-indent' controls this; it specifies
the maximum indentation a line number can have.  Line numbers are
indented to right-justify them to end in column 4 unless that would
require more than this maximum indentation.  The default value of the
variable is 1.

   Simply inserting a line number is enough to indent it according to
these rules.  As each digit is inserted, the indentation is recomputed.
To turn off this feature, set the variable
`fortran-electric-line-number' to `nil'.  Then inserting line numbers
is like inserting anything else.


File: emacs,  Node: ForIndent Conv,  Next: ForIndent Vars,  Prev: ForIndent Num,  Up: Fortran Indent

19.15.2.4 Syntactic Conventions
...............................

Fortran mode assumes that you follow certain conventions that simplify
the task of understanding a Fortran program well enough to indent it
properly:

   * Two nested `do' loops never share a `continue' statement.

   * Fortran keywords such as `if', `else', `then', `do' and others are
     written without embedded whitespace or line breaks.

     Fortran compilers generally ignore whitespace outside of string
     constants, but Fortran mode does not recognize these keywords if
     they are not contiguous.  Constructs such as `else if' or `end do'
     are acceptable, but the second word should be on the same line as
     the first and not on a continuation line.

If you fail to follow these conventions, the indentation commands may
indent some lines unaesthetically.  However, a correct Fortran program
retains its meaning when reindented even if the conventions are not
followed.


File: emacs,  Node: ForIndent Vars,  Prev: ForIndent Conv,  Up: Fortran Indent

19.15.2.5 Variables for Fortran Indentation
...........................................

Several additional variables control how Fortran indentation works:

`fortran-do-indent'
     Extra indentation within each level of `do' statement (default 3).

`fortran-if-indent'
     Extra indentation within each level of `if' statement (default 3).
     This value is also used for extra indentation within each level of
     the Fortran 90 `where' statement.

`fortran-structure-indent'
     Extra indentation within each level of `structure', `union', or
     `map' statements (default 3).

`fortran-continuation-indent'
     Extra indentation for bodies of continuation lines (default 5).

`fortran-check-all-num-for-matching-do'
     If this is `nil', indentation assumes that each `do' statement
     ends on a `continue' statement.  Therefore, when computing
     indentation for a statement other than `continue', it can save time
     by not checking for a `do' statement ending there.  If this is
     non-`nil', indenting any numbered statement must check for a `do'
     that ends there.  The default is `nil'.

`fortran-blink-matching-if'
     If this is `t', indenting an `endif' statement moves the cursor
     momentarily to the matching `if' statement to show where it is.
     The default is `nil'.

`fortran-minimum-statement-indent-fixed'
     Minimum indentation for fortran statements when using fixed format
     continuation line style.  Statement bodies are never indented less
     than this much.  The default is 6.

`fortran-minimum-statement-indent-tab'
     Minimum indentation for fortran statements for tab format
     continuation line style.  Statement bodies are never indented less
     than this much.  The default is 8.


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

19.15.3 Fortran Comments
------------------------

The usual Emacs comment commands assume that a comment can follow a line
of code.  In Fortran, 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 a nonstandard comment syntax where
comments start with `!' and can follow other text.  Because only some
Fortran 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 `comment-start' to `"!"' (*note Variables::).

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

`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-comment-indent'.  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 columns automatically at all.

   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.

   Fortran mode introduces two variables `comment-line-start' and
`comment-line-start-skip' which play for full-line comments the same
roles played by `comment-start' and `comment-start-skip' for ordinary
text-following comments.  Normally these are set properly by Fortran
mode so you do not need to change them.

   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

19.15.4 Fortran Auto Fill Mode
------------------------------

Fortran Auto Fill mode is a minor mode which automatically splits
Fortran 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.

   `M-x fortran-auto-fill-mode' turns Fortran Auto Fill mode on if it
was off, or off if it was on.  This command works the same as `M-x
auto-fill-mode' does for normal Auto Fill mode (*note Filling::).  A
positive numeric argument turns Fortran Auto Fill mode on, and a
negative argument turns it off.  You can see when Fortran Auto Fill mode
is in effect by the presence of the word `Fill' in the mode line,
inside the parentheses.  Fortran Auto Fill mode is a minor mode, turned
on or off for each buffer individually.  *Note Minor Modes::.

   Fortran Auto Fill mode breaks lines at spaces or delimiters when the
lines get longer than the desired width (the value of `fill-column').
The delimiters that Fortran Auto Fill mode may 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.

   By default, Fortran Auto Fill mode is not enabled.  If you want this
feature turned on permanently, add a hook function to
`fortran-mode-hook' to execute `(fortran-auto-fill-mode 1)'.  *Note
Hooks::.


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

19.15.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.  This may help you avoid making lines longer than
     the 72 character limit that some fortran compilers impose
     (`fortran-window-create-momentarily').

   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 variable `fortran-column-ruler-tab' is
displayed.  By changing these variables, you can change the column
ruler display.

   For even more help, use `C-c C-w' (`fortran-window-create'), a
command which splits the current window horizontally, making a window 72
columns wide.  By editing in this window you can immediately see when
you make a line too wide to be correct Fortran.


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

19.15.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: Asm Mode,  Prev: Fortran,  Up: Programs

19.16 Asm Mode
==============

Asm mode is a major mode for editing files of assembler code.  It
defines these commands:

`<TAB>'
     `tab-to-tab-stop'.

`<LFD>'
     Insert a newline and then indent using `tab-to-tab-stop'.

`:'
     Insert a colon and then remove the indentation from before the
     label preceding colon.  Then do `tab-to-tab-stop'.

`;'
     Insert or align a comment.

   The variable `asm-comment-char' specifies which character starts
comments in assembler syntax.


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

20 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 developing and maintaining programs.

* Menu:

* Compilation::                   Compiling programs in languages other
                                    than Lisp (C, Pascal, etc.)
* 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.
* Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
* Eval: Lisp Eval.                Executing a single Lisp expression in Emacs.
* External Lisp::                 Communicating through Emacs with a
                                    separate Lisp.


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

20.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 to
     `*compilation*' buffer.

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

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

`C-x `'
     Visit the locus of the next compiler error message or `grep' 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.

   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.

   When the shell command line is read, the minibuffer appears
containing a default command line, which is the command you used the
last time you did `M-x compile'.  If you type just <RET>, the same
command line is used again.  For the first `M-x compile', the default is
`make -k'.  The default compilation command comes from the variable
`compile-command'; if the appropriate compilation command for a file is
something other than `make -k', it can be useful for the file to
specify a local value for `compile-command' (*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' 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.

   To kill the compilation process, do `M-x kill-compilation'.  When
the compiler process terminates, the mode line of the `*compilation*'
buffer changes to say `signal' instead of `run'.  Starting a new
compilation also kills any running compilation, as only one can exist
at any time.  However, `M-x compile' asks for confirmation before
actually killing a compilation that is running.

   The `*compilation*' buffer uses a special major mode, Compilation
mode.  This mode provides the keys <SPC> and <DEL> to scroll by
screenfuls, and `M-n' and `M-p' to move to the next or previous error
message.  You can also use `M-{' and `M-}' to move up or down to an
error message for a different source file.

   You can visit the source for any particular error message by moving
point in `*compilation*' to that error message and typing <RET>
(`compile-goto-error').  Or 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.

   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.  This way, you can process the same set of errors again.

   Just as you can run a compiler, you can also run `grep' and then
visit the lines on which matches were found.  To do this, type `M-x
grep' with an argument line that contains 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.  The output from `grep' goes in the
`*grep*' buffer, and you can find the matching lines in the source with
`C-x `' and <RET> just like compiler errors.

   Note: a shell is used to run the compile command, but the shell is
told that it should be noninteractive.  This means in particular that
the shell starts up 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.  (The init file name may be `.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.  In csh, here is how to do it:

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

And here's how to do it in bash:

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

   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 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.  In an Rlogin
buffer (*note Remote Host::), Compilation minor mode automatically
accesses remote source files by FTP (*note File Names::).

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

20.2 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 you can also run DBX, SDB or XDB if you
have them.  GUD can also serve as an interface to the Perl's debugging
mode.

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


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

20.2.1 Starting GUD
-------------------

There are five 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.  This command creates a buffer
     for input and output to GDB, and switches to it.  If a GDB buffer
     already exists, it just switches to that buffer.

`M-x dbx <RET> FILE <RET>'
     Similar, but run DBX instead of GDB.

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

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

     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.

   You can only run one debugger process at a time.

   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 wild cards and variables are not
allowed.  GUD assumes that the first argument not preceded by a `-' is
the executable file name.


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

20.2.2 Debugger Operation
-------------------------

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.  The
debugger displays the source files of the program by visiting them in
Emacs buffers.  An arrow (`=>') in one of these buffers indicates the
current execution line.  Moving point in this buffer does not move the
arrow.

   You can start editing these source files at any time in the buffers
that were made to display them.  The arrow is not part of the file's
text; it appears only on the screen.  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.

   If you wish, you can control your debugger process entirely through
the debugger buffer, which uses a variant of Shell mode.  All the usual
commands for your debugger are available, and you can use the Shell mode
history commands to repeat them.  *Note Shell Mode::.


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

20.2.3 Commands of GUD
----------------------

The GUD interaction buffer uses a variant of Shell mode, so the
commands of Shell mode are available (*note Shell Mode::).  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.

   The breakpoint commands are usually used in source file buffers,
because that is the 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 bindings that start with `C-x C-a' are available in the GUD buffer
and also in source files.

`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-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.  If
     you use this command in the GUD interaction buffer, it applies to
     the line where the program last stopped.

   The above commands are common to all supported debuggers.  If you are
using GDB or (some versions of) DBX, these additional commands are
available:

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

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

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

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

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

   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,  Prev: Commands of GUD,  Up: Debuggers

20.2.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.  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 use the command thus defined 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'
     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.


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

20.3 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
     <LFD> 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 Interaction,  Prev: Executing Lisp,  Up: Building

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

   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-library', or with `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 prints a warning, because it's likely that somebody made changes to
the `.el' file and forgot to recompile it.

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

   Emacs Lisp code can be compiled into byte-code which loads faster,
takes up less space when loaded, and executes faster.  *Note Byte
Compilation: (elisp)Byte Compilation.  By convention, the compiled code
for a library goes in a separate file whose name consists of the
library source file with `c' appended.  Thus, the compiled code for
`foo.el' goes in `foo.elc'.  That's why `load-library' searches for
`.elc' files first.


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

20.5 Evaluating Emacs-Lisp Expressions
======================================

Lisp programs intended to be run in Emacs should be edited in
Emacs-Lisp mode; this happens automatically for file names ending in
`.el'.  By contrast, Lisp mode itself is used for editing Lisp programs
intended for other Lisp systems.  To switch to Emacs-Lisp mode
explicitly, use the command `M-x emacs-lisp-mode'.

   For testing of Lisp programs to run in Emacs, it is often useful to
evaluate part of the program as it is found in the Emacs buffer.  For
example, after changing the text of a Lisp function definition,
evaluating the definition installs the change for future calls to the
function.  Evaluation of Lisp expressions is also useful in any kind of
editing, for invoking noninteractive functions (functions that are not
commands).

`M-:'
     Read a single Lisp expression in the minibuffer, evaluate it, and
     print the value in the echo area (`eval-expression').

`C-x C-e'
     Evaluate the Lisp expression before point, and print the value in
     the echo area (`eval-last-sexp').

`C-M-x'
     Evaluate the defun containing or after point, and print the value
     in the echo area (`eval-defun').

`M-x eval-region'
     Evaluate all the Lisp expressions in the region.

`M-x eval-current-buffer'
     Evaluate all the Lisp expressions in the buffer.

   `M-:' (`eval-expression') is the most basic command for evaluating a
Lisp expression interactively.  It reads the expression using the
minibuffer, so you can execute any expression on a buffer regardless of
what the buffer contains.  When the expression is evaluated, the current
buffer is once again the buffer that was current when `M-:' was typed.

   `M-:' can easily confuse users who do not understand it.  Therefore,
`eval-expression' is normally a disabled command.  Attempting to use
this command asks for confirmation and gives you the option of enabling
it; once you enable the command, confirmation will no longer be
required for it.  *Note Disabling::.

   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.  This special
feature is convenient for debugging Lisp programs.

   The command `C-x C-e' (`eval-last-sexp') evaluates the Lisp
expression preceding point in the buffer, and displays the value in the
echo area.  It is available in all major modes, not just Emacs-Lisp
mode.  It does not treat `defvar' specially.

   If `C-M-x' or `C-x C-e' is given a numeric argument, it inserts the
value into the current buffer at point, rather than displaying it in
the echo area.  The argument's value does not matter.

   The most general command for evaluating Lisp expressions from a
buffer is `eval-region'.  `M-x eval-region' parses the text of the
region as one or more Lisp expressions, evaluating them one by one.
`M-x eval-current-buffer' is similar but evaluates the entire buffer.
This is a reasonable way to install the contents of a file of Lisp code
that you are just 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.


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

20.6 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 <LFD> 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 <LFD>.

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

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


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

20.7 Running an External Lisp
=============================

Emacs has facilities for running programs in other Lisp systems.  You
can run a Lisp process as an inferior of Emacs, and pass expressions to
it to be evaluated.  You can also pass changed function definitions
directly from the Emacs buffers in which you edit the Lisp programs to
the inferior Lisp process.

   To run an inferior Lisp process, type `M-x run-lisp'.  This runs the
program named `lisp', the same program you would run by typing `lisp'
as a shell command, with both input and output going through an Emacs
buffer named `*lisp*'.  That is to say, any "terminal output" from Lisp
will go into the buffer, advancing point, and any "terminal input" for
Lisp comes from text in the buffer.  (You can change the name of the
Lisp executable file by setting the variable `inferior-lisp-program'.)

   To give input to Lisp, go to the end of the buffer and type the
input, terminated by <RET>.  The `*lisp*' buffer is in Inferior Lisp
mode, which combines the special characteristics of Lisp mode with most
of the features of Shell mode (*note Shell Mode::).  The definition of
<RET> to send a line to a subprocess is one of the features of Shell
mode.

   For the source files of programs to run in external Lisps, use Lisp
mode.  This mode can be selected with `M-x lisp-mode', and is used
automatically for files whose names end in `.l', `.lsp', or `.lisp', as
most Lisp systems usually expect.

   When you edit a function in a Lisp program you are running, the
easiest way to send the changed definition to the inferior Lisp process
is the key `C-M-x'.  In Lisp mode, this runs the function
`lisp-eval-defun', which finds the defun around or following point and
sends it as input to the Lisp process.  (Emacs can send input to any
inferior process regardless of what buffer is current.)

   Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
programs to be run in Emacs): in both modes it has the effect of
installing the function definition that point is in, but the way of
doing so is different according to where the relevant Lisp environment
is found.  *Note Executing Lisp::.


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

21 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 would be able to 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::.

* 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

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

   Abbrev definitions can be "mode-specific"--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.

   Abbrevs can be defined interactively during the editing session.
Lists of abbrev definitions can also be saved in files and reloaded 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

21.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 kill-all-abbrevs'
     This command discards all abbrev definitions currently in effect,
     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 text already in the buffer is the abbrev, rather than its
expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
instead of `C-x a l'.  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).

   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 for 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 the abbrev definitions there are,
both global and local.


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

21.3 Controlling Abbrev Expansion
=================================

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 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' (a non-`nil' value chooses the first of the two
expansions).

   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 with a prefix attached; 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.

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

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


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

21.4 Examining and Editing Abbrevs
==================================

`M-x list-abbrevs'
     Display a list of all abbrev definitions.

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

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

   `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

21.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.  `M-x quietly-read-abbrev-file' is the same except that it does
not display a message in the echo area saying that it is doing its
work; it is actually useful primarily in the `.emacs' file.  If an
empty argument is given to either of these functions, they use the file
name specified in the variable `abbrev-file-name', which is by default
`"~/.abbrev_defs"'.

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

21.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 abbrevs 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 considering the entire buffer
before point, it searches the text after point.  The variable
`dabbrev-limit', if non-`nil', specifies how far in the buffer to
search for an expansion.

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

   A negative argument to `M-/', as in `C-u - M-/', says to search
first for expansions after point, and second for expansions before
point.  If you repeat the `M-/' to look for another expansion, do not
specify an argument.  This tries 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 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 abbreviation.  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

21.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.  If you set `dabbrev-case-fold-search' to `nil',
then the word and the expansion must match in case.

   The value of `dabbrev-case-fold-search' may be any expression.
Dynamic abbrev expansion evaluates that expression, and ignores case
while searching if its value is not `nil'.  The default value of
`dabbrev-case-fold-search' is `case-fold-search', so normally the value
of `case-fold-search' controls the decision.  The reason why dynamic
abbrev expansion normally ignores case when searching for expansions is
that normally the value of `case-fold-search' is `t'.

   Normally, dynamic abbrev expansion preserves the case pattern _of
the word you are expanding_, by converting the expansion to that case
pattern.  If you set `dabbrev-case-replace' to `nil', the expansion is
copied without conversion.

   The variables `dabbrev-case-fold-search' and `dabbrev-case-replace'
are handled in a special way.  Their values are actually Lisp
expressions which are evaluated each time a decision needs to be made.
If the expression's value is non-`nil', then case is ignored in
searching, or converted on replacement, respectively.  If the
expression's value is `nil', case is not ignored or not converted.  The
default values let the variables `case-fold-search' (*note Search
Case::) and `case-replace' (*note Replacement and Case::) control what
to do.

   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: abbreviations 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 abbreviation 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
abbreviation should ignore.


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

22 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 pretty 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' (*note
Hooks::).

* 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,  Prev: Picture,  Up: Picture

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

   Picture mode provides erasure instead of deletion and killing of
text.  <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.  <LFD> (`picture-duplicate-line') inserts
below the current line another line with the same contents.

   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

22.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 <'
     Move left after insertion (`picture-movement-left').

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

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

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

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

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

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

`C-c \'
     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

22.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'.  *Note Just Spaces::.


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

22.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 overwriting 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,  Up: Top

23 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 (`mail').

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

`C-x 5 m'
     Likewise, but make a new frame (`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' (`mail') selects a buffer named `*mail*' and
initializes it with the skeleton of an outgoing message.  `C-x 4 m'
(`mail-other-window') selects the `*mail*' buffer in a different
window, leaving the previous current buffer visible.  `C-x 5 m'
(`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 is left 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.

* 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.
* Spook: Distracting NSA.    How to distract the NSA's attention.


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

23.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 the date and sender are created automatically after the
message is sent.  Others, such as the recipient names, must be
specified by you in order to send the message properly.

   Mail mode provides a few commands to help you edit some header
fields, and some are preinitialized in the buffer automatically at
times.  You can insert and edit header fields using ordinary editing
commands.

   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@prep.ai.mit.edu
     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

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

`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, but whose readers should not regard the message as
     addressed to 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'.

`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
     to Rmail format; otherwise, Emacs writes the message in system
     mail file format.

     To put a fixed file name as in `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 a 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::).

   The `To', `CC', `BCC' and `FCC' fields can appear any number of
times, to specify many places to send the message.  The `To', `CC', and
`BCC' fields can have continuation lines.  All the lines starting with
whitespace, following the line on which the field starts, are
considered part of the field.  For example,

     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'
     Just the email address, as in `king@grassland.com'.

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

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


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

23.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@prep.ai.mit.edu' plus
a local address of your own, put in this line:

     alias maingnu gnu@prep.ai.mit.edu local-gnu

   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@prep.ai.mit.edu")

   `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.  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-setup-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-setup-hook
               '(lambda ()
                  (substitute-key-definition
                    'next-line 'mail-abbrev-next-line
                    mail-mode-map global-map)
                  (substitute-key-definition
                    'end-of-buffer 'mail-abbrev-end-of-buffer
                    mail-mode-map global-map)))


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

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

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

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

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

`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-y'
     Yank the selected message from Rmail (`mail-yank-original').  This
     command does nothing unless your command to start sending a
     message was issued with Rmail.

`C-c C-q'
     Fill all paragraphs of yanked old messages, each individually
     (`mail-fill-yanked-message').

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

   There are two ways to send the message.  `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.

   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').  For completion purposes, the valid
mailing addresses are taken to be the local users' names plus your
personal mail aliases.  Additionally, if your site provides a mail
directory or a specific host to use for any unrecognized user name, you
can arrange to query that host for completion--see the variables
`mail-directory-process' and `mail-directory-stream' in the source code.

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

   Mail mode provides special commands for editing the headers and text
of the message before you send it.  There are five commands defined to
move point to particular header fields, all based on the prefix `C-c
C-f' (`C-f' is for "field").  They are `C-c C-f C-t' (`mail-to') to
move to the `To' field, `C-c C-f C-s' (`mail-subject') for the
`Subject' field, `C-c C-f C-c' (`mail-cc') for the `CC' field, `C-c C-f
C-b' (`mail-bcc') for the `BCC' field, and `C-c C-f C-f' (`mail-fcc')
for the `FCC' field.  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.

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

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

   After using `C-c C-y', you can use the command `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', after first setting the fill prefix appropriately
to handle the indentation.  *Note Filling::.

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

   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.  That is a useful thing to do if
you have saved draft message text in a file.  In a file-visiting buffer,
`C-c C-c' does not clear the modified flag, because only saving the
file should do that.  As a result, you don't get a warning about trying
to send the same message twice.

   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 puts
in the default contents of the buffer.  After these default contents
are inserted, `mail-setup-hook' runs.


File: emacs,  Node: Distracting NSA,  Prev: Mail Mode,  Up: Sending Mail

23.5 Distracting the NSA
========================

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


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

24 Reading Mail with Rmail
**************************

Rmail is an Emacs subsystem for reading and disposing of mail that you
receive.  Rmail stores mail messages in files called Rmail files.
Reading the 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.
* 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.
* 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.


File: emacs,  Node: Rmail Basics,  Next: Rmail Scrolling,  Up: Rmail

24.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
assigned consecutive integers as 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 the file is saved.  You can save it with `s'
(`rmail-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 and then switches to another buffer.  But there is no
need to `exit' formally.  If you switch from Rmail to editing in other
buffers, and never happen to switch back, you have exited.  (The Rmail
command `b', `rmail-bury', does this for you.)  Just make sure to save
the Rmail file eventually (like any other file you have changed).  `C-x
s' is a good enough way to do this (*note Saving::).


File: emacs,  Node: Rmail Scrolling,  Next: Rmail Motion,  Prev: Rmail Basics,  Up: Rmail

24.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 to type.

`<SPC>'
     Scroll forward (`scroll-up').

`<DEL>'
     Scroll backward (`scroll-down').

`.'
     Scroll to start of message (`rmail-beginning-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.


File: emacs,  Node: Rmail Motion,  Next: Rmail Deletion,  Prev: Rmail Scrolling,  Up: Rmail

24.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 Labels::).  Move forward to see
the other new messages; move backward to reexamine 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

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

   Whenever Rmail deletes a message, it invokes the function(s) listed
in `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 Labels::.


File: emacs,  Node: Rmail Inbox,  Next: Rmail Files,  Prev: Rmail Deletion,  Up: Rmail

24.5 Rmail Files and Inboxes
============================

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 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 is `/var/mail/USERNAME',
`/usr/spool/mail/USERNAME', or `/usr/mail/USERNAME', depending on your
operating system.  You can specify the inbox file(s) for any Rmail file
with the command `set-rmail-inbox-list'; see *Note Rmail Files::.

   Some sites use a method called POP for accessing users' inbox data
instead of storing the data in inbox files.  `movemail' can work with
POP if you compile it with the macro `MAIL_USE_POP' defined, and then
install it setuid to `root'.  It is safe to install `movemail' in this
way.  Note: `movemail' only works with POP3, not with older versions of
POP.

   Assuming you have compiled and installed `movemail' appropriately,
you can specify a POP inbox with a "file name" of the form
`po:USERNAME'.  `movemail' handles such a name by opening a connection
to the POP server.  The `MAILHOST' environment variable specifies the
machine to look for the server on.

   Accessing mail via POP may require a password.  If the variable
`rmail-pop-password' is non-`nil', it specifies the password to use for
POP.  Alternatively, if `rmail-pop-password-required' is non-`nil',
then Rmail asks you for the password to use.

   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 on systems where 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 truncates
the inbox file.  This way, a system crash may cause duplication of mail
between the inbox and the Rmail file, but cannot lose mail.

   When `movemail' copies mail from an inbox in the system's mailer
directory, it actually puts it in an intermediate file
`~/.newmail-INBOXNAME'.  Once it finishes, Rmail reads that file,
merges the new mail, 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.


File: emacs,  Node: Rmail Files,  Next: Rmail Output,  Prev: Rmail Inbox,  Up: Rmail

24.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 may
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.

   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.  Choose first the menu
bar Classify item, then from 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 a list of inboxes is specified, 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 specified 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

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

   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.

   You can also output a message to an Rmail file chosen with a menu.
Choose first the menu bar Classify item, then from the Classify menu
choose the Output Rmail 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 gives the original copy of the message the `filed'
attribute, so that `filed' appears in the mode line when such a message
is current.  If you like to keep just a single copy of every mail
message, set the variable `rmail-delete-after-output' to `t'; then the
`o' and `C-o' 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 Reply,  Prev: Rmail Output,  Up: Rmail

24.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".  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').

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

   Some labels such as `deleted' and `filed' have built-in meanings and
are assigned to or removed from 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 file output commands (*note Rmail Files::).

`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 the user, and have
no standard meaning.


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

24.9 Sending Replies
====================

Rmail has several commands that use Mail mode to send outgoing mail.
*Note Sending Mail::, for information on using Mail mode.  What are
documented here 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'--are available in Rmail mode and work just as they
usually do.

`m'
     Send a message (`rmail-mail').

`c'
     Continue editing already started outgoing message
     (`rmail-continue').

`r'
     Send a reply to the current Rmail message (`rmail-reply').

`f'
     Forward 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' and `In-reply-to'
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'.

   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 right for you.  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 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; it defaults to
nil.

   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 `Don't Send' item in the `Mail' menu.


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

24.10 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, the sender, the labels, and the subject.  Almost all Rmail
commands are valid in the summary buffer also; these apply to the
message described by the current line of the summary.  Moving point in
the summary buffer selects messages as you move to their summary lines.

   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

24.10.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 message 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').

   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.

   Note that there is only one summary buffer for any Rmail file;
making one kind of summary discards any previously made summary.

   The variable `rmail-summary-window-size' says how many lines to use
for the summary window.


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

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

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

24.11 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 Editing,  Prev: Rmail Sorting,  Up: Rmail

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

   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.  Selecting
the message again also reformats.

   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 used with a window system that supports multiple fonts, 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 for the `highlight' face.  That is
worth doing because the `highlight' face is used for other kinds of
highlighting as well.  *Note Faces::, for how to do this.

   To turn off highlighting entirely in Rmail, set
`rmail-highlighted-headers' to `nil'.


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

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


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

24.14 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

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


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

24.16 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
ever seeing the real text of the message.

   To view a buffer using 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: Dired,  Next: Calendar/Diary,  Prev: Rmail,  Up: Top

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

* Menu:

* Enter: Dired Enter.         How to invoke Dired.
* Commands: Dired Commands.   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.
* 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.


File: emacs,  Node: Dired Enter,  Next: Dired Commands,  Up: Dired

25.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 which files to list.  Where `dired' differs from
`list-directory' is in putting 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 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 after you finish entering the
directory specification.

   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 Commands,  Next: Dired Deletion,  Prev: Dired Enter,  Up: Dired

25.2 Commands in the Dired Buffer
=================================

The Dired buffer is "read-only", and inserting text in it is not
useful, so ordinary printing characters such as `d' and `x' are used
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.

   All the usual Emacs cursor motion commands are available in Dired
buffers.  Some special purpose cursor motion commands are also
provided.  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.


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

25.3 Deleting Files with Dired
==============================

The primary use of Dired is to "flag" files for deletion and then
delete the files previously 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'.  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 files are flagged for deletion rather than deleted immediately to
reduce the danger of deleting a file accidentally.  Until you direct
Dired to expunge the flagged files, you can remove deletion flags using
the commands `u' and <DEL>.  `u' works just like `d', but removes flags
rather than making flags.  <DEL> moves upward, removing flags; it is
like `u' with numeric argument automatically negated.

   To delete the flagged files, type `x' (`dired-expunge').  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 shortened Dired buffer 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.


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

25.4 Flagging Many Files
========================

`#'
     Flag all auto-save files (files whose names start and end with `#')
     for deletion (*note Auto Save::).

`~'
     Flag all backup files (files whose names end with `~') for deletion
     (*note Backup::).

`. (Period)'
     Flag excess numeric backup files for deletion.  The oldest and
     newest few backup files of any one file are exempt; the middle
     ones are flagged.

`% d REGEXP <RET>'
     Flag for deletion all files whose names match the regular
     expression REGEXP (`dired-flag-files-regexp').

   The `#', `~' and `.' commands flag many files for deletion, based on
their file names.  These commands are useful precisely because they do
not actually delete any files; you can remove the deletion flags from
any flagged files that you really wish to keep.

   `#' flags for deletion all files whose names look like auto-save
files (*note Auto Save::)--that is, files whose names begin and end
with `#'.  `~' flags for deletion all files whose names say they are
backup files (*note Backup::)--that is, whose names end in `~'.

   `.' (Period) 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 subdirectories by hiding them (*note
Hiding Subdirectories::).


File: emacs,  Node: Dired Visiting,  Next: Marks vs Flags,  Prev: Flagging Many Files,  Up: Dired

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


File: emacs,  Node: Marks vs Flags,  Next: Operating on Files,  Prev: Dired Visiting,  Up: Dired

25.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, aside from "expunge" (`x'), look for files marked with `*'.

   Here are some commands for marking with `*' (and also for
unmarking).  (*Note Dired Deletion::, for commands to flag and unflag
files.)

`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 actually directories, except for
     `.' and `..' (`dired-mark-directories').  With a numeric argument,
     unmark all those files.

`M-<DEL> MARKCHAR'
     Remove all marks that use the character MARKCHAR
     (`dired-unmark-all-files').  If you specify <RET> as MARKCHAR,
     this command removes all marks, no matter what the marker
     character is.

     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, `!' to remove the marks from the
     remaining files without asking about them.

`c OLD NEW'
     Replace all marks that use the character OLD with marks that use
     the character NEW (`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 is a
     space (` '), then the command operates on all unmarked files; if
     NEW is a space, then the command unmarks the files it acts on.

     To illustrate the power of this command, here is how to put `*'
     marks on all the files that are unmarked, while unmarking all
     those that have `*' marks:

          c * t  c SPC *  c t SPC

`% m REGEXP <RET>'
     Mark (with `*') all files whose names match the regular expression
     REGEXP (`dired-mark-files-regexp').  `% m' is like `% d', except
     that it marks files with `*' instead of flagging with `D'.  *Note
     Flagging Many Files::.

     Only the non-directory part of the file name is used in matching.
     Use `^' and `$' to anchor matches.  Exclude subdirectories by
     hiding them (*note Hiding Subdirectories::).


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

25.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 use the following convention to
decide which files to manipulate:

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

   Here are the file-manipulating commands that operate on files in this
way.  (Some other Dired commands, such as `!' and the `%' commands,
also use these conventions to decide which files to work on.)

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

     If `dired-copy-preserve-time' is non-`nil', then copying with this
     command sets the modification time of the new file to be the same
     as that of the old file.

`R NEW <RET>'
     Rename the specified files (`dired-do-rename').  The argument NEW
     is the directory to rename into, or (if renaming a single file)
     the new name.

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

`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-file' uses; *note
     Hardcopy::).

`Z'
     Compress or uncompress the specified files (`dired-do-compress').
     If the file appears to be a compressed file, it is uncompressed;
     otherwise, it is compressed.

`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 FROM <RET> TO <RET>'
     Perform `query-replace-regexp' on each of the specified files,
     replacing matches for FROM (a regular expression) with the string
     TO (`dired-do-query-replace').

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

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


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

25.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.  There are two ways of applying a shell command to
multiple files:

   * If you use `*' in the shell command, then it 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 the command string doesn't contain `*', then it runs once _for
     each file_, with the file name added at the end.

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

   What if you want to run the shell command once for each file but with
the file name inserted in the middle?  Or if you want to use the file
names in a more complicated fashion?  Use a shell loop.  For example,
this shell command would run `uuencode' on each of the specified files,
writing the output into a corresponding `.uu' file:

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

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

   The `!' command does not attempt to update the Dired buffer to show
new or modified files, because it doesn't really 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

25.9 Transforming File Names in Dired
=====================================

Here are commands that alter file names in a systematic way:

`% 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 in the Dired buffer.
They read two arguments: a regular expression FROM, and a substitution
pattern TO.

   The commands match each "old" file name against the regular
expression 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 `query-replace-regexp' (*note Query
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 filename.)

   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.

   Often you will want to apply the command to all files matching the
same REGEXP that you use in the command.  To do this, mark those files
with `% m REGEXP <RET>', then use the same regular expression in the
command to operate on the files.  To make this easier, 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

25.10 File Comparison with Dired
================================

Here are two Dired commands that compare specified files using `diff'.

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

`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 backup version of your choice.

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


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

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

   But usually all the subdirectories are too many; usually you will
prefer to include specific subdirectories only.  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 `k' to delete the subdirectory.  *Note
Dired Updating::.


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

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

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


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

25.13 Hiding Subdirectories
===========================

"Hiding" a subdirectory means to make it invisible, except for its
header line, via selective display (*note Selective Display::).

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

   The subdirectory hiding commands toggle; that is, they hide what was
visible, and show what was hidden.


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

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

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

`s'
     Toggle between sorting by file name and sorting by date/time
     (`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').
This command applies to the next N files, or to the marked files if
any, or to the current file.  Updating them means reading their current
status from the file system and changing the buffer to reflect it
properly.

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

   To delete the specified _file lines_--not the files, just the
lines--type `k' (`dired-do-kill-lines').  This command applies to the
next N files, or to the marked files if any, or to the current file.

   If you kill the line for a file that is a directory, the directory's
contents are also deleted from the buffer.  Typing `C-u k' on the
header line for a subdirectory is another way to delete a 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 each subdirectory.

   The files in a Dired buffers are normally in listed 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,  Prev: Dired Updating,  Up: Dired

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

   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
`-ldi' for `ls'.  If your listings are corrupted, you may need to
change the value of this variable.


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

26 The Calendar and the Diary
*****************************

Emacs provides the functions of a desk calendar, with a diary of
planned or past events.  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; `C-Mouse-3' brings up a menu of commonly used calendar
features that are independent of any particular date.  To exit the
calendar, type `q'.  *Note Customizing the Calendar and Diary:
(elisp)Calendar, for customization information about the calendar and
diary.

* 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.
* TeX Calendar::          Print a calendar using TeX.
* 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.
* Daylight Savings::      How to specify when daylight savings time is active.


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

26.1 Movement in the Calendar
=============================

Calendar mode lets you 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, convert it to other
calendars; moving longer 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

26.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-forward-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's time.  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, which usually involves skipping across the end of a 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

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

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

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

   `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

26.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 it means moving the strip so that new months become
visible in the window.

`C-x <'
     Scroll calendar one month forward (`scroll-calendar-left').

`C-x >'
     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.  `C-x <' scrolls the
calendar contents one month to the left; that is, it moves the display
forward in time.  `C-x >' scrolls the contents to the right, which
moves 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

26.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 printed is
_inclusive_; that is, it includes the days specified by mark and point.


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

26.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 (`scroll-other-window').

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

   To print 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 number of days elapsed includes the selected date.
The number 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') to
scroll the other window.  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: TeX Calendar,  Next: Holidays,  Prev: General Calendar,  Up: Calendar/Diary

26.5 TeX Calendar
=================

The Calendar TeX 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-landscape-year').

`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 weekly and monthly calendars only).


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

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

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

   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> in the calendar window to
scroll that list.

   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 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 American holidays and the major
Christian, Jewish, and Islamic holidays; also the solstices and
equinoxes.

   The dates used by Emacs for holidays are based on _current
practice_, not historical fact.  Historically, for instance, the start
of daylight savings time and even its existence have varied from year to
year, but present American law mandates that daylight savings time
begins on the first Sunday in April.  In an American locale, Emacs
always uses this definition, even though it is wrong for some prior
years.


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

26.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 savings time_.  *Note Daylight Savings::, for how daylight
savings 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

26.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 savings, when appropriate); but if
the variable `calendar-time-zone' is void, Coordinated Universal Time
(the Greenwich time zone) is used.  *Note Daylight Savings::.


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

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

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

26.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.)

   Put point on the desired date of the Gregorian calendar, then type
the appropriate keys.  The `p' is a mnemonic for "print" since Emacs
"prints" the equivalent date in the echo area.


File: emacs,  Node: From Other Calendar,  Next: Mayan Calendar,  Prev: To Other Calendar,  Up: Other Calendars

26.9.3 Converting From Other Calendars
--------------------------------------

You can use the other supported calendars to specify a date to move to.
This section describes the commands for doing this using calendars
other than Mayan; for the Mayan calendar, see the following section.

`g c'
     Move to a date specified in the ISO commercial calendar
     (`calendar-goto-iso-date').

`g j'
     Move to a date specified in the Julian calendar
     (`calendar-goto-julian-date').

`g a'
     Move to a date specified in astronomical (Julian) day number
     (`calendar-goto-astro-day-number').

`g h'
     Move to a date specified in the Hebrew calendar
     (`calendar-goto-hebrew-date').

`g i'
     Move to a date specified in the Islamic calendar
     (`calendar-goto-islamic-date').

`g f'
     Move to a date specified in the French Revolutionary calendar
     (`calendar-goto-french-date').

`g C'
     Move to a date specified in the Chinese calendar
     (`calendar-goto-chinese-date').

`g p'
     Move to a date specified in the Persian calendar
     (`calendar-goto-persian-date').

`g k'
     Move to a date specified in the Coptic calendar
     (`calendar-goto-coptic-date').

`g e'
     Move to a date specified in the Ethiopic calendar
     (`calendar-goto-ethiopic-date').

   These commands ask you for a date on the other calendar, move point
to the Gregorian calendar date equivalent to that date, and display the
other calendar's date in the echo area.  Emacs uses strict completion
(*note Completion::) whenever it asks you to type a month name, so you
don't have to worry about the spelling of Hebrew, Islamic, or French
names.

   One common question concerning the Hebrew calendar is the computation
of the anniversary of a date of death, called a "yahrzeit."  The Emacs
calendar includes a facility for such calculations.  If you are in the
calendar, the command `M-x list-yahrzeit-dates' asks you for a range of
years and then displays a list of the yahrzeit dates for those years
for the date given by point.  If you are not in the calendar, this
command first asks you for the date of death and the range of years,
and then displays the list of yahrzeit dates.


File: emacs,  Node: Mayan Calendar,  Prev: From Other Calendar,  Up: Other Calendars

26.9.4 Converting from the Mayan Calendar
-----------------------------------------

Here are the commands to select dates based on the Mayan calendar:

`g m l'
     Move to a date specified by the long count calendar
     (`calendar-goto-mayan-long-count-date').

`g m n t'
     Move to the next occurrence of a place in the tzolkin calendar
     (`calendar-next-tzolkin-date').

`g m p t'
     Move to the previous occurrence of a place in the tzolkin calendar
     (`calendar-previous-tzolkin-date').

`g m n h'
     Move to the next occurrence of a place in the haab calendar
     (`calendar-next-haab-date').

`g m p h'
     Move to the previous occurrence of a place in the haab calendar
     (`calendar-previous-haab-date').

`g m n c'
     Move to the next occurrence of a place in the calendar round
     (`calendar-next-calendar-round-date').

`g m p c'
     Move to the previous occurrence of a place in the calendar round
     (`calendar-previous-calendar-round-date').

   To understand these commands, you need to understand the Mayan
calendars.  The "long count" is a counting of days with these units:

     1 kin = 1 day   1 uinal = 20 kin   1 tun = 18 uinal
     1 katun = 20 tun   1 baktun = 20 katun

Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
tun, 16 uinal, and 6 kin.  The Emacs calendar can handle Mayan long
count dates as early as 7.17.18.13.1, but no earlier.  When you use the
`g m l' command, type the Mayan long count date with the baktun, katun,
tun, uinal, and kin separated by periods.

   The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
independent cycles of 13 and 20 days.  Since this cycle repeats
endlessly, Emacs provides commands to move backward and forward to the
previous or next point in the cycle.  Type `g m p t' to go to the
previous tzolkin date; Emacs asks you for a tzolkin date and moves point
to the previous occurrence of that date.  Similarly, type `g m n t' to
go to the next occurrence of a tzolkin date.

   The Mayan haab calendar is a cycle of 365 days arranged as 18 months
of 20 days each, followed a 5-day monthless period.  Like the tzolkin
cycle, this cycle repeats endlessly, and there are commands to move
backward and forward to the previous or next point in the cycle.  Type
`g m p h' to go to the previous haab date; Emacs asks you for a haab
date and moves point to the previous occurrence of that date.
Similarly, type `g m n h' to go to the next occurrence of a haab date.

   The Maya also used the combination of the tzolkin date and the haab
date.  This combination is a cycle of about 52 years called a _calendar
round_.  If you type `g m p c', Emacs asks you for both a haab and a
tzolkin date and then moves point to the previous occurrence of that
combination.  Use `g m n c' to move point to the next occurrence of a
combination.  These commands signal an error if the haab/tzolkin date
combination you have typed is impossible.

   Emacs uses strict completion (*note Strict Completion::) whenever it
asks you to type a Mayan name, so you don't have to worry about
spelling.


File: emacs,  Node: Diary,  Next: Appointments,  Prev: Other Calendars,  Up: Calendar/Diary

26.10 The Diary
===============

The Emacs diary keeps track of appointments or other events on a daily
basis, in conjunction with the calendar.  To use the diary feature, you
must first create a "diary file" containing a list of events and their
dates.  Then Emacs can automatically pick out and display the events
for today, for the immediate future, or for any specified date.

   By default, Emacs uses `~/diary' as the diary file.  This is the
same file that the `calendar' utility uses.  A sample `~/diary' file is:

     12/22/1988  Twentieth wedding anniversary!!
     &1/1.       Happy New Year!
     10/22       Ruth's birthday.
     * 21, *:    Payday
     Tuesday--weekly meeting with grad students at 10am
              Supowit, Shen, Bitner, and Kapoor to attend.
     1/13/89     Friday the thirteenth!!
     &thu 4pm    squash game with Lloyd.
     mar 16      Dad's birthday
     April 15, 1989 Income tax due.
     &* 15       time cards due.

This example uses extra spaces to align the event descriptions of most
of the entries.  Such formatting is purely a matter of taste.

   Although you probably will start by creating a diary manually, Emacs
provides a number of commands to let you view, add, and change diary
entries.

* Menu:

* Diary Commands::         Viewing diary entries and associated calendar dates.
* Format of Diary File::   Entering events in your diary.
* Date Formats::	   Various ways you can specify dates.
* Adding to Diary::	   Commands to create diary entries.
* Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.


File: emacs,  Node: Diary Commands,  Next: Format of Diary File,  Up: Diary

26.10.1 Commands Displaying Diary Entries
-----------------------------------------

Once you have created a `~/diary' file, you can use the calendar to
view it.  You can also view today's events outside of Calendar mode.

`d'
     Display all diary entries for the selected date
     (`view-diary-entries').

`Mouse-2 Diary'
     Display all diary entries for the date you click on.

`s'
     Display the entire diary file (`show-all-diary-entries').

`m'
     Mark all visible dates that have diary entries
     (`mark-diary-entries').

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

`M-x print-diary-entries'
     Print hard copy of the diary display as it appears.

`M-x diary'
     Display all diary entries for today's date.

   Displaying the diary entries with `d' shows in a separate window the
diary entries for the selected date in the calendar.  The mode line of
the new window shows the date of the diary entries and any holidays
that fall on that date.  If you specify a numeric argument with `d', it
shows all the diary entries for that many successive days.  Thus, `2 d'
displays all the entries for the selected date and for the following
day.

   Another way to display the diary entries for a date is to click
`Mouse-2' on the date, and then choose `Diary' from the menu that
appears.

   To get a broader view of which days are mentioned in the diary, use
the `m' command.  This displays the dates that have diary entries fall
in a different face (or places a `+' after these dates, if display with
multiple faces is not available).  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 turns off holiday marks (*note Holidays::).

   To see the full diary file, rather than just some of the entries, use
the `s' command.

   Display of selected diary entries uses the selective display feature
to hide entries that don't apply.  This is the same feature that Outline
mode uses to show part of an outline (*note Outline Mode::).

   The diary buffer as you see it is an illusion, so simply printing the
buffer does not print what you see on your screen.  There is a special
command to print hard copy of the diary buffer _as it appears_; this
command is `M-x print-diary-entries'.  It sends the data directly to
the printer.  You can customize it like `lpr-region' (*note Hardcopy::).

   The command `M-x diary' displays the diary entries for the current
date, independently of the calendar display, and optionally for the next
few days as well; the variable `number-of-diary-entries' specifies how
many days to include.  *Note Calendar/Diary Options:
(elisp)Calendar/Diary Options.

   If you put `(diary)' in your `.emacs' file, this automatically
displays a window with the day's diary entries, when you enter Emacs.
The mode line of the displayed window shows the date and any holidays
that fall on that date.


File: emacs,  Node: Format of Diary File,  Next: Date Formats,  Prev: Diary Commands,  Up: Diary

26.10.2 The Diary File
----------------------

Your "diary file" is a file that records events associated with
particular dates.  The name of the diary file is specified by the
variable `diary-file'; `~/diary' is the default.  The `calendar'
utility program supports a subset of the format allowed by the Emacs
diary facilities, so you can use that utility to view the diary file,
with reasonable results aside from the entries it cannot understand.

   Each entry in the diary file describes one event and consists of one
or more lines.  An entry always begins with a date specification at the
left margin.  The rest of the entry is simply text to describe the
event.  If the entry has more than one line, then the lines after the
first must begin with whitespace to indicate they continue a previous
entry.  Lines that do not begin with valid dates and do not continue a
preceding entry are ignored.

   You can inhibit the marking of certain diary entries in the calendar
window; to do this, insert an ampersand (`&') at the beginning of the
entry, before the date.  This has no effect on display of the entry in
the diary window; it affects only marks on dates in the calendar
window.  Nonmarking entries are especially useful for generic entries
that would otherwise mark many different dates.

   If the first line of a diary entry consists only of the date or day
name with no following blanks or punctuation, then the diary window
display doesn't include that line; only the continuation lines appear.
For example, this entry:

     02/11/1989
           Bill B. visits Princeton today
           2pm Cognitive Studies Committee meeting
           2:30-5:30 Liz at Lawrenceville
           4:00pm Dentist appt
           7:30pm Dinner at George's
           8:00-10:00pm concert

appears in the diary window without the date line at the beginning.
This style of entry looks neater when you display just a single day's
entries, but can cause confusion if you ask for more than one day's
entries.

   You can edit the diary entries as they appear in the window, but it
is important to remember that the buffer displayed contains the _entire_
diary file, with portions of it concealed from view.  This means, for
instance, that the `C-f' (`forward-char') command can put point at what
appears to be the end of the line, but what is in reality the middle of
some concealed line.

   _Be careful when editing the diary entries!_  Inserting additional
lines or adding/deleting characters in the middle of a visible line
cannot cause problems, but editing at the end of a line may not do what
you expect.  Deleting a line may delete other invisible entries that
follow it.  Before editing the diary, it is best to display the entire
file with `s' (`show-all-diary-entries').


File: emacs,  Node: Date Formats,  Next: Adding to Diary,  Prev: Format of Diary File,  Up: Diary

26.10.3 Date Formats
--------------------

Here are some sample diary entries, illustrating different ways of
formatting a date.  The examples all show dates in American order
(month, day, year), but Calendar mode supports European order (day,
month, year) as an option.

     4/20/93  Switch-over to new tabulation system
     apr. 25  Start tabulating annual results
     4/30  Results for April are due
     */25  Monthly cycle finishes
     Friday  Don't leave without backing up files

   The first entry appears only once, on April 20, 1993.  The second and
third appear every year on the specified dates, and the fourth uses a
wildcard (asterisk) for the month, so it appears on the 25th of every
month.  The final entry appears every week on Friday.

   You can use just numbers to express a date, as in `MONTH/DAY' or
`MONTH/DAY/YEAR'.  This must be followed by a nondigit.  In the date
itself, MONTH and DAY are numbers of one or two digits.  The optional
YEAR is also a number, and may be abbreviated to the last two digits;
that is, you can use `11/12/1989' or `11/12/89'.

   Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY,
YEAR', where the month's name can be spelled in full or abbreviated to
three characters (with or without a period).  Case is not significant.

   A date may be "generic"; that is, partially unspecified.  Then the
entry applies to all dates that match the specification.  If the date
does not contain a year, it is generic and applies to any year.
Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any
month, day, or year, respectively.  Thus, a diary entry `3/*/*' matches
any day in March of any year; so does `march *'.

   If you prefer the European style of writing dates--in which the day
comes before the month--type `M-x european-calendar' while in the
calendar, or set the variable `european-calendar-style' to `t' _before_
using any calendar or diary command.  This mode interprets all dates in
the diary in the European manner, and also uses European style for
displaying diary dates.  (Note that there is no comma after the
MONTHNAME in the European style.)  To go back to the (default) American
style of writing dates, type `M-x american-calendar'.

   You can use the name of a day of the week as a generic date which
applies to any date falling on that day of the week.  You can abbreviate
the day of the week to three letters (with or without a period) or spell
it in full; case is not significant.


File: emacs,  Node: Adding to Diary,  Next: Special Diary Entries,  Prev: Date Formats,  Up: Diary

26.10.4 Commands to Add to the Diary
------------------------------------

While in the calendar, there are several commands to create diary
entries:

`i d'
     Add a diary entry for the selected date (`insert-diary-entry').

`i w'
     Add a diary entry for the selected day of the week
     (`insert-weekly-diary-entry').

`i m'
     Add a diary entry for the selected day of the month
     (`insert-monthly-diary-entry').

`i y'
     Add a diary entry for the selected day of the year
     (`insert-yearly-diary-entry').

   You can make a diary entry for a specific date by selecting that date
in the calendar window and typing the `i d' command.  This command
displays the end of your diary file in another window and inserts the
date; you can then type the rest of the diary entry.

   If you want to make a diary entry that applies to a specific day of
the week, select that day of the week (any occurrence will do) and type
`i w'.  This inserts the day-of-week as a generic date; you can then
type the rest of the diary entry.  You can make a monthly diary entry in
the same fashion.  Select the day of the month, use the `i m' command,
and type rest of the entry.  Similarly, you can insert a yearly diary
entry with the `i y' command.

   All of the above commands make marking diary entries by default.  To
make a nonmarking diary entry, give a numeric argument to the command.
For example, `C-u i w' makes a nonmarking weekly diary entry.

   When you modify the diary file, be sure to save the file before
exiting Emacs.


File: emacs,  Node: Special Diary Entries,  Prev: Adding to Diary,  Up: Diary

26.10.5 Special Diary Entries
-----------------------------

In addition to entries based on calendar dates, the diary file can
contain "sexp entries" for regular events such as anniversaries.  These
entries are based on Lisp expressions (sexps) that Emacs evaluates as
it scans the diary file.  Instead of a date, a sexp entry contains `%%'
followed by a Lisp expression which must begin and end with
parentheses.  The Lisp expression determines which dates the entry
applies to.

   Calendar mode provides commands to insert certain commonly used sexp
entries:

`i a'
     Add an anniversary diary entry for the selected date
     (`insert-anniversary-diary-entry').

`i b'
     Add a block diary entry for the current region
     (`insert-block-diary-entry').

`i c'
     Add a cyclic diary entry starting at the date
     (`insert-cyclic-diary-entry').

   If you want to make a diary entry that applies to the anniversary of
a specific date, move point to that date and use the `i a' command.
This displays the end of your diary file in another window and inserts
the anniversary description; you can then type the rest of the diary
entry.  The entry looks like this:

     %%(diary-anniversary 10 31 1948) Arthur's birthday

This entry applies to October 31 in any year after 1948; `10 31 1948'
specifies the date.  (If you are using the European calendar style, the
month and day are interchanged.)  The reason this expression requires a
beginning year is that advanced diary functions can use it to calculate
the number of elapsed years.

   A "block" diary entry applies to a specified range of consecutive
dates.  Here is a block diary entry that applies to all dates from June
24, 1990 through July 10, 1990:

     %%(diary-block 6 24 1990 7 10 1990) Vacation

The `6 24 1990' indicates the starting date and the `7 10 1990'
indicates the stopping date.  (Again, if you are using the European
calendar style, the month and day are interchanged.)

   To insert a block entry, place point and the mark on the two dates
that begin and end the range, and type `i b'.  This command displays
the end of your diary file in another window and inserts the block
description; you can then type the diary entry.

   "Cyclic" diary entries repeat after a fixed interval of days.  To
create one, select the starting date and use the `i c' command.  The
command prompts for the length of interval, then inserts the entry,
which looks like this:

     %%(diary-cyclic 50 3 1 1990) Renew medication

This entry applies to March 1, 1990 and every 50th day following; `3 1
1990' specifies the starting date.  (If you are using the European
calendar style, the month and day are interchanged.)

   All three of these commands make marking diary entries.  To insert a
nonmarking entry, give a numeric argument to the command.  For example,
`C-u i a' makes a nonmarking anniversary diary entry.

   Marking sexp diary entries in the calendar is _extremely_
time-consuming, since every date visible in the calendar window must be
individually checked.  So it's a good idea to make sexp diary entries
nonmarking (with `&') when possible.

   Another sophisticated kind of sexp entry, a "floating" diary entry,
specifies a regularly-occurring event by offsets specified in days,
weeks, and months.  It is comparable to a crontab entry interpreted by
the `cron' utility.  Here is a nonmarking, floating diary entry that
applies to the last Thursday in November:

     &%%(diary-float 11 4 -1) American Thanksgiving

The 11 specifies November (the eleventh month), the 4 specifies Thursday
(the fourth day of the week, where Sunday is numbered zero), and the -1
specifies "last" (1 would mean "first", 2 would mean "second", -2 would
mean "second-to-last", and so on).  The month can be a single month or
a list of months.  Thus you could change the 11 above to `'(1 2 3)' and
have the entry apply to the last Thursday of January, February, and
March.  If the month is `t', the entry applies to all months of the
year.

   Most generally, sexp diary entries can perform arbitrary
computations to determine when they apply.  *Note Sexp Diary Entries:
(elisp)Sexp Diary Entries.


File: emacs,  Node: Appointments,  Next: Daylight Savings,  Prev: Diary,  Up: Calendar/Diary

26.11 Appointments
==================

If you have a diary entry for an appointment, and that diary entry
begins with a recognizable time of day, Emacs can warn you, several
minutes beforehand, that that appointment is pending.  Emacs alerts you
to the appointment by displaying a message in the mode line.

   To enable appointment notification, you must enable the time display
feature of Emacs, `M-x display-time' (*note Mode Line::).  You must
also add the function `appt-make-list' to the `diary-hook', like this:

     (add-hook 'diary-hook 'appt-make-list)

   With these preparations done, when you display the diary (either with
the `d' command in the calendar window or with the `M-x diary'
command), it sets up an appointment list of all the diary entries found
with recognizable times of day, and reminds you just before each of
them.

   For example, suppose the diary file contains these lines:

     Monday
       9:30am Coffee break
      12:00pm Lunch

Then on Mondays, after you have displayed the diary, you will be
reminded at 9:20am about your coffee break and at 11:50am about lunch.

   You can write times in am/pm style (with `12:00am' standing for
midnight and `12:00pm' standing for noon), or 24-hour European/military
style.  You need not be consistent; your diary file can have a mixture
of the two styles.

   Emacs updates the appointments list automatically just after
midnight.  This also displays the next day's diary entries in the diary
buffer, unless you set `appt-display-diary' to `nil'.

   You can also use the appointment notification facility like an alarm
clock.  The command `M-x appt-add' adds entries to the appointment list
without affecting your diary file.  You delete entries from the
appointment list with `M-x appt-delete'.

   You can turn off the appointment notification feature at any time by
setting `appt-issue-message' to `nil'.


File: emacs,  Node: Daylight Savings,  Prev: Appointments,  Up: Calendar/Diary

26.12 Daylight Savings Time
===========================

Emacs understands the difference between standard time and daylight
savings time--the times given for sunrise, sunset, solstices,
equinoxes, and the phases of the moon take that into account.  The rules
for daylight savings time vary from place to place and have also varied
historically from year to year.  To do the job properly, Emacs needs to
know which rules to use.

   Some operating systems keep track of the rules that apply to the
place where you are; on these systems, Emacs gets the information it
needs from the system automatically.  If some or all of this
information is missing, Emacs fills in the gaps with the rules
currently used in Cambridge, Massachusetts.  If the resulting rules are
not what you want, you can tell Emacs the rules to use by setting
certain variables.

   These values should be Lisp expressions that refer to the variable
`year', and evaluate to the Gregorian date on which daylight savings
time starts or (respectively) ends, in the form of a list `(MONTH DAY
YEAR)'.  The values should be `nil' if your area does not use daylight
savings time.

   Emacs uses these expressions to determine the starting date of
daylight savings time for the holiday list and for correcting times of
day in the solar and lunar calculations.

   The values for Cambridge, Massachusetts are as follows:

     (calendar-nth-named-day 1 0 4 year)
     (calendar-nth-named-day -1 0 10 year)

That is, the first 0th day (Sunday) of the fourth month (April) in the
year specified by `year', and the last Sunday of the tenth month
(October) of that year.  If daylight savings time were changed to start
on October 1, you would set `calendar-daylight-savings-starts' to this:

     (list 10 1 year)

   If there is no daylight savings time at your location, or if you want
all times in standard time, set `calendar-daylight-savings-starts' and
`calendar-daylight-savings-ends' to `nil'.

   The variable `calendar-daylight-time-offset' specifies the
difference between daylight savings time and standard time, measured in
minutes.  The value for Cambridge, Massachusetts is 60.

   The two variables `calendar-daylight-savings-starts-time' and
`calendar-daylight-savings-ends-time' specify the number of minutes
after midnight local time when the transition to and from daylight
savings time should occur.  For Cambridge, Massachusetts both variables'
values are 120.


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

26.13 Gnus
==========

Gnus is an Emacs package primarily designed for reading and posting
Usenet news.  It can also be used to read and respond to messages from a
number of other sources--mail, remote directories, digests, and so on.

   Here we introduce Gnus and describe several basic features.  For
full details, see *Note Gnus: (gnus)Top.

   To start Gnus, type `M-x gnus <RET>'.

* Menu:

* Buffers of Gnus::	   The group, summary and article buffers.
* Gnus Startup::	   What you should know about starting Gnus.
* Summary of Gnus::	   A short description of the basic Gnus commands.


File: emacs,  Node: Buffers of Gnus,  Next: Gnus Startup,  Up: Gnus

26.13.1 Gnus Buffers
--------------------

As opposed to most normal Emacs packages, Gnus uses a number of
different buffers to display information and to receive commands.  The
three buffers users spend most of their time in are the "group buffer",
the "summary buffer" and the "article buffer".

   The "group buffer" contains a list of groups.  This is the first
buffer Gnus displays when it starts up.  It normally displays only the
groups to which you subscribe and that contain unread articles.  Use
this buffer to select a specific group.

   The "summary buffer" lists one line for each article in a single
group.  By default, the author, the subject and the line number are
displayed for each article, but this is customizable, like most aspects
of Gnus display.  The summary buffer is created when you select a group
in the group buffer, and is killed when you exit the group.  Use this
buffer to select an article.

   The "article buffer" displays the article.  In normal Gnus usage,
you don't select this buffer--all useful article-oriented commands work
in the summary buffer.  But you can select the article buffer, and
execute all Gnus commands from that buffer, if you want to.


File: emacs,  Node: Gnus Startup,  Next: Summary of Gnus,  Prev: Buffers of Gnus,  Up: Gnus

26.13.2 When Gnus Starts Up
---------------------------

At startup, Gnus reads your `.newsrc' news initialization file and
attempts to communicate with the local news server, which is a
repository of news articles.  The news server need not be the same
computer you are logged in on.

   If you start Gnus and connect to the server, but do not see any
newsgroups listed in the group buffer, type `L' or `A k' to get a
listing of all the groups.  Then type `u' to toggle subscription to
groups.

   The first time you start Gnus, Gnus subscribes you to a few selected
groups.  All other groups start out as "killed groups" for you; you can
list them with `A k'.  All new groups that subsequently come to exist
at the news server become "zombie groups" for you; type `A z' to list
them.  You can subscribe to a group shown in these lists using the `u'
command.

   When you quit Gnus with `q', it automatically records in your
`.newsrc' and `.newsrc.eld' initialization files the subscribed or
unsubscribed status of all groups.  You should normally not edit these
files manually, but you may if you know how.


File: emacs,  Node: Summary of Gnus,  Prev: Gnus Startup,  Up: Gnus

26.13.3 Summary of Gnus Commands
--------------------------------

Reading news is a two step process:

  1. Choose a group in the group buffer.

  2. Select articles from the summary buffer.  Each article selected is
     displayed in the article buffer in a large window, below the
     summary buffer in its small window.

   Each Gnus buffer has its own special commands; however, the meanings
of any given key in the various Gnus buffers are usually analogous, even
if not identical.  Here are commands for the group and summary buffers:

`q'
     In the group buffer, update your `.newsrc' initialization file and
     quit Gnus.

     In the summary buffer, exit the current group and return to the
     group buffer.  Thus, typing `q' twice quits Gnus.

`L'
     In the group buffer, list all the groups available on your news
     server (except those you have killed).  This may be a long list!

`l'
     In the group buffer, list only the groups to which you subscribe
     and which contain unread articles.

`u'
     In the group buffer, unsubscribe from (or subscribe to) the group
     listed in the line that point is on.  When you quit Gnus by typing
     `q', Gnus lists in your `.newsrc' file which groups you have
     subscribed to.  The next time you start Gnus, you won't see this
     group, because Gnus normally displays only subscribed-to groups.

`C-k'
     In the group buffer, "kill" the current line's group--don't even
     list it in `.newsrc' from now on.  This affects future Gnus
     sessions as well as the present session.

     When you quit Gnus by typing `q', Gnus writes information in the
     file `.newsrc' describing all newsgroups except those you have
     "killed."

`<SPC>'
     In the group buffer, select the group on the line under the cursor
     and display the first unread article in that group.

     In the summary buffer,

        * Select the article on the line under the cursor if none is
          selected.

        * Scroll the text of the selected article (if there is one).

        * Select the next unread article if at the end of the current
          article.

     Thus, you can move through all the articles by repeatedly typing
     <SPC>.

`<DEL>'
     In the group buffer, move point to the previous group containing
     unread articles.

     In the summary buffer, scroll the text of the article backwards.

`n'
     Move point to the next unread group, or select the next unread
     article.

`p'
     Move point to the previous unread group, or select the previous
     unread article.

`C-n'
`C-p'
     Move point to the next or previous item, even if it is marked as
     read.  This does not select the article or group on that line.

`s'
     In the summary buffer, do an incremental search of the current
     text in the article buffer, just as if you switched to the article
     buffer and typed `C-s'.

`M-s REGEXP RET'
     In the summary buffer, search forward for articles containing a
     match for REGEXP.



File: emacs,  Node: Shell,  Next: Emacs Server,  Prev: Gnus,  Up: Top

26.14 Running Shell Commands from Emacs
=======================================

Emacs has commands for passing single command lines to inferior shell
processes; it can also run a shell interactively with input and output
to an Emacs buffer named `*shell*'.

`M-! CMD <RET>'
     Run the shell command line CMD and display the output
     (`shell-command').

`M-| CMD <RET>'
     Run the shell command line CMD with region contents as input;
     optionally replace the region with the output
     (`shell-command-on-region').

`M-x shell'
     Run a subshell with input and output through an Emacs buffer.  You
     can then give commands interactively.

* Menu:

* Single Shell::           How to run one shell command and return.
* Interactive Shell::      Permanent shell taking input via Emacs.
* Shell Mode::             Special Emacs commands used with permanent shell.
* History: Shell History.  Repeating previous commands in a shell buffer.
* Options: Shell Options.  Options for customizing Shell mode.
* Remote Host::            Connecting to another computer.


File: emacs,  Node: Single Shell,  Next: Interactive Shell,  Up: Shell

26.14.1 Single Shell Commands
-----------------------------

`M-!' (`shell-command') reads a line of text using the minibuffer and
executes it as a shell command in a subshell made just for that
command.  Standard input for the command comes from the null device.
If the shell command produces any output, the output goes into an Emacs
buffer named `*Shell Command Output*', which is displayed in another
window but not selected.  A numeric argument, as in `M-1 M-!', directs
this command to insert any output into the current buffer.  In that
case, point is left before the output and the mark is set after the
output.

   If the shell command line ends in `&', it runs asynchronously.

   `M-|' (`shell-command-on-region') is like `M-!' but passes the
contents of the region as the standard input to the shell command,
instead of no input.  If a numeric argument is used, meaning insert the
output in the current buffer, then the old region is deleted first and
the output replaces it as the contents of the region.

   Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
use.  This variable is initialized based on your `SHELL' environment
variable when Emacs is started.  If the file name does not specify a
directory, the directories in the list `exec-path' are searched; this
list is initialized based on the environment variable `PATH' when Emacs
is started.  Your `.emacs' file can override either or both of these
default initializations.

   Both `M-!' and `M-|' wait for the shell command to complete.  To
stop waiting, type `C-g' to quit; that terminates the shell command
with the signal `SIGINT'--the same signal that `C-c' normally generates
in the shell.  Emacs waits until the command actually terminates.  If
the shell command doesn't stop (because it ignores the `SIGINT'
signal), type `C-g' again; this sends the command a `SIGKILL' signal
which is impossible to ignore.


File: emacs,  Node: Interactive Shell,  Next: Shell Mode,  Prev: Single Shell,  Up: Shell

26.14.2 Interactive Inferior Shell
----------------------------------

To run a subshell interactively, putting its typescript in an Emacs
buffer, use `M-x shell'.  This creates (or reuses) a buffer named
`*shell*' and runs a subshell with input coming from and output going
to that buffer.  That is to say, any "terminal output" from the subshell
goes into the buffer, advancing point, and any "terminal input" for the
subshell comes from text in the buffer.  To give input to the subshell,
go to the end of the buffer and type the input, terminated by <RET>.

   Emacs does not wait for the subshell to do anything.  You can switch
windows or buffers and edit them while the shell is waiting, or while
it is running a command.  Output from the subshell waits until Emacs
has time to process it; this happens whenever Emacs is waiting for
keyboard input or for time to elapse.

   To make multiple subshells, rename the buffer `*shell*' to something
different using `M-x rename-uniquely'.  Then type `M-x shell' again to
create a new buffer `*shell*' with its own subshell.  If you rename
this buffer as well, you can create a third one, and so on.  All the
subshells run independently and in parallel.

   The file name used to load the subshell is the value of the variable
`explicit-shell-file-name', if that is non-`nil'.  Otherwise, the
environment variable `ESHELL' is used, or the environment variable
`SHELL' if there is no `ESHELL'.  If the file name specified is
relative, the directories in the list `exec-path' are searched; this
list is initialized based on the environment variable `PATH' when Emacs
is started.  Your `.emacs' file can override either or both of these
default initializations.

   As soon as the subshell is started, it is sent as input the contents
of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME
is the name of the file that the shell was loaded from.  For example,
if you use bash, the file sent to it is `~/.emacs_bash'.

   `cd', `pushd' and `popd' commands given to the inferior shell are
watched by Emacs so it can keep the `*shell*' buffer's default
directory the same as the shell's working directory.  These commands
are recognized syntactically by examining lines of input that are sent.
If you use aliases for these commands, you can tell Emacs to recognize
them also.  For example, if the value of the variable
`shell-pushd-regexp' matches the beginning of a shell command line,
that line is regarded as a `pushd' command.  Change this variable when
you add aliases for `pushd'.  Likewise, `shell-popd-regexp' and
`shell-cd-regexp' are used to recognize commands with the meaning of
`popd' and `cd'.  These commands are recognized only at the beginning
of a shell command line.

   If Emacs gets an error while trying to handle what it believes is a
`cd', `pushd' or `popd' command, it runs the hook
`shell-set-directory-error-hook' (*note Hooks::).

   If Emacs does not properly track changes in the current directory of
the subshell, use the command `M-x dirs' to ask the shell what its
current directory is.  This command works for shells that support the
most common command syntax; it may not work for unusual shells.


File: emacs,  Node: Shell Mode,  Next: Shell History,  Prev: Interactive Shell,  Up: Shell

26.14.3 Shell Mode
------------------

Shell buffers use Shell mode, which defines several special keys
attached to the `C-c' prefix.  They are chosen to resemble the usual
editing and job control characters present in shells that are not under
Emacs, except that you must type `C-c' first.  Here is a complete list
of the special key bindings of Shell mode:

`<RET>'
     At end of buffer send line as input; otherwise, copy current line
     to end of buffer and send it (`comint-send-input').  When a line is
     copied, any text at the beginning of the line that matches the
     variable `shell-prompt-pattern' is left out; this variable's value
     should be a regexp string that matches the prompts that your shell
     uses.

`<TAB>'
     Complete the command name or file name before point in the shell
     buffer (`comint-dynamic-complete').  <TAB> also completes history
     references (*note History References::) and environment variable
     names.

     The variable `shell-completion-fignore' specifies a list of file
     name extensions to ignore in Shell mode completion.  The default
     setting ignores file names ending in `~', `#' or `%'.  Other
     related Comint modes use the variable `comint-completion-fignore'
     instead.

`M-?'
     Display temporarily a list of the possible completions of the file
     name before point in the shell buffer
     (`comint-dynamic-list-filename-completions').

`C-d'
     Either delete a character or send EOF
     (`comint-delchar-or-maybe-eof').  Typed at the end of the shell
     buffer, `C-d' sends EOF to the subshell.  Typed at any other
     position in the buffer, `C-d' deletes a character as usual.

`C-c C-a'
     Move to the beginning of the line, but after the prompt if any
     (`comint-bol').

`C-c C-u'
     Kill all text pending at end of buffer to be sent as input
     (`comint-kill-input').

`C-c C-w'
     Kill a word before point (`backward-kill-word').

`C-c C-c'
     Interrupt the shell or its current subjob if any
     (`comint-interrupt-subjob').

`C-c C-z'
     Stop the shell or its current subjob if any (`comint-stop-subjob').

`C-c C-\'
     Send quit signal to the shell or its current subjob if any
     (`comint-quit-subjob').

`C-c C-o'
     Kill the last batch of output from a shell command
     (`comint-kill-output').  This is useful if a shell command spews
     out lots of output that just gets in the way.

`C-c C-r'
`C-M-l'
     Scroll to display the beginning of the last batch of output at the
     top of the window; also move the cursor there
     (`comint-show-output').

`C-c C-e'
     Scroll to put the end of the buffer at the bottom of the window
     (`comint-show-maximum-output').

`C-c C-f'
     Move forward across one shell command, but not beyond the current
     line (`shell-forward-command').  The variable
     `shell-command-regexp' specifies how to recognize the end of a
     command.

`C-c C-b'
     Move backward across one shell command, but not beyond the current
     line (`shell-backward-command').

`C-c C-l'
     Display the buffer's history of shell commands in another window
     (`comint-dynamic-list-input-ring').

`M-x dirs'
     Ask the shell what its current directory is, so that Emacs can
     agree with the shell.

`M-x send-invisible <RET> TEXT <RET>'
     Send TEXT as input to the shell, after reading it without echoing.
     This is useful when a shell command runs a program that asks for
     a password.

     Alternatively, you can arrange for Emacs to notice password prompts
     and turn off echoing for them, as follows:

          (add-hook 'comint-output-filter-functions
                    'comint-watch-for-password-prompt)

`M-x comint-continue-subjob'
     Continue the shell process.  This is useful if you accidentally
     suspend the shell process.(1)

`M-x comint-strip-ctrl-m'
     Discard all control-m characters from the current group of shell
     output.  The most convenient way to use this command is to make it
     run automatically when you get output from the subshell.  To do
     that, evaluate this Lisp expression:

          (add-hook 'comint-output-filter-functions
                    'comint-strip-ctrl-m)

`M-x comint-truncate-buffer'
     This command truncates the shell buffer to a certain maximum
     number of lines, specified by the variable
     `comint-buffer-maximum-size'.  Here's how to do this automatically
     each time you get output from the subshell:

          (add-hook 'comint-output-filter-functions
                    'comint-truncate-buffer)

   Shell mode also customizes the paragraph commands so that only shell
prompts start new paragraphs.  Thus, a paragraph consists of an input
command plus the output that follows it in the buffer.

   Shell mode is a derivative of Comint mode, a general purpose mode for
communicating with interactive subprocesses.  Most of the features of
Shell mode actually come from Comint mode, as you can see from the
command names listed above.  The special features of Shell mode in
particular include the choice of regular expression for detecting
prompts, the directory tracking feature, and a few user commands.

   Other Emacs features that use variants of Comint mode include GUD
(*note Debuggers::) and `M-x run-lisp' (*note External Lisp::).

   You can use `M-x comint-run' to execute any program of your choice
in a subprocess using unmodified Comint mode--without the
specializations of Shell mode.

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

   (1) You should not suspend the shell process.  Suspending a subjob
of the shell is a completely different matter--that is normal practice,
but you must use the shell to continue the subjob; this command won't
do it.


File: emacs,  Node: Shell History,  Next: Shell Options,  Prev: Shell Mode,  Up: Shell

26.14.4 Shell Command History
-----------------------------

Shell buffers support three ways of repeating earlier commands.  You
can use the same keys used in the minibuffer; these work much as they do
in the minibuffer, inserting text from prior commands while point
remains always at the end of the buffer.  You can move through the
buffer to previous inputs in their original place, then resubmit them or
copy them to the end.  Or you can use a `!'-style history reference.

* Menu:

* Ring: Shell Ring.             Fetching commands from the history list.
* Copy: Shell History Copying.  Moving to a command and then copying it.
* History References::          Expanding `!'-style history references.


File: emacs,  Node: Shell Ring,  Next: Shell History Copying,  Up: Shell History

26.14.4.1 Shell History Ring
............................

`M-p'
     Fetch the next earlier old shell command.

`M-n'
     Fetch the next later old shell command.

`M-r REGEXP <RET>'
`M-s REGEXP <RET>'
     Search backwards or forwards for old shell commands that match
     REGEXP.

   Shell buffers provide a history of previously entered shell
commands.  To reuse shell commands from the history, use the editing
commands `M-p', `M-n', `M-r' and `M-s'.  These work just like the
minibuffer history commands except that they operate on the text at the
end of the shell buffer, where you would normally insert text to send
to the shell.

   `M-p' fetches an earlier shell command to the end of the shell
buffer.  Successive use of `M-p' fetches successively earlier shell
commands, each replacing any text that was already present as potential
shell input.  `M-n' does likewise except that it finds successively
more recent shell commands from the buffer.

   The history search commands `M-r' and `M-s' read a regular
expression and search through the history for a matching command.  Aside
from the choice of which command to fetch, they work just like `M-p'
and `M-r'.  If you enter an empty regexp, these commands reuse the same
regexp used last time.

   When you find the previous input you want, you can resubmit it by
typing <RET>, or you can edit it first and then resubmit it if you wish.

   These commands get the text of previous shell commands from a special
history list, not from the shell buffer itself.  Thus, editing the shell
buffer, or even killing large parts of it, does not affect the history
that these commands access.

   Some shells store their command histories in files so that you can
refer to previous commands from previous shell sessions.  Emacs reads
the command history file for your chosen shell, to initialize its own
command history.  The file name is `~/.bash_history' for bash,
`~/.sh_history' for ksh, and `~/.history' for other shells.


File: emacs,  Node: Shell History Copying,  Next: History References,  Prev: Shell Ring,  Up: Shell History

26.14.4.2 Shell History Copying
...............................

`C-c C-p'
     Move point to the previous prompt (`comint-previous-prompt').

`C-c C-n'
     Move point to the following prompt (`comint-next-prompt').

`C-c <RET>'
     Copy the input command which point is in, inserting the copy at
     the end of the buffer (`comint-copy-old-input').  This is useful
     if you move point back to a previous command.  After you copy the
     command, you can submit the copy as input with <RET>.  If you
     wish, you can edit the copy before resubmitting it.

   Moving to a previous input and then copying it with `C-c <RET>'
produces the same results--the same buffer contents--that you would get
by using `M-p' enough times to fetch that previous input from the
history list.  However, `C-c <RET>' copies the text from the buffer,
which can be different from what is in the history list if you edit the
input text in the buffer after it has been sent.


File: emacs,  Node: History References,  Prev: Shell History Copying,  Up: Shell History

26.14.4.3 Shell History References
..................................

Various shells including csh and bash support "history references" that
begin with `!' and `^'.  Shell mode can understand these constructs and
perform the history substitution for you.  If you insert a history
reference and type <TAB>, this searches the input history for a
matching command, performs substitution if necessary, and places the
result in the buffer in place of the history reference.  For example,
you can fetch the most recent command beginning with `mv' with `! m v
<TAB>'.  You can edit the command if you wish, and then resubmit the
command to the shell by typing <RET>.

   History references take effect only following a shell prompt.  The
variable `shell-prompt-pattern' specifies how to recognize a shell
prompt.  Comint modes in general use the variable
`comint-prompt-regexp' to specify how to find a prompt; Shell mode uses
`shell-prompt-pattern' to set up the local value of
`comint-prompt-regexp'.

   Shell mode can optionally expand history references in the buffer
when you send them to the shell.  To request this, set the variable
`comint-input-autoexpand' to `input'.

   You can make <SPC> perform history expansion by binding <SPC> to the
command `comint-magic-space'.


File: emacs,  Node: Shell Options,  Next: Remote Host,  Prev: Shell History,  Up: Shell

26.14.5 Shell Mode Options
--------------------------

If the variable `comint-scroll-to-bottom-on-input' is non-`nil',
insertion and yank commands scroll the selected window to the bottom
before inserting.

   If `comint-scroll-show-maximum-output' is non-`nil', then scrolling
due to arrival of output tries to place the last line of text at the
bottom line of the window, so as to show as much useful text as
possible.  (This mimics the scrolling behavior of many terminals.)  The
default is `nil'.

   By setting `comint-scroll-to-bottom-on-output', you can opt for
having point jump to the end of the buffer whenever output arrives--no
matter where in the buffer point was before.  If the value is `this',
point jumps in the selected window.  If the value is `all', point jumps
in each window that shows the comint buffer.  If the value is `other',
point jumps in all nonselected windows that show the current buffer.
The default value is `nil', which means point does not jump to the end.

   The variable `comint-input-ignoredups' controls whether successive
identical inputs are stored in the input history.  A non-`nil' value
means to omit an input that is the same as the previous input.  The
default is `nil', which means to store each input even if it is equal
to the previous input.

   Three variables customize file name completion.  The variable
`comint-completion-addsuffix' controls whether completion inserts a
space or a slash to indicate a fully completed file or directory name
(non-`nil' means do insert a space or slash).
`comint-completion-recexact', if non-`nil', directs <TAB> to choose the
shortest possible completion if the usual Emacs completion algorithm
cannot add even a single character.  `comint-completion-autolist', if
non-`nil', says to list all the possible completions whenever
completion is not exact.

   The command `comint-dynamic-complete-variable' does variable name
completion using the environment variables as set within Emacs.  The
variables controlling file name completion apply to variable name
completion too.  This command is normally available through the menu
bar.

   Command completion normally considers only executable files.  If you
set `shell-command-execonly' to `nil', it considers nonexecutable files
as well.

   You can configure the behavior of `pushd'.  Variables control
whether `pushd' behaves like `cd' if no argument is given
(`shell-pushd-tohome'), pop rather than rotate with a numeric argument
(`shell-pushd-dextract'), and only add directories to the directory
stack if they are not already on it (`shell-pushd-dunique').  The
values you choose should match the underlying shell, of course.


File: emacs,  Node: Remote Host,  Prev: Shell Options,  Up: Shell

26.14.6 Remote Host Shell
-------------------------

Emacs provides two commands for logging in to another computer and
communicating with it through an Emacs buffer.

`M-x telnet <RET> HOSTNAME <RET>'
     Set up a Telnet connection to the computer named HOSTNAME.

`M-x rlogin <RET> HOSTNAME <RET>'
     Set up an Rlogin connection to the computer named HOSTNAME.

   Use `M-x telnet' to set up a Telnet connection to another computer.
(Telnet is the standard Internet protocol for remote login.)  It reads
the host name of the other computer as an argument with the minibuffer.
Once the connection is established, talking to the other computer
works like talking to a subshell: you can edit input with the usual
Emacs commands, and send it a line at a time by typing <RET>.  The
output is inserted in the Telnet buffer interspersed with the input.

   Use `M-x rlogin' to set up an Rlogin connection.  Rlogin is another
remote login communication protocol, essentially much like the Telnet
protocol but incompatible with it, and supported only by certain
systems.  Rlogin's advantages are that you can arrange not to have to
give your user name and password when communicating between two machines
you frequently use, and that you can make an 8-bit-clean connection.
(To do that in Emacs, set `rlogin-explicit-args' to `("-8")' before you
run Rlogin.)

   `M-x rlogin' sets up the default file directory of the Emacs buffer
to access the remote host via FTP (*note File Names::), and it tracks
the shell commands that change the current directory just like Shell
mode.

   There are two ways of doing directory tracking in an Rlogin
buffer--either with remote directory names `/HOST:DIR/' or with local
names (that works if the "remote" machine shares file systems with your
machine of origin).  You can use the command
`rlogin-directory-tracking-mode' to switch modes.  No argument means
use remote directory names, a positive argument means use local names,
and a negative argument means turn off directory tracking.


File: emacs,  Node: Emacs Server,  Next: Hardcopy,  Prev: Shell,  Up: Top

26.15 Using Emacs as a Server
=============================

Various programs such as `mail' can invoke your choice of editor to
edit a particular piece of text, such as a message that you are
sending.  By convention, most of these programs use the environment
variable `EDITOR' to specify which editor to run.  If you set `EDITOR'
to `emacs', they invoke Emacs--but in an inconvenient fashion, by
starting a new, separate Emacs process.  This is inconvenient because
it takes time and because the new Emacs process doesn't share the
buffers in the existing Emacs process.

   You can arrange to use your existing Emacs process as the editor for
programs like `mail' by using the Emacs client and Emacs server
programs.  Here is how.

   First, the preparation.  Within Emacs, call the function
`server-start'.  (Your `.emacs' file can do this automatically if you
add the expression `(server-start)' to it.)  Then, outside Emacs, set
the `EDITOR' environment variable to `emacsclient'.  (Note that some
programs use a different environment variable; for example, to make TeX
use `emacsclient', you should set the `TEXEDIT' environment variable to
`emacsclient +%d %s'.)

   Then, whenever any program invokes your specified `EDITOR' program,
the effect is to send a message to your principal Emacs telling it to
visit a file.  (That's what the program `emacsclient' does.)  Emacs
displays the buffer immediately and you can immediately begin editing
it.

   When you've finished editing that buffer, type `C-x #'
(`server-edit').  This saves the file and sends a message back to the
`emacsclient' program telling it to exit.  The programs that use
`EDITOR' wait for the "editor" (actually, `emacsclient') to exit.  `C-x
#' also checks for other pending external requests to edit various
files, and selects the next such file.

   You can switch to a server buffer manually if you wish; you don't
have to arrive at it with `C-x #'.  But `C-x #' is the only way to say
that you are "finished" with one.

   If you set the variable `server-window' to a window or a frame, `C-x
#' displays the server buffer in that window or in that frame.

   While `mail' or another application is waiting for `emacsclient' to
finish, `emacsclient' does not read terminal input.  So the terminal
that `mail' was using is effectively blocked for the duration.  In
order to edit with your principal Emacs, you need to be able to use it
without using that terminal.  There are two ways to do this:

   * Using a window system, run `mail' and the principal Emacs in two
     separate windows.  While `mail' is waiting for `emacsclient', the
     window where it was running is blocked, but you can use Emacs by
     switching windows.

   * Use Shell mode in Emacs to run the other program such as `mail';
     then, `emacsclient' blocks only the subshell under Emacs, and you
     can still use Emacs to edit the file.

   Some programs write temporary files for you to edit.  After you edit
the temporary file, the program reads it back and deletes it.  If the
Emacs server is later asked to edit the same file name, it should assume
this has nothing to do with the previous occasion for that file name.
The server accomplishes this by killing the temporary file's buffer when
you finish with the file.  Use the variable `server-temp-file-regexp'
to specify which files are temporary in this sense; its value should be
a regular expression that matches file names that are temporary.


File: emacs,  Node: Hardcopy,  Next: Postscript,  Prev: Emacs Server,  Up: Top

26.16 Hardcopy Output
=====================

The Emacs commands for making hardcopy let you print either an entire
buffer or just part of one, either with or without page headers.  See
also the hardcopy commands of Dired (*note Misc File Ops::) and the
diary (*note Diary Commands::).

`M-x print-buffer'
     Print hardcopy of current buffer with page headings containing the
     file name and page number.

`M-x lpr-buffer'
     Print hardcopy of current buffer without page headings.

`M-x print-region'
     Like `print-buffer' but print only the current region.

`M-x lpr-region'
     Like `lpr-buffer' but print only the current region.

   The hardcopy commands (aside from the Postscript commands) pass extra
switches to the `lpr' program based on the value of the variable
`lpr-switches'.  Its value should be a list of strings, each string an
option starting with `-'.  For example, to use a printer named
`nearme', set `lpr-switches' like this:

     (setq lpr-switches '("-Pnearme"))

   The variable `lpr-command' specifies the name of the printer program
to run; the default value depends on your operating system type.  On
most systems, the default is `"lpr"'.  The variable
`lpr-headers-switches' similarly specifies the extra switches to use to
make page headers.  The variable `lpr-add-switches' controls whether to
supply `-T' and `-J' options (suitable for `lpr') to the printer
program: `nil' means don't add them.  `lpr-add-switches' should be
`nil' if your printer program is not compatible with `lpr'.


File: emacs,  Node: Postscript,  Next: Sorting,  Prev: Hardcopy,  Up: Top

26.17 Postscript Hardcopy
=========================

These commands convert buffer contents to Postscript, either printing
it or leaving it in another Emacs buffer.

`M-x ps-print-buffer'
     Print hardcopy of the current buffer in Postscript form.

`M-x ps-print-region'
     Print hardcopy of the current region in Postscript form.

`M-x ps-print-buffer-with-faces'
     Print hardcopy of the current buffer in Postscript form, showing
     the faces used in the text by means of Postscript features.

`M-x ps-print-region-with-faces'
     Print hardcopy of the current region in Postscript form, showing
     the faces used in the text.

`M-x ps-spool-buffer'
     Generate Postscript for the current buffer text.

`M-x ps-spool-region'
     Generate Postscript for the current region.

`M-x ps-spool-buffer-with-faces'
     Generate Postscript for the current buffer, showing the faces used.

`M-x ps-spool-region-with-faces'
     Generate Postscript for the current region, showing the faces used.

   The Postscript commands, `ps-print-buffer' and `ps-print-region',
print buffer contents in Postscript form.  One command prints the
entire buffer; the other, just the region.  The corresponding
`-with-faces' commands, `ps-print-buffer-with-faces' and
`ps-print-region-with-faces', use Postscript features to show the faces
(fonts and colors) in the text properties of the text being printed.

   If you are using a color display, you can print a buffer of program
code with color highlighting by turning on Font-Lock mode in that
buffer, and using `ps-print-buffer-with-faces'.

   All four of the commands above use the variables `ps-lpr-command'
and `ps-lpr-switches' to specify how to print the output.
`ps-lpr-command' specifies the command name to run, and
`ps-lpr-switches' specifies command line options to use.  If you don't
set these variables yourself, they take their initial values from
`lpr-command' and `lpr-switches'.

   The variable `ps-print-header' controls whether these commands add
header lines to each page--set it to `nil' to turn headers off.  You
can turn off color processing by setting `ps-print-color-p' to `nil'.
Many other customization variables for these commands are defined and
described in the Lisp file `ps-print.el'.

   The commands whose names have `spool' instead of `print' generate
the Postscript output in an Emacs buffer instead of sending it to the
printer.


File: emacs,  Node: Sorting,  Next: Narrowing,  Prev: Postscript,  Up: Top

26.18 Sorting Text
==================

Emacs provides several commands for sorting text in the buffer.  All
operate on the contents of the region (the text between point and the
mark).  They divide the text of the region into many "sort records",
identify a "sort key" for each record, and then reorder the records
into the order determined by the sort keys.  The records are ordered so
that their keys are in alphabetical order, or, for numeric sorting, in
numeric order.  In alphabetic sorting, all upper case letters `A'
through `Z' come before lower case `a', in accord with the ASCII
character sequence.

   The various sort commands differ in how they divide the text into
sort records and in which part of each record is used as the sort key.
Most of the commands make each line a separate sort record, but some
commands use paragraphs or pages as sort records.  Most of the sort
commands use each entire sort record as its own sort key, but some use
only a portion of the record as the sort key.

`M-x sort-lines'
     Divide the region into lines, and sort by comparing the entire
     text of a line.  A numeric argument means sort into descending
     order.

`M-x sort-paragraphs'
     Divide the region into paragraphs, and sort by comparing the entire
     text of a paragraph (except for leading blank lines).  A numeric
     argument means sort into descending order.

`M-x sort-pages'
     Divide the region into pages, and sort by comparing the entire
     text of a page (except for leading blank lines).  A numeric
     argument means sort into descending order.

`M-x sort-fields'
     Divide the region into lines, and sort by comparing the contents of
     one field in each line.  Fields are defined as separated by
     whitespace, so the first run of consecutive non-whitespace
     characters in a line constitutes field 1, the second such run
     constitutes field 2, etc.

     Specify which field to sort by with a numeric argument: 1 to sort
     by field 1, etc.  A negative argument means count fields from the
     right instead of from the left; thus, minus 1 means sort by the
     last field.  If several lines have identical contents in the field
     being sorted, they keep same relative order that they had in the
     original buffer.

     A negative argument means count fields from the right (from the
     end of the line).

`M-x sort-numeric-fields'
     Like `M-x sort-fields' except the specified field is converted to
     an integer for each line, and the numbers are compared.  `10'
     comes before `2' when considered as text, but after it when
     considered as a number.

`M-x sort-columns'
     Like `M-x sort-fields' except that the text within each line used
     for comparison comes from a fixed range of columns.  See below for
     an explanation.

`M-x reverse-region'
     Reverse the order of the lines in the region.  This is useful for
     sorting into descending order by fields or columns, since those
     sort commands do not have a feature for doing that.

   For example, if the buffer contains this:

     On systems where clash detection (locking of files being edited) is
     implemented, Emacs also checks the first time you modify a buffer
     whether the file has changed on disk since it was last visited or
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.

applying `M-x sort-lines' to the entire buffer produces this:

     On systems where clash detection (locking of files being edited) is
     implemented, Emacs also checks the first time you modify a buffer
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.
     whether the file has changed on disk since it was last visited or

where the upper case `O' sorts before all lower case letters.  If you
use `C-u 2 M-x sort-fields' instead, you get this:

     implemented, Emacs also checks the first time you modify a buffer
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.
     On systems where clash detection (locking of files being edited) is
     whether the file has changed on disk since it was last visited or

where the sort keys were `Emacs', `If', `buffer', `systems' and `the'.

   `M-x sort-columns' requires more explanation.  You specify the
columns by putting point at one of the columns and the mark at the other
column.  Because this means you cannot put point or the mark at the
beginning of the first line to sort, this command uses an unusual
definition of `region': all of the line point is in is considered part
of the region, and so is all of the line the mark is in, as well as all
the lines in between.

   For example, to sort a table by information found in columns 10 to
15, you could put the mark on column 10 in the first line of the table,
and point on column 15 in the last line of the table, and then run
`sort-columns'.  Equivalently, you could run it with the mark on column
15 in the first line and point on column 10 in the last line.

   This can be thought of as sorting the rectangle specified by point
and the mark, except that the text on each line to the left or right of
the rectangle moves along with the text inside the rectangle.  *Note
Rectangles::.

   Many of the sort commands ignore case differences when comparing, if
`sort-fold-case' is non-`nil'.


File: emacs,  Node: Narrowing,  Next: Two-Column,  Prev: Sorting,  Up: Top

26.19 Narrowing
===============

"Narrowing" means focusing in on some portion of the buffer, making the
rest temporarily inaccessible.  The portion which you can still get to
is called the "accessible portion".  Canceling the narrowing, which
makes the entire buffer once again accessible, is called "widening".
The amount of narrowing in effect in a buffer at any time is called the
buffer's "restriction".

   Narrowing can make it easier to concentrate on a single subroutine or
paragraph by eliminating clutter.  It can also be used to restrict the
range of operation of a replace command or repeating keyboard macro.

`C-x n n'
     Narrow down to between point and mark (`narrow-to-region').

`C-x n w'
     Widen to make the entire buffer accessible again (`widen').

`C-x n p'
     Narrow down to the current page (`narrow-to-page').

   When you have narrowed down to a part of the buffer, that part
appears to be all there is.  You can't see the rest, you can't move
into it (motion commands won't go outside the accessible part), you
can't change it in any way.  However, it is not gone, and if you save
the file all the inaccessible text will be saved.  The word `Narrow'
appears in the mode line whenever narrowing is in effect.

   The primary narrowing command is `C-x n n' (`narrow-to-region').  It
sets the current buffer's restrictions so that the text in the current
region remains accessible but all text before the region or after the
region is inaccessible.  Point and mark do not change.

   Alternatively, use `C-x n p' (`narrow-to-page') to narrow down to
the current page.  *Note Pages::, for the definition of a page.

   The way to cancel narrowing is to widen with `C-x n w' (`widen').
This makes all text in the buffer accessible again.

   You can get information on what part of the buffer you are narrowed
down to using the `C-x =' command.  *Note Position Info::.

   Because narrowing can easily confuse users who do not understand it,
`narrow-to-region' is normally a disabled command.  Attempting to use
this command asks for confirmation and gives you the option of enabling
it; if you enable the command, confirmation will no longer be required
for it.  *Note Disabling::.


File: emacs,  Node: Two-Column,  Next: Editing Binary Files,  Prev: Narrowing,  Up: Top

26.20 Two-Column Editing
========================

Two-column mode lets you conveniently edit two side-by-side columns of
text.  It uses two side-by-side windows, each showing its own buffer.

   There are three ways to enter two-column mode:

`f2 2' or `C-x 6 2'
     Enter two-column mode with the current buffer on the left, and on
     the right, a buffer whose name is based on the current buffer's
     name (`2C-two-columns').  If the right-hand buffer doesn't already
     exist, it starts out empty; the current buffer's contents are not
     changed.

     This command is appropriate when the current buffer is empty or
     contains just one column and you want to add another column.

`f2 s' or `C-x 6 s'
     Split the current buffer, which contains two-column text, into two
     buffers, and display them side by side (`2C-split').  The current
     buffer becomes the left-hand buffer, but the text in the right-hand
     column is moved into the right-hand buffer.  The current column
     specifies the split point.  Splitting starts with the current line
     and continues to the end of the buffer.

     This command is appropriate when you have a buffer that already
     contains two-column text, and you wish to separate the columns
     temporarily.

`f2 b BUFFER <RET>'
`C-x 6 b BUFFER <RET>'
     Enter two-column mode using the current buffer as the left-hand
     buffer, and using buffer BUFFER as the right-hand buffer
     (`2C-associate-buffer').

   `f2 s' or `C-x 6 s' looks for a column separator which is a string
that appears on each line between the two columns.  You can specify the
width of the separator with a numeric argument to `f2 s'; that many
characters, before point, constitute the separator string.  By default,
the width is 1, so the column separator is the character before point.

   When a line has the separator at the proper place, `f2 s' puts the
text after the separator into the right-hand buffer, and deletes the
separator.  Lines that don't have the column separator at the proper
place remain unsplit; they stay in the left-hand buffer, and the
right-hand buffer gets an empty line to correspond.  (This is the way to
write a line which "spans both columns while in two-column mode": write
it in the left-hand buffer, and put an empty line in the right-hand
buffer.)

   The command `C-x 6 <RET>' or `f2 <RET>' (`2C-newline') inserts a
newline in each of the two buffers at corresponding positions.  This is
the easiest way to add a new line to the two-column text while editing
it in split buffers.

   When you have edited both buffers as you wish, merge them with `f2
1' or `C-x 6 1' (`2C-merge').  This copies the text from the right-hand
buffer as a second column in the other buffer.  To go back to
two-column editing, use `f2 s'.

   Use `f2 d' or `C-x 6 d' to disassociate the two buffers, leaving
each as it stands (`2C-dissociate').  If the other buffer, the one not
current when you type `f2 d', is empty, `f2 d' kills it.


File: emacs,  Node: Editing Binary Files,  Next: Saving Emacs Sessions,  Prev: Two-Column,  Up: Top

26.21 Editing Binary Files
==========================

There is a special major mode for editing binary files: Hexl mode.  To
use it, use `M-x hexl-find-file' instead of `C-x C-f' to visit the
file.  This command converts the file's contents to hexadecimal and
lets you edit the translation.  When you save the file, it is converted
automatically back to binary.

   You can also use `M-x hexl-mode' to translate an existing buffer
into hex.  This is useful if you visit a file normally and then discover
it is a binary file.

   Ordinary text characters overwrite in Hexl mode.  This is to reduce
the risk of accidentally spoiling the alignment of data in the file.
There are special commands for insertion.  Here is a list of the
commands of Hexl mode:

`C-M-d'
     Insert a byte with a code typed in decimal.

`C-M-o'
     Insert a byte with a code typed in octal.

`C-M-x'
     Insert a byte with a code typed in hex.

`C-x ['
     Move to the beginning of a 1k-byte "page".

`C-x ]'
     Move to the end of a 1k-byte "page".

`M-g'
     Move to an address specified in hex.

`M-j'
     Move to an address specified in decimal.

`C-c C-c'
     Leave Hexl mode, going back to the major mode this buffer had
     before you invoked `hexl-mode'.


File: emacs,  Node: Saving Emacs Sessions,  Next: Recursive Edit,  Prev: Editing Binary Files,  Up: Top

26.22 Saving Emacs Sessions
===========================

You can use the Desktop library to save the state of Emacs from one
session to another.  Saving the state means that Emacs starts up with
the same set of buffers, major modes, buffer positions, and so on that
the previous Emacs session had.

   To use Desktop, you should first add these lines at the end of your
`.emacs' file:

     (load "desktop")
     (desktop-load-default)
     (desktop-read)

The first time you save the state of the Emacs session, you must do it
manually, with the command `M-x desktop-save'.  Once you have done
that, exiting Emacs will save the state again--not only the present
Emacs session, but also subsequent sessions.  You can also save the
state at any time, without exiting Emacs, by typing `M-x desktop-save'
again.

   In order for Emacs to recover the state from a previous session, you
must start it with the same current directory as you used when you
started the previous session.

   The variable `desktop-files-not-to-save' controls which files are
excluded from state saving.  Its value is a regular expression that
matches the files to exclude.  By default, remote (ftp-accessed) files
are excluded; this is because visiting them again in the subsequent
session would be slow.  If you want to include these files in state
saving, set `desktop-files-not-to-save' to `"^$"'.


File: emacs,  Node: Recursive Edit,  Next: Emulation,  Prev: Saving Emacs Sessions,  Up: Top

26.23 Recursive Editing Levels
==============================

A "recursive edit" is a situation in which you are using Emacs commands
to perform arbitrary editing while in the middle of another Emacs
command.  For example, when you type `C-r' inside of a `query-replace',
you enter a recursive edit in which you can change the current buffer.
On exiting from the recursive edit, you go back to the `query-replace'.

   "Exiting" the recursive edit means returning to the unfinished
command, which continues execution.  The command to exit is `C-M-c'
(`exit-recursive-edit').

   You can also "abort" the recursive edit.  This is like exiting, but
also quits the unfinished command immediately.  Use the command `C-]'
(`abort-recursive-edit') to do this.  *Note Quitting::.

   The mode line shows you when you are in a recursive edit by
displaying square brackets around the parentheses that always surround
the major and minor mode names.  Every window's mode line shows this,
in the same way, since being in a recursive edit is true of Emacs as a
whole rather than any particular window or buffer.

   It is possible to be in recursive edits within recursive edits.  For
example, after typing `C-r' in a `query-replace', you may type a
command that enters the debugger.  This begins a recursive editing level
for the debugger, within the recursive editing level for `C-r'.  Mode
lines display a pair of square brackets for each recursive editing
level currently in progress.

   Exiting the inner recursive edit (such as, with the debugger `c'
command) resumes the command running in the next level up.  When that
command finishes, you can then use `C-M-c' to exit another recursive
editing level, and so on.  Exiting applies to the innermost level only.
Aborting also gets out of only one level of recursive edit; it returns
immediately to the command level of the previous recursive edit.  If you
wish, you can then abort the next recursive editing level.

   Alternatively, the command `M-x top-level' aborts all levels of
recursive edits, returning immediately to the top level command reader.

   The text being edited inside the recursive edit need not be the same
text that you were editing at top level.  It depends on what the
recursive edit is for.  If the command that invokes the recursive edit
selects a different buffer first, that is the buffer you will edit
recursively.  In any case, you can switch buffers within the recursive
edit in the normal manner (as long as the buffer-switching keys have
not been rebound).  You could probably do all the rest of your editing
inside the recursive edit, visiting files and all.  But this could have
surprising effects (such as stack overflow) from time to time.  So
remember to exit or abort the recursive edit when you no longer need it.

   In general, we try to minimize the use of recursive editing levels in
GNU Emacs.  This is because they constrain you to "go back" in a
particular order-from the innermost level toward the top level.  When
possible, we present different activities in separate buffers so that
you can switch between them as you please.  Some commands switch to a
new major mode which provides a command to switch back.  These
approaches give you more flexibility to go back to unfinished tasks in
the order you choose.


File: emacs,  Node: Emulation,  Next: Dissociated Press,  Prev: Recursive Edit,  Up: Top

26.24 Emulation
===============

GNU Emacs can be programmed to emulate (more or less) most other
editors.  Standard facilities can emulate these:

EDT (DEC VMS editor)
     Turn on EDT emulation with `M-x edt-emulation-on'.  `M-x
     edt-emulation-off' restores normal Emacs command bindings.

     Most of the EDT emulation commands are keypad keys, and most
     standard Emacs key bindings are still available.  The EDT
     emulation rebindings are done in the global keymap, so there is no
     problem switching buffers or major modes while in EDT emulation.

vi (Berkeley editor)
     Viper is the newest emulator for vi.  It implements several levels
     of emulation; level 1 is closest to vi itself, while level 5
     departs somewhat from strict emulation to take advantage of the
     capabilities of Emacs.  To invoke Viper, type `M-x viper-mode'; it
     will guide you the rest of the way and ask for the emulation level.

vi (another emulator)
     `M-x vi-mode' enters a major mode that replaces the previously
     established major mode.  All of the vi commands that, in real vi,
     enter "input" mode are programmed instead to return to the
     previous major mode.  Thus, ordinary Emacs serves as vi's "input"
     mode.

     Because vi emulation works through major modes, it does not work
     to switch buffers during emulation.  Return to normal Emacs first.

     If you plan to use vi emulation much, you probably want to bind a
     key to the `vi-mode' command.

vi (alternate emulator)
     `M-x vip-mode' invokes another vi emulator, said to resemble real
     vi more thoroughly than `M-x vi-mode'.  "Input" mode in this
     emulator is changed from ordinary Emacs so you can use <ESC> to go
     back to emulated vi command mode.  To get from emulated vi command
     mode back to ordinary Emacs, type `C-z'.

     This emulation does not work through major modes, and it is
     possible to switch buffers in various ways within the emulator.
     It is not so necessary to assign a key to the command `vip-mode' as
     it is with `vi-mode' because terminating insert mode does not use
     it.

     For full information, see the long comment at the beginning of the
     source file, which is `lisp/vip.el' in the Emacs distribution.


File: emacs,  Node: Dissociated Press,  Next: Amusements,  Prev: Emulation,  Up: Top

26.25 Dissociated Press
=======================

`M-x dissociated-press' is a command for scrambling a file of text
either word by word or character by character.  Starting from a buffer
of straight English, it produces extremely amusing output.  The input
comes from the current Emacs buffer.  Dissociated Press writes its
output in a buffer named `*Dissociation*', and redisplays that buffer
after every couple of lines (approximately) so you can read the output
as it comes out.

   Dissociated Press asks every so often whether to continue generating
output.  Answer `n' to stop it.  You can also stop at any time by
typing `C-g'.  The dissociation output remains in the `*Dissociation*'
buffer for you to copy elsewhere if you wish.

   Dissociated Press operates by jumping at random from one point in the
buffer to another.  In order to produce plausible output rather than
gibberish, it insists on a certain amount of overlap between the end of
one run of consecutive words or characters and the start of the next.
That is, if it has just printed out `president' and then decides to jump
to a different point in the file, it might spot the `ent' in `pentagon'
and continue from there, producing `presidentagon'.(1)  Long sample
texts produce the best results.

   A positive argument to `M-x dissociated-press' tells it to operate
character by character, and specifies the number of overlap characters.
A negative argument tells it to operate word by word and specifies the
number of overlap words.  In this mode, whole words are treated as the
elements to be permuted, rather than characters.  No argument is
equivalent to an argument of two.  For your againformation, the output
goes only into the buffer `*Dissociation*'.  The buffer you start with
is not changed.

   Dissociated Press produces nearly the same results as a Markov chain
based on a frequency table constructed from the sample text.  It is,
however, an independent, ignoriginal invention.  Dissociated Press
techniquitously copies several consecutive characters from the sample
between random choices, whereas a Markov chain would choose randomly for
each word or character.  This makes for more plausible sounding results,
and runs faster.

   It is a mustatement that too much use of Dissociated Press can be a
developediment to your real work.  Sometimes to the point of outragedy.
And keep dissociwords out of your documentation, if you want it to be
well userenced and properbose.  Have fun.  Your buggestions are welcome.

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

   (1) This dissociword actually appeared during the Vietnam War, when
it was very appropriate.


File: emacs,  Node: Amusements,  Next: Customization,  Prev: Dissociated Press,  Up: Top

26.26 Other Amusements
======================

If you are a little bit bored, you can try `M-x hanoi'.  If you are
considerably bored, give it a numeric argument.  If you are very very
bored, try an argument of 9.  Sit back and watch.

   If you want a little more personal involvement, try `M-x gomoku',
which plays the game Go Moku with you.

   `M-x blackbox' and `M-x mpuz' are two kinds of puzzles.  `blackbox'
challenges you to determine the location of objects inside a box by
tomography.  `mpuz' displays a multiplication puzzle with letters
standing for digits in a code that you must guess--to guess a value,
type a letter and then the digit you think it stands for.

   `M-x dunnet' runs an adventure-style exploration game, which is a
bigger sort of puzzle.

   When you are frustrated, try the famous Eliza program.  Just do `M-x
doctor'.  End each input by typing `RET' twice.

   When you are feeling strange, type `M-x yow'.


File: emacs,  Node: Customization,  Next: Quitting,  Prev: Amusements,  Up: Top

27 Customization
****************

This chapter talks about various topics relevant to adapting the
behavior of Emacs in minor ways.  See `The Emacs Lisp Reference Manual'
for how to make more far-reaching changes.

   All kinds of customization affect only the particular Emacs session
that you do them in.  They are completely lost when you kill the Emacs
session, and have no effect on other Emacs sessions you may run at the
same time or later.  The only way an Emacs session can affect anything
outside of it is by writing a file; in particular, the only way to make
a customization `permanent' is to put something in your `.emacs' file
or other appropriate file to do the customization in each session.
*Note Init File::.

* Menu:

* Minor Modes::		   Each minor mode is one feature you can turn on
			     independently of any others.
* Variables::		   Many Emacs commands examine Emacs variables
			     to decide what to do; by setting variables,
			     you can control their functioning.
* Keyboard Macros::	   A keyboard macro records a sequence of
			     keystrokes to be replayed with a single
			     command.
* Key Bindings::	   The keymaps say what command each key runs.
			     By changing them, you can "redefine keys".
* Keyboard Translations::  If your keyboard passes an undesired code
			     for a key, you can tell Emacs to
			     substitute another code.
* Syntax::		   The syntax table controls how words and
			      expressions are parsed.
* Init File::		   How to write common customizations in the
                             `.emacs' file.


File: emacs,  Node: Minor Modes,  Next: Variables,  Up: Customization

27.1 Minor Modes
================

Minor modes are optional features which you can turn on or off.  For
example, Auto Fill mode is a minor mode in which <SPC> breaks lines
between words as you type.  All the minor modes are independent of each
other and of the selected major mode.  Most minor modes say in the mode
line when they are on; for example, `Fill' in the mode line means that
Auto Fill mode is on.

   Append `-mode' to the name of a minor mode to get the name of a
command function that turns the mode on or off.  Thus, the command to
enable or disable Auto Fill mode is called `M-x auto-fill-mode'.  These
commands are usually invoked with `M-x', but you can bind keys to them
if you wish.  With no argument, the function turns the mode on if it was
off and off if it was on.  This is known as "toggling".  A positive
argument always turns the mode on, and an explicit zero argument or a
negative argument always turns it off.

   Enabling or disabling some minor modes applies only to the current
buffer; each buffer is independent of the other buffers.  Therefore, you
can enable the mode in particular buffers and disable it in others.  The
per-buffer minor modes include Auto Fill mode, Auto Save mode, Font-Lock
mode, ISO Accents mode, Outline minor mode, Overwrite mode, and Binary
Overwrite mode.

   Auto Fill mode allows you to enter filled text without breaking lines
explicitly.  Emacs inserts newlines as necessary to prevent lines from
becoming too long.  *Note Filling::.

   Auto Save mode causes the contents of a buffer to be saved
periodically to reduce the amount of work you can lose in case of a
system crash.  *Note Auto Save::.

   Enriched mode enables editing and saving of formatted text.  *Note
Formatted Text::.

   Font-Lock mode automatically highlights certain textual units found
in programs, such as comments, strings, and function names being
defined.  This requires a window system that can display multiple fonts.
*Note Faces::.

   ISO Accents mode makes the characters ``', `'', `"', `^', `/' and
`~' combine with the following letter, to produce an accented letter in
the ISO Latin-1 character set.  *Note European Display::.

   Outline minor mode provides the same facilities as the major mode
called Outline mode; but since it is a minor mode instead, you can
combine it with any major mode.  *Note Outline Mode::.

   Overwrite mode causes ordinary printing characters to replace
existing text instead of shoving it to the right.  For example, if
point is in front of the `B' in `FOOBAR', then in Overwrite mode typing
a `G' changes it to `FOOGAR', instead of producing it `FOOGBAR' as
usual.  Binary Overwrite mode is a variant of Overwrite mode for
editing binary files; it treats newlines and tabs like other
characters, so that they overwrite other characters and can be
overwritten by them.

   The following minor modes normally apply to all buffers at once.
Since each is enabled or disabled by the value of a variable, you _can_
set them differently for particular buffers, by explicitly making the
corresponding variables local in those buffers.  *Note Locals::.

   Abbrev mode allows you to define abbreviations that automatically
expand as you type them.  For example, `amd' might expand to `abbrev
mode'.  *Note Abbrevs::, for full information.

   Icomplete mode displays an indication of available completions when
you are in the minibuffer and completion is active.  *Note Completion
Options::.

   Line Number mode enables continuous display in the mode line of the
line number of point.  *Note Mode Line::.

   Resize-Minibuffer mode makes the minibuffer expand as necessary to
hold the text that you put in it.  *Note Minibuffer Edit::.

   Scroll Bar mode gives each window a scroll bar (*note Scroll Bars::).
Menu Bar mode gives each frame a menu bar (*note Menu Bars::).  Both of
these modes are enabled by default when you use the X Window System.

   In Transient Mark mode, every change in the buffer contents
"deactivates" the mark, so that commands that operate on the region
will get an error.  This means you must either set the mark, or
explicitly "reactivate" it, before each command that uses the region.
The advantage of Transient Mark mode is that Emacs can display the
region highlighted (currently only when using X).  *Note Setting Mark::.

   For most minor modes, the command name is also the name of a variable
which directly controls the mode.  The mode is enabled whenever this
variable's value is non-`nil', and the minor mode command works by
setting the variable.  For example, the command `outline-minor-mode'
works by setting the value of `outline-minor-mode' as a variable; it is
this variable that directly turns Outline minor mode on and off.  To
check whether a given minor mode works this way, use `C-h v' to ask for
documentation on the variable name.

   These minor mode variables provide a good way for Lisp programs to
turn minor modes on and off; they are also useful in a file's local
variables list.  But please think twice before setting minor modes with
a local variables list, because most minor modes are matter of user
preference--other users editing the same file might not want the same
minor modes you prefer.


File: emacs,  Node: Variables,  Next: Keyboard Macros,  Prev: Minor Modes,  Up: Customization

27.2 Variables
==============

A "variable" is a Lisp symbol which has a value.  The symbol's name is
also called the name of the variable.  A variable name can contain any
characters that can appear in a file, but conventionally variable names
consist of words separated by hyphens.  A variable can have a
documentation string which describes what kind of value it should have
and how the value will be used.

   Lisp allows any variable to have any kind of value, but most
variables that Emacs uses require a value of a certain type.  Often the
value should always be a string, or should always be a number.
Sometimes we say that a certain feature is turned on if a variable is
"non-`nil'," meaning that if the variable's value is `nil', the feature
is off, but the feature is on for _any_ other value.  The conventional
value to use to turn on the feature--since you have to pick one
particular value when you set the variable--is `t'.

   Emacs uses many Lisp variables for internal record keeping, as any
Lisp program must, but the most interesting variables for you are the
ones that exist for the sake of customization.  Emacs does not (usually)
change the values of these variables; instead, you set the values, and
thereby alter and control the behavior of certain Emacs commands.  These
variables are called "user options".  Most user options are documented
in this manual, and appear in the Variable Index (*note Variable
Index::).

   One example of a variable which is a user option is `fill-column',
which specifies the position of the right margin (as a number of
characters from the left margin) to be used by the fill commands (*note
Filling::).

* Menu:

* Examining::	     Examining or setting one variable's value.
* Edit Options::     Examining or editing list of all user options' values.
* Hooks::	     Hook variables let you specify programs for parts
		       of Emacs to run on particular occasions.
* Locals::	     Per-buffer values of variables.
* File Variables::   How files can specify variable values.


File: emacs,  Node: Examining,  Next: Edit Options,  Up: Variables

27.2.1 Examining and Setting Variables
--------------------------------------

`C-h v VAR <RET>'
     Display the value and documentation of variable VAR
     (`describe-variable').

`M-x set-variable <RET> VAR <RET> VALUE <RET>'
     Change the value of variable VAR to VALUE.

   To examine the value of a single variable, use `C-h v'
(`describe-variable'), which reads a variable name using the
minibuffer, with completion.  It displays both the value and the
documentation of the variable.  For example,

     C-h v fill-column <RET>

displays something like this:

     fill-column's value is 75

     Documentation:
     *Column beyond which automatic line-wrapping should happen.
     Automatically becomes buffer-local when set in any fashion.

The star at the beginning of the documentation indicates that this
variable is a user option.  `C-h v' is not restricted to user options;
it allows any variable name.

   The most convenient way to set a specific user option is with `M-x
set-variable'.  This reads the variable name with the minibuffer (with
completion), and then reads a Lisp expression for the new value using
the minibuffer a second time.  For example,

     M-x set-variable <RET> fill-column <RET> 75 <RET>

sets `fill-column' to 75.

   `M-x set-variable' is limited to user option variables.  You can set
any variable with a Lisp expression using the function `setq'.  Here's
how to use it to set `fill-column':

     (setq fill-column 75)

   Setting variables, like all means of customizing Emacs except where
otherwise stated, affects only the current Emacs session.


File: emacs,  Node: Edit Options,  Next: Hooks,  Prev: Examining,  Up: Variables

27.2.2 Editing Variable Values
------------------------------

These two functions make it easy to display all the Emacs user option
variables, and to change some of them if you wish.

`M-x list-options'
     Display a buffer listing names, values and documentation of all
     options.

`M-x edit-options'
     Change user option values by editing a list of user option
     variables.

   `M-x list-options' displays a list of all Emacs option variables, in
an Emacs buffer named `*List Options*'.  Each user option is shown with
its documentation and its current value.  Here is what a portion of it
might look like:

     ;; exec-path:
     ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
     *List of directories to search programs to run in subprocesses.
     Each element is a string (directory name)
     or nil (try the default directory).
     ;;
     ;; fill-column:
     75
     *Column beyond which automatic line-wrapping should happen.
     Automatically becomes buffer-local when set in any fashion.
     ;;

   `M-x edit-options' goes one step further and immediately selects the
`*List Options*' buffer; this buffer uses the major mode Options mode,
which provides commands that allow you to point at a user option
variable and change its value:

`s'
     Set the variable point is in or near to a new value read using the
     minibuffer.

`x'
     Toggle the variable point is in or near: if the value was `nil',
     it becomes `t'; otherwise it becomes `nil'.

`1'
     Set the variable point is in or near to `t'.

`0'
     Set the variable point is in or near to `nil'.

`n'
`p'
     Move to the next or previous user option.

   Any changes take effect immediately, and last until you exit from
Emacs.


File: emacs,  Node: Hooks,  Next: Locals,  Prev: Edit Options,  Up: Variables

27.2.3 Hooks
------------

A "hook" is a variable where you can store a function or functions to
be called on a particular occasion by an existing program.  Emacs
provides a number of hooks for the sake of customization.

   Most of the hooks in Emacs are "normal hooks".  These variables
contain lists of functions to be called with no arguments.  The reason
most hooks are normal hooks is so that you can use them in a uniform
way.  Every variable in Emacs whose name ends in `-hook' is a normal
hook.

   Most major modes run hooks as the last step of initialization.  This
makes it easy for a user to customize the behavior of the mode, by
overriding the local variable assignments already made by the mode.  But
hooks may also be used in other contexts.  For example, the hook
`suspend-hook' runs just before Emacs suspends itself (*note Exiting::).

   The recommended way to add a hook function to a normal hook is by
calling `add-hook'.  You can use any valid Lisp function as the hook
function.  For example, here's how to set up a hook to turn on Auto
Fill mode when entering Text mode and other modes based on Text mode:

     (add-hook 'text-mode-hook 'turn-on-auto-fill)

   The next example shows how to use a hook to customize the indentation
of C code.  (People often have strong personal preferences for one
format compared to another.)  Here the hook function is an anonymous
lambda expression.

     (setq my-c-style
       '((c-comment-only-line-offset . 4)
         (c-cleanup-list . (scope-operator
     		       empty-defun-braces
     		       defun-close-semi))
         (c-offsets-alist . ((arglist-close . c-lineup-arglist)
     			(substatement-open . 0)))))

     (add-hook 'c-mode-common-hook
       (function (lambda ()
         (c-add-style "my-style" my-c-style t))))

   It is best to design your hook functions so that the order in which
they are executed does not matter.  Any dependence on the order is
"asking for trouble."  However, the order is predictable: the most
recently added hook functions are executed first.

