This is ../info/emacs, produced by makeinfo version 4.6 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: Registering,  Next: VC Mode Line,  Prev: Version Control Undo,  Up: Editing with VC

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

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

   You can put any file under version control by simply visiting it, and
then typing `C-x v i' (`vc-register'). After `C-x v i', the file is
unlocked and read-only.  Type `C-x C-q' if you wish to start editing it.

   When you register the file, Emacs must choose which version control
system to use for it.  You can specify your choice explicitly by setting
`vc-default-back-end' to `RCS', `CVS' or `SCCS'.  Otherwise, if there
is a subdirectory named `RCS', `SCCS', or `CVS', Emacs uses the
corresponding version control system.  In the absence of any
specification, the default choice is RCS if RCS is installed, otherwise
SCCS.

   After registering a file with CVS, you must subsequently commit the
initial version by typing `C-x C-q'.  *Note CVS and VC::.

   The initial version number for a newly registered file is 1.1, by
default.  To specify a different number, give `C-x v i' a numeric
argument; then it reads the initial version number using the minibuffer.

   If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
comment (much like a log entry) to describe the purpose of this source
file.


File: emacs,  Node: Version Control Undo,  Next: Registering,  Prev: Check-In,  Up: Editing with VC

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

`C-x v u'
     Revert the buffer and the file to the last checked in version.

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

   If you want to discard your current set of changes and revert to the
last version checked in, use `C-x v u' (`vc-revert-buffer').  This
cancels your last check-out, leaving the file unlocked.  If you want to
make a different set of changes, you must first check the file out
again.  `C-x v u' requires confirmation, unless it sees that you
haven't made any changes since the last checked-in version.

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

   You can cancel a change after checking it in, with `C-x v c'
(`vc-cancel-version').  This command discards all record of the most
recent checked in version.  `C-x v c' also offers to revert your work
file and buffer to the previous version (the one that precedes the
version that is deleted).  If you say `no', then VC keeps your changes
in the buffer and locks the file.

   The no-revert option is useful when you have checked in a change and
then discover a trivial error in it; you can cancel the erroneous
check-in, fix the error, and check the file in again.

   When `C-x v c' does not revert the buffer, it unexpands all version
control headers in the buffer instead (*note Version Headers::).  This
is because the buffer no longer corresponds to any existing version.
If you check it in again, the checkin process will expand the headers
properly for the new version number.

   However, it is impossible to unexpand the RCS `$Log$' header
automatically.  If you use that header feature, you have to unexpand it
by hand--by deleting the entry for the version that you just canceled.

   Be careful when invoking `C-x v c', as it is easy to throw away a
lot of work with it.  To help you be careful, this command always
requires confirmation with `yes'.  Note also that this command is
disabled under CVS, because canceling versions is very dangerous and
discouraged with this back end.


File: emacs,  Node: VC Mode Line,  Next: CVS and VC,  Prev: Registering,  Up: Editing with VC

The VC Mode Line
................

When you visit a file that is under version control, the mode line
indicates the current status of the file: the name of the version
control back end system, the locking state, and the version.

   The locking state is displayed as a single character, which can be
either `-' or `:'.  `-' means the file is not locked or not modified by
you.  Once you lock the file, the state indicator changes to `:'.  If
the file is locked by someone else, that user's name appears after the
version number.

   For example, `RCS-1.3' means you are looking at RCS version 1.3,
which is not locked.  `RCS:1.3' means that you have locked the file,
and possibly already changed it.  `RCS:jim:1.3' means that the file is
locked by jim.


File: emacs,  Node: CVS and VC,  Prev: VC Mode Line,  Up: Editing with VC

Using VC with CVS
.................

In CVS, files are never locked.  Two users can check out the same file
at the same time; each user has a separate copy and can edit it.  Work
files are always writable; once you have one, you need not type a VC
command to start editing the file.  You can edit it at any time.

   When using RCS and SCCS, you normally use `C-x C-q' twice for each
change; once before the change, for checkout, and once after, for
checkin.  With CVS, it's different: you normally use `C-x C-q' just
once for each change, to commit the change when it is done.  The work
file remains writable, so you can begin editing again with no special
commands.

   One way to understand this is that VC does an "implicit" check-out
when you save the modified file for the first time.  VC indicates this
on the mode line: the status indicator changes from `-' to `:' as soon
as you save a modified version, telling you that you are not in sync
with the repository anymore (*note VC Mode Line::).  The file stays
"checked out" until you check it back in, even if you kill the buffer
and visit the file again.

   If, instead, you would like to use explicit check-out with CVS, set
the `CVSREAD' environment variable to some value.  (It does not matter
what value you use.)  CVS then makes your work files read-only by
default, and VC requires you to check them out explicitly with `C-x
C-q'.  When setting `CVSREAD' for the first time, make sure to check
out all your modules anew, so that the file protections are set
correctly.

   VC does not provide a way to check out a working copy of an existing
file in the repository.  You have to use the CVS shell commands to do
that.  Once you have a work file, you can start using VC for that file.

   CVS terminology speaks of "committing" a change rather than checking
it in.  But in practical terms they work the same way: Emacs asks you
to type in a log entry, and you finish it with `C-c C-c'.

   When you try to commit a change in a file, but someone else has
committed another change in the meanwhile, that creates a "conflict".
VC detects this situation and offers to "merge" your changes and those
of the other user, creating a new local version of the file, which you
can then commit to the repository.  This works smoothly if the changes
are in different parts of the file, although it is wise to check the
resulting file for semantic consistency.

   However, if you and the other user changed the same parts of the
file, the conflict cannot be resolved automatically.  In this case, CVS
inserts both variants of the conflicting regions into your working file,
and puts so-called "conflict markers" around them.  They indicate how
the region looks in the respective user's version.  You must resolve
the conflict manually, for example by choosing one of the two variants
and deleting the other one (and the conflict markers).  Then you can
commit the resulting file into the repository.  The example below shows
how a conflict region looks; the file is called `name' and the current
repository version with user B's changes in it is 1.11.

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

   You can turn off use of VC for CVS-managed files by setting the
variable `vc-handle-cvs' to `nil'.  If you do this, Emacs treats these
files as if they were not managed, and the VC commands are not
available for them.  You must do all CVS operations manually.


File: emacs,  Node: Log Entries,  Next: Change Logs and VC,  Prev: Editing with VC,  Up: Version Control

Log Entries
-----------

When you're editing an initial comment or log entry for inclusion in a
master file, finish your entry by typing `C-c C-c'.

`C-c C-c'
     Finish the comment edit normally (`vc-finish-logentry').  This
     finishes check-in.

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

   If you change several source files for the same reason, it is often
convenient to specify the same log entry for many of the files.  To do
this, use the history of previous log entries.  The commands `M-n',
`M-p', `M-s' and `M-r' for doing this work just like the minibuffer
history commands (except that these versions are used outside the
minibuffer).

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


File: emacs,  Node: Change Logs and VC,  Next: Old Versions,  Prev: Log Entries,  Up: Version Control

Change Logs and VC
------------------

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

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

     This command works with RCS only; it does not work with CVS or
     SCCS.

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

     Fri May  8 21:45:00 1992  Nathaniel Bowditch  <nat@apn.org>
     
             * rcs2log: Ignore log messages that start with `#'.

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

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

     Wed May  6 10:53:00 1992  Nathaniel Bowditch  <nat@apn.org>
     
             * vc.el (vc-do-command): Check call-process status.

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

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

They appear like this in `ChangeLog':

     Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  <nat@apn.org>
     
             * vc.texinfo: Fix expansion typos.
     
             * vc.el, vc-hooks.el: Don't call expand-file-name.

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

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

Then the text in `ChangeLog' looks like this:

     Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  <nat@apn.org>
     
             * vc.texinfo: Fix expansion typos.
             * vc.el, vc-hooks.el: Don't call expand-file-name.

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


File: emacs,  Node: Old Versions,  Next: Branches,  Prev: Change Logs and VC,  Up: Version Control

Examining And Comparing Old Versions
------------------------------------

`C-u C-x C-q VERSION <RET>'
     Select version VERSION as the current work file version.

`C-x v ~ VERSION <RET>'
     Examine version VERSION of the visited file, in a buffer of its
     own.

`C-x v ='
     Compare the current buffer contents with the latest checked-in
     version of the file.

`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
     Compare the specified two versions of FILE.

   There are two ways to work with an old version of a file.  You can
make the old version your current work file, for example if you want to
reproduce a former stage of development, or if you want to create a
branch from the old version (*note Branches::).  To do this, visit the
file and type `C-u C-x C-q VERSION <RET>'.  (This works only with RCS.)

   If you want only to examine an old version, without changing your
work file, visit the file and then type `C-x v ~ VERSION <RET>'
(`vc-version-other-window').  This puts the text of version VERSION in
a file named `FILENAME.~VERSION~', and visits it in its own buffer in a
separate window.

   To compare two versions of a file, use the command `C-x v ='
(`vc-diff').  Plain `C-x v =' compares the current buffer contents
(saving them in the file if necessary) with the last checked-in version
of the file.  `C-u C-x v =', with a numeric argument, reads a file name
and two version numbers, then compares those versions of the specified
file.

   If you supply a directory name instead of the name of a work file,
this command compares the two specified versions of all registered files
in that directory and its subdirectories.  You can also specify a
snapshot name (*note Snapshots::) instead of one or both version
numbers.

   You can specify a checked-in version by its number; an empty input
specifies the current contents of the work file (which may be different
from all the checked-in versions).

   This command works by running the `diff' utility, getting the
options from the variable `diff-switches'.  It displays the output in a
special buffer in another window.  Unlike the `M-x diff' command, `C-x
v =' does not try to locate the changes in the old and new versions.
This is because normally one or both versions do not exist as files
when you compare them; they exist only in the records of the master
file.  *Note Comparing Files::, for more information about `M-x diff'.


File: emacs,  Node: Branches,  Next: Status in VC,  Prev: Old Versions,  Up: Version Control

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

One use of version control is to maintain multiple "current" versions
of a file.  For example, you might have different versions of a program
in which you are gradually adding various unfinished new features.
Each such independent line of development is called a "branch".  VC
allows you to create branches, and switch between existing branches.
Note, however, that branches are supported only with RCS.

   A file's main line of development is usually called the "trunk".
The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc.  At
any such version, you may start an independent branch.  A branch
starting at version 1.2 would have version number 1.2.1.1.  Consecutive
versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4,
and so on.  If there is a second branch also starting at version 1.2; it
would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, and so on.

   If you omit the final component of a version number, that is called a
"branch number".  It refers to the highest existing version on that
branch.  The branches in the example above have branch numbers 1.2.1 and
1.2.2.

   A version which is the last in its branch is called a "head" version.

* Menu:

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


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

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

To switch between branches, type `C-u C-x C-q' and specify the version
number you want to select.  This version is then checked out _unlocked_
(write-protected), so you can examine it before really checking it out.
Switching branches in this way is allowed only when the file is not
locked.

   You may omit the minor version number, thus giving only the branch
number; this takes you to the highest version on the indicated branch.
If you only type `RET', Emacs goes to the highest version on the trunk.

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


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

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

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

   To create a new branch at an older version (one that is no longer the
head of a branch), first select that version, then lock it with `C-x
C-q'.  You'll be asked to confirm, when you lock the old version, that
you really mean to create a new branch--if you say no, you'll be offered
a chance to lock the latest version instead.

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

   After the branch is created, you "stay" on it.  That means that
subsequent checkouts and checkins create new versions on that branch.
To leave the branch, you must explicitly select a different version with
`C-u C-x C-q' for checkout.


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

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

It is sometimes useful for multiple developers to work simultaneously
on different branches of a file.  This is possible if you create
multiple source directories.  Each source directory should have a link
named `RCS' which points to a common directory of RCS master files.
Then each source directory can have its own choice of versions checked
out, but all share the same common RCS records.

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

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


File: emacs,  Node: Status in VC,  Next: Renaming and VC,  Prev: Branches,  Up: Version Control

VC Status Commands
------------------

To view the detailed version control status and history of a file, type
`C-x v l' (`vc-print-log').  It displays the history of changes to the
current file, including the text of the log entries.  The output
appears in a separate window.

   When you are working on a large program, it's often useful to find
all the files that are currently locked, or all the files maintained in
version control at all.  You can use `C-x v d' (`vc-directory') to show
all the locked files in or beneath a certain directory.  This includes
all files that are locked by any user.  `C-u C-x v d' lists all files
in or beneath the specified directory that are maintained with version
control.

   The list of files is displayed as a buffer that uses an augmented
Dired mode.  The names of the users locking various files are shown (in
parentheses) in place of the owner and group.  (With CVS, a more
detailed status is shown for each file.)  All the normal Dired commands
work in this buffer.  Most interactive VC commands work also, and apply
to the file name on the current line.

   The `C-x v v' command (`vc-next-action'), when used in the augmented
Dired buffer, operates on all the marked files (or the file on the
current line).  If it operates on more than one file, it handles each
file according to its current state; thus, it may check out one file
and check in another (because it is already checked out).  If it has to
check in any files, it reads a single log entry, then uses that text
for all the files being checked in.  This can be convenient for
registering or checking in several files at once, as part of the same
change.


File: emacs,  Node: Renaming and VC,  Next: Snapshots,  Prev: Status in VC,  Up: Version Control

Renaming VC Work Files and Master Files
---------------------------------------

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

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


File: emacs,  Node: Snapshots,  Next: Version Headers,  Prev: Renaming and VC,  Up: Version Control

Snapshots
---------

A "snapshot" is a named set of file versions (one for each registered
file) that you can treat as a unit.  One important kind of snapshot is
a "release", a (theoretically) stable version of the system that is
ready for distribution to users.

* Menu:

* Making Snapshots::		The snapshot facilities.
* Snapshot Caveats::		Things to be careful of when using snapshots.


File: emacs,  Node: Making Snapshots,  Next: Snapshot Caveats,  Up: Snapshots

Making and Using Snapshots
..........................

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

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

`C-x v r NAME <RET>'
     Check out all registered files at or below the current directory
     level using whatever versions correspond to the snapshot NAME
     (`vc-retrieve-snapshot').

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

   A snapshot uses a very small amount of resources--just enough to
record the list of file names and which version belongs to the
snapshot.  Thus, you need not hesitate to create snapshots whenever
they are useful.

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


File: emacs,  Node: Snapshot Caveats,  Prev: Making Snapshots,  Up: Snapshots

Snapshot Caveats
................

VC's snapshot facilities are modeled on RCS's named-configuration
support.  They use RCS's native facilities for this, so under VC
snapshots made using RCS are visible even when you bypass VC.

   For SCCS, VC implements snapshots itself.  The files it uses contain
name/file/version-number triples.  These snapshots are visible only
through VC.

   A snapshot is a set of checked-in versions.  So make sure that all
the files are checked in and not locked when you make a snapshot.

   File renaming and deletion can create some difficulties with
snapshots.  This is not a VC-specific problem, but a general design
issue in version control systems that no one has solved very well yet.

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

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


File: emacs,  Node: Version Headers,  Next: Customizing VC,  Prev: Snapshots,  Up: Version Control

Inserting Version Control Headers
---------------------------------

Sometimes it is convenient to put version identification strings
directly into working files.  Certain special strings called "version
headers" are replaced in each successive version by the number of that
version.

   If you are using RCS, and version headers are present in your working
files, Emacs can use them to determine the current version and the
locking state of the files.  This is more reliable than referring to the
master files, which is done when there are no version headers.  Note
that in a multi-branch environment, version headers are necessary to
make VC behave correctly (*note Multi-User Branching::).

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

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

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

   The default header string is `$Id$' for RCS and `%W%' for SCCS.  You
can specify other headers to insert by setting the variable
`vc-header-alist'.  Its value is a list of elements of the form
`(PROGRAM . STRING)' where PROGRAM is `RCS' or `SCCS' and STRING is the
string to use.

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

   It is often necessary to use "superfluous" backslashes when writing
the strings that you put in this variable.  This is to prevent the
string in the constant from being interpreted as a header itself if the
Emacs Lisp file containing it is maintained with version control.

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

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

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

It specifies insertion of text of this form:


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

Note that the text above starts with a blank line.

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


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

Customizing VC
--------------

There are many ways of customizing VC.  The variables that control its
behavior fall into three categories, described in the following
sections.

* Menu:

* VC Workfile Handling::  Various options concerning working files.
* VC Status Retrieval::   How VC finds the version control status of a file,
                            and how to customize this.
* VC Command Execution::  Which commands VC should run, and how.


File: emacs,  Node: VC Workfile Handling,  Next: VC Status Retrieval,  Up: Customizing VC

VC Workfile Handling
....................

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

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

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

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


File: emacs,  Node: VC Status Retrieval,  Next: VC Command Execution,  Prev: VC Workfile Handling,  Up: Customizing VC

VC Status Retrieval
...................

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

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

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


File: emacs,  Node: VC Command Execution,  Prev: VC Status Retrieval,  Up: Customizing VC

VC Command Execution
....................

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

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

   You can specify additional directories to search for version control
programs by setting the variable `vc-path'.  These directories are
searched before the usual search path.  But the proper files are usually
found automatically.


File: emacs,  Node: Directories,  Next: Comparing Files,  Prev: Version Control,  Up: Files

File Directories
================

The file system groups files into "directories".  A "directory listing"
is a list of all the files in a directory.  Emacs provides commands to
create and delete directories, and to make directory listings in brief
format (file names only) and verbose format (sizes, dates, and authors
included).  There is also a directory browser called Dired; see *Note
Dired::.

`C-x C-d DIR-OR-PATTERN <RET>'
     Display a brief directory listing (`list-directory').

`C-u C-x C-d DIR-OR-PATTERN <RET>'
     Display a verbose directory listing.

`M-x make-directory <RET> DIRNAME <RET>'
     Create a new directory named DIRNAME.

`M-x delete-directory <RET> DIRNAME <RET>'
     Delete the directory named DIRNAME.  It must be empty, or you get
     an error.

   The command to display a directory listing is `C-x C-d'
(`list-directory').  It reads using the minibuffer a file name which is
either a directory to be listed or a wildcard-containing pattern for
the files to be listed.  For example,

     C-x C-d /u2/emacs/etc <RET>

lists all the files in directory `/u2/emacs/etc'.  Here is an example
of specifying a file name pattern:

     C-x C-d /u2/emacs/src/*.c <RET>

   Normally, `C-x C-d' prints a brief directory listing containing just
file names.  A numeric argument (regardless of value) tells it to make
a verbose listing including sizes, dates, and authors (like `ls -l').

   The text of a directory listing is obtained by running `ls' in an
inferior process.  Two Emacs variables control the switches passed to
`ls': `list-directory-brief-switches' is a string giving the switches
to use in brief listings (`"-CF"' by default), and
`list-directory-verbose-switches' is a string giving the switches to
use in a verbose listing (`"-l"' by default).


File: emacs,  Node: Comparing Files,  Next: Misc File Ops,  Prev: Directories,  Up: Files

Comparing Files
===============

The command `M-x diff' compares two files, displaying the differences
in an Emacs buffer named `*Diff*'.  It works by running the `diff'
program, using options taken from the variable `diff-switches', whose
value should be a string.

   The buffer `*Diff*' has Compilation mode as its major mode, so you
can use `C-x `' to visit successive changed locations in the two source
files.  You can also move to a particular hunk of changes and type
<RET> or `C-c C-c', or click `Mouse-2' on it, to move to the
corresponding source location.  You can also use the other special
commands of Compilation mode: <SPC> and <DEL> for scrolling, and `M-p'
and `M-n' for cursor motion.  *Note Compilation::.

   The command `M-x diff-backup' compares a specified file with its most
recent backup.  If you specify the name of a backup file, `diff-backup'
compares it with the source file that it is a backup of.

   The command `M-x compare-windows' compares the text in the current
window with that in the next window.  Comparison starts at point in each
window, and each starting position is pushed on the mark ring in its
respective buffer.  Then point moves forward in each window, a character
at a time, until a mismatch between the two windows is reached.  Then
the command is finished.  For more information about windows in Emacs,
*Note Windows::.

   With a numeric argument, `compare-windows' ignores changes in
whitespace.  If the variable `compare-ignore-case' is non-`nil', it
ignores differences in case as well.

   See also *Note Emerge::, for convenient facilities for merging two
similar files.


File: emacs,  Node: Misc File Ops,  Next: Compressed Files,  Prev: Comparing Files,  Up: Files

Miscellaneous File Operations
=============================

Emacs has commands for performing many other operations on files.  All
operate on one file; they do not accept wild card file names.

   `M-x view-file' allows you to scan or read a file by sequential
screenfuls.  It reads a file name argument using the minibuffer.  After
reading the file into an Emacs buffer, `view-file' displays the
beginning.  You can then type <SPC> to scroll forward one windowful, or
<DEL> to scroll backward.  Various other commands are provided for
moving around in the file, but none for changing it; type `?' while
viewing for a list of them.  They are mostly the same as normal Emacs
cursor motion commands.  To exit from viewing, type `q'.  The commands
for viewing are defined by a special major mode called View mode.

   A related command, `M-x view-buffer', views a buffer already present
in Emacs.  *Note Misc Buffer::.

   `M-x insert-file' inserts a copy of the contents of the specified
file into the current buffer at point, leaving point unchanged before
the contents and the mark after them.

   `M-x write-region' is the inverse of `M-x insert-file'; it copies
the contents of the region into the specified file.  `M-x
append-to-file' adds the text of the region to the end of the specified
file.  *Note Accumulating Text::.

   `M-x delete-file' deletes the specified file, like the `rm' command
in the shell.  If you are deleting many files in one directory, it may
be more convenient to use Dired (*note Dired::).

   `M-x rename-file' reads two file names OLD and NEW using the
minibuffer, then renames file OLD as NEW.  If a file named NEW already
exists, you must confirm with `yes' or renaming is not done; this is
because renaming causes the old meaning of the name NEW to be lost.  If
OLD and NEW are on different file systems, the file OLD is copied and
deleted.

   The similar command `M-x add-name-to-file' is used to add an
additional name to an existing file without removing its old name.  The
new name must belong on the same file system that the file is on.

   `M-x copy-file' reads the file OLD and writes a new file named NEW
with the same contents.  Confirmation is required if a file named NEW
already exists, because copying has the consequence of overwriting the
old contents of the file NEW.

   `M-x make-symbolic-link' reads two file names OLD and LINKNAME, then
creates a symbolic link named LINKNAME and pointing at OLD.  The effect
is that future attempts to open file LINKNAME will refer to whatever
file is named OLD at the time the opening is done, or will get an error
if the name OLD is not in use at that time.  This command does not
expand the argument FILENAME, so that it allows you to specify a
relative name as the target of the link.

   Confirmation is required when creating the link if LINKNAME is in
use.  Note that not all systems support symbolic links.


File: emacs,  Node: Compressed Files,  Prev: Misc File Ops,  Up: Files

Accessing Compressed Files
==========================

Emacs comes with a library that can automatically uncompress compressed
files when you visit them, and automatically recompress them if you
alter them and save them.  To enable this feature, type the command
`M-x auto-compression-mode'.

   When automatic compression (which implies automatic uncompression as
well) is enabled, Emacs recognizes compressed files by their file names.
File names ending in `.gz' indicate a file compressed with `gzip'.
Other endings indicate other compression programs.

   Automatic uncompression and compression apply to all the operations
in which Emacs uses the contents of a file.  This includes visiting it,
saving it, inserting its contents into a buffer, loading it, and byte
compiling it.


File: emacs,  Node: Buffers,  Next: Windows,  Prev: Files,  Up: Top

Using Multiple Buffers
**********************

The text you are editing in Emacs resides in an object called a
"buffer".  Each time you visit a file, a buffer is created to hold the
file's text.  Each time you invoke Dired, a buffer is created to hold
the directory listing.  If you send a message with `C-x m', a buffer
named `*mail*' is used to hold the text of the message.  When you ask
for a command's documentation, that appears in a buffer called `*Help*'.

   At any time, one and only one buffer is "selected".  It is also
called the "current buffer".  Often we say that a command operates on
"the buffer" as if there were only one; but really this means that the
command operates on the selected buffer (most commands do).

   When Emacs has multiple windows, each window has a chosen buffer
which is displayed there, but at any time only one of the windows is
selected and its chosen buffer is the selected buffer.  Each window's
mode line displays the name of the buffer that the window is displaying
(*note Windows::).

   Each buffer has a name, which can be of any length, and you can
select any buffer by giving its name.  Most buffers are made by
visiting files, and their names are derived from the files' names.  But
you can also create an empty buffer with any name you want.  A newly
started Emacs has a buffer named `*scratch*' which can be used for
evaluating Lisp expressions in Emacs.  The distinction between upper
and lower case matters in buffer names.

   Each buffer records individually what file it is visiting, whether
it is modified, and what major mode and minor modes are in effect in it
(*note Major Modes::).  Any Emacs variable can be made "local to" a
particular buffer, meaning its value in that buffer can be different
from the value in other buffers.  *Note Locals::.

* Menu:

* Select Buffer::      Creating a new buffer or reselecting an old one.
* List Buffers::       Getting a list of buffers that exist.
* Misc Buffer::	       Renaming; changing read-onliness; copying text.
* Kill Buffer::	       Killing buffers you no longer need.
* Several Buffers::    How to go through the list of all buffers
			 and operate variously on several of them.
* Indirect Buffers::   An indirect buffer shares the text of another buffer.


File: emacs,  Node: Select Buffer,  Next: List Buffers,  Up: Buffers

Creating and Selecting Buffers
==============================

`C-x b BUFFER <RET>'
     Select or create a buffer named BUFFER (`switch-to-buffer').

`C-x 4 b BUFFER <RET>'
     Similar, but select BUFFER in another window
     (`switch-to-buffer-other-window').

`C-x 5 b BUFFER <RET>'
     Similar, but select BUFFER in a separate frame
     (`switch-to-buffer-other-frame').

   To select the buffer named BUFNAME, type `C-x b BUFNAME <RET>'.
This runs the command `switch-to-buffer' with argument BUFNAME.  You
can use completion on an abbreviation for the buffer name you want
(*note Completion::).  An empty argument to `C-x b' specifies the most
recently selected buffer that is not displayed in any window.

   Most buffers are created by visiting files, or by Emacs commands that
want to display some text, but you can also create a buffer explicitly
by typing `C-x b BUFNAME <RET>'.  This makes a new, empty buffer which
is not visiting any file, and selects it for editing.  Such buffers are
used for making notes to yourself.  If you try to save one, you are
asked for the file name to use.  The new buffer's major mode is
determined by the value of `default-major-mode' (*note Major Modes::).

   Note that `C-x C-f', and any other command for visiting a file, can
also be used to switch to an existing file-visiting buffer.  *Note
Visiting::.

   Emacs uses buffer names that start with a space for internal
purposes.  It treats these buffers specially in minor ways--for
example, by default they do not record undo information.  It is best to
avoid using such buffer names yourself.


File: emacs,  Node: List Buffers,  Next: Misc Buffer,  Prev: Select Buffer,  Up: Buffers

Listing Existing Buffers
========================

`C-x C-b'
     List the existing buffers (`list-buffers').

   To display a list of all the buffers that exist, type `C-x C-b'.
Each line in the list shows one buffer's name, major mode and visited
file.  The buffers are listed in the order, most recently visited first.

   `*' at the beginning of a line indicates the buffer is "modified".
If several buffers are modified, it may be time to save some with `C-x
s' (*note Saving::).  `%' indicates a read-only buffer.  `.' marks the
selected buffer.  Here is an example of a buffer list:

      MR Buffer         Size  Mode           File
      -- ------         ----  ----           ----
     .*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
         *Help*         1287  Fundamental
         files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
       % RMAIL          64042 RMAIL          /u/rms/RMAIL
      *% man            747   Dired          /u2/emacs/man/
         net.emacs      343885 Fundamental   /u/rms/net.emacs
         fileio.c       27691 C              /u2/emacs/src/fileio.c
         NEWS           67340 Text           /u2/emacs/etc/NEWS
         *scratch*	   0	 Lisp Interaction

Note that the buffer `*Help*' was made by a help request; it is not
visiting any file.  The buffer `man' was made by Dired on the directory
`/u2/emacs/man/'.


File: emacs,  Node: Misc Buffer,  Next: Kill Buffer,  Prev: List Buffers,  Up: Buffers

Miscellaneous Buffer Operations
===============================

`C-x C-q'
     Toggle read-only status of buffer (`vc-toggle-read-only').

`M-x rename-buffer <RET> NAME <RET>'
     Change the name of the current buffer.

`M-x rename-uniquely'
     Rename the current buffer by adding `<NUMBER>' to the end.

`M-x view-buffer <RET> BUFFER <RET>'
     Scroll through buffer BUFFER.

   A buffer can be "read-only", which means that commands to change its
contents are not allowed.  The mode line indicates read-only buffers
with `%%' or `%*' near the left margin.  Read-only buffers are usually
made by subsystems such as Dired and Rmail that have special commands
to operate on the text; also by visiting a file whose access control
says you cannot write it.

   If you wish to make changes in a read-only buffer, use the command
`C-x C-q' (`vc-toggle-read-only').  It makes a read-only buffer
writable, and makes a writable buffer read-only.  In most cases, this
works by setting the variable `buffer-read-only', which has a local
value in each buffer and makes the buffer read-only if its value is
non-`nil'.  If the file is maintained with version control, `C-x C-q'
works through the version control system to change the read-only status
of the file as well as the buffer.  *Note Version Control::.

   `M-x rename-buffer' changes the name of the current buffer.  Specify
the new name as a minibuffer argument.  There is no default.  If you
specify a name that is in use for some other buffer, an error happens
and no renaming is done.

   `M-x rename-uniquely' renames the current buffer to a similar name
with a numeric suffix added to make it both different and unique.  This
command does not need an argument.  It is useful for creating multiple
shell buffers: if you rename the `*Shell*' buffer, then do `M-x shell'
again, it makes a new shell buffer named `*Shell*'; meanwhile, the old
shell buffer continues to exist under its new name.  This method is
also good for mail buffers, compilation buffers, and most Emacs
features that create special buffers with particular names.

   `M-x view-buffer' is much like `M-x view-file' (*note Misc File
Ops::) except that it examines an already existing Emacs buffer.  View
mode provides commands for scrolling through the buffer conveniently
but not for changing it.  When you exit View mode, the value of point
that resulted from your perusal remains in effect.

   The commands `M-x append-to-buffer' and `M-x insert-buffer' can be
used to copy text from one buffer to another.  *Note Accumulating
Text::.


File: emacs,  Node: Kill Buffer,  Next: Several Buffers,  Prev: Misc Buffer,  Up: Buffers

Killing Buffers
===============

If you continue an Emacs session for a while, you may accumulate a
large number of buffers.  You may then find it convenient to "kill" the
buffers you no longer need.  On most operating systems, killing a
buffer releases its space back to the operating system so that other
programs can use it.  Here are some commands for killing buffers:

`C-x k BUFNAME <RET>'
     Kill buffer BUFNAME (`kill-buffer').

`M-x kill-some-buffers'
     Offer to kill each buffer, one by one.

   `C-x k' (`kill-buffer') kills one buffer, whose name you specify in
the minibuffer.  The default, used if you type just <RET> in the
minibuffer, is to kill the current buffer.  If you kill the current
buffer, another buffer is selected; one that has been selected recently
but does not appear in any window now.  If you ask to kill a
file-visiting buffer that is modified (has unsaved editing), then you
must confirm with `yes' before the buffer is killed.

   The command `M-x kill-some-buffers' asks about each buffer, one by
one.  An answer of `y' means to kill the buffer.  Killing the current
buffer or a buffer containing unsaved changes selects a new buffer or
asks for confirmation just like `kill-buffer'.

   The buffer menu feature (*note Several Buffers::) is also convenient
for killing various buffers.

   If you want to do something special every time a buffer is killed,
you can add hook functions to the hook `kill-buffer-hook' (*note
Hooks::).


File: emacs,  Node: Several Buffers,  Next: Indirect Buffers,  Prev: Kill Buffer,  Up: Buffers

Operating on Several Buffers
============================

The "buffer-menu" facility is like a "Dired for buffers"; it allows you
to request operations on various Emacs buffers by editing an Emacs
buffer containing a list of them.  You can save buffers, kill them
(here called "deleting" them, for consistency with Dired), or display
them.

`M-x buffer-menu'
     Begin editing a buffer listing all Emacs buffers.

   The command `buffer-menu' writes a list of all Emacs buffers into
the buffer `*Buffer List*', and selects that buffer in Buffer Menu
mode.  The buffer is read-only, and can be changed only through the
special commands described in this section.  The usual Emacs cursor
motion commands can be used in the `*Buffer List*' buffer.  The
following commands apply to the buffer described on the current line.

`d'
     Request to delete (kill) the buffer, then move down.  The request
     shows as a `D' on the line, before the buffer name.  Requested
     deletions take place when you type the `x' command.

`C-d'
     Like `d' but move up afterwards instead of down.

`s'
     Request to save the buffer.  The request shows as an `S' on the
     line.  Requested saves take place when you type the `x' command.
     You may request both saving and deletion for the same buffer.

`x'
     Perform previously requested deletions and saves.

`u'
     Remove any request made for the current line, and move down.

`<DEL>'
     Move to previous line and remove any request made for that line.

   The `d', `C-d', `s' and `u' commands to add or remove flags also
move down (or up) one line.  They accept a numeric argument as a repeat
count.

   These commands operate immediately on the buffer listed on the
current line:

`~'
     Mark the buffer "unmodified".  The command `~' does this
     immediately when you type it.

`%'
     Toggle the buffer's read-only flag.  The command `%' does this
     immediately when you type it.

`t'
     Visit the buffer as a tags table.  *Note Select Tags Table::.

   There are also commands to select another buffer or buffers:

`q'
     Quit the buffer menu--immediately display the most recent formerly
     visible buffer in its place.

`<RET>'
`f'
     Immediately select this line's buffer in place of the `*Buffer
     List*' buffer.

`o'
     Immediately select this line's buffer in another window as if by
     `C-x 4 b', leaving `*Buffer List*' visible.

`C-o'
     Immediately display this line's buffer in another window, but don't
     select the window.

`1'
     Immediately select this line's buffer in a full-screen window.

`2'
     Immediately set up two windows, with this line's buffer in one,
     and the previously selected buffer (aside from the buffer `*Buffer
     List*') in the other.

`m'
     Mark this line's buffer to be displayed in another window if you
     exit with the `v' command.  The request shows as a `>' at the
     beginning of the line.  (A single buffer may not have both a delete
     request and a display request.)

`v'
     Immediately select this line's buffer, and also display in other
     windows any buffers previously marked with the `m' command.  If
     you have not marked any buffers, this command is equivalent to `1'.

   All that `buffer-menu' does directly is create and switch to a
suitable buffer, and turn on Buffer Menu mode.  Everything else
described above is implemented by the special commands provided in
Buffer Menu mode.  One consequence of this is that you can switch from
the `*Buffer List*' buffer to another Emacs buffer, and edit there.
You can reselect the `*Buffer List*' buffer later, to perform the
operations already requested, or you can kill it, or pay no further
attention to it.

   The only difference between `buffer-menu' and `list-buffers' is that
`buffer-menu' switches to the `*Buffer List*' buffer in the selected
window; `list-buffers' displays it in another window.  If you run
`list-buffers' (that is, type `C-x C-b') and select the buffer list
manually, you can use all of the commands described here.

   The buffer `*Buffer List*' is not updated automatically when buffers
are created and killed; its contents are just text.  If you have
created, deleted or renamed buffers, the way to update `*Buffer List*'
to show what you have done is to type `g' (`revert-buffer') or repeat
the `buffer-menu' command.


File: emacs,  Node: Indirect Buffers,  Prev: Several Buffers,  Up: Buffers

Indirect Buffers
================

An "indirect buffer" shares the text of some other buffer, which is
called the "base buffer" of the indirect buffer.  In some ways it is
the analogue, for buffers, of a symbolic link between files.

`M-x make-indirect-buffer BASE-BUFFER <RET> INDIRECT-NAME <RET>'
     Create an indirect buffer named INDIRECT-NAME whose base buffer is
     BASE-BUFFER.

   The text of the indirect buffer is always identical to the text of
its base buffer; changes made by editing either one are visible
immediately in the other.  But in all other respects, the indirect
buffer and its base buffer are completely separate.  They have
different names, different values of point, different narrowing,
different markers, different major modes, and different local variables.

   An indirect buffer cannot visit a file, but its base buffer can.  If
you try to save the indirect buffer, that actually works by saving the
base buffer.  Killing the base buffer effectively kills the indirect
buffer, but killing an indirect buffer has no effect on its base buffer.

   One way to use indirect buffers is to display multiple views of an
outline.  *Note Outline Views::.


File: emacs,  Node: Windows,  Next: Frames,  Prev: Buffers,  Up: Top

Multiple Windows
****************

Emacs can split a frame into two or many windows.  Multiple windows can
display parts of different buffers, or different parts of one buffer.
Multiple frames always imply multiple windows, because each frame has
its own set of windows.  Each window belongs to one and only one frame.

* Menu:

* Basic Window::       Introduction to Emacs windows.
* Split Window::       New windows are made by splitting existing windows.
* Other Window::       Moving to another window or doing something to it.
* Pop Up Window::      Finding a file or buffer in another window.
* Force Same Window::  Forcing certain buffers to appear in the selected
                         window rather than in another window.
* Change Window::      Deleting windows and changing their sizes.


File: emacs,  Node: Basic Window,  Next: Split Window,  Up: Windows

Concepts of Emacs Windows
=========================

Each Emacs window displays one Emacs buffer at any time.  A single
buffer may appear in more than one window; if it does, any changes in
its text are displayed in all the windows where it appears.  But the
windows showing the same buffer can show different parts of it, because
each window has its own value of point.

   At any time, one of the windows is the "selected window"; the buffer
this window is displaying is the current buffer.  The terminal's cursor
shows the location of point in this window.  Each other window has a
location of point as well, but since the terminal has only one cursor
there is no way to show where those locations are.  When multiple
frames are visible in X Windows, each frame has a cursor which appears
in the frame's selected window.  The cursor in the selected frame is
solid; the cursor in other frames is a hollow box.

   Commands to move point affect the value of point for the selected
Emacs window only.  They do not change the value of point in any other
Emacs window, even one showing the same buffer.  The same is true for
commands such as `C-x b' to change the selected buffer in the selected
window; they do not affect other windows at all.  However, there are
other commands such as `C-x 4 b' that select a different window and
switch buffers in it.  Also, all commands that display information in a
window, including (for example) `C-h f' (`describe-function') and `C-x
C-b' (`list-buffers'), work by switching buffers in a nonselected window
without affecting the selected window.

   When multiple windows show the same buffer, they can have different
regions, because they can have different values of point.  This means
that in Transient Mark mode, each window highlights a different part of
the buffer.  The part that is highlighted in the selected window is the
region that editing commands use.

   Each window has its own mode line, which displays the buffer name,
modification status and major and minor modes of the buffer that is
displayed in the window.  *Note Mode Line::, for full details on the
mode line.


File: emacs,  Node: Split Window,  Next: Other Window,  Prev: Basic Window,  Up: Windows

Splitting Windows
=================

`C-x 2'
     Split the selected window into two windows, one above the other
     (`split-window-vertically').

`C-x 3'
     Split the selected window into two windows positioned side by side
     (`split-window-horizontally').

`C-Mouse-2'
     In the mode line or scroll bar of a window, split that window.

   The command `C-x 2' (`split-window-vertically') breaks the selected
window into two windows, one above the other.  Both windows start out
displaying the same buffer, with the same value of point.  By default
the two windows each get half the height of the window that was split; a
numeric argument specifies how many lines to give to the top window.

   `C-x 3' (`split-window-horizontally') breaks the selected window
into two side-by-side windows.  A numeric argument specifies how many
columns to give the one on the left.  A line of vertical bars separates
the two windows.  Windows that are not the full width of the screen
have mode lines, but they are truncated; also, they do not always
appear in inverse video, because the Emacs display routines have not
been taught how to display a region of inverse video that is only part
of a line on the screen.

   You can split a window horizontally or vertically by clicking
`C-Mouse-2' in the mode line or the scroll bar.  The line of splitting
goes through the place where you click: if you click on the mode line,
the new scroll bar goes above the spot; if you click in the scroll bar,
the mode line of the split window is side by side with your click.

   When a window is less than the full width, text lines too long to
fit are frequent.  Continuing all those lines might be confusing.  The
variable `truncate-partial-width-windows' can be set non-`nil' to force
truncation in all windows less than the full width of the screen,
independent of the buffer being displayed and its value for
`truncate-lines'.  *Note Continuation Lines::.

   Horizontal scrolling is often used in side-by-side windows.  *Note
Display::.

   If `split-window-keep-point' is non-nil, `C-x 2' tries to avoid
shifting any text on the screen by putting point in whichever window
happens to contain the screen line the cursor is already on.  The
default is that `split-window-keep-point' is non-nil on slow terminals.


File: emacs,  Node: Other Window,  Next: Pop Up Window,  Prev: Split Window,  Up: Windows

Using Other Windows
===================

`C-x o'
     Select another window (`other-window').  That is `o', not zero.

`C-M-v'
     Scroll the next window (`scroll-other-window').

`M-x compare-windows'
     Find next place where the text in the selected window does not
     match the text in the next window.

`Mouse-1'
     `Mouse-1', in a window's mode line, selects that window but does
     not move point in it (`mouse-select-region').

   To select a different window, click with `Mouse-1' on its mode line.
With the keyboard, you can switch windows by typing `C-x o'
(`other-window').  That is an `o', for `other', not a zero.  When there
are more than two windows, this command moves through all the windows
in a cyclic order, generally top to bottom and left to right.  After
the rightmost and bottommost window, it goes back to the one at the
upper left corner.  A numeric argument means to move several steps in
the cyclic order of windows.  A negative argument moves around the
cycle in the opposite order.  When the minibuffer is active, the
minibuffer is the last window in the cycle; you can switch from the
minibuffer window to one of the other windows, and later switch back and
finish supplying the minibuffer argument that is requested.  *Note
Minibuffer Edit::.

   The usual scrolling commands (*note Display::) apply to the selected
window only, but there is one command to scroll the next window.
`C-M-v' (`scroll-other-window') scrolls the window that `C-x o' would
select.  It takes arguments, positive and negative, like `C-v'.  (In
the minibuffer, `C-M-v' scrolls the window that contains the minibuffer
help display, if any, rather than the next window in the standard
cyclic order.)

   The command `M-x compare-windows' lets you compare two files or
buffers visible in two windows, by moving through them to the next
mismatch.  *Note Comparing Files::, for details.


File: emacs,  Node: Pop Up Window,  Next: Force Same Window,  Prev: Other Window,  Up: Windows

Displaying in Another Window
============================

`C-x 4' is a prefix key for commands that select another window
(splitting the window if there is only one) and select a buffer in that
window.  Different `C-x 4' commands have different ways of finding the
buffer to select.

`C-x 4 b BUFNAME <RET>'
     Select buffer BUFNAME in another window.  This runs
     `switch-to-buffer-other-window'.

`C-x 4 C-o BUFNAME <RET>'
     Display buffer BUFNAME in another window, but don't select that
     buffer or that window.  This runs `display-buffer'.

`C-x 4 f FILENAME <RET>'
     Visit file FILENAME and select its buffer in another window.  This
     runs `find-file-other-window'.  *Note Visiting::.

`C-x 4 d DIRECTORY <RET>'
     Select a Dired buffer for directory DIRECTORY in another window.
     This runs `dired-other-window'.  *Note Dired::.

`C-x 4 m'
     Start composing a mail message in another window.  This runs
     `mail-other-window'; its same-window analogue is `C-x m' (*note
     Sending Mail::).

`C-x 4 .'
     Find a tag in the current tags table, in another window.  This runs
     `find-tag-other-window', the multiple-window variant of `M-.'
     (*note Tags::).

`C-x 4 r FILENAME <RET>'
     Visit file FILENAME read-only, and select its buffer in another
     window.  This runs `find-file-read-only-other-window'.  *Note
     Visiting::.


File: emacs,  Node: Force Same Window,  Next: Change Window,  Prev: Pop Up Window,  Up: Windows

Forcing Display in the Same Window
==================================

Certain Emacs commands switch to a specific buffer with special
contents.  For example, `M-x shell' switches to a buffer named
`*Shell*'.  By convention, all these commands are written to pop up the
buffer in a separate window.  But you can specify that certain of these
buffers should appear in the selected window.

   If you add a buffer name to the list `same-window-buffer-names', the
effect is that such commands display that particular buffer by
switching to it in the selected window.  For example, if you add the
element `"*grep*"' to the list, the `grep' command will display its
output buffer in the selected window.

   The default value of `same-window-buffer-names' is not `nil'.  It
specifies the buffers `*info*', `*mail*' and `*shell*'.  This is why
`M-x shell' normally switches to the `*shell*' buffer in the selected
window.  If you delete this element from the value of
`same-window-buffer-names', the behavior of `M-x shell' will change--it
will pop up the buffer in another window instead.

   You can specify these buffers more generally with the variable
`same-window-regexps'.  Set it to a list of regular expressions; then
any buffer whose name matches one of those regular expressions is
displayed by switching to it in the selected window.  (Once again, this
applies only to buffers that normally get displayed for you in a
separate window.)  The default value of this variable specifies Telnet
and rlogin buffers.

   An analogous feature lets you specify buffers which should be
displayed in their own individual frames.  *Note Special Buffer
Frames::.


File: emacs,  Node: Change Window,  Prev: Force Same Window,  Up: Windows

Deleting and Rearranging Windows
================================

`C-x 0'
     Delete the selected window (`delete-window').  That is a zero.

`C-x 1'
     Delete all windows in the selected frame except the selected window
     (`delete-other-windows').

`C-x ^'
     Make selected window taller (`enlarge-window').

`C-x }'
     Make selected window wider (`enlarge-window-horizontally').

`Drag-Mouse-1'
     Dragging a window's mode line up or down with `Mouse-1' changes
     window heights.

`Mouse-2'
     `Mouse-2' in a window's mode line deletes all other windows in the
     frame (`mouse-delete-other-windows').

`Mouse-3'
     `Mouse-3' in a window's mode line deletes that window
     (`mouse-delete-window').

   To delete a window, type `C-x 0' (`delete-window').  (That is a
zero.)  The space occupied by the deleted window is given to an
adjacent window (but not the minibuffer window, even if that is active
at the time).  Once a window is deleted, its attributes are forgotten;
only restoring a window configuration can bring it back.  Deleting the
window has no effect on the buffer it used to display; the buffer
continues to exist, and you can select it in any window with `C-x b'.

   `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it
deletes all the windows except the selected one (and the minibuffer);
the selected window expands to use the whole frame except for the echo
area.

   You can also delete a window by clicking on its mode line with
`Mouse-2', and expand a window to fill its frame by clicking on its
mode line with `Mouse-3'.

   The easiest way to adjust window heights is with a mouse.  If you
press `Mouse-1' on a mode line, you can drag that mode line up or down,
changing the heights of the windows above and below it.

   To readjust the division of space among vertically adjacent windows,
use `C-x ^' (`enlarge-window').  It makes the currently selected window
get one line bigger, or as many lines as is specified with a numeric
argument.  With a negative argument, it makes the selected window
smaller.  `C-x }' (`enlarge-window-horizontally') makes the selected
window wider by the specified number of columns.  The extra screen
space given to a window comes from one of its neighbors, if that is
possible.  If this makes any window too small, it is deleted and its
space is given to an adjacent window.  The minimum size is specified by
the variables `window-min-height' and `window-min-width'.

   *Note Minibuffer Edit::, for information about the Resize-Minibuffer
mode, which automatically changes the size of the minibuffer window to
fit the text in the minibuffer.


File: emacs,  Node: Frames,  Next: Major Modes,  Prev: Windows,  Up: Top

Frames and X Windows
********************

When using the X Window System, you can create multiple windows at the
X level in a single Emacs session.  Each X window that belongs to Emacs
displays a "frame" which can contain one or several Emacs windows.  A
frame initially contains a single general-purpose Emacs window which
you can subdivide vertically or horizontally into smaller windows.  A
frame normally contains its own echo area and minibuffer, but you can
make frames that don't have these--they use the echo area and
minibuffer of another frame.

   Editing you do in one frame also affects the other frames.  For
instance, if you put text in the kill ring in one frame, you can yank it
in another frame.  If you exit Emacs through `C-x C-c' in one frame, it
terminates all the frames.  To delete just one frame, use `C-x 5 0'.

   To avoid confusion, we reserve the word "window" for the
subdivisions that Emacs implements, and never use it to refer to a
frame.

* Menu:

* Mouse Commands::     Moving, cutting, and pasting, with the mouse.
* Secondary Selection::Cutting without altering point and mark.
* Mouse References::   Using the mouse to select an item from a list.
* Menu Mouse Clicks::  Mouse clicks that bring up menus.
* Mode Line Mouse::    Mouse clicks on the mode line.
* Creating Frames::    Creating additional Emacs frames with various contents.
* Multiple Displays::  How one Emacs job can talk to several displays.
* Special Buffer Frames::  You can make certain buffers have their own frames.
* Frame Parameters::   Changing the colors and other modes of frames.
* Scroll Bars::	       How to enable and disable scroll bars; how to use them.
* Menu Bars::	       Enabling and disabling the menu bar.
* Faces::	       How to change the display style using faces.
* Modifying Faces::    How to change what a particular face looks like.
* Font Lock::          Minor mode for syntactic highlighting using faces.
* Support Modes::      Font Lock support modes make Font Lock faster.
* Misc X::	       Iconifying and deleting frames.	Region highlighting.
* Non-Window Terminals::  Multiple frames on terminals that only show one.


File: emacs,  Node: Mouse Commands,  Next: Secondary Selection,  Up: Frames

Mouse Commands for Editing
==========================

The mouse commands for selecting and copying a region are mostly
compatible with the `xterm' program.  You can use the same mouse
commands for copying between Emacs and other X client programs.

`Mouse-1'
     Move point to where you click (`mouse-set-point').  This is
     normally the left button.

`Drag-Mouse-1'
     Set the region to the text you select by dragging, and copy it to
     the kill ring (`mouse-set-region').  You can specify both ends of
     the region with this single command.

     If you move the mouse off the top or bottom of the window while
     dragging, the window scrolls at a steady rate until you move the
     mouse back into the window.  This way, you can select regions that
     don't fit entirely on the screen.  The number of lines scrolled
     per step depends on how far away from the window edge the mouse
     has gone; the variable `mouse-scroll-min-lines' specifies a
     minimum step size.

`Mouse-2'
     Yank the last killed text, where you click (`mouse-yank-at-click').
     This is normally the middle button.

`Mouse-3'
     This command, `mouse-save-then-kill', has several functions
     depending on where you click and the status of the region.

     The most basic case is when you click `Mouse-1' in one place and
     then `Mouse-3' in another.  This selects the text between those two
     positions as the region.  It also copies the new region to the kill
     ring, so that you can copy it to someplace else.

     If you click `Mouse-1', scroll with the scroll bar, and then click
     `Mouse-3', it remembers where point was before scrolling (where you
     put it with `Mouse-1'), and uses that position as the other end of
     the region.  This is so that you can select a region that doesn't
     fit entirely on the screen.

     More generally, if you do not have a highlighted region, `Mouse-3'
     selects the text between point and the click position as the
     region.  It does this by setting the mark where point was, and
     moving point to where you click.

     If you have a highlighted region, or if the region was set just
     before by dragging button 1, `Mouse-3' adjusts the nearer end of
     the region by moving it to where you click.  The adjusted region's
     text also replaces the old region's text in the kill ring.

     If you originally specified the region using a double or triple
     `Mouse-1', so that the region is defined to consist of entire words
     or lines, then adjusting the region with `Mouse-3' also proceeds by
     entire words or lines.

     If you use `Mouse-3' a second time consecutively, at the same
     place, that kills the region already selected.

`Double-Mouse-1'
     This key sets the region around the word which you click on.  If
     you click on a character with "symbol" syntax (such as underscore,
     in C mode), it sets the region around the symbol surrounding that
     character.

     If you click on a character with open-parenthesis or
     close-parenthesis syntax, it sets the region around the
     parenthetical grouping (sexp) which that character starts or ends.
     If you click on a character with string-delimiter syntax (such as
     a singlequote or doublequote in C), it sets the region around the
     string constant (using heuristics to figure out whether that
     character is the beginning or the end of it).

`Double-Drag-Mouse-1'
     This key selects a region made up of the words that you drag
     across.

`Triple-Mouse-1'
     This key sets the region around the line which you click on.

`Triple-Drag-Mouse-1'
     This key selects a region made up of the lines that you drag
     across.

   The simplest way to kill text with the mouse is to press `Mouse-1'
at one end, then press `Mouse-3' twice at the other end.  *Note
Killing::.  To copy the text into the kill ring without deleting it
from the buffer, press `Mouse-3' just once--or just drag across the
text with `Mouse-1'.  Then you can copy it elsewhere by yanking it.

   To yank the killed or copied text somewhere else, move the mouse
there and press `Mouse-2'.  *Note Yanking::.  However, if
`mouse-yank-at-point' is non-`nil', `Mouse-2' yanks at point.  Then it
does not matter precisely where you click; all that matters is which
window you click on.  The default value is `nil'.  This variable also
effects yanking the secondary selection.

   To copy text to another X window, kill it or save it in the kill
ring.  Under X, this also sets the "primary selection".  Then use the
"paste" or "yank" command of the program operating the other window to
insert the text from the selection.

   To copy text from another X window, use the "cut" or "copy" command
of the program operating the other window, to select the text you want.
Then yank it in Emacs with `C-y' or `Mouse-2'.

   When Emacs puts text into the kill ring, or rotates text to the front
of the kill ring, it sets the "primary selection" in the X server.
This is how other X clients can access the text.  Emacs also stores the
text in the cut buffer, but only if the text is short enough
(`x-cut-buffer-max' specifies the maximum number of characters);
putting long strings in the cut buffer can be slow.

   The commands to yank the first entry in the kill ring actually check
first for a primary selection in another program; after that, they check
for text in the cut buffer.  If neither of those sources provides text
to yank, the kill ring contents are used.


File: emacs,  Node: Secondary Selection,  Next: Mouse References,  Prev: Mouse Commands,  Up: Frames

Secondary Selection
===================

The "secondary selection" is another way of selecting text using X.  It
does not use point or the mark, so you can use it to kill text without
setting point or the mark.

`M-Drag-Mouse-1'
     Set the secondary selection, with one end at the place where you
     press down the button, and the other end at the place where you
     release it (`mouse-set-secondary').  The highlighting appears and
     changes as you drag.

     If you move the mouse off the top or bottom of the window while
     dragging, the window scrolls at a steady rate until you move the
     mouse back into the window.  This way, you can mark regions that
     don't fit entirely on the screen.

`M-Mouse-1'
     Set one endpoint for the "secondary selection"
     (`mouse-start-secondary').

`M-Mouse-3'
     Make a secondary selection, using the place specified with
     `M-Mouse-1' as the other end (`mouse-secondary-save-then-kill').
     A second click at the same place kills the secondary selection
     just made.

`M-Mouse-2'
     Insert the secondary selection where you click
     (`mouse-kill-secondary').  This places point at the end of the
     yanked text.

   Double or triple clicking of `M-Mouse-1' operates on words and
lines, much like `Mouse-1'.

   If `mouse-yank-at-point' is non-`nil', `M-Mouse-2' yanks at point.
Then it does not matter precisely where you click; all that matters is
which window you click on.  *Note Mouse Commands::.


File: emacs,  Node: Mouse References,  Next: Menu Mouse Clicks,  Prev: Secondary Selection,  Up: Frames

Following References with the Mouse
===================================

Some Emacs buffers display lists of various sorts.  These include lists
of files, of buffers, of possible completions, of matches for a
pattern, and so on.

   Since yanking text into these buffers is not very useful, most of
them define `Mouse-2' specially, as a command to use or view the item
you click on.

   For example, if you click `Mouse-2' on a file name in a Dired
buffer, you visit the that file.  If you click `Mouse-2' on an error
message in the `*Compilation*' buffer, you go to the source code for
that error message.  If you click `Mouse-2' on a completion in the
`*Completions*' buffer, you choose that completion.

   You can usually tell when `Mouse-2' has this special sort of meaning
because the sensitive text highlights when you move the mouse over it.


File: emacs,  Node: Menu Mouse Clicks,  Next: Mode Line Mouse,  Prev: Mouse References,  Up: Frames

Mouse Clicks for Menus
======================

Mouse clicks modified with the <CONTROL> and <SHIFT> keys bring up
menus.

`C-Mouse-1'
     This menu is for selecting a buffer.

`C-Mouse-2'
     This menu is for specifying faces and other text properties for
     editing formatted text.  *Note Formatted Text::.

`C-Mouse-3'
     This menu is mode-specific.  For most modes, this menu has the same
     items as all the mode-specific menu bar menus put together.  Some
     modes may specify a different menu for this button.(1)

`S-mouse-1'
     This menu is for specifying the frame's default font.

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

   (1) Some systems use `Mouse-3' for a mode-specific menu.  We took a
survey of users, and found they preferred to keep `Mouse-3' for
selecting and killing regions.  Hence the decision to use `C-Mouse-3'
for this menu.


File: emacs,  Node: Mode Line Mouse,  Next: Creating Frames,  Prev: Menu Mouse Clicks,  Up: Frames

Mode Line Mouse Commands
========================

You can use mouse clicks on window mode lines to select and manipulate
windows.

`Mouse-1'
     `Mouse-1' on a mode line selects the window above.  By dragging
     `Mouse-1' on the mode line, you can move it, thus changing the
     height of the windows above and below.

`Mouse-2'
     `Mouse-2' on a mode line expands that window to fill its frame.

`Mouse-3'
     `Mouse-3' on a mode line deletes the window above.

`C-Mouse-2'
     `C-Mouse-2' on a mode line splits the window above horizontally,
     above the place in the mode line where you click.

   `C-Mouse-2' on a scroll bar splits the corresponding window
vertically.  *Note Split Window::.


File: emacs,  Node: Creating Frames,  Next: Multiple Displays,  Prev: Mode Line Mouse,  Up: Frames

Creating Frames
===============

The prefix key `C-x 5' is analogous to `C-x 4', with parallel
subcommands.  The difference is that `C-x 5' commands create a new
frame rather than just a new window in the selected frame  (*Note Pop
Up Window::).  If an existing visible or iconified frame already
displays the requested material, these commands use the existing frame,
after raising or deiconifying as necessary.

   The various `C-x 5' commands differ in how they find or create the
buffer to select:

`C-x 5 2'
     Create a new frame (`make-frame').

`C-x 5 b BUFNAME <RET>'
     Select buffer BUFNAME in another window.  This runs
     `switch-to-buffer-other-frame'.

`C-x 5 f FILENAME <RET>'
     Visit file FILENAME and select its buffer in another frame.  This
     runs `find-file-other-frame'.  *Note Visiting::.

`C-x 5 d DIRECTORY <RET>'
     Select a Dired buffer for directory DIRECTORY in another frame.
     This runs `dired-other-frame'.  *Note Dired::.

`C-x 5 m'
     Start composing a mail message in another frame.  This runs
     `mail-other-frame'.  It is the other-frame variant of `C-x m'.
     *Note Sending Mail::.

`C-x 5 .'
     Find a tag in the current tag table in another frame.  This runs
     `find-tag-other-frame', the multiple-frame variant of `M-.'.
     *Note Tags::.

`C-x 5 r FILENAME <RET>'
     Visit file FILENAME read-only, and select its buffer in another
     frame.  This runs `find-file-read-only-other-frame'.  *Note
     Visiting::.

   You can control the appearance of new frames you create by setting
the frame parameters in `default-frame-alist'.  You can use the
variable `initial-frame-alist' to specify parameters that affect only
the initial frame.  *Note Initial Parameters: (elisp)Initial
Parameters, for more information.


File: emacs,  Node: Multiple Displays,  Next: Special Buffer Frames,  Prev: Creating Frames,  Up: Frames

Multiple Displays
=================

A single Emacs can talk to more than one X Windows display.  Initially,
Emacs uses just one display--the one specified with the `DISPLAY'
environment variable or with the `--display' option (*note Initial
Options::).  To connect to another display, use the command
`make-frame-on-display':

`M-x make-frame-on-display <RET> DISPLAY <RET>'
     Create a new frame on display DISPLAY.

   A single X server can handle more than one screen.  When you open
frames on two screens belonging to one server, Emacs knows they share a
single keyboard, and it treats all the commands arriving from these
screens as a single stream of input.

   When you open frames on different X servers, Emacs makes a separate
input stream for each server.  This way, two users can type
simultaneously on the two displays, and Emacs will not garble their
input.  Each server also has its own selected frame.  The commands you
enter with a particular X server apply to that server's selected frame.

   Despite these features, people using the same Emacs job from
different displays can still interfere with each other if they are not
careful.  For example, if any one types `C-x C-c', that exits the Emacs
job for all of them!


File: emacs,  Node: Special Buffer Frames,  Next: Frame Parameters,  Prev: Multiple Displays,  Up: Frames

Special Buffer Frames
=====================

You can make certain chosen buffers, for which Emacs normally creates a
second window when you have just one window, appear in special frames
of their own.  To do this, set the variable
`special-display-buffer-names' to a list of buffer names; any buffer
whose name is in that list automatically gets a special frame, when an
Emacs command wants to display it "in another window."

   For example, if you set the variable this way,

     (setq special-display-buffer-names
           '("*Completions*" "*grep*" "*tex-shell*"))

then completion lists, `grep' output and the TeX mode shell buffer get
individual frames of their own.  These frames, and the windows in them,
are never automatically split or reused for any other buffers.  They
continue to show the buffers they were created for, unless you alter
them by hand.  Killing the special buffer deletes its frame
automatically.

   More generally, you can set `special-display-regexps' to a list of
regular expressions; then a buffer gets its own frame if its name
matches any of those regular expressions.  (Once again, this applies
only to buffers that normally get displayed for you in a separate
window.)

   The variable `special-display-frame-alist' specifies the frame
parameters for these frames.  It has a default value, so you don't need
to set it.

   For those who know Lisp, an element of
`special-display-buffer-names' or `special-display-regexps' can also be
a list.  Then the first element is the buffer name or regular
expression; the rest of the list specifies how to create the frame.  It
can be an association list specifying frame parameter values; these
values take precedence over parameter values specified in
`special-display-frame-alist'.  Alternatively, it can have this form:

     (FUNCTION ARGS...)

where FUNCTION is a symbol.  Then the frame is constructed by calling
FUNCTION; its first argument is the buffer, and its remaining arguments
are ARGS.


File: emacs,  Node: Frame Parameters,  Next: Scroll Bars,  Prev: Special Buffer Frames,  Up: Frames

Setting Frame Parameters
========================

This section describes commands for altering the display style and
window management behavior of the selected frame.

`M-x set-foreground-color <RET> COLOR <RET>'
     Specify color COLOR for the foreground of the selected frame.

`M-x set-background-color <RET> COLOR <RET>'
     Specify color COLOR for the background of the selected frame.
     This changes the foreground color of the `modeline' face also, so
     that it remains in inverse video compared with the default.

`M-x set-cursor-color <RET> COLOR <RET>'
     Specify color COLOR for the cursor of the selected frame.

`M-x set-mouse-color <RET> COLOR <RET>'
     Specify color COLOR for the mouse cursor when it is over the
     selected frame.

`M-x set-border-color <RET> COLOR <RET>'
     Specify color COLOR for the border of the selected frame.

`M-x list-colors-display'
     Display the defined color names and show what the colors look like.
     This command is somewhat slow.

`M-x auto-raise-mode'
     Toggle whether or not the selected frame should auto-raise.
     Auto-raise means that every time you move the mouse onto the
     frame, it raises the frame.

     Note that this auto-raise feature is implemented by Emacs itself.
     Some window managers also implement auto-raise.  If you enable
     auto-raise for Emacs frames in your X window manager, it should
     work, but it is beyond Emacs's control and therefore
     `auto-raise-mode' has no effect on it.

`M-x auto-lower-mode'
     Toggle whether or not the selected frame should auto-lower.
     Auto-lower means that every time you move the mouse off of the
     frame, the frame moves to the bottom of the stack of X windows.

     The command `auto-lower-mode' has no effect on auto-lower
     implemented by the X window manager.  To control that, you must use
     the appropriate window manager features.

`M-x set-default-font <RET> FONT <RET>'
     Specify font FONT as the default for the selected frame.  *Note
     Font X::, for ways to list the available fonts on your system.

     You can also set a frame's default font through a pop-up menu.
     Press `S-Mouse-1' to activate this menu.

   In Emacs versions that use an X toolkit, the color-setting and
font-setting functions don't affect menus and the menu bar, since they
are displayed by their own widget classes.  To change the appearance of
the menus and menu bar, you must use X resources (*note Resources X::).
*Note Colors X::, regarding colors.  *Note Font X::, regarding choice of
font.

   For information on frame parameters and customization, see *Note
Frame Parameters: (elisp)Frame Parameters.


File: emacs,  Node: Scroll Bars,  Next: Menu Bars,  Prev: Frame Parameters,  Up: Frames

Scroll Bars
===========

When using X, Emacs normally makes a "scroll bar" at the right of each
Emacs window.  The scroll bar runs the height of the window, and shows
a moving rectangular inner box which represents the portion of the
buffer currently displayed.  The entire height of the scroll bar
represents the entire length of the buffer.

   You can use `Mouse-2' (normally, the middle button) in the scroll
bar to move or drag the inner box up and down.  If you move it to the
top of the scroll bar, you see the top of the buffer.  If you move it to
the bottom of the scroll bar, you see the bottom of the buffer.

   The left and right buttons in the scroll bar scroll by controlled
increments.  `Mouse-1' (normally, the left button) moves the line at
the level where you click up to the top of the window.  `Mouse-3'
(normally, the right button) moves the line at the top of the window
down to the level where you click.  By clicking repeatedly in the same
place, you can scroll by the same distance over and over.

   Aside from scrolling, you can also click `C-Mouse-2' in the scroll
bar to split a window vertically.  The split occurs on the line where
you click.

   You can enable or disable Scroll Bar mode with the command `M-x
scroll-bar-mode'.  With no argument, it toggles the use of scroll bars.
With an argument, it turns use of scroll bars on if and only if the
argument is positive.  This command applies to all frames, including
frames yet to be created.  You can use the X resource
`verticalScrollBars' to control the initial setting of Scroll Bar mode.
*Note Resources X::.

   To enable or disable scroll bars for just the selected frame, use the
`M-x toggle-scroll-bar' command.


File: emacs,  Node: Menu Bars,  Next: Faces,  Prev: Scroll Bars,  Up: Frames

Menu Bars
=========

By default, each Emacs frame has a menu bar at the top which you can
use to perform certain common operations.  There's no need to describe
them in detail here, as you can more easily see for yourself; also, we
may change them and add to them in subsequent Emacs versions.

   When you are using a window system, you can use the mouse to choose a
command from the menu bar.  On text-only terminals, you can use the menu
bar by typing `M-`' (`tmm-menubar').  This enters a mode in which you
can select a menu item from the keyboard.  Either type the initial of
the item you want, or use the left and right arrow keys to choose an
item and use <RET> to finalize the choice.

   Each of the operations in the menu bar is bound to an ordinary Emacs
command which you can invoke equally well with `M-x' or with its own
key bindings.  The menu lists one equivalent key binding (if the command
has any) at the right margin.  To see the command's name and
documentation, type `C-h k' and then select the menu bar item you are
interested in.

   You can turn display of menu bars on or off with `M-x
menu-bar-mode'.  With no argument, this command toggles Menu Bar mode, a
minor mode.  With an argument, the command turns Menu Bar mode on if the
argument is positive, off if the argument is not positive.  You can use
the X resource `menuBarLines' to control the initial setting of Menu
Bar mode.  *Note Resources X::.  Expert users often turn off the menu
bar, especially on text-only terminals where this makes one additional
line available for text.


File: emacs,  Node: Faces,  Next: Modifying Faces,  Prev: Menu Bars,  Up: Frames

Using Multiple Typefaces
========================

When using Emacs with X, you can set up multiple styles of displaying
characters.  The aspects of style that you can control are the type
font, the foreground color, the background color, and whether to
underline.  Emacs on MS-DOS supports faces partially by letting you
control the foreground and background colors of each face (*note
MS-DOS::).

   The way you control display style is by defining named "faces".
Each face can specify a type font, a foreground color, a background
color, and an underline flag; but it does not have to specify all of
them.

   The style of display used for a given character in the text is
determined by combining several faces.  Any aspect of the display style
that isn't specified by overlays or text properties comes from the frame
itself.

   Enriched mode, the mode for editing formatted text, includes several
commands and menus for specifying faces.  *Note Format Faces::, for how
to specify the font for text in the buffer.  *Note Format Colors::, for
how to specify the foreground and background color.

   To see what faces are currently defined, and what they look like,
type `M-x list-faces-display'.  It's possible for a given face to look
different in different frames; this command shows the appearance in the
frame in which you type it.  Here's a list of the standardly defined
faces:

`default'
     This face is used for ordinary text that doesn't specify any other
     face.

`modeline'
     This face is used for mode lines.  By default, it's set up as the
     inverse of the default face.  *Note Display Vars::.

`highlight'
     This face is used for highlighting portions of text, in various
     modes.

`region'
     This face is used for displaying a selected region (when Transient
     Mark mode is enabled--see below).

`secondary-selection'
     This face is used for displaying a secondary selection (*note
     Secondary Selection::).

`bold'
     This face uses a bold variant of the default font, if it has one.

`italic'
     This face uses an italic variant of the default font, if it has
     one.

`bold-italic'
     This face uses a bold italic variant of the default font, if it
     has one.

`underline'
     This face underlines text.

   When Transient Mark mode is enabled, the text of the region is
highlighted when the mark is active.  This uses the face named
`region'; you can control the style of highlighting by changing the
style of this face (*note Modifying Faces::).  *Note Transient Mark::,
for more information about Transient Mark mode and activation and
deactivation of the mark.

   One easy way to use faces is to turn on Font Lock mode.  This minor
mode, which is always local to a particular buffer, arranges to choose
faces according to the syntax of the text you are editing.  It can
recognize comments and strings in most languages; in several languages,
it can also recognize and properly highlight various other important
constructs.  *Note Font Lock::, for more information about Font Lock
mode and syntactic highlighting.

   You can print out the buffer with the highlighting that appears on
your screen using the command `ps-print-buffer-with-faces'.  *Note
Postscript::.


File: emacs,  Node: Modifying Faces,  Next: Font Lock,  Prev: Faces,  Up: Frames

Modifying Faces
===============

Here are the commands for changing the font of a face:

`M-x set-face-font <RET> FACE <RET> FONT <RET>'
     Change face FACE to use font FONT.  *Note Font X::, for more
     information about font naming under X.

`M-x make-face-bold <RET> FACE <RET>'
     Convert face FACE to use a bold version of its current font.

`M-x make-face-italic <RET> FACE <RET>'
     Convert face FACE to use a italic version of its current font.

`M-x make-face-bold-italic <RET> FACE <RET>'
     Convert face FACE to use a bold-italic version of its current font.

`M-x make-face-unbold <RET> FACE <RET>'
     Convert face FACE to use a non-bold version of its current font.

`M-x make-face-unitalic <RET> FACE <RET>'
     Convert face FACE to use a non-italic version of its current font.

   Here are the commands for setting the colors and underline flag of a
face:

`M-x set-face-foreground <RET> FACE <RET> COLOR <RET>'
     Use color COLOR for the foreground of characters in face FACE.

`M-x set-face-background <RET> FACE <RET> COLOR <RET>'
     Use color COLOR for the background of characters in face FACE.

     On a black-and-white display, the colors you can use for the
     background are `black', `white', `gray', `gray1' and `gray3'.
     Emacs supports the gray colors by using background stipple
     patterns instead of a color.

`M-x set-face-stipple <RET> FACE <RET> PATTERN <RET>'
     Use stipple pattern PATTERN for the background of characters in
     face FACE.

`M-x list-colors-display'
     Display the defined color names and show what the colors look like.

`M-x set-face-underline-p <RET> FACE <RET> FLAG <RET>'
     Specify whether to underline characters in face FACE.

`M-x invert-face <RET> FACE <RET>'
     Swap the foreground and background colors of face FACE.

`M-x modify-face <RET> FACE <RET> ATTRIBUTES...'
     Change various attributes of face FACE.  This command prompts for
     all the attribute of the face, one attribute at a time.  For the
     color and stipple attributes, the attribute's current value is the
     default--type just <RET> if you don't want to change that
     attribute.  Type `none' if you want to clear out the attribute.

   You can also use X resources to specify attributes of particular
faces.  *Note Resources X::.


File: emacs,  Node: Font Lock,  Next: Support Modes,  Prev: Modifying Faces,  Up: Frames

Font Lock mode
==============

Font Lock mode is a minor mode, always local to a particular buffer,
which highlights (or "fontifies") using various faces according to the
syntax of the text you are editing.  It can recognize comments and
strings in most languages; in several languages, it can also recognize
and properly highlight various other important constructs--for example,
names of functions being defined or reserved keywords.

   The command `M-x font-lock-mode' turns Font Lock mode on or off
according to the argument, and toggles the mode when it has no argument.
The function `turn-on-font-lock' unconditionally enables Font Lock
mode.  This is useful in mode-hook functions.  For example, to enable
Font Lock mode whenever you edit a C file, you can do this:

     (add-hook 'c-mode-hook 'turn-on-font-lock)

   To turn on Font Lock mode automatically in all modes which support
it, use the function `global-font-lock-mode', like this:

     (global-font-lock-mode t)

   In Font Lock mode, when you edit the text, the highlighting updates
automatically in the line that you changed.  Most changes don't affect
the highlighting of subsequent lines, but occasionally they do.  To
rehighlight a range of lines, use the command `C-M-g'
(`font-lock-fontify-block').

   In certain major modes, `C-M-g' refontifies the entire current
function.  (The variable `font-lock-mark-block-function' controls how
to find the current function.)  In other major modes, `C-M-g'
refontifies 16 lines above and below point.

   With a prefix argument N, `C-M-g' refontifies N lines above and
below point, regardless of the mode.

   To get the full benefit of Font Lock mode, you need to choose a
default font which has bold, italic, and bold-italic variants; or else
you need to have a color or grayscale screen.  The variable
`font-lock-display-type' specifies whether Font Lock mode should use
font styles, colors, or shades of gray to distinguish the various kinds
of text.  Emacs chooses the default value according to the
characteristics of your display.

   The variable `font-lock-maximum-decoration' specifies the preferred
level of fontification for modes that provide multiple levels.  The
normal default is 1; larger numbers request more fontification, and
some modes support levels as high as 3.  These variables can also
specify different numbers for particular major modes; for example, to
use level 3 for C/C++ modes, and the default level otherwise, use this:

     (setq font-lock-maximum-decoration
           '((c-mode . 3) (c++-mode . 3)))

   Fontification can be too slow for large buffers, so you can suppress
it.  The variable `font-lock-maximum-size' specifies a buffer size,
beyond which buffer fontification is suppressed.


File: emacs,  Node: Support Modes,  Next: Misc X,  Prev: Font Lock,  Up: Frames

Font Lock Support Modes
=======================

Font Lock support modes make Font Lock mode faster for large buffers.
There are two support modes: Fast Lock mode and Lazy Lock mode.  They
use two different methods of speeding up Font Lock mode.

* Menu:

* Fast Lock Mode::     Saving font information in files.
* Lazy Lock Mode::     Fontifying only text that is actually displayed.
* Fast or Lazy::       Which support mode is best for you?


File: emacs,  Node: Fast Lock Mode,  Next: Lazy Lock Mode,  Up: Support Modes

Fast Lock Mode
--------------

To make Font Lock mode faster for buffers visiting large files, you can
use Fast Lock mode.  Fast Lock mode saves the font information for each
file in a separate cache file; each time you visit the file, it rereads
the font information from the cache file instead of refontifying the
text from scratch.

   The command `M-x fast-lock-mode' turns Fast Lock mode on or off,
according to the argument (with no argument, it toggles).  You can also
arrange to enable Fast Lock mode whenever you use Font Lock mode, like
this:

     (setq font-lock-support-mode 'fast-lock-mode)

   It is not worth writing a cache file for small buffers.  Therefore,
the variable `fast-lock-minimum-size' specifies a minimum file size for
caching font information.

   The variable `fast-lock-cache-directories' specifies where to put
the cache files.  Its value is a list of directories to try; `"."'
means the same directory as the file being edited.  The default value is
`("." "~/.emacs-flc")', which means to use the same directory if
possible, and otherwise the directory `~/.emacs-flc'.

   The variable `fast-lock-save-others' specifies whether Fast Lock
mode should save cache files for files that you do not own.  A
non-`nil' value means yes (and that is the default).


File: emacs,  Node: Lazy Lock Mode,  Next: Fast or Lazy,  Prev: Fast Lock Mode,  Up: Support Modes

Lazy Lock Mode
--------------

To make Font Lock mode faster for large buffers, you can use Lazy Lock
mode to reduce the amount of text that is fontified.  In Lazy Lock mode,
buffer fontification is demand-driven; it happens to portions of the
buffer that are about to be displayed.  And fontification of your
changes is deferred; it happens only when Emacs has been idle for a
certain short period of time.

   The command `M-x lazy-lock-mode' turns Lazy Lock mode on or off,
according to the argument (with no argument, it toggles).  You can also
arrange to enable Lazy Lock mode whenever you use Font Lock mode, like
this:

     (setq font-lock-support-mode 'lazy-lock-mode)

   It is not worth avoiding buffer fontification for small buffers.
Therefore, the variable `lazy-lock-minimum-size' specifies a minimum
buffer size for demand-driven buffer fontification.  Buffers smaller
than that are fontified all at once, as in plain Font Lock mode.

   When you alter the buffer, Lazy Lock mode defers fontification of the
text you changed.  The variable `lazy-lock-defer-time' specifies how
many seconds Emacs must be idle before it starts fontifying your
changes.  If the value is `nil', then changes are fontified
immediately, as in plain Font Lock mode.

   Lazy Lock mode normally fontifies newly visible portions of the
buffer before they are first displayed.  However, if the value of
`lazy-lock-defer-driven' is non-`nil', newly visible text is fontified
only when Emacs is idle for `lazy-lock-defer-time' seconds.

   When Emacs is idle for a long time, Lazy Lock fontifies additional
portions of the buffer, not yet displayed, in case you will display them
later.  This is called "stealth fontification".

   The variable `lazy-lock-stealth-time' specifies how many seconds
Emacs has to be idle before stealth fontification starts.  A value of
`nil' means no stealth fontification.  The variables
`lazy-lock-stealth-lines' and `lazy-lock-stealth-verbose' specify the
granularity and verbosity of stealth fontification.


File: emacs,  Node: Fast or Lazy,  Prev: Lazy Lock Mode,  Up: Support Modes

Fast Lock or Lazy Lock?
-----------------------

Here is a simple guide to help you choose one of the Font Lock support
modes.

   * Fast Lock mode only intervenes during file visiting and buffer
     killing (and related events); therefore buffer editing and window
     scrolling are no faster or slower than plain Font Lock mode.

   * Fast Lock mode is slower at reading a cache file than Lazy Lock
     mode is at fontifying a window; therefore Fast Lock mode is slower
     at visiting a file than Lazy Lock mode.

   * Lazy Lock mode intervenes during window scrolling to fontify text
     that scrolls onto the screen; therefore, scrolling is slower than
     in plain Font Lock mode.

   * Lazy Lock mode doesn't fontify during buffer editing (it defers
     fontification of changes); therefore, editing is faster than in
     plain Font Lock mode.

   * Fast Lock mode can be fooled by a file that is kept under version
     control software; therefore buffer fontification may occur even
     when a cache file exists for the file.

   * Fast Lock mode only works with a buffer visiting a file; Lazy Lock
     mode works with any buffer.

   * Fast Lock mode generates cache files; Lazy Lock mode does not.

   The variable `font-lock-support-mode' specifies which of these
support modes to use; for example, to specify that Fast Lock mode is
used for C/C++ modes, and Lazy Lock mode otherwise, set the variable
like this:

     (setq font-lock-support-mode
           '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode)
             (t . lazy-lock-mode)))


File: emacs,  Node: Misc X,  Next: Non-Window Terminals,  Prev: Support Modes,  Up: Frames

Miscellaneous X Window Features
===============================

The following commands let you create, delete and operate on frames:

`C-z'
     To iconify the selected Emacs frame, type `C-z'
     (`iconify-or-deiconify-frame').  The normal meaning of `C-z', to
     suspend Emacs, is not useful under a window system, so it has a
     different binding in that case.

     If you type this command on an Emacs frame's icon, it deiconifies
     the frame.

`C-x 5 0'
     To delete the selected frame, type `C-x 5 0' (`delete-frame').
     This is not allowed if there is only one frame.

`C-x 5 o'
     Select another frame, raise it, and warp the mouse to it so that it
     stays selected.  If you repeat this command, it cycles through all
     the frames on your terminal.

`M-x transient-mark-mode'
     Under X Windows, when Transient Mark mode is enabled, Emacs
     highlights the region when the mark is active.  This feature is
     the main motive for using Transient Mark mode.  To toggle the
     state of this mode, use the command `M-x transient-mark-mode'.
     *Note Mark::.


File: emacs,  Node: Non-Window Terminals,  Prev: Misc X,  Up: Frames

Non-Window Terminals
====================

If your terminal does not have a window system that Emacs supports,
then it can display only one Emacs frame at a time.  However, you can
still create multiple Emacs frames, and switch between them.  Switching
frames on these terminals is much like switching between different
window configurations.

   Use `C-x 5 2' to create a new frame and switch to it; use `C-x 5 o'
to cycle through the existing frames; use `C-x 5 0' to delete the
current frame.

   Each frame has a number to distinguish it.  The selected frame's
number appears in the mode line after `Emacs', except when frame 1 is
selected.


File: emacs,  Node: Major Modes,  Next: Indentation,  Prev: Frames,  Up: Top

Major Modes
***********

Emacs provides many alternative "major modes", each of which customizes
Emacs for editing text of a particular sort.  The major modes are
mutually exclusive, and each buffer has one major mode at any time.
The mode line normally shows the name of the current major mode, in
parentheses (*note Mode Line::).

   The least specialized major mode is called "Fundamental mode".  This
mode has no mode-specific redefinitions or variable settings, so that
each Emacs command behaves in its most general manner, and each option
is in its default state.  For editing text of a specific type that
Emacs knows about, such as Lisp code or English text, you should switch
to the appropriate major mode, such as Lisp mode or Text mode.

   Selecting a major mode changes the meanings of a few keys to become
more specifically adapted to the language being edited.  The ones which
are changed frequently are <TAB>, <DEL>, and <LFD>.  The prefix key
`C-c' normally contains mode-specific commands.  In addition, the
commands which handle comments use the mode to determine how comments
are to be delimited.  Many major modes redefine the syntactical
properties of characters appearing in the buffer.  *Note Syntax::.

   The major modes fall into three major groups.  Lisp mode (which has
several variants), C mode, Fortran mode and others are for specific
programming languages.  Text mode, Nroff mode, TeX mode and Outline
mode are for editing English text.  The remaining major modes are not
intended for use on users' files; they are used in buffers created for
specific purposes by Emacs, such as Dired mode for buffers made by Dired
(*note Dired::), and Mail mode for buffers made by `C-x m' (*note
Sending Mail::), and Shell mode for buffers used for communicating with
an inferior shell process (*note Interactive Shell::).

   Most programming language major modes specify that only blank lines
separate paragraphs.  This is to make the paragraph commands useful.
(*Note Paragraphs::.)  They also cause Auto Fill mode to use the
definition of <TAB> to indent the new lines it creates.  This is
because most lines in a program are usually indented.  (*Note
Indentation::.)

* Menu:

* Choosing Modes::     How major modes are specified or chosen.


File: emacs,  Node: Choosing Modes,  Prev: Major Modes,  Up: Major Modes

How Major Modes are Chosen
==========================

You can select a major mode explicitly for the current buffer, but most
of the time Emacs determines which mode to use based on the file name
or on special text in the file.

   Explicit selection of a new major mode is done with a `M-x' command.
From the name of a major mode, add `-mode' to get the name of a command
to select that mode.  Thus, you can enter Lisp mode by executing `M-x
lisp-mode'.

   When you visit a file, Emacs usually chooses the right major mode
based on the file's name.  For example, files whose names end in `.c'
are edited in C mode.  The correspondence between file names and major
modes is controlled by the variable `auto-mode-alist'.  Its value is a
list in which each element has this form,

     (REGEXP . MODE-FUNCTION)

or this form,

     (REGEXP MODE-FUNCTION FLAG)

For example, one element normally found in the list has the form
`("\\.c\\'" . c-mode)', and it is responsible for selecting C mode for
files whose names end in `.c'.  (Note that `\\' is needed in Lisp
syntax to include a `\' in the string, which is needed to suppress the
special meaning of `.' in regexps.)  If the element has the form
`(REGEXP MODE-FUNCTION FLAG)' and FLAG is non-nil, then after calling
FUNCTION, the suffix that matched REGEXP is deleted and the list is
searched again for another match.

   You can specify which major mode should be used for editing a certain
file by a special sort of text in the first nonblank line of the file.
The mode name should appear in this line both preceded and followed by
`-*-'.  Other text may appear on the line as well.  For example,

     ;-*-Lisp-*-

tells Emacs to use Lisp mode.  Such an explicit specification overrides
any defaulting based on the file name.  Note how the semicolon is used
to make Lisp treat this line as a comment.

   Another format of mode specification is

     -*-Mode: MODENAME;-*-

which allows you to specify local variables as well, like this:

     -*- mode: MODENAME; VAR: VALUE; ... -*-

*Note File Variables::, for more information about this.

   When a file's contents begin with `#!', it can serve as an
executable shell command, which works by running an interpreter named on
the file's first line.  The rest of the file is used as input to the
interpreter.

   When you visit such a file in Emacs, if the file's name does not
specify a major mode, Emacs uses the interpreter name on the first line
to choose a mode.  If the first line is the name of a recognized
interpreter program, such as `perl' or `tcl', Emacs uses a mode
appropriate for programs for that interpreter.  The variable
`interpreter-mode-alist' specifies the correspondence between
interpreter program names and major modes.

   When you visit a file that does not specify a major mode to use, or
when you create a new buffer with `C-x b', the variable
`default-major-mode' specifies which major mode to use.  Normally its
value is the symbol `fundamental-mode', which specifies Fundamental
mode.  If `default-major-mode' is `nil', the major mode is taken from
the previously selected buffer.

   If you change the major mode of a buffer, you can go back to the
major mode Emacs would choose automatically: use the command `M-x
normal-mode' to do this.  This is the same function that `find-file'
calls to choose the major mode.  It also processes the file's local
variables list if any.


File: emacs,  Node: Indentation,  Next: Text,  Prev: Major Modes,  Up: Top

Indentation
***********

This chapter describes the Emacs commands that add, remove, or adjust
indentation.

`<TAB>'
     Indent current line "appropriately" in a mode-dependent fashion.

`<LFD>'
     Perform <RET> followed by <TAB> (`newline-and-indent').

`M-^'
     Merge two lines (`delete-indentation').  This would cancel out the
     effect of <LFD>.

`C-M-o'
     Split line at point; text on the line after point becomes a new
     line indented to the same column that it now starts in
     (`split-line').

`M-m'
     Move (forward or back) to the first nonblank character on the
     current line (`back-to-indentation').

`C-M-\'
     Indent several lines to same column (`indent-region').

`C-x <TAB>'
     Shift block of lines rigidly right or left (`indent-rigidly').

`M-i'
     Indent from point to the next prespecified tab stop column
     (`tab-to-tab-stop').

`M-x indent-relative'
     Indent from point to under an indentation point in the previous
     line.

   Most programming languages have some indentation convention.  For
Lisp code, lines are indented according to their nesting in
parentheses.  The same general idea is used for C code, though many
details are different.

   Whatever the language, to indent a line, use the <TAB> command.  Each
major mode defines this command to perform the sort of indentation
appropriate for the particular language.  In Lisp mode, <TAB> aligns
the line according to its depth in parentheses.  No matter where in the
line you are when you type <TAB>, it aligns the line as a whole.  In C
mode, <TAB> implements a subtle and sophisticated indentation style that
knows about many aspects of C syntax.

   In Text mode, <TAB> runs the command `tab-to-tab-stop', which
indents to the next tab stop column.  You can set the tab stops with
`M-x edit-tab-stops'.

* Menu:

* Indentation Commands::  Various commands and techniques for indentation.
* Tab Stops::             You can set arbitrary "tab stops" and then
                            indent to the next tab stop when you want to.
* Just Spaces::           You can request indentation using just spaces.


File: emacs,  Node: Indentation Commands,  Next: Tab Stops,  Prev: Indentation,  Up: Indentation

Indentation Commands and Techniques
===================================

To move over the indentation on a line, do `M-m'
(`back-to-indentation').  This command, given anywhere on a line,
positions point at the first nonblank character on the line.

   To insert an indented line before the current line, do `C-a C-o
<TAB>'.  To make an indented line after the current line, use `C-e
<LFD>'.

   If you just want to insert a tab character in the buffer, you can
type `C-q <TAB>'.

   `C-M-o' (`split-line') moves the text from point to the end of the
line vertically down, so that the current line becomes two lines.
`C-M-o' first moves point forward over any spaces and tabs.  Then it
inserts after point a newline and enough indentation to reach the same
column point is on.  Point remains before the inserted newline; in this
regard, `C-M-o' resembles `C-o'.

   To join two lines cleanly, use the `M-^' (`delete-indentation')
command.  It deletes the indentation at the front of the current line,
and the line boundary as well, replacing them with a single space.  As
a special case (useful for Lisp code) the single space is omitted if
the characters to be joined are consecutive open parentheses or closing
parentheses, or if the junction follows another newline.  To delete
just the indentation of a line, go to the beginning of the line and use
`M-\' (`delete-horizontal-space'), which deletes all spaces and tabs
around the cursor.

   If you have a fill prefix, `M-^' deletes the fill prefix if it
appears after the newline that is deleted.  *Note Fill Prefix::.

   There are also commands for changing the indentation of several lines
at once.  `C-M-\' (`indent-region') applies to all the lines that begin
in the region; it indents each line in the "usual" way, as if you had
typed <TAB> at the beginning of the line.  A numeric argument specifies
the column to indent to, and each line is shifted left or right so that
its first nonblank character appears in that column.  `C-x <TAB>'
(`indent-rigidly') moves all of the lines in the region right by its
argument (left, for negative arguments).  The whole group of lines
moves rigidly sideways, which is how the command gets its name.

   `M-x indent-relative' indents at point based on the previous line
(actually, the last nonempty line).  It inserts whitespace at point,
moving point, until it is underneath an indentation point in the
previous line.  An indentation point is the end of a sequence of
whitespace or the end of the line.  If point is farther right than any
indentation point in the previous line, the whitespace before point is
deleted and the first indentation point then applicable is used.  If no
indentation point is applicable even then, `indent-relative' runs
`tab-to-tab-stop' (*note Tab Stops::).

   `indent-relative' is the definition of <TAB> in Indented Text mode.
*Note Text::.

   *Note Format Indentation::, for another way of specifying the
indentation for part of your text.


File: emacs,  Node: Tab Stops,  Next: Just Spaces,  Prev: Indentation Commands,  Up: Indentation

Tab Stops
=========

For typing in tables, you can use Text mode's definition of <TAB>,
`tab-to-tab-stop'.  This command inserts indentation before point,
enough to reach the next tab stop column.  If you are not in Text mode,
this command can be found on the key `M-i'.

   You can specify the tab stops used by `M-i'.  They are stored in a
variable called `tab-stop-list', as a list of column-numbers in
increasing order.

   The convenient way to set the tab stops is with `M-x edit-tab-stops',
which creates and selects a buffer containing a description of the tab
stop settings.  You can edit this buffer to specify different tab
stops, and then type `C-c C-c' to make those new tab stops take effect.
In the tab stop buffer, `C-c C-c' runs the function
`edit-tab-stops-note-changes' rather than its usual definition
`save-buffer'.  `edit-tab-stops' records which buffer was current when
you invoked it, and stores the tab stops back in that buffer; normally
all buffers share the same tab stops and changing them in one buffer
affects all, but if you happen to make `tab-stop-list' local in one
buffer then `edit-tab-stops' in that buffer will edit the local
settings.

   Here is what the text representing the tab stops looks like for
ordinary tab stops every eight columns.

             :       :       :       :       :       :
     0         1         2         3         4
     0123456789012345678901234567890123456789012345678
     To install changes, type C-c C-c

   The first line contains a colon at each tab stop.  The remaining
lines are present just to help you see where the colons are and know
what to do.

   Note that the tab stops that control `tab-to-tab-stop' have nothing
to do with displaying tab characters in the buffer.  *Note Display
Vars::, for more information on that.


File: emacs,  Node: Just Spaces,  Prev: Tab Stops,  Up: Indentation

Tabs vs. Spaces
===============

Emacs normally uses both tabs and spaces to indent lines.  If you
prefer, all indentation can be made from spaces only.  To request this,
set `indent-tabs-mode' to `nil'.  This is a per-buffer variable;
altering the variable affects only the current buffer, but there is a
default value which you can change as well.  *Note Locals::.

   There are also commands to convert tabs to spaces or vice versa,
always preserving the columns of all nonblank text.  `M-x tabify' scans
the region for sequences of spaces, and converts sequences of at least
three spaces to tabs if that can be done without changing indentation.
`M-x untabify' changes all tabs in the region to appropriate numbers of
spaces.


File: emacs,  Node: Text,  Next: Programs,  Prev: Indentation,  Up: Top

Commands for Human Languages
****************************

The term "text" has two widespread meanings in our area of the computer
field.  One is data that is a sequence of characters.  Any file that
you edit with Emacs is text, in this sense of the word.  The other
meaning is more restrictive: a sequence of characters in a human
language for humans to read (possibly after processing by a text
formatter), as opposed to a program or commands for a program.

   Human languages have syntactic/stylistic conventions that can be
supported or used to advantage by editor commands: conventions involving
words, sentences, paragraphs, and capital letters.  This chapter
describes Emacs commands for all of these things.  There are also
commands for "filling", which means rearranging the lines of a
paragraph to be approximately equal in length.  The commands for moving
over and killing words, sentences and paragraphs, while intended
primarily for editing text, are also often useful for editing programs.

   Emacs has several major modes for editing human language text.  If
the file contains text pure and simple, use Text mode, which customizes
Emacs in small ways for the syntactic conventions of text.  Outline mode
provides special commands for operating on text with an outline
structure.

   For text which contains embedded commands for text formatters, Emacs
has other major modes, each for a particular text formatter.  Thus, for
input to TeX, you would use TeX mode.  For input to nroff, use Nroff
mode.

   Instead of using a text formatter, you can edit formatted text in
WYSIWYG style ("what you see is what you get"), with Enriched mode.
Then the formatting appears on the screen in Emacs while you edit.

* Menu:

* Words::         Moving over and killing words.
* Sentences::     Moving over and killing sentences.
* Paragraphs::	  Moving over paragraphs.
* Pages::	  Moving over pages.
* Filling::       Filling or justifying text.
* Case::          Changing the case of text.
* Text Mode::     The major modes for editing text files.
* Outline Mode::  The major mode for editing outlines.
* TeX Mode::      The major modes for editing input to the formatter TeX.
* Nroff Mode::    The major mode for editing input to the formatter nroff.
* Formatted Text::Editing formatted text directly in WYSIWYG fashion.


File: emacs,  Node: Words,  Next: Sentences,  Up: Text

Words
=====

Emacs has commands for moving over or operating on words.  By
convention, the keys for them are all Meta characters.

`M-f'
     Move forward over a word (`forward-word').

`M-b'
     Move backward over a word (`backward-word').

`M-d'
     Kill up to the end of a word (`kill-word').

`M-<DEL>'
     Kill back to the beginning of a word (`backward-kill-word').

`M-@'
     Mark the end of the next word (`mark-word').

`M-t'
     Transpose two words or drag a word across other words
     (`transpose-words').

   Notice how these keys form a series that parallels the
character-based `C-f', `C-b', `C-d', `C-t' and <DEL>.  `M-@' is cognate
to `C-@', which is an alias for `C-<SPC>'.

   The commands `M-f' (`forward-word') and `M-b' (`backward-word') move
forward and backward over words.  These Meta characters are thus
analogous to the corresponding control characters, `C-f' and `C-b',
which move over single characters in the text.  The analogy extends to
numeric arguments, which serve as repeat counts.  `M-f' with a negative
argument moves backward, and `M-b' with a negative argument moves
forward.  Forward motion stops right after the last letter of the word,
while backward motion stops right before the first letter.

   `M-d' (`kill-word') kills the word after point.  To be precise, it
kills everything from point to the place `M-f' would move to.  Thus, if
point is in the middle of a word, `M-d' kills just the part after
point.  If some punctuation comes between point and the next word, it
is killed along with the word.  (If you wish to kill only the next word
but not the punctuation before it, simply do `M-f' to get the end, and
kill the word backwards with `M-<DEL>'.)  `M-d' takes arguments just
like `M-f'.

   `M-<DEL>' (`backward-kill-word') kills the word before point.  It
kills everything from point back to where `M-b' would move to.  If
point is after the space in `FOO, BAR', then `FOO, ' is killed.  (If
you wish to kill just `FOO', do `M-b M-d' instead of `M-<DEL>'.)

   `M-t' (`transpose-words') exchanges the word before or containing
point with the following word.  The delimiter characters between the
words do not move.  For example, `FOO, BAR' transposes into `BAR, FOO'
rather than `BAR FOO,'.  *Note Transpose::, for more on transposition
and on arguments to transposition commands.

   To operate on the next N words with an operation which applies
between point and mark, you can either set the mark at point and then
move over the words, or you can use the command `M-@' (`mark-word')
which does not move point, but sets the mark where `M-f' would move to.
`M-@' accepts a numeric argument that says how many words to scan for
the place to put the mark.  In Transient Mark mode, this command
activates the mark.

   The word commands' understanding of syntax is completely controlled
by the syntax table.  Any character can, for example, be declared to be
a word delimiter.  *Note Syntax::.


File: emacs,  Node: Sentences,  Next: Paragraphs,  Prev: Words,  Up: Text

Sentences
=========

The Emacs commands for manipulating sentences and paragraphs are mostly
on Meta keys, so as to be like the word-handling commands.

`M-a'
     Move back to the beginning of the sentence (`backward-sentence').

`M-e'
     Move forward to the end of the sentence (`forward-sentence').

`M-k'
     Kill forward to the end of the sentence (`kill-sentence').

`C-x <DEL>'
     Kill back to the beginning of the sentence
     (`backward-kill-sentence').

   The commands `M-a' and `M-e' (`backward-sentence' and
`forward-sentence') move to the beginning and end of the current
sentence, respectively.  They were chosen to resemble `C-a' and `C-e',
which move to the beginning and end of a line.  Unlike them, `M-a' and
`M-e' if repeated or given numeric arguments move over successive
sentences.

   Moving backward over a sentence places point just before the first
character of the sentence; moving forward places point right after the
punctuation that ends the sentence.  Neither one moves over the
whitespace at the sentence boundary.

   Just as `C-a' and `C-e' have a kill command, `C-k', to go with them,
so `M-a' and `M-e' have a corresponding kill command `M-k'
(`kill-sentence') which kills from point to the end of the sentence.
With minus one as an argument it kills back to the beginning of the
sentence.  Larger arguments serve as a repeat count.  There is also a
command, `C-x <DEL>' (`backward-kill-sentence'), for killing back to
the beginning of a sentence.  This command is useful when you change
your mind in the middle of composing text.

   The sentence commands assume that you follow the American typist's
convention of putting two spaces at the end of a sentence; they consider
a sentence to end wherever there is a `.', `?' or `!' followed by the
end of a line or two spaces, with any number of `)', `]', `'', or `"'
characters allowed in between.  A sentence also begins or ends wherever
a paragraph begins or ends.

   The variable `sentence-end' controls recognition of the end of a
sentence.  It is a regexp that matches the last few characters of a
sentence, together with the whitespace following the sentence.  Its
normal value is

     "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"

This example is explained in the section on regexps.  *Note Regexps::.

   If you want to use just one space between sentences, you should set
`sentence-end' to this value:

     "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"

You should also set the variable `sentence-end-double-space' to `nil'
so that the fill commands expect and leave just one space at the end of
a sentence.  Note that this makes it impossible to distinguish between
periods that end sentences and those that indicate abbreviations.


File: emacs,  Node: Paragraphs,  Next: Pages,  Prev: Sentences,  Up: Text

Paragraphs
==========

The Emacs commands for manipulating paragraphs are also Meta keys.

`M-{'
     Move back to previous paragraph beginning (`backward-paragraph').

`M-}'
     Move forward to next paragraph end (`forward-paragraph').

`M-h'
     Put point and mark around this or next paragraph
     (`mark-paragraph').

   `M-{' moves to the beginning of the current or previous paragraph,
while `M-}' moves to the end of the current or next paragraph.  Blank
lines and text formatter command lines separate paragraphs and are not
considered part of any paragraph.  Also, an indented line starts a new
paragraph.

   In major modes for programs (as opposed to Text mode), paragraphs
begin and end only at blank lines.  This makes the paragraph commands
continue to be useful even though there are no paragraphs per se.

   When there is a fill prefix, then paragraphs are delimited by all
lines which don't start with the fill prefix.  *Note Filling::.

   When you wish to operate on a paragraph, you can use the command
`M-h' (`mark-paragraph') to set the region around it.  Thus, for
example, `M-h C-w' kills the paragraph around or after point.  The
`M-h' command puts point at the beginning and mark at the end of the
paragraph point was in.  In Transient Mark mode, it activates the mark.
If point is between paragraphs (in a run of blank lines, or at a
boundary), the paragraph following point is surrounded by point and
mark.  If there are blank lines preceding the first line of the
paragraph, one of these blank lines is included in the region.

   The precise definition of a paragraph boundary is controlled by the
variables `paragraph-separate' and `paragraph-start'.  The value of
`paragraph-start' is a regexp that should match any line that either
starts or separates paragraphs.  The value of `paragraph-separate' is
another regexp that should match only lines that separate paragraphs
without being part of any paragraph.  Lines that start a new paragraph
and are contained in it must match only `paragraph-start', not
`paragraph-separate'.  For example, normally `paragraph-start' is `"[
\t\n\f]"' and `paragraph-separate' is `"[ \t\f]*$"'.

   Normally it is desirable for page boundaries to separate paragraphs.
The default values of these variables recognize the usual separator for
pages.


File: emacs,  Node: Pages,  Next: Filling,  Prev: Paragraphs,  Up: Text

Pages
=====

Files are often thought of as divided into "pages" by the "formfeed"
character (ASCII control-L, octal code 014).  When you print hardcopy
for a file, this character forces a page break; thus, each page of the
file goes on a separate page on paper.  Most Emacs commands treat the
page-separator character just like any other character: you can insert
it with `C-q C-l', and delete it with <DEL>.  Thus, you are free to
paginate your file or not.  However, since pages are often meaningful
divisions of the file, Emacs provides commands to move over them and
operate on them.

`C-x ['
     Move point to previous page boundary (`backward-page').

`C-x ]'
     Move point to next page boundary (`forward-page').

`C-x C-p'
     Put point and mark around this page (or another page)
     (`mark-page').

`C-x l'
     Count the lines in this page (`count-lines-page').

   The `C-x [' (`backward-page') command moves point to immediately
after the previous page delimiter.  If point is already right after a
page delimiter, it skips that one and stops at the previous one.  A
numeric argument serves as a repeat count.  The `C-x ]' (`forward-page')
command moves forward past the next page delimiter.

   The `C-x C-p' command (`mark-page') puts point at the beginning of
the current page and the mark at the end.  The page delimiter at the
end is included (the mark follows it).  The page delimiter at the front
is excluded (point follows it).  `C-x C-p C-w' is a handy way to kill a
page to move it elsewhere.  If you move to another page delimiter with
`C-x [' and `C-x ]', then yank the killed page, all the pages will be
properly delimited once again.  The reason `C-x C-p' includes only the
following page delimiter in the region is to ensure that.

   A numeric argument to `C-x C-p' is used to specify which page to go
to, relative to the current one.  Zero means the current page.  One
means the next page, and -1 means the previous one.

   The `C-x l' command (`count-lines-page') is good for deciding where
to break a page in two.  It prints in the echo area the total number of
lines in the current page, and then divides it up into those preceding
the current line and those following, as in

     Page has 96 (72+25) lines

Notice that the sum is off by one; this is correct if point is not at
the beginning of a line.

   The variable `page-delimiter' controls where pages begin.  Its value
is a regexp that matches the beginning of a line that separates pages.
The normal value of this variable is `"^\f"', which matches a formfeed
character at the beginning of a line.


File: emacs,  Node: Filling,  Next: Case,  Prev: Pages,  Up: Text

Filling Text
============

"Filling" text means breaking it up into lines that fit a specified
width.  Emacs does filling in two ways.  In Auto Fill mode, inserting
text with self-inserting characters also automatically fills it.  There
are also explicit fill commands that you can use when editing text
leaves it unfilled.  When you edit formatted text, you can specify a
style of filling for each portion of the text (*note Formatted Text::).

* Menu:

* Auto Fill::	  Auto Fill mode breaks long lines automatically.
* Fill Commands:: Commands to refill paragraphs and center lines.
* Fill Prefix::	  Filling when every line is indented or in a comment, etc.


File: emacs,  Node: Auto Fill,  Next: Fill Commands,  Up: Filling

Auto Fill Mode
--------------

"Auto Fill" mode is a minor mode in which lines are broken
automatically when they become too wide.  Breaking happens only when
you type a <SPC> or <RET>.

`M-x auto-fill-mode'
     Enable or disable Auto Fill mode.

`<SPC>'
`<RET>'
     In Auto Fill mode, break lines when appropriate.

   `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
if it was on.  With a positive numeric argument it always turns Auto
Fill mode on, and with a negative argument always turns it off.  You can
see when Auto Fill mode is in effect by the presence of the word `Fill'
in the mode line, inside the parentheses.  Auto Fill mode is a minor
mode which is enabled or disabled for each buffer individually.  *Note
Minor Modes::.

   In Auto Fill mode, lines are broken automatically at spaces when
they get longer than the desired width.  Line breaking and
rearrangement takes place only when you type <SPC> or <RET>.  If you
wish to insert a space or newline without permitting line-breaking,
type `C-q <SPC>' or `C-q <LFD>' (recall that a newline is really a
linefeed).  Also, `C-o' inserts a newline without line breaking.

   Auto Fill mode works well with Lisp mode, because when it makes a new
line in Lisp mode it indents that line with <TAB>.  If a line ending in
a comment gets too long, the text of the comment is split into two
comment lines.  Optionally new comment delimiters are inserted at the
end of the first line and the beginning of the second so that each line
is a separate comment; the variable `comment-multi-line' controls the
choice (*note Comments::).

   Adaptive filling (see the following section) works for Auto Filling
as well as for explicit fill commands.  It takes a fill prefix
automatically from the second or first line of a paragraph.

   Auto Fill mode does not refill entire paragraphs; it can break lines
but cannot merge lines.  So editing in the middle of a paragraph can
result in a paragraph that is not correctly filled.  The easiest way to
make the paragraph properly filled again is usually with the explicit
fill commands.  *Note Fill Commands::.

   Many users like Auto Fill mode and want to use it in all text files.
The section on init files says how to arrange this permanently for
yourself.  *Note Init File::.


File: emacs,  Node: Fill Commands,  Next: Fill Prefix,  Prev: Auto Fill,  Up: Filling

Explicit Fill Commands
----------------------

`M-q'
     Fill current paragraph (`fill-paragraph').

`C-x f'
     Set the fill column (`set-fill-column').

`M-x fill-region'
     Fill each paragraph in the region (`fill-region').

`M-x fill-region-as-paragraph.'
     Fill the region, considering it as one paragraph.

`M-s'
     Center a line.

   To refill a paragraph, use the command `M-q' (`fill-paragraph').
This operates on the paragraph that point is inside, or the one after
point if point is between paragraphs.  Refilling works by removing all
the line-breaks, then inserting new ones where necessary.

   To refill many paragraphs, use `M-x fill-region', which divides the
region into paragraphs and fills each of them.

   `M-q' and `fill-region' use the same criteria as `M-h' for finding
paragraph boundaries (*note Paragraphs::).  For more control, you can
use `M-x fill-region-as-paragraph', which refills everything between
point and mark.  This command deletes any blank lines within the
region, so separate blocks of text end up combined into one block.

   A numeric argument to `M-q' causes it to "justify" the text as well
as filling it.  This means that extra spaces are inserted to make the
right margin line up exactly at the fill column.  To remove the extra
spaces, use `M-q' with no argument.  (Likewise for `fill-region'.)
Another way to control justification, and choose other styles of
filling, is with the `justification' text property; see *Note Format
Justification::.

   The fill commands can deduce the proper fill prefix for a paragraph
automatically in certain cases: either whitespace or certain punctuation
characters at the beginning of a line are treated as a fill prefix.
They take the fill prefix from the paragraph's second line, unless the
paragraph has just one line.  You can turn off this feature by setting
`adaptive-fill-mode' to `nil'.

   Some major modes, including Text mode, treat whitespace at the
beginning of a line as a signal that this line starts a new paragraph.
It would be a mistake to copy text which implies the start of a
paragraph onto each line of the paragraph when filling it.  Therefore,
adaptive filling does not accept a fill prefix from a line which is a
paragraph-starter.  In particular, adaptive filling in Text mode does
not accept a fill prefix consisting of just whitespace.

   However, other modes including Indented Text mode (*note Text Mode::)
do not consider whitespace as a signal to start a new paragraph.  In
these modes, adaptive filling does accept a fill prefix consisting of
just whitespace, if the first or second line of a paragraph begins with
whitespace.

   The variable `adaptive-fill-regexp' determines what kinds of line
beginnings can serve as a fill prefix: any characters at the start of
the line which match this regular expression are used.

   You can specify more complex ways of choosing a fill prefix
automatically by setting the variable `adaptive-fill-function' to a
function.  This function is called with point after the left margin of a
line, and it should return the appropriate fill prefix based on that
line.  If it returns `nil', that means it sees no fill prefix in that
line.

   The command `M-s' (`center-line') centers the current line within
the current fill column.  With an argument N, it centers N lines
individually and moves past them.

   The maximum line width for filling is in the variable `fill-column'.
Altering the value of `fill-column' makes it local to the current
buffer; until that time, the default value is in effect.  The default
is initially 70.  *Note Locals::.  The easiest way to set `fill-column'
is to use the command `C-x f' (`set-fill-column').  With a numeric
argument, it uses that as the new fill column.  With just `C-u' as
argument, it sets `fill-column' to the current horizontal position of
point.

   Emacs commands normally consider a period followed by two spaces or
by a newline as the end of a sentence; a period followed by just one
space indicates an abbreviation and not the end of a sentence.  To
preserve the distinction between these two ways of using a period, the
fill commands do not break a line after a period followed by just one
space.

   If the variable `sentence-end-double-space' is `nil', the fill
commands expect and leave just one space at the end of a sentence.
Ordinarily this variable is `t', so the fill commands insist on two
spaces for the end of a sentence, as explained above.  *Note
Sentences::.

   If the variable `colon-double-space' is non-`nil', the fill commands
put two spaces after a colon.


File: emacs,  Node: Fill Prefix,  Prev: Fill Commands,  Up: Filling

The Fill Prefix
---------------

To fill a paragraph in which each line starts with a special marker
(which might be a few spaces, giving an indented paragraph), use the
"fill prefix" feature.  The fill prefix is a string which Emacs expects
every line to start with, and which is not included in filling.

`C-x .'
     Set the fill prefix (`set-fill-prefix').

`M-q'
     Fill a paragraph using current fill prefix (`fill-paragraph').

`M-x fill-individual-paragraphs'
     Fill the region, considering each change of indentation as
     starting a new paragraph.

`M-x fill-nonuniform-paragraphs'
     Fill the region, considering only paragraph-separator lines as
     starting a new paragraph.

   To specify a fill prefix, move to a line that starts with the desired
prefix, put point at the end of the prefix, and give the command
`C-x .' (`set-fill-prefix').  That's a period after the `C-x'.  To turn
off the fill prefix, specify an empty prefix: type `C-x .' with point
at the beginning of a line.

   When a fill prefix is in effect, the fill commands remove the fill
prefix from each line before filling and insert it on each line after
filling.  Auto Fill mode also inserts the fill prefix automatically when
it makes a new line.  The `C-o' command inserts the fill prefix on new
lines it creates, when you use it at the beginning of a line (*note
Blank Lines::).  Conversely, the command `M-^' deletes the prefix (if
it occurs) after the newline that it deletes (*note Indentation::).

   For example, if `fill-column' is 40 and you set the fill prefix to
`;; ', then `M-q' in the following text

     ;; This is an
     ;; example of a paragraph
     ;; inside a Lisp-style comment.

produces this:

     ;; This is an example of a paragraph
     ;; inside a Lisp-style comment.

   Lines that do not start with the fill prefix are considered to start
paragraphs, both in `M-q' and the paragraph commands; this gives good
results for paragraphs with hanging indentation (every line indented
except the first one).  Lines which are blank or indented once the
prefix is removed also separate or start paragraphs; this is what you
want if you are writing multi-paragraph comments with a comment
delimiter on each line.

   You can use `M-x fill-individual-paragraphs' to set the fill prefix
for each paragraph automatically.  This command divides the region into
paragraphs, treating every change in the amount of indentation as the
start of a new paragraph, and fills each of these paragraphs.  Thus,
all the lines in one "paragraph" have the same amount of indentation.
That indentation serves as the fill prefix for that paragraph.

   `M-x fill-nonuniform-paragraphs' is a similar command that divides
the region into paragraphs in a different way.  It considers only
paragraph-separating lines (as defined by `paragraph-separate') as
starting a new paragraph.  Since this means that the lines of one
paragraph may have different amounts of indentation, the fill prefix
used is the smallest amount of indentation of any of the lines of the
paragraph.  This gives good results with styles that indent a
paragraph's first line more or less that the rest of the paragraph.

   The fill prefix is stored in the variable `fill-prefix'.  Its value
is a string, or `nil' when there is no fill prefix.  This is a
per-buffer variable; altering the variable affects only the current
buffer, but there is a default value which you can change as well.
*Note Locals::.

   The `indentation' text property provides another way to control the
amount of indentation paragraphs receive.  *Note Format Indentation::.


File: emacs,  Node: Case,  Next: Text Mode,  Prev: Filling,  Up: Text

Case Conversion Commands
========================

Emacs has commands for converting either a single word or any arbitrary
range of text to upper case or to lower case.

`M-l'
     Convert following word to lower case (`downcase-word').

`M-u'
     Convert following word to upper case (`upcase-word').

`M-c'
     Capitalize the following word (`capitalize-word').

`C-x C-l'
     Convert region to lower case (`downcase-region').

`C-x C-u'
     Convert region to upper case (`upcase-region').

   The word conversion commands are the most useful.  `M-l'
(`downcase-word') converts the word after point to lower case, moving
past it.  Thus, repeating `M-l' converts successive words.  `M-u'
(`upcase-word') converts to all capitals instead, while `M-c'
(`capitalize-word') puts the first letter of the word into upper case
and the rest into lower case.  All these commands convert several words
at once if given an argument.  They are especially convenient for
converting a large amount of text from all upper case to mixed case,
because you can move through the text using `M-l', `M-u' or `M-c' on
each word as appropriate, occasionally using `M-f' instead to skip a
word.

   When given a negative argument, the word case conversion commands
apply to the appropriate number of words before point, but do not move
point.  This is convenient when you have just typed a word in the wrong
case: you can give the case conversion command and continue typing.

   If a word case conversion command is given in the middle of a word,
it applies only to the part of the word which follows point.  This is
just like what `M-d' (`kill-word') does.  With a negative argument,
case conversion applies only to the part of the word before point.

   The other case conversion commands are `C-x C-u' (`upcase-region')
and `C-x C-l' (`downcase-region'), which convert everything between
point and mark to the specified case.  Point and mark do not move.

   The region case conversion commands `upcase-region' and
`downcase-region' are normally disabled.  This means that they ask for
confirmation if you try to use them.  When you confirm, you may enable
the command, which means it will not ask for confirmation again.  *Note
Disabling::.


File: emacs,  Node: Text Mode,  Next: Outline Mode,  Prev: Case,  Up: Text

Text Mode
=========

When you edit files of text in a human language, it's more convenient
to use Text mode rather than Fundamental mode.  Invoke `M-x text-mode'
to enter Text mode.  In Text mode, <TAB> runs the function
`tab-to-tab-stop', which allows you to use arbitrary tab stops set with
`M-x edit-tab-stops' (*note Tab Stops::).  Features concerned with
comments in programs are turned off in Text mode except when explicitly
invoked.  The syntax table is changed so that periods are not
considered part of a word, while apostrophes, backspaces and underlines
are part of words.

   A similar variant mode is Indented Text mode, intended for editing
text in which most lines are indented.  This mode defines <TAB> to run
`indent-relative' (*note Indentation::), and makes Auto Fill indent the
lines it creates.  The result is that normally a line made by Auto
Filling, or by <LFD>, is indented just like the previous line.  In
Indented Text mode, only blank lines separate paragraphs--indented
lines continue the current paragraph.  Use `M-x indented-text-mode' to
select this mode.

   Text mode, and all the modes based on it, define `M-<TAB>' as the
command `ispell-complete-word', which performs completion of the
partial word in the buffer before point, using the spelling dictionary
as the space of possible words.  *Note Spelling::.

   Entering Text mode or Indented Text mode runs the hook
`text-mode-hook'.  Other major modes related to Text mode also run this
hook, followed by hooks of their own; this includes Nroff mode, TeX
mode, Outline mode and Mail mode.  Hook functions on `text-mode-hook'
can look at the value of `major-mode' to see which of these modes is
actually being entered.  *Note Hooks::.

   Emacs provides two other modes for editing text that is to be passed
through a text formatter to produce fancy formatted printed output.
*Note Nroff Mode::, for editing input to the formatter nroff.  *Note
TeX Mode::, for editing input to the formatter TeX.

   Another mode is used for editing outlines.  It allows you to view the
text at various levels of detail.  You can view either the outline
headings alone or both headings and text; you can also hide some of the
headings at lower levels from view to make the high level structure more
visible.  *Note Outline Mode::.


File: emacs,  Node: Outline Mode,  Next: TeX Mode,  Prev: Text Mode,  Up: Text

Outline Mode
============

Outline mode is a major mode much like Text mode but intended for
editing outlines.  It allows you to make parts of the text temporarily
invisible so that you can see the outline structure.  Type `M-x
outline-mode' to switch to Outline mode as the major mode of the current
buffer.

   When Outline mode makes a line invisible, the line does not appear on
the screen.  The screen appears exactly as if the invisible line were
deleted, except that an ellipsis (three periods in a row) appears at the
end of the previous visible line (only one ellipsis no matter how many
invisible lines follow).

   All editing commands treat the text of the invisible line as part of
the previous visible line.  For example, `C-n' moves onto the next
visible line.  Killing an entire visible line, including its
terminating newline, really kills all the following invisible lines
along with it; yanking it all back yanks the invisible lines and they
remain invisible.

   Outline minor mode provides the same commands as the major mode,
Outline mode, but you can use it in conjunction with other major modes.
Type `M-x outline-minor-mode' to enable the Outline minor mode in the
current buffer.  You can also specify this in the text of a file, with
a file local variable of the form `mode: outline-minor' (*note File
Variables::).

   The major mode, Outline mode, provides special key bindings on the
`C-c' prefix.  Outline minor mode provides similar bindings with `C-c
@' as the prefix; this is to reduce the conflicts with the major mode's
special commands.  (The variable `outline-minor-mode-prefix' controls
the prefix used.)

   Entering Outline mode runs the hook `text-mode-hook' followed by the
hook `outline-mode-hook' (*note Hooks::).

* Menu:

* Format: Outline Format.	   What the text of an outline looks like.
* Motion: Outline Motion.	   Special commands for moving through
                                     outlines.
* Visibility: Outline Visibility.  Commands to control what is visible.
* Views: Outline Views.            Outlines and multiple views.


File: emacs,  Node: Outline Format,  Next: Outline Motion,  Up: Outline Mode

Format of Outlines
------------------

Outline mode assumes that the lines in the buffer are of two types:
"heading lines" and "body lines".  A heading line represents a topic in
the outline.  Heading lines start with one or more stars; the number of
stars determines the depth of the heading in the outline structure.
Thus, a heading line with one star is a major topic; all the heading
lines with two stars between it and the next one-star heading are its
subtopics; and so on.  Any line that is not a heading line is a body
line.  Body lines belong with the preceding heading line.  Here is an
example:

     * Food
     
     This is the body,
     which says something about the topic of food.
     
     ** Delicious Food
     
     This is the body of the second-level header.
     
     ** Distasteful Food
     
     This could have
     a body too, with
     several lines.
     
     *** Dormitory Food
     
     * Shelter
     
     Another first-level topic with its header line.

   A heading line together with all following body lines is called
collectively an "entry".  A heading line together with all following
deeper heading lines and their body lines is called a "subtree".

   You can customize the criterion for distinguishing heading lines by
setting the variable `outline-regexp'.  Any line whose beginning has a
match for this regexp is considered a heading line.  Matches that start
within a line (not at the left margin) do not count.  The length of the
matching text determines the level of the heading; longer matches make
a more deeply nested level.  Thus, for example, if a text formatter has
commands `@chapter', `@section' and `@subsection' to divide the
document into chapters and sections, you could make those lines count
as heading lines by setting `outline-regexp' to
`"@chap\\|@\\(sub\\)*section"'.  Note the trick: the two words
`chapter' and `section' are equally long, but by defining the regexp to
match only `chap' we ensure that the length of the text matched on a
chapter heading is shorter, so that Outline mode will know that
sections are contained in chapters.  This works as long as no other
command starts with `@chap'.

   It is possible to change the rule for calculating the level of a
heading line by setting the variable `outline-level'.  The value of
`outline-level' should be a function that takes no arguments and
returns the level of the current heading.  Some major modes such as C,
Nroff, and Emacs Lisp mode set this variable in order to work with
Outline minor mode.

   Outline mode makes a line invisible by changing the newline before it
into an ASCII control-M (code 015).  Most editing commands that work on
lines treat an invisible line as part of the previous line because,
strictly speaking, it _is_ part of that line, since there is no longer a
newline in between.  When you save the file in Outline mode, control-M
characters are saved as newlines, so the invisible lines become ordinary
lines in the file.  But saving does not change the visibility status of
a line inside Emacs.


File: emacs,  Node: Outline Motion,  Next: Outline Visibility,  Prev: Outline Format,  Up: Outline Mode

Outline Motion Commands
-----------------------

Outline mode provides special motion commands that move backward and
forward to heading lines.

`C-c C-n'
     Move point to the next visible heading line
     (`outline-next-visible-heading').

`C-c C-p'
     Move point to the previous visible heading line
     (`outline-previous-visible-heading').

`C-c C-f'
     Move point to the next visible heading line at the same level as
     the one point is on (`outline-forward-same-level').

`C-c C-b'
     Move point to the previous visible heading line at the same level
     (`outline-backward-same-level').

`C-c C-u'
     Move point up to a lower-level (more inclusive) visible heading
     line (`outline-up-heading').

   `C-c C-n' (`outline-next-visible-heading') moves down to the next
heading line.  `C-c C-p' (`outline-previous-visible-heading') moves
similarly backward.  Both accept numeric arguments as repeat counts.
The names emphasize that invisible headings are skipped, but this is
not really a special feature.  All editing commands that look for lines
ignore the invisible lines automatically.

   More powerful motion commands understand the level structure of
headings.  `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
(`outline-backward-same-level') move from one heading line to another
visible heading at the same depth in the outline.  `C-c C-u'
(`outline-up-heading') moves backward to another heading that is less
deeply nested.


File: emacs,  Node: Outline Visibility,  Next: Outline Views,  Prev: Outline Motion,  Up: Outline Mode

Outline Visibility Commands
---------------------------

The other special commands of outline mode are used to make lines
visible or invisible.  Their names all start with `hide' or `show'.
Most of them fall into pairs of opposites.  They are not undoable;
instead, you can undo right past them.  Making lines visible or
invisible is simply not recorded by the undo mechanism.

`C-c C-t'
     Make all body lines in the buffer invisible (`hide-body').

`C-c C-a'
     Make all lines in the buffer visible (`show-all').

`C-c C-d'
     Make everything under this heading invisible, not including this
     heading itself
     (`hide-subtree').

`C-c C-s'
     Make everything under this heading visible, including body,
     subheadings, and their bodies (`show-subtree').

`C-c C-l'
     Make the body of this heading line, and of all its subheadings,
     invisible (`hide-leaves').

`C-c C-k'
     Make all subheadings of this heading line, at all levels, visible
     (`show-branches').

`C-c C-i'
     Make immediate subheadings (one level down) of this heading line
     visible (`show-children').

`C-c C-c'
     Make this heading line's body invisible (`hide-entry').

`C-c C-e'
     Make this heading line's body visible (`show-entry').

`C-c C-q'
     Hide everything except the top N levels of heading lines
     (`hide-sublevels').

`C-c C-o'
     Hide everything except for the heading or body that point is in,
     plus the headings leading up from there to the top level of the
     outline (`hide-other').

   Two commands that are exact opposites are `C-c C-c' (`hide-entry')
and `C-c C-e' (`show-entry').  They are used with point on a heading
line, and apply only to the body lines of that heading.  Subheadings
and their bodies are not affected.

   Two more powerful opposites are `C-c C-d' (`hide-subtree') and `C-c
C-s' (`show-subtree').  Both expect to be used when point is on a
heading line, and both apply to all the lines of that heading's
"subtree": its body, all its subheadings, both direct and indirect, and
all of their bodies.  In other words, the subtree contains everything
following this heading line, up to and not including the next heading of
the same or higher rank.

   Intermediate between a visible subtree and an invisible one is having
all the subheadings visible but none of the body.  There are two
commands for doing this, depending on whether you want to hide the
bodies or make the subheadings visible.  They are `C-c C-l'
(`hide-leaves') and `C-c C-k' (`show-branches').

   A little weaker than `show-branches' is `C-c C-i' (`show-children').
It makes just the direct subheadings visible--those one level down.
Deeper subheadings remain invisible, if they were invisible.

   Two commands have a blanket effect on the whole file.  `C-c C-t'
(`hide-body') makes all body lines invisible, so that you see just the
outline structure.  `C-c C-a' (`show-all') makes all lines visible.
These commands can be thought of as a pair of opposites even though
`C-c C-a' applies to more than just body lines.

   The command `C-c C-q' (`hide-sublevels') hides all but the top level
headings.  With a numeric argument N, it hides everything except the
top N levels of heading lines.

   The command `C-c C-o' (`hide-other') hides everything except the
heading or body text that point is in, plus its parents (the headers
leading up from there to top level in the outline).

   You can turn off the use of ellipses at the ends of visible lines by
setting `selective-display-ellipses' to `nil'.  Then there is no
visible indication of the presence of invisible lines.


File: emacs,  Node: Outline Views,  Prev: Outline Visibility,  Up: Outline Mode

Viewing One Outline in Multiple Views
-------------------------------------

You can display two views of a single outline at the same time, in
different windows, by means of an alternative implementation of Outline
mode called `noutline'.

   To do this, first load the library `noutline' with `M-x load-library
<RET> noutline <RET>'.  This loads the alternative implementation of
Outline mode.  It provides the same command names and key bindings as
regular Outline mode, but it implements them differently.

   Then, to display a second view of an outline buffer, you must create
an indirect buffer using `M-x make-indirect-buffer'.  The first
argument of this command is the existing outline buffer name, and its
second argument is the name to use for the new indirect buffer.  *Note
Indirect Buffers::.

   Once the indirect buffer exists, you can display it in a window in
the normal fashion, with `C-x 4 b' or other Emacs commands.  The Outline
mode commands to show and hide parts of the text operate on each buffer
independently; as a result, each buffer can have its own view.  If you
want more than two views on the same outline, create additional indirect
buffers.

   In a future Emacs version, the alternative `noutline' implementation
will probably become the principal implementation.


File: emacs,  Node: TeX Mode,  Next: Nroff Mode,  Prev: Outline Mode,  Up: Text

TeX Mode
========

TeX is a powerful text formatter written by Donald Knuth; it is also
free, like GNU Emacs.  LaTeX is a simplified input format for TeX,
implemented by TeX macros; it comes with TeX.  SliTeX is a special form
of LaTeX.

   Emacs has a special TeX mode for editing TeX input files.  It
provides facilities for checking the balance of delimiters and for
invoking TeX on all or part of the file.

   TeX mode has three variants, Plain TeX mode, LaTeX mode, and SliTeX
mode (these three distinct major modes differ only slightly).  They are
designed for editing the three different formats.  The command `M-x
tex-mode' looks at the contents of the buffer to determine whether the
contents appear to be either LaTeX input or SliTeX input; if so, it
selects the appropriate mode.  If the file contents do not appear to be
LaTeX or SliTeX, it selects Plain TeX mode.  If the contents are
insufficient to determine this, the variable `tex-default-mode'
controls which mode is used.

   When `M-x tex-mode' does not guess right, you can use the commands
`M-x plain-tex-mode', `M-x latex-mode', and `M-x slitex-mode' to select
explicitly the particular variants of TeX mode.

* Menu:

* Editing: TeX Editing.   Special commands for editing in TeX mode.
* LaTeX: LaTeX Editing.   Additional commands for LaTeX input files.
* Printing: TeX Print.    Commands for printing part of a file with TeX.
* Getting: TeX Distrib.   Getting the latest Unix TeX distribution.


File: emacs,  Node: TeX Editing,  Next: LaTeX Editing,  Up: TeX Mode

TeX Editing Commands
--------------------

Here are the special commands provided in TeX mode for editing the text
of the file.

`"'
     Insert, according to context, either ```' or `"' or `'''
     (`tex-insert-quote').

`<LFD>'
     Insert a paragraph break (two newlines) and check the previous
     paragraph for unbalanced braces or dollar signs
     (`tex-terminate-paragraph').

`M-x validate-tex-region'
     Check each paragraph in the region for unbalanced braces or dollar
     signs.

`C-c {'
     Insert `{}' and position point between them (`tex-insert-braces').

`C-c }'
     Move forward past the next unmatched close brace (`up-list').

   In TeX, the character `"' is not normally used; we use ```' to start
a quotation and `''' to end one.  To make editing easier under this
formatting convention, TeX mode overrides the normal meaning of the key
`"' with a command that inserts a pair of single-quotes or backquotes
(`tex-insert-quote').  To be precise, this command inserts ```' after
whitespace or an open brace, `"' after a backslash, and `''' after any
other character.

   If you need the character `"' itself in unusual contexts, use `C-q'
to insert it.  Also, `"' with a numeric argument always inserts that
number of `"' characters.

   In TeX mode, `$' has a special syntax code which attempts to
understand the way TeX math mode delimiters match.  When you insert a
`$' that is meant to exit math mode, the position of the matching `$'
that entered math mode is displayed for a second.  This is the same
feature that displays the open brace that matches a close brace that is
inserted.  However, there is no way to tell whether a `$' enters math
mode or leaves it; so when you insert a `$' that enters math mode, the
previous `$' position is shown as if it were a match, even though they
are actually unrelated.

   TeX uses braces as delimiters that must match.  Some users prefer to
keep braces balanced at all times, rather than inserting them singly.
Use `C-c {' (`tex-insert-braces') to insert a pair of braces.  It
leaves point between the two braces so you can insert the text that
belongs inside.  Afterward, use the command `C-c }' (`up-list') to move
forward past the close brace.

   There are two commands for checking the matching of braces.  <LFD>
(`tex-terminate-paragraph') checks the paragraph before point, and
inserts two newlines to start a new paragraph.  It prints a message in
the echo area if any mismatch is found.  `M-x validate-tex-region'
checks a region, paragraph by paragraph.  When it finds a paragraph that
contains a mismatch, it displays point at the beginning of the paragraph
for a few seconds and sets the mark at that spot.  Scanning continues
until the whole buffer has been checked or until you type another key.
Afterward, you can use the mark ring to find the last several paragraphs
that had mismatches (*note Mark Ring::).

   Note that Emacs commands count square brackets and parentheses in
TeX mode, not just braces.  This is not strictly correct for the
purpose of checking TeX syntax.  However, parentheses and square
brackets are likely to be used in text as matching delimiters and it is
useful for the various motion commands and automatic match display to
work with them.


File: emacs,  Node: LaTeX Editing,  Next: TeX Print,  Prev: TeX Editing,  Up: TeX Mode

LaTeX Editing Commands
----------------------

LaTeX mode, and its variant, SliTeX mode, provide a few extra features
not applicable to plain TeX.

`C-c C-o'
     Insert `\begin' and `\end' for LaTeX block and position point on a
     line between them. (`tex-latex-block').

`C-c C-e'
     Close the last unended block for LaTeX (`tex-close-latex-block').

   In LaTeX input, `\begin' and `\end' commands are used to group
blocks of text.  To insert a `\begin' and a matching `\end' (on a new
line following the `\begin'), use `C-c C-o' (`tex-latex-block').  A
blank line is inserted between the two, and point is left there.  You
can use completion when you enter the block type; to specify additional
block type names beyond the standard list, set the variable
`latex-block-names'.  For example, here's how to add `theorem',
`corollary', and `proof':

     (setq latex-block-names '("theorem" "corollary" "proof"))

   In LaTeX input, `\begin' and `\end' commands must balance.  You can
use `C-c C-e' (`tex-close-latex-block') to insert automatically a
matching `\end' to match the last unmatched `\begin'.  It indents the
`\end' to match the corresponding `\begin'.  It inserts a newline after
`\end' if point is at the beginning of a line.


File: emacs,  Node: TeX Print,  Next: TeX Distrib,  Prev: LaTeX Editing,  Up: TeX Mode

TeX Printing Commands
---------------------

You can invoke TeX as an inferior of Emacs on either the entire
contents of the buffer or just a region at a time.  Running TeX in this
way on just one chapter is a good way to see what your changes look
like without taking the time to format the entire file.

`C-c C-r'
     Invoke TeX on the current region, together with the buffer's header
     (`tex-region').

`C-c C-b'
     Invoke TeX on the entire current buffer (`tex-buffer').

`C-c TAB'
     Invoke BibTeX on the current file (`tex-bibtex-file').

`C-c C-f'
     Invoke TeX on the current file (`tex-file').

`C-c C-l'
     Recenter the window showing output from the inferior TeX so that
     the last line can be seen (`tex-recenter-output-buffer').

`C-c C-k'
     Kill the TeX subprocess (`tex-kill-job').

`C-c C-p'
     Print the output from the last `C-c C-r', `C-c C-b', or `C-c C-f'
     command (`tex-print').

`C-c C-v'
     Preview the output from the last `C-c C-r', `C-c C-b', or `C-c
     C-f' command (`tex-view').

`C-c C-q'
     Show the printer queue (`tex-show-print-queue').

   You can pass the current buffer through an inferior TeX by means of
`C-c C-b' (`tex-buffer').  The formatted output appears in a temporary
file; to print it, type `C-c C-p' (`tex-print').  Afterward, you can
use `C-c C-q' (`tex-show-print-queue') to view the progress of your
output towards being printed.  If your terminal has the ability to
display TeX output files, you can preview the output on the terminal
with `C-c C-v' (`tex-view').

   You can specify the directory to use for running TeX by setting the
variable `tex-directory'.  `"."' is the default value.  If your
environment variable `TEXINPUTS' contains relative directory names, or
if your files contains `\input' commands with relative file names, then
`tex-directory' _must_ be `"."' or you will get the wrong results.
Otherwise, it is safe to specify some other directory, such as `"/tmp"'.

   If you want to specify which shell commands are used in the inferior
TeX, you can do so by setting the values of the variables
`tex-run-command', `latex-run-command', `slitex-run-command',
`tex-dvi-print-command', `tex-dvi-view-command', and
`tex-show-queue-command'.  You _must_ set the value of
`tex-dvi-view-command' for your particular terminal; this variable has
no default value.  The other variables have default values that may (or
may not) be appropriate for your system.

   Normally, the file name given to these commands comes at the end of
the command string; for example, `latex FILENAME'.  In some cases,
however, the file name needs to be embedded in the command; an example
is when you need to provide the file name as an argument to one command
whose output is piped to another.  You can specify where to put the
file name with `*' in the command string.  For example,

     (setq tex-dvi-print-command "dvips -f * | lpr")

   The terminal output from TeX, including any error messages, appears
in a buffer called `*tex-shell*'.  If TeX gets an error, you can switch
to this buffer and feed it input (this works as in Shell mode; *note
Interactive Shell::).  Without switching to this buffer you can scroll
it so that its last line is visible by typing `C-c C-l'.

   Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
that its output is no longer useful.  Using `C-c C-b' or `C-c C-r' also
kills any TeX process still running.

   You can also pass an arbitrary region through an inferior TeX by
typing `C-c C-r' (`tex-region').  This is tricky, however, because most
files of TeX input contain commands at the beginning to set parameters
and define macros, without which no later part of the file will format
correctly.  To solve this problem, `C-c C-r' allows you to designate a
part of the file as containing essential commands; it is included before
the specified region as part of the input to TeX.  The designated part
of the file is called the "header".

   To indicate the bounds of the header in Plain TeX mode, you insert
two special strings in the file.  Insert `%**start of header' before the
header, and `%**end of header' after it.  Each string must appear
entirely on one line, but there may be other text on the line before or
after.  The lines containing the two strings are included in the header.
If `%**start of header' does not appear within the first 100 lines of
the buffer, `C-c C-r' assumes that there is no header.

   In LaTeX mode, the header begins with `\documentstyle' and ends with
`\begin{document}'.  These are commands that LaTeX requires you to use
in any case, so nothing special needs to be done to identify the header.

   The commands (`tex-buffer') and (`tex-region') do all of their work
in a temporary directory, and do not have available any of the auxiliary
files needed by TeX for cross-references; these commands are generally
not suitable for running the final copy in which all of the
cross-references need to be correct.  When you want the auxiliary
files, use `C-c C-f' (`tex-file') which runs TeX on the current
buffer's file, in that file's directory.  Before TeX runs, you will be
asked about saving any modified buffers.  Generally, you need to use
(`tex-file') twice to get cross-references correct.

   For LaTeX files, you can use BibTeX to process the auxiliary file
for the current buffer's file.  BibTeX looks up bibliographic citations
in a data base and prepares the cited references for the bibliography
section.  The command `C-c TAB' (`tex-bibtex-file') runs the shell
command (`tex-bibtex-command') to produce a `.bbl' file for the current
buffer's file.  Generally, you need to do `C-c C-f' (`tex-file') once
to generate the `.aux' file, then do `C-c TAB' (`tex-bibtex-file'), and
then repeat `C-c C-f' (`tex-file') twice more to get the
cross-references correct.

   Entering any kind of TeX mode runs the hooks `text-mode-hook' and
`tex-mode-hook'.  Then it runs either `plain-tex-mode-hook' or
`latex-mode-hook', whichever is appropriate.  For SliTeX files, it
calls `slitex-mode-hook'.  Starting the TeX shell runs the hook
`tex-shell-hook'.  *Note Hooks::.


File: emacs,  Node: TeX Distrib,  Prev: TeX Print,  Up: TeX Mode

Unix TeX Distribution
---------------------

TeX for Unix systems can be obtained from the University of Washington
for a distribution fee.

   To order a full distribution, specify whether you prefer 1/4 inch
QIC-24 or 4mm DAT tape (9-track reel-to-reel is no longer available)
and send $210.00 for a (tar or cpio) cartridge, payable to the
University of Washington to:

     Pierre MacKay
     Department of Classics
     Denny Hall, Mail Stop DH-10
     University of Washington
     Seattle, Washington 98195

Purchase orders are acceptable, but there is an extra charge of $10.00,
to pay for processing charges.

For overseas orders please add $20.00 to the base cost for shipment via
air parcel post, or $30.00 for shipment via courier.

   The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
industry standard 2400 foot half-inch reel.  The physical format for the
1/4 inch streamer cartridges is QIC-24.  System V tapes can be written
in cpio format, blocked 5120 bytes, with ASCII headers.


File: emacs,  Node: Nroff Mode,  Next: Formatted Text,  Prev: TeX Mode,  Up: Text

Nroff Mode
==========

Nroff mode is a mode like Text mode but modified to handle nroff
commands present in the text.  Invoke `M-x nroff-mode' to enter this
mode.  It differs from Text mode in only a few ways.  All nroff command
lines are considered paragraph separators, so that filling will never
garble the nroff commands.  Pages are separated by `.bp' commands.
Comments start with backslash-doublequote.  Also, three special
commands are provided that are not in Text mode:

`M-n'
     Move to the beginning of the next line that isn't an nroff command
     (`forward-text-line').  An argument is a repeat count.

`M-p'
     Like `M-n' but move up (`backward-text-line').

`M-?'
     Prints in the echo area the number of text lines (lines that are
     not nroff commands) in the region (`count-text-lines').

   The other feature of Nroff mode is that you can turn on Electric
Nroff mode.  This is a minor mode that you can turn on or off with `M-x
electric-nroff-mode' (*note Minor Modes::).  When the mode is on, each
time you use <RET> to end a line that contains an nroff command that
opens a kind of grouping, the matching nroff command to close that
grouping is automatically inserted on the following line.  For example,
if you are at the beginning of a line and type `. ( b <RET>', this
inserts the matching command `.)b' on a new line following point.

   If you use Outline minor mode with Nroff mode (*note Outline Mode::),
heading lines are lines of the form `.H' followed by a number (the
header level).

   Entering Nroff mode runs the hook `text-mode-hook', followed by the
hook `nroff-mode-hook' (*note Hooks::).


File: emacs,  Node: Formatted Text,  Prev: Nroff Mode,  Up: Text

Editing Formatted Text
======================

"Enriched mode" is a minor mode for editing files that contain
formatted text in WYSIWYG fashion, as in a word processor.  Currently,
formatted text in Enriched mode can specify fonts, colors, underlining,
margins, and types of filling and justification.  In the future, we plan
to implement other formatting features as well.

   Enriched mode is a minor mode (*note Minor Modes::).  Typically it is
used in conjunction with Text mode (*note Text Mode::).  However, you
can also use it with other major modes such as Outline mode and Indented
Text mode.

   Potentially, Emacs can store formatted text files in various file
formats.  Currently, only one format is implemented: "text/enriched"
format, which is defined by the MIME protocol.  *Note Format
Conversion: (elisp)Format Conversion, for details of how Emacs
recognizes and converts file formats.

   The Emacs distribution contains a formatted text file that can serve
as an example.  Its name is `etc/enriched.doc'.  It contains samples
illustrating all the features described in this section.  It also
contains a list of ideas for future enhancements.

* Menu:

* Requesting Formatted Text::   Entering and exiting Enriched mode.
* Hard and Soft Newlines::      There are two different kinds of newlines.
* Editing Format Info::         How to edit text properties.
* Faces: Format Faces.          Bold, italic, underline, etc.
* Color: Format Colors.         Changing the color of text.
* Indent: Format Indentation.   Changing the left and right margins.
* Justification: Format Justification.
                                Centering, setting text flush with the
                                  left or right margin, etc.
* Other: Format Properties.     The "special" text properties submenu.
* Forcing Enriched Mode::       How to force use of Enriched mode.


File: emacs,  Node: Requesting Formatted Text,  Next: Hard and Soft Newlines,  Up: Formatted Text

Requesting to Edit Formatted Text
---------------------------------

Whenever you visit a file that Emacs saved in the text/enriched format,
Emacs automatically converts the formatting information in the file into
Emacs's own internal format (text properties), and turns on Enriched
mode.

   To create a new file of formatted text, first visit the nonexistent
file, then type `M-x enriched-mode' before you start inserting text.
This command turns on Enriched mode.  Do this before you begin inserting
text, to ensure that the text you insert is handled properly.

   More generally, the command `enriched-mode' turns Enriched mode on
if it was off, and off if it was on.  With a prefix argument, this
command turns Enriched mode on if the argument is positive, and turns
the mode off otherwise.

   When you save a buffer while Enriched mode is enabled in it, Emacs
automatically converts the text to text/enriched format while writing it
into the file.  When you visit the file again, Emacs will automatically
recognize the format, reconvert the text, and turn on Enriched mode
again.

   Normally, after reading a file in text/enriched format, Emacs refills
each paragraph to fit the width of the window.  You can turn off this
refilling, to save time, by setting the variable
`enriched-fill-after-visiting' to `nil' or to `ask'.

   In any case, if the window width is the same as the width with which
the file was saved, Emacs trusts that the file is already properly
filled.

   You can add annotations for saving additional text properties, which
Emacs normally does not save, by adding to `enriched-translations'.
Note that the text/enriched standard requires any non-standard
annotations to have names starting with `x-', as in `x-read-only'.
This ensures that they will not conflict with standard annotations that
may be added later.


File: emacs,  Node: Hard and Soft Newlines,  Next: Editing Format Info,  Prev: Requesting Formatted Text,  Up: Formatted Text

Hard and Soft Newlines
----------------------

In formatted text, Emacs distinguishes between two different kinds of
newlines, "hard" newlines and "soft" newlines.

   Hard newlines are used to separate paragraphs, or items in a list, or
anywhere that there should always be a line break regardless of the
margins.  The `RET' command (`newline') and `C-o' (`open-line') insert
hard newlines.

   Soft newlines are used to make text fit between the margins.  All the
fill commands, including Auto Fill, insert soft newlines--and they
delete only soft newlines.

   Although hard and soft newlines look the same, it is important to
bear the difference in mind.  Do not use <RET> to break lines in the
middle of filled paragraphs, or else you will get hard newlines that are
barriers to further filling.  Instead, let Auto Fill mode break lines,
so that if the text or the margins change, Emacs can refill the lines
properly.  *Note Auto Fill::.

   On the other hand, in tables and lists, where the lines should always
remain as you type them, you can use <RET> to end lines.  For these
lines, you may also want to set the justification style to `unfilled'.
*Note Format Justification::.


File: emacs,  Node: Editing Format Info,  Next: Format Faces,  Prev: Hard and Soft Newlines,  Up: Formatted Text

Editing Format Information
--------------------------

There are two ways to alter the formatting information for a formatted
text file: with keyboard commands, and with the mouse.

   The easiest way to add properties to your document is by using the
Text Properties menu.  You can get to this menu in two ways: from the
Edit menu in the menu bar, or with `C-mouse-2' (hold the <CTRL> key and
press the middle mouse button).

   Most of the items in the Text Properties menu lead to other submenus.
These are described in the sections that follow.  Some items run
commands directly:

`Remove Properties'
     Delete from the region all the text properties that the Text
     Properties menu works with (`facemenu-remove-props').

`Remove All'
     Delete _all_ text properties from the region
     (`facemenu-remove-all').

`List Properties'
     List all the text properties of the character following point
     (`list-text-properties-at').

`Display Faces'
     Display a list of all the defined faces.

`Display Colors'
     Display a list of all the defined colors.


File: emacs,  Node: Format Faces,  Next: Format Colors,  Prev: Editing Format Info,  Up: Formatted Text

Faces in Formatted Text
-----------------------

The Faces submenu lists various Emacs faces including `bold', `italic',
and `underline'.  Selecting one of these adds the chosen face to the
region.  *Note Faces::.  You can also specify a face with these
keyboard commands:

`M-g d'
     Set the region, or the next inserted character, to the `default'
     face (`facemenu-set-default').

`M-g b'
     Set the region, or the next inserted character, to the `bold' face
     (`facemenu-set-bold').

`M-g i'
     Set the region, or the next inserted character, to the `italic'
     face (`facemenu-set-italic').

`M-g l'
     Set the region, or the next inserted character, to the
     `bold-italic' face (`facemenu-set-bold-italic').

`M-g u'
     Set the region, or the next inserted character, to the `underline'
     face (`facemenu-set-underline').

`M-g o FACE <RET>'
     Set the region, or the next inserted character, to the face FACE
     (`facemenu-set-face').

   If you use these commands with a prefix argument--or, in Transient
Mark mode, if the region is not active--then these commands specify a
face to use for your next self-inserting input.  *Note Transient
Mark::.  This applies to both the keyboard commands and the menu
commands.

   Enriched mode defines two additional faces: `excerpt' and `fixed'.
These correspond to codes used in the text/enriched file format.

   The `excerpt' face is intended for quotations.  This face is the
same as `italic' unless you customize it (*note Modifying Faces::).

   The `fixed' face is meant to say, "Use a fixed-width font for this
part of the text."  Emacs currently supports only fixed-width fonts;
therefore, the `fixed' annotation is not necessary now.  However, we
plan to support variable width fonts in future Emacs versions, and
other systems that display text/enriched format may not use a
fixed-width font as the default.  So if you specifically want a certain
part of the text to use a fixed-width font, you should specify the
`fixed' face for that part.

   The `fixed' face is normally defined to use a different font from
the default.  However, systems have different fonts installed, you may
need to customize this.

   If your terminal cannot display different faces, you will not be able
to see them, but you can still edit documents containing faces.  You can
even add faces and colors to documents.  They will be visible when the
file is viewed on a terminal that can display them.


File: emacs,  Node: Format Colors,  Next: Format Indentation,  Prev: Format Faces,  Up: Formatted Text

Colors in Formatted Text
------------------------

You can specify foreground and background colors for portions of the
text.  There is a menu for specifying the foreground color and a menu
for specifying the background color.  Each color menu lists all the
colors that you have used in Enriched mode in the current Emacs session.

   If you specify a color with a prefix argument--or, in Transient Mark
mode, if the region is not active--then it applies to your next
self-inserting input.  *Note Transient Mark::.  Otherwise, the command
applies to the region.

   Each color menu contains one additional item: `Other'.  You can use
this item to specify a color that is not listed in the menu; it reads
the color name with the minibuffer.  To display list of available colors
and their names, use the `Display Colors' menu item in the Text
Properties menu (*note Editing Format Info::).

   Any color that you specify in this way, or that is mentioned in a
formatted text file that you read in, is added to both color menus for
the duration of the Emacs session.

   There are no key bindings for specifying colors, but you can do so
with the extended commands `M-x facemenu-set-foreground' and `M-x
facemenu-set-background'.  Both of these commands read the name of the
color with the minibuffer.


File: emacs,  Node: Format Indentation,  Next: Format Justification,  Prev: Format Colors,  Up: Formatted Text

Indentation in Formatted Text
-----------------------------

When editing formatted text, you can specify different amounts of
indentation for the right or left margin of an entire paragraph or a
part of a paragraph.  The margins you specify automatically affect the
Emacs fill commands (*note Filling::) and line-breaking commands.

   The Indentation submenu provides a convenient interface for
specifying these properties.  The submenu contains four items:

`Indent More'
     Indent the region by 4 columns (`increase-left-margin').  In
     Enriched mode, this command is also available on `C-x <TAB>'; if
     you supply a numeric argument, that says how many columns to add
     to the margin (a negative argument reduces the number of columns).

`Indent Less'
     Remove 4 columns of indentation from the region.

`Indent Right More'
     Make the text narrower by indenting 4 columns at the right margin.

`Indent Right Less'
     Remove 4 columns of indentation from the right margin.

   You can use these commands repeatedly to increase or decrease the
indentation.

   The most common way to use these commands is to change the
indentation of an entire paragraph.  However, that is not the only use.
You can change the margins at any point; the new values take effect at
the end of the line (for right margins) or the beginning of the next
line (for left margins).

   This makes it possible to format paragraphs with "hanging indents",
which means that the first line is indented less than subsequent lines.
To set up a hanging indent, increase the indentation of the region
starting after the first word of the paragraph and running until the end
of the paragraph.

   Indenting the first line of a paragraph is easier.  Set the margin
for the whole paragraph where you want it to be for the body of the
paragraph, then indent the first line by inserting extra spaces or tabs.

   Sometimes, as a result of editing, the filling of a paragraph becomes
messed up--parts of the paragraph may extend past the left or right
margins.  When this happens, use `M-q' (`fill-paragraph') to refill the
paragraph.

   The variable `standard-indent' specifies how many columns these
commands should add to or subtract from the indentation.  The default
value is 4.

   Enriched mode automatically sets the variable `fill-column' based on
the window width: it leaves a certain number of columns for the right
margin.  The variable `enriched-default-right-margin' says how many
columns.  The default value is 10.


File: emacs,  Node: Format Justification,  Next: Format Properties,  Prev: Format Indentation,  Up: Formatted Text

Justification in Formatted Text
-------------------------------

When editing formatted text, you can specify various styles of
justification for a paragraph.  The style you specify automatically
affects the Emacs fill commands.

   The Justification submenu provides a convenient interface for
specifying the style.  The submenu contains five items:

`Flush Left'
     This is the most common style of justification (at least for
     English).  Lines are aligned at the left margin but left uneven at
     the right.

`Flush Right'
     This aligns each line with the right margin.  Spaces and tabs are
     added on the left, if necessary, to make lines line up on the
     right.

`Full'
     This justifies the text, aligning both edges of each line.
     Justified text looks very nice in a printed book, where the spaces
     can all be adjusted equally, but it does not look as nice with a
     fixed-width font on the screen.  Perhaps a future version of Emacs
     will be able to adjust the width of spaces in a line to achieve
     elegant justification.

`Center'
     This centers every line between the current margins.

`None'
     This turns off filling entirely.  Each line will remain as you
     wrote it; the fill and auto-fill functions will have no effect on
     text which has this setting.  You can, however, still indent the
     left margin.  In unfilled regions, all newlines are treated as
     hard newlines (*note Hard and Soft Newlines::) .

   In Enriched mode, you can also specify justification from the
keyboard using the `M-j' prefix character:

`M-j l'
     Make the region left-filled (`set-justification-left').

`M-j r'
     Make the region right-filled (`set-justification-right').

`M-j f'
     Make the region fully-justified (`set-justification-full').

`M-j c'
`M-S'
     Make the region centered (`set-justification-center').

`M-j u'
     Make the region unfilled (`set-justification-none').

   Justification styles apply to entire paragraphs.  All the
justification-changing commands operate on the paragraph containing
point, or, if the region is active, on all paragraphs which overlap the
region.

   The default justification style is specified by the variable
`default-justification'.  Its value should be one of the symbols
`left', `right', `full', `center', or `none'.


File: emacs,  Node: Format Properties,  Next: Forcing Enriched Mode,  Prev: Format Justification,  Up: Formatted Text

Setting Other Text Properties
-----------------------------

The Other Properties menu lets you add or remove three other useful text
properties: `read-only', `invisible' and `intangible'.  The
`intangible' property disallows moving point within the text, the
`invisible' text property hides text from display, and the `read-only'
property disallows alteration of the text.

   Each of these special properties has a menu item to add it to the
region.  The last menu item, `Remove Special', removes all of these
special properties from the text in the region.

   Currently, the `invisible' and `intangible' properties are _not_
saved in the text/enriched format.  The `read-only' property is saved,
but it is not a standard part of the text/enriched format, so other
editors may not respect it.


File: emacs,  Node: Forcing Enriched Mode,  Prev: Format Properties,  Up: Formatted Text

Forcing Enriched Mode
---------------------

Normally, Emacs knows when you are editing formatted text because it
recognizes the special annotations used in the file that you visited.
However, there are situations in which you must take special actions to
convert file contents or turn on Enriched mode:

   * When you visit a file that was created with some other editor,
     Emacs may not recognize the file as being in the text/enriched
     format.  In this case, when you visit the file you will see the
     formatting commands rather than the formatted text.  Type `M-x
     format-decode-buffer' to translate it.

   * When you _insert_ a file into a buffer, rather than visiting it.
     Emacs does the necessary conversions on the text which you insert,
     but it does not enable Enriched mode.  If you wish to do that,
     type `M-x enriched-mode'.

   The command `format-decode-buffer' translates text in various
formats into Emacs's internal format.  It asks you to specify the format
to translate from; however, normally you can type just <RET>, which
tells Emacs to guess the format.

   If you wish to look at a file in text/enriched format in its raw
form, as a sequence of characters with no formatting, use `M-x
format-find-file <RET> FILENAME <RET> <RET>'.  The empty second
argument means, "read without format conversion."


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

Editing Programs
****************

Emacs has many commands designed to understand the syntax of programming
languages such as Lisp and C.  These commands can

   * Move over or kill balanced expressions or "sexps" (*note Lists::).

   * Move over or mark top-level expressions--"defuns", in Lisp;
     functions, in C (*note Defuns::).

   * Show how parentheses balance (*note Matching::).

   * Insert, kill or align comments (*note Comments::).

   * Follow the usual indentation conventions of the language (*note
     Program Indent::).

   The commands for words, sentences and paragraphs are very useful in
editing code even though their canonical application is for editing
human language text.  Most symbols contain words (*note Words::);
sentences can be found in strings and comments (*note Sentences::).
Paragraphs per se don't exist in code, but the paragraph commands are
useful anyway, because programming language major modes define
paragraphs to begin and end at blank lines (*note Paragraphs::).
Judicious use of blank lines to make the program clearer will also
provide useful chunks of text for the paragraph commands to work on.

   The selective display feature is useful for looking at the overall
structure of a function (*note Selective Display::).  This feature
causes only the lines that are indented less than a specified amount to
appear on the screen.

* Menu:

* Program Modes::     Major modes for editing programs.
* Lists::             Expressions with balanced parentheses.
* List Commands::     The commands for working with list and sexps.
* Defuns::            Each program is made up of separate functions.
                        There are editing commands to operate on them.
* Program Indent::    Adjusting indentation to show the nesting.
* Matching::          Insertion of a close-delimiter flashes matching open.
* Comments::          Inserting, killing, and aligning comments.
* Balanced Editing::  Inserting two matching parentheses at once, etc.
* Symbol Completion:: Completion on symbol names of your program or language.
* Documentation::     Getting documentation of functions you plan to call.
* Change Log::        Maintaining a change history for your program.
* Tags::              Go direct to any function in your program in one
                        command.  Tags remembers which file it is in.
* Emerge::	      A convenient way of merging two versions of a program.
* C Mode::	      Special commands of C, C++, Objective-C and Java modes.
* Fortran::	      Fortran mode and its special features.
* Asm Mode::	      Asm mode and its special features.


File: emacs,  Node: Program Modes,  Next: Lists,  Up: Programs

Major Modes for Programming Languages
=====================================

Emacs also has major modes for the programming languages Lisp, Scheme
(a variant of Lisp), Awk, C, C++, Fortran, Icon, Java, Objective-C,
Pascal, Perl and Tcl.  There is also a major mode for makefiles, called
Makefile mode.

   Ideally, a major mode should be implemented for each programming
language that you might want to edit with Emacs; but often the mode for
one language can serve for other syntactically similar languages.  The
language modes that exist are those that someone decided to take the
trouble to write.

   There are several forms of Lisp mode, which differ in the way they
interface to Lisp execution.  *Note Executing Lisp::.

   Each of the programming language modes defines the <TAB> key to run
an indentation function that knows the indentation conventions of that
language and updates the current line's indentation accordingly.  For
example, in C mode <TAB> is bound to `c-indent-line'.  <LFD> is
normally defined to do <RET> followed by <TAB>; thus, it too indents in
a mode-specific fashion.

   In most programming languages, indentation is likely to vary from
line to line.  So the major modes for those languages rebind <DEL> to
treat a tab as if it were the equivalent number of spaces (using the
command `backward-delete-char-untabify').  This makes it possible to
rub out indentation one column at a time without worrying whether it is
made up of spaces or tabs.  Use `C-b C-d' to delete a tab character
before point, in these modes.

   Programming language modes define paragraphs to be separated only by
blank lines, so that the paragraph commands remain useful.  Auto Fill
mode, if enabled in a programming language major mode, indents the new
lines which it creates.

   Turning on a major mode runs a normal hook called the "mode hook",
which is the value of a Lisp variable.  Each major mode has a mode hook,
and the hook's name is always made from the mode command's name by
adding `-hook'.  For example, turning on C mode runs the hook
`c-mode-hook', while turning on Lisp mode runs the hook
`lisp-mode-hook'.  *Note Hooks::.


File: emacs,  Node: Lists,  Next: List Commands,  Prev: Program Modes,  Up: Programs

Lists and Sexps
===============

By convention, Emacs keys for dealing with balanced expressions are
usually Control-Meta characters.  They tend to be analogous in function
to their Control and Meta equivalents.  These commands are usually
thought of as pertaining to expressions in programming languages, but
can be useful with any language in which some sort of parentheses exist
(including human languages).

   These commands fall into two classes.  Some deal only with "lists"
(parenthetical groupings).  They see nothing except parentheses,
brackets, braces (whichever ones must balance in the language you are
working with), and escape characters that might be used to quote those.

   The other commands deal with expressions or "sexps".  The word `sexp'
is derived from "s-expression", the ancient term for an expression in
Lisp.  But in Emacs, the notion of `sexp' is not limited to Lisp.  It
refers to an expression in whatever language your program is written in.
Each programming language has its own major mode, which customizes the
syntax tables so that expressions in that language count as sexps.

   Sexps typically include symbols, numbers, and string constants, as
well as anything contained in parentheses, brackets or braces.

   In languages that use prefix and infix operators, such as C, it is
not possible for all expressions to be sexps.  For example, C mode does
not recognize `foo + bar' as a sexp, even though it _is_ a C expression;
it recognizes `foo' as one sexp and `bar' as another, with the `+' as
punctuation between them.  This is a fundamental ambiguity: both `foo +
bar' and `foo' are legitimate choices for the sexp to move over if
point is at the `f'.  Note that `(foo + bar)' is a single sexp in C
mode.

   Some languages have obscure forms of expression syntax that nobody
has bothered to make Emacs understand properly.


File: emacs,  Node: List Commands,  Next: Defuns,  Prev: Lists,  Up: Programs

List And Sexp Commands
======================

`C-M-f'
     Move forward over a sexp (`forward-sexp').

`C-M-b'
     Move backward over a sexp (`backward-sexp').

`C-M-k'
     Kill sexp forward (`kill-sexp').

`C-M-<DEL>'
     Kill sexp backward (`backward-kill-sexp').

`C-M-u'
     Move up and backward in list structure (`backward-up-list').

`C-M-d'
     Move down and forward in list structure (`down-list').

`C-M-n'
     Move forward over a list (`forward-list').

`C-M-p'
     Move backward over a list (`backward-list').

`C-M-t'
     Transpose expressions (`transpose-sexps').

`C-M-@'
     Put mark after following expression (`mark-sexp').

   To move forward over a sexp, use `C-M-f' (`forward-sexp').  If the
first significant character after point is an opening delimiter (`(' in
Lisp; `(', `[' or `{' in C), `C-M-f' moves past the matching closing
delimiter.  If the character begins a symbol, string, or number,
`C-M-f' moves over that.

   The command `C-M-b' (`backward-sexp') moves backward over a sexp.
The detailed rules are like those above for `C-M-f', but with
directions reversed.  If there are any prefix characters (single-quote,
backquote and comma, in Lisp) preceding the sexp, `C-M-b' moves back
over them as well.  The sexp commands move across comments as if they
were whitespace in most modes.

   `C-M-f' or `C-M-b' with an argument repeats that operation the
specified number of times; with a negative argument, it moves in the
opposite direction.

   Killing a sexp at a time can be done with `C-M-k' (`kill-sexp') or
`C-M-<DEL>' (`backward-kill-sexp').  `C-M-k' kills the characters that
`C-M-f' would move over, and `C-M-<DEL>' kills the characters that
`C-M-b' would move over.

   The "list commands" move over lists like the sexp commands but skip
blithely over any number of other kinds of sexps (symbols, strings,
etc).  They are `C-M-n' (`forward-list') and `C-M-p' (`backward-list').
The main reason they are useful is that they usually ignore comments
(since the comments usually do not contain any lists).

   `C-M-n' and `C-M-p' stay at the same level in parentheses, when
that's possible.  To move _up_ one (or N) levels, use `C-M-u'
(`backward-up-list').  `C-M-u' moves backward up past one unmatched
opening delimiter.  A positive argument serves as a repeat count; a
negative argument reverses direction of motion and also requests
repetition, so it moves forward and up one or more levels.

   To move _down_ in list structure, use `C-M-d' (`down-list').  In
Lisp mode, where `(' is the only opening delimiter, this is nearly the
same as searching for a `('.  An argument specifies the number of levels
of parentheses to go down.

   A somewhat random-sounding command which is nevertheless handy is
`C-M-t' (`transpose-sexps'), which drags the previous sexp across the
next one.  An argument serves as a repeat count, and a negative
argument drags backwards (thus canceling out the effect of `C-M-t' with
a positive argument).  An argument of zero, rather than doing nothing,
transposes the sexps ending after point and the mark.

   To set the region around the next sexp in the buffer, use `C-M-@'
(`mark-sexp'), which sets mark at the same place that `C-M-f' would
move to.  `C-M-@' takes arguments like `C-M-f'.  In particular, a
negative argument is useful for putting the mark at the beginning of
the previous sexp.

   The list and sexp commands' understanding of syntax is completely
controlled by the syntax table.  Any character can, for example, be
declared to be an opening delimiter and act like an open parenthesis.
*Note Syntax::.


File: emacs,  Node: Defuns,  Next: Program Indent,  Prev: List Commands,  Up: Programs

Defuns
======

In Emacs, a parenthetical grouping at the top level in the buffer is
called a "defun".  The name derives from the fact that most top-level
lists in a Lisp file are instances of the special form `defun', but any
top-level parenthetical grouping counts as a defun in Emacs parlance
regardless of what its contents are, and regardless of the programming
language in use.  For example, in C, the body of a function definition
is a defun.

`C-M-a'
     Move to beginning of current or preceding defun
     (`beginning-of-defun').

`C-M-e'
     Move to end of current or following defun (`end-of-defun').

`C-M-h'
     Put region around whole current or following defun (`mark-defun').

   The commands to move to the beginning and end of the current defun
are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').

   If you wish to operate on the current defun, use `C-M-h'
(`mark-defun') which puts point at the beginning and mark at the end of
the current or next defun.  For example, this is the easiest way to get
ready to move the defun to a different place in the text.  In C mode,
`C-M-h' runs the function `mark-c-function', which is almost the same
as `mark-defun'; the difference is that it backs up over the argument
declarations, function name and returned data type so that the entire C
function is inside the region.  *Note Marking Objects::.

   Emacs assumes that any open-parenthesis found in the leftmost column
is the start of a defun.  Therefore, *never put an open-parenthesis at
the left margin in a Lisp file unless it is the start of a top level
list.  Never put an open-brace or other opening delimiter at the
beginning of a line of C code unless it starts the body of a function.*
The most likely problem case is when you want an opening delimiter at
the start of a line inside a string.  To avoid trouble, put an escape
character (`\', in C and Emacs Lisp, `/' in some other Lisp dialects)
before the opening delimiter.  It will not affect the contents of the
string.

   In the remotest past, the original Emacs found defuns by moving
upward a level of parentheses until there were no more levels to go up.
This always required scanning all the way back to the beginning of the
buffer, even for a small function.  To speed up the operation, Emacs
was changed to assume that any `(' (or other character assigned the
syntactic class of opening-delimiter) at the left margin is the start
of a defun.  This heuristic is nearly always right and avoids the
costly scan; however, it mandates the convention described above.


File: emacs,  Node: Program Indent,  Next: Matching,  Prev: Defuns,  Up: Programs

Indentation for Programs
========================

The best way to keep a program properly indented is to use Emacs to
re-indent it as you change it.  Emacs has commands to indent properly
either a single line, a specified number of lines, or all of the lines
inside a single parenthetical grouping.

* Menu:

* Basic Indent::	Indenting a single line.
* Multi-line Indent::   Commands to reindent many lines at once.
* Lisp Indent::		Specifying how each Lisp function should be indented.
* C Indent::		Extra features for indenting C code.
* Custom C Indent::	Controlling indentation style for C code.

   Emacs also provides a Lisp pretty-printer in the library `pp'.  This
program prints a Lisp object with indentation chosen to look nice.


File: emacs,  Node: Basic Indent,  Next: Multi-line Indent,  Up: Program Indent

Basic Program Indentation Commands
----------------------------------

`<TAB>'
     Adjust indentation of current line.

`<LFD>'
     Equivalent to <RET> followed by <TAB> (`newline-and-indent').

   The basic indentation command is <TAB>, which gives the current line
the correct indentation as determined from the previous lines.  The
function that <TAB> runs depends on the major mode; it is
`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc.  These
functions understand different syntaxes for different languages, but
they all do about the same thing.  <TAB> in any programming language
major mode inserts or deletes whitespace at the beginning of the
current line, independent of where point is in the line.  If point is
inside the whitespace at the beginning of the line, <TAB> leaves it at
the end of that whitespace; otherwise, <TAB> leaves point fixed with
respect to the characters around it.

   Use `C-q <TAB>' to insert a tab at point.

   When entering lines of new code, use <LFD> (`newline-and-indent'),
which is equivalent to a <RET> followed by a <TAB>.  <LFD> creates a
blank line, and then gives it the appropriate indentation.

   <TAB> indents the second and following lines of the body of a
parenthetical grouping each under the preceding one; therefore, if you
alter one line's indentation to be nonstandard, the lines below will
tend to follow it.  This behavior is convenient in cases where you have
overridden the standard result of <TAB> because you find it unaesthetic
for a particular line.

   Remember that an open-parenthesis, open-brace or other opening
delimiter at the left margin is assumed by Emacs (including the
indentation routines) to be the start of a function.  Therefore, you
must never have an opening delimiter in column zero that is not the
beginning of a function, not even inside a string.  This restriction is
vital for making the indentation commands fast; you must simply accept
it.  *Note Defuns::, for more information on this.


File: emacs,  Node: Multi-line Indent,  Next: Lisp Indent,  Prev: Basic Indent,  Up: Program Indent

Indenting Several Lines
-----------------------

When you wish to re-indent several lines of code which have been altered
or moved to a different level in the list structure, you have several
commands available.

`C-M-q'
     Re-indent all the lines within one list (`indent-sexp').

`C-u <TAB>'
     Shift an entire list rigidly sideways so that its first line is
     properly indented.

`C-M-\'
     Re-indent all lines in the region (`indent-region').

   You can re-indent the contents of a single list by positioning point
before the beginning of it and typing `C-M-q' (`indent-sexp' in Lisp
mode, `indent-c-exp' in C mode; also bound to other suitable commands
in other modes).  The indentation of the line the sexp starts on is not
changed; therefore, only the relative indentation within the list, and
not its position, is changed.  To correct the position as well, type a
<TAB> before the `C-M-q'.

   If the relative indentation within a list is correct but the
indentation of its first line is not, go to that line and type `C-u
<TAB>'.  <TAB> with a numeric argument reindents the current line as
usual, then reindents by the same amount all the lines in the grouping
starting on the current line.  In other words, it reindents the whole
grouping rigidly as a unit.  It is clever, though, and does not alter
lines that start inside strings, or C preprocessor lines when in C mode.

   Another way to specify the range to be re-indented is with the
region.  The command `C-M-\' (`indent-region') applies <TAB> to every
line whose first character is between point and mark.


File: emacs,  Node: Lisp Indent,  Next: C Indent,  Prev: Multi-line Indent,  Up: Program Indent

Customizing Lisp Indentation
----------------------------

The indentation pattern for a Lisp expression can depend on the function
called by the expression.  For each Lisp function, you can choose among
several predefined patterns of indentation, or define an arbitrary one
with a Lisp program.

   The standard pattern of indentation is as follows: the second line
of the expression is indented under the first argument, if that is on
the same line as the beginning of the expression; otherwise, the second
line is indented underneath the function name.  Each following line is
indented under the previous line whose nesting depth is the same.

   If the variable `lisp-indent-offset' is non-`nil', it overrides the
usual indentation pattern for the second line of an expression, so that
such lines are always indented `lisp-indent-offset' more columns than
the containing list.

   The standard pattern is overridden for certain functions.  Functions
whose names start with `def' always indent the second line by
`lisp-body-indent' extra columns beyond the open-parenthesis starting
the expression.

   The standard pattern can be overridden in various ways for individual
functions, according to the `lisp-indent-function' property of the
function name.  There are four possibilities for this property:

`nil'
     This is the same as no property; the standard indentation pattern
     is used.

`defun'
     The pattern used for function names that start with `def' is used
     for this function also.

a number, NUMBER
     The first NUMBER arguments of the function are "distinguished"
     arguments; the rest are considered the "body" of the expression.
     A line in the expression is indented according to whether the
     first argument on it is distinguished or not.  If the argument is
     part of the body, the line is indented `lisp-body-indent' more
     columns than the open-parenthesis starting the containing
     expression.  If the argument is distinguished and is either the
     first or second argument, it is indented _twice_ that many extra
     columns.  If the argument is distinguished and not the first or
     second argument, the standard pattern is followed for that line.

a symbol, SYMBOL
     SYMBOL should be a function name; that function is called to
     calculate the indentation of a line within this expression.  The
     function receives two arguments:
    STATE
          The value returned by `parse-partial-sexp' (a Lisp primitive
          for indentation and nesting computation) when it parses up to
          the beginning of this line.

    POS
          The position at which the line being indented begins.

     It should return either a number, which is the number of columns of
     indentation for that line, or a list whose car is such a number.
     The difference between returning a number and returning a list is
     that a number says that all following lines at the same nesting
     level should be indented just like this one; a list says that
     following lines might call for different indentations.  This makes
     a difference when the indentation is being computed by `C-M-q'; if
     the value is a number, `C-M-q' need not recalculate indentation
     for the following lines until the end of the list.


File: emacs,  Node: C Indent,  Next: Custom C Indent,  Prev: Lisp Indent,  Up: Program Indent

Commands for C Indentation
--------------------------

Here are the commands for indentation in C mode and related modes:

`C-c C-q'
     Reindent the current top-level function definition or aggregate
     type declaration (`c-indent-defun').

`C-M-q'
     Reindent each line in the balanced expression that follows point
     (`c-indent-exp').  A prefix argument inhibits error checking and
     warning messages about invalid syntax.

`<TAB>'
     Reindent the current line, and/or in some cases insert a tab
     character (`c-indent-command').

     If `c-tab-always-indent' is `t', this command always reindents the
     current line and does nothing else.  This is the default.

     If that variable is `nil', this command reindents the current line
     only if point is at the left margin or in the line's indentation;
     otherwise, it inserts a tab.

     Any other value (not `nil' or `t') means always reindent the line,
     and also insert a tab if within a comment, a string, or a
     preprocessor directive.

`C-u <TAB>'
     Reindent the current line according to its syntax; also rigidly
     reindent any other lines of the expression that starts on the
     current line.  *Note Multi-line Indent::.

   To reindent the whole current buffer, type `C-x h C-M-\'.  This
first selects the whole buffer as the region, then reindents that
region.

   To reindent the current block, use `C-M-u C-M-q'.  This moves to the
front of the block and then reindents it all.


File: emacs,  Node: Custom C Indent,  Prev: C Indent,  Up: Program Indent

Customizing C Indentation
-------------------------

C mode and related modes use a simple yet flexible mechanism for
customizing indentation.  The mechanism works in two steps: first it
classifies the line syntactically according to its contents and context;
second, it associates each kind of syntactic construct with an
indentation offset which you can customize.

* Menu:

* Syntactic Analysis::
* Indentation Calculation::
* Changing Indent Style::
* Syntactic Symbols::
* Variables for C Indent::
* C Indent Styles::


File: emacs,  Node: Syntactic Analysis,  Next: Indentation Calculation,  Up: Custom C Indent

Step 1--Syntactic Analysis
..........................

In the first step, the C indentation mechanism looks at the line you
are currently indenting and determines the syntactic components of the
construct on that line.  It builds a list of these syntactic components,
where each component on the list contains a "syntactic symbol" and a
relative buffer position.  Syntactic symbols describe grammatical
elements such as STATEMENT, SUBSTATEMENT, CLASS-OPEN, CLASS-CLOSE,
KNR-ARGDECL, etc.

   Conceptually, a line of C code is always indented relative to the
indentation of some line higher up in the buffer.  This is represented
by the relative buffer positions in the syntactic component list.

   Here is an example.  Suppose we have the following code in a C++ mode
buffer (the line numbers don't actually appear in the buffer):

     1: void swap (int& a, int& b)
     2: {
     3:   int tmp = a;
     4:   a = b;
     5:   b = tmp;
     6: }

   If you type `C-c C-s' (which runs the command
`c-show-syntactic-information') on line 4, it shows the result of the
indentation mechanism for that line:

     ((statement . 32))

   This indicates that the line is a statement and it is indented
relative to buffer position 32, which happens to be the `i' in `int' on
line 3.  If you move the cursor to line 3 and type `C-c C-s', it
displays this:

     ((defun-block-intro . 28))

   This indicates that the `int' line is the first statement in a
block, and is indented relative to buffer position 28, which is the
brace just after the function header.

Here is another example:

     1: int add (int val, int incr, int doit)
     2: {
     3:   if (doit)
     4:     {
     5:       return (val + incr);
     6:     }
     7:   return (val);
     8: }

Typing `C-c C-s' on line 4 displays this:

     ((substatement-open . 43))

   This says that the brace _opens_ a substatement block.  By the way,
a "substatement" indicates the line after an `if', `else', `while',
`do', `switch', and `for' statements.

   After a line has been analyzed syntactically for indentation, the
global variable `c-syntactic-context' contains a list that describes
the results.  Each element in this list is a a "syntactic component": a
cons cell containing a syntactic symbol and (optionally) its
corresponding buffer position.  There may be several elements in a
component list; typically only one element has a buffer position.


File: emacs,  Node: Indentation Calculation,  Next: Changing Indent Style,  Prev: Syntactic Analysis,  Up: Custom C Indent

Step 2--Indentation Calculation
...............................

The C indentation mechanism calculates the indentation for the current
line using the list of syntactic components, `c-syntactic-context',
derived from syntactic analysis.  Each component is a cons cell that
contains a syntactic symbol and may also contain a pointer to a location
in the buffer.

   Each component contributes to the final total indentation of the line
in two ways.  First, the syntactic symbol identifies an element of
`c-offsets-alist', which is an association list mapping syntactic
symbols into indentation offsets.  Each syntactic symbol's offset adds
to the total indentation.  Second, if the component includes a buffer
position, the column number of that position adds to the indentation.
All these offsets and column numbers, added together, give the total
indentation.

   The following examples demonstrate the workings of the C indentation
mechanism:

     1: void swap (int& a, int& b)
     2: {
     3:   int tmp = a;
     4:   a = b;
     5:   b = tmp;
     6: }

   Suppose that point is on line 3 and you type <TAB> to reindent the
line.  As explained above (*note Syntactic Analysis::), the syntactic
component list for that line is:

     ((defun-block-intro . 28))

   In this case, the indentation calculation first looks up
`defun-block-intro' in the `c-offsets-alist' alist.  Suppose that it
finds the integer 2; it adds this to the running total (initialized to
zero), yielding a updated total indentation of 2 spaces.

   The next step is to find the column number of buffer position 28.
Since the brace at buffer position 28 is in column zero, this adds 0 to
the running total.  Since this line has only one syntactic component,
the total indentation for the line is 2 spaces.

     1: int add (int val, int incr, int doit)
     2: {
     3:   if (doit)
     4:     {
     5:       return(val + incr);
     6:     }
     7:   return(val);
     8: }

   If you type <TAB> on line 4, the same process is performed, but with
different data.  The syntactic component list for this line is:

     ((substatement-open . 43))

   Here, the indentation calculation's first job is to look up the
symbol `substatement-open' in `c-offsets-alist'.  Let's assume that the
offset for this symbol is 2.  At this point the running total is 2 (0 +
2 = 2).  Then it adds the column number of buffer position 43, which is
the `i' in `if' on line 3.  This character is in column 2 on that line.
Adding this yields a total indentation of 4 spaces.

   If a syntactic symbol in the analysis of a line does not appear in
`c-offsets-alist', it is ignored; if in addition the variable
`c-strict-syntax-p' is non-`nil', it is an error.


File: emacs,  Node: Changing Indent Style,  Next: Syntactic Symbols,  Prev: Indentation Calculation,  Up: Custom C Indent

Changing Indentation Style
..........................

There are two ways to customize the indentation style for the C modes.
First, you can select one of several predefined styles, each of which
specifies offsets for all the syntactic symbols.  For more flexibility,
you can customize the handling of individual syntactic symbols.  *Note
Syntactic Symbols::, for a list of all defined syntactic symbols.

`M-x c-set-style <RET> STYLE <RET>'
     Select predefined indentation style STYLE.  Type `?' when entering
     STYLE to see a list of supported styles; to find out what a style
     looks like, select it and reindent some C code.

`C-c C-o SYMBOL <RET> OFFSET <RET>'
     Set the indentation offset for syntactic symbol SYMBOL
     (`c-set-offset').  The second argument OFFSET specifies the new
     indentation offset.

   The `c-offsets-alist' variable controls the amount of indentation to
give to each syntactic symbol.  Its value is an association list, and
each element of the list has the form `(SYNTACTIC-SYMBOL . OFFSET)'.
By changing the offsets for various syntactic symbols, you can
customize indentation in fine detail.

   Each offset value in `c-offsets-alist' can be an integer, a function
or variable name, or one of the following symbols: `+', `-', `++', or
`--', indicating positive or negative multiples of the variable
`c-basic-offset'.  Thus, if you want to change the levels of
indentation to be 3 spaces instead of 2 spaces, set `c-basic-offset' to
3.

   Using a function as the offset value provides the ultimate
flexibility in customizing indentation.  The function is called with a
single argument containing the `cons' of the syntactic symbol and the
relative indent point.  The function should return an integer offset.

   The command `C-c C-o' (`c-set-offset') is the easiest way to set
offsets, both interactively or in your `~/.emacs' file.  First specify
the syntactic symbol, then the offset you want.  *Note Syntactic
Symbols::, for a list of valid syntactic symbols and their meanings.

   The variable `c-offsets-alist-default' holds the default settings
for the offsets of the syntactic symbols.  _Do not change this value!_


File: emacs,  Node: Syntactic Symbols,  Next: Variables for C Indent,  Prev: Changing Indent Style,  Up: Custom C Indent

Syntactic Symbols
.................

Here is a table of valid syntactic symbols for C mode indentation, with
their syntactic meanings.  Normally, most of these symbols are assigned
offsets in `c-offsets-alist'.

`string'
     Inside a multi-line string.

`c'
     Inside a multi-line C style block comment.

`defun-open'
     On a brace that opens a function definition.

`defun-close'
     On a brace that closes a function definition.

`defun-block-intro'
     In the first line in a top-level defun.

`class-open'
     On a brace that opens a class definition.

`class-close'
     On a brace that closes a class definition.

`inline-open'
     On a brace that opens an in-class inline method.

`inline-close'
     On a brace that closes an in-class inline method.

`ansi-funcdecl-cont'
     In the nether region between an ANSI function declaration and the
     defun opening brace.

`knr-argdecl-intro'
     On the first line of a K&R C argument declaration.

`knr-argdecl'
     In one of the subsequent lines in a K&R C argument declaration.

`topmost-intro'
     On the first line in a topmost construct definition.

`topmost-intro-cont'
     On the topmost definition continuation lines.

`member-init-intro'
     On the first line in a member initialization list.

`member-init-cont'
     On one of the subsequent member initialization list lines.

`inher-intro'
     On the first line of a multiple inheritance list.

`inher-cont'
     On one of the subsequent multiple inheritance lines.

`block-open'
     On a statement block open brace.

`block-close'
     On a statement block close brace.

`brace-list-open'
     On the opening brace of an `enum' or `static' array list.

`brace-list-close'
     On the closing brace of an `enum' or `static' array list.

`brace-list-intro'
     On the first line in an `enum' or `static' array list.

`brace-list-entry'
     On one of the subsequent lines in an `enum' or `static' array list.

`statement'
     On an ordinary statement.

`statement-cont'
     On a continuation line of a statement.

`statement-block-intro'
     On the first line in a new statement block.

`statement-case-intro'
     On the first line in a `case' "block".

`statement-case-open'
     On the first line in a `case' block starting with brace.

`substatement'
     On the first line after an `if', `while', `for', `do', or `else'.

`substatement-open'
     On the brace that opens a substatement block.

`case-label'
     On a `case' or `default' label.

`access-label'
     On a C++ `private', `protected', or `public' access label.

`label'
     On any ordinary label.

`do-while-closure'
     On the `while' that ends a `do'-`while' construct.

`else-clause'
     On the `else' of an `if'-`else' construct.

`comment-intro'
     On a line containing only a comment introduction.

`arglist-intro'
     On the first line in an argument list.

`arglist-cont'
     On one of the subsequent argument list lines when no arguments
     follow on the same line as the the arglist opening parenthesis.

`arglist-cont-nonempty'
     On one of the subsequent argument list lines when at least one
     argument follows on the same line as the arglist opening
     parenthesis.

`arglist-close'
     On the closing parenthesis of an argument list.

`stream-op'
     On one of the lines continuing a stream operator construct.

`inclass'
     On a construct which is nested inside a class definition.

`cpp-macro'
     On the start of a cpp macro.

`friend'
     On a C++ `friend' declaration.

`objc-method-intro'
     On the first line of an Objective-C method definition.

`objc-method-args-cont'
     On one of the lines continuing an Objective-C method definition.

`objc-method-call-cont'
     On one of the lines continuing an Objective-C method call.


File: emacs,  Node: Variables for C Indent,  Next: C Indent Styles,  Prev: Syntactic Symbols,  Up: Custom C Indent

Variables for C Indentation
...........................

This section describes additional variables which control the
indentation behavior of C mode and related mode.

`c-offsets-alist'
     Association list of syntactic symbols and their indentation
     offsets.  *Note Changing Indent Style::, for details.

`c-offsets-alist-default'
     Default settings for the offsets of the syntactic symbols.  *Note
     Changing Indent Style::.

`c-style-alist'
     Variable for specifying styles of indentation; see below.

`c-basic-offset'
     Amount of basic offset used by `+' and `-' symbols in
     `c-offsets-alist'.

`c-recognize-knr-p'
     If this variable is non-`nil', C mode and Objective C mode
     recognize K&R constructs.  This variable is needed because of
     ambiguities in C syntax that make recognition of K&R constructs
     problematic and slow.  If you always use ANSI C prototype syntax,
     set this variable to `nil' to speed up C indentation.

     This variable is `nil' by default in C++ mode, and `t' by default
     in C mode and Objective C mode.

`c-special-indent-hook'
     Hook for user-defined special indentation adjustments.  This hook
     is called after a line is indented by C mode and related modes.

   The variable `c-style-alist' specifies the predefined indentation
styles.  Each element has form `(NAME VARIABLE-SETTING...)', where NAME
is the name of the style.  Each VARIABLE-SETTING has the form `(VARIABLE
. VALUE)'; VARIABLE is one of the customization variables used by C
mode, and VALUE is the value for that variable when using the selected
style.

   When VARIABLE is `c-offsets-alist', that is a special case: VALUE is
appended to the front of the value of `c-offsets-alist' instead of
replacing that value outright.  Therefore, it is not necessary for
VALUE to specify each and every syntactic symbol--only those for which
the style differs from the default.

   The indentation of lines containing only comments is also affected by
the variable `c-comment-only-line-offset' (*note Comments in C::).


File: emacs,  Node: C Indent Styles,  Prev: Variables for C Indent,  Up: Custom C Indent

C Indentation Styles
....................

A "C style" is a collection of indentation style customizations.  Emacs
comes with several predefined indentation styles for C code including
`gnu', `k&r', `bsd', `stroustrup' `whitesmith', `ellemtel', and
`cc-mode'.  The default style is `gnu'.

   To choose the style you want, use the command `M-x c-set-style'.
Specify a style name as an argument (case is not significant in C style
names).  The chosen style only affects newly visited buffers, not those
you are already editing.

   To define a new C indentation style, call the function `c-add-style':

     (c-add-style NAME VALUES USE-NOW)

Here NAME is the name of the new style (a string), and VALUES is an
alist whose elements have the form `(VARIABLE . VALUE)'.  The variables
you specify should be among those documented in *Note Variables for C
Indent::.

   If USE-NOW is non-`nil', `c-add-style' switches to the new style
after defining it.


File: emacs,  Node: Matching,  Next: Comments,  Prev: Program Indent,  Up: Programs

Automatic Display Of Matching Parentheses
=========================================

The Emacs parenthesis-matching feature is designed to show
automatically how parentheses match in the text.  Whenever you type a
self-inserting character that is a closing delimiter, the cursor moves
momentarily to the location of the matching opening delimiter, provided
that is on the screen.  If it is not on the screen, some text near it is
displayed in the echo area.  Either way, you can tell what grouping is
being closed off.

   In Lisp, automatic matching applies only to parentheses.  In C, it
applies to braces and brackets too.  Emacs knows which characters to
regard as matching delimiters based on the syntax table, which is set
by the major mode.  *Note Syntax::.

   If the opening delimiter and closing delimiter are mismatched--such
as in `[x)'--a warning message is displayed in the echo area.  The
correct matches are specified in the syntax table.

   Three variables control parenthesis match display.
`blink-matching-paren' turns the feature on or off; `nil' turns it off,
but the default is `t' to turn match display on.
`blink-matching-delay' says how many seconds to wait; the default is 1,
but on some systems it is useful to specify a fraction of a second.
`blink-matching-paren-distance' specifies how many characters back to
search to find the matching opening delimiter.  If the match is not
found in that far, scanning stops, and nothing is displayed.  This is
to prevent scanning for the matching delimiter from wasting lots of
time when there is no match.  The default is 12,000.

   When using X Windows, you can request a more powerful kind of
automatic parenthesis matching by loading the `paren' library.  To load
it, type `M-x load-library <RET> paren <RET>'.  This library turns off
the usual kind of matching parenthesis display and substitutes another:
whenever point is after a close parenthesis, the close parenthesis and
its matching open parenthesis are both highlighted; otherwise, if point
is before an open parenthesis, the matching close parenthesis is
highlighted.  (There is no need to highlight the open parenthesis after
point because the cursor appears on top of that character.)


File: emacs,  Node: Comments,  Next: Balanced Editing,  Prev: Matching,  Up: Programs

Manipulating Comments
=====================

Because comments are such an important part of programming, Emacs
provides special commands for editing and inserting comments.

* Menu:

* Comment Commands::
* Multi-Line Comments::
* Options for Comments::


File: emacs,  Node: Comment Commands,  Next: Multi-Line Comments,  Up: Comments

Comment Commands
----------------

The comment commands insert, kill and align comments.

`M-;'
     Insert or align comment (`indent-for-comment').

`C-x ;'
     Set comment column (`set-comment-column').

`C-u - C-x ;'
     Kill comment on current line (`kill-comment').

`M-<LFD>'
     Like <RET> followed by inserting and aligning a comment
     (`indent-new-comment-line').

`M-x comment-region'
     Add or remove comment delimiters on all the lines in the region.

   The command that creates a comment is `M-;' (`indent-for-comment').
If there is no comment already on the line, a new comment is created,
aligned at a specific column called the "comment column".  The comment
is created by inserting the string Emacs thinks comments should start
with (the value of `comment-start'; see below).  Point is left after
that string.  If the text of the line extends past the comment column,
then the indentation is done to a suitable boundary (usually, at least
one space is inserted).  If the major mode has specified a string to
terminate comments, that is inserted after point, to keep the syntax
valid.

   `M-;' can also be used to align an existing comment.  If a line
already contains the string that starts comments, then `M-;' just moves
point after it and re-indents it to the conventional place.  Exception:
comments starting in column 0 are not moved.

   Some major modes have special rules for indenting certain kinds of
comments in certain contexts.  For example, in Lisp code, comments which
start with two semicolons are indented as if they were lines of code,
instead of at the comment column.  Comments which start with three
semicolons are supposed to start at the left margin.  Emacs understands
these conventions by indenting a double-semicolon comment using <TAB>,
and by not changing the indentation of a triple-semicolon comment at
all.

     ;; This function is just an example
     ;;; Here either two or three semicolons are appropriate.
     (defun foo (x)
     ;;; And now, the first part of the function:
       ;; The following line adds one.
       (1+ x))           ; This line adds one.

   In C code, a comment preceded on its line by nothing but whitespace
is indented like a line of code.

   Even when an existing comment is properly aligned, `M-;' is still
useful for moving directly to the start of the comment.

   `C-u - C-x ;' (`kill-comment') kills the comment on the current line,
if there is one.  The indentation before the start of the comment is
killed as well.  If there does not appear to be a comment in the line,
nothing is done.  To reinsert the comment on another line, move to the
end of that line, do `C-y', and then do `M-;' to realign it.  Note that
`C-u - C-x ;' is not a distinct key; it is `C-x ;'
(`set-comment-column') with a negative argument.  That command is
programmed so that when it receives a negative argument it calls
`kill-comment'.  However, `kill-comment' is a valid command which you
could bind directly to a key if you wanted to.


File: emacs,  Node: Multi-Line Comments,  Next: Options for Comments,  Prev: Comment Commands,  Up: Comments

Multiple Lines of Comments
--------------------------

If you are typing a comment and wish to continue it on another line,
you can use the command `M-<LFD>' (`indent-new-comment-line').  This
terminates the comment you are typing, creates a new blank line
afterward, and begins a new comment indented under the old one.  When
Auto Fill mode is on, going past the fill column while typing a comment
causes the comment to be continued in just this fashion.  If point is
not at the end of the line when `M-<LFD>' is typed, the text on the
rest of the line becomes part of the new comment line.

   To turn existing lines into comment lines, use the `M-x
comment-region' command.  It adds comment delimiters to the lines that
start in the region, thus commenting them out.  With a negative
argument, it does the opposite--it deletes comment delimiters from the
lines in the region.

   With a positive argument, `comment-region' duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert.  Thus, in Lisp mode, `C-u 2
M-x comment-region' adds `;;' to each line.  Duplicating the comment
delimiter is a way of calling attention to the comment.  It can also
affect how the comment is indented.  In Lisp, for proper indentation,
you should use an argument of two, if between defuns, and three, if
within a defun.


File: emacs,  Node: Options for Comments,  Prev: Multi-Line Comments,  Up: Comments

Options Controlling Comments
----------------------------

The comment column is stored in the variable `comment-column'.  You can
set it to a number explicitly.  Alternatively, the command `C-x ;'
(`set-comment-column') sets the comment column to the column point is
at.  `C-u C-x ;' sets the comment column to match the last comment
before point in the buffer, and then does a `M-;' to align the current
line's comment under the previous one.  Note that `C-u - C-x ;' runs
the function `kill-comment' as described above.

   The variable `comment-column' is per-buffer: setting the variable in
the normal fashion affects only the current buffer, but there is a
default value which you can change with `setq-default'.  *Note
Locals::.  Many major modes initialize this variable for the current
buffer.

   The comment commands recognize comments based on the regular
expression that is the value of the variable `comment-start-skip'.
Make sure this regexp does not match the null string.  It may match more
than the comment starting delimiter in the strictest sense of the word;
for example, in C mode the value of the variable is `"/\\*+ *"', which
matches extra stars and spaces after the `/*' itself.  (Note that `\\'
is needed in Lisp syntax to include a `\' in the string, which is
needed to deny the first star its special meaning in regexp syntax.
*Note Regexps::.)

   When a comment command makes a new comment, it inserts the value of
`comment-start' to begin it.  The value of `comment-end' is inserted
after point, so that it will follow the text that you will insert into
the comment.  In C mode, `comment-start' has the value `"/* "' and
`comment-end' has the value `" */"'.

   The variable `comment-multi-line' controls how `M-<LFD>'
(`indent-new-comment-line') behaves when used inside a comment.  If
`comment-multi-line' is `nil', as it normally is, then the comment on
the starting line is terminated and a new comment is started on the new
following line.  If `comment-multi-line' is not `nil', then the new
following line is set up as part of the same comment that was found on
the starting line.  This is done by not inserting a terminator on the
old line, and not inserting a starter on the new line.  In languages
where multi-line comments work, the choice of value for this variable
is a matter of taste.

   The variable `comment-indent-function' should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment.  It is set differently by
various major modes.  The function is called with no arguments, but with
point at the beginning of the comment, or at the end of a line if a new
comment is to be inserted.  It should return the column in which the
comment ought to start.  For example, in Lisp mode, the indent hook
function bases its decision on how many semicolons begin an existing
comment, and on the code in the preceding lines.


File: emacs,  Node: Balanced Editing,  Next: Symbol Completion,  Prev: Comments,  Up: Programs

Editing Without Unbalanced Parentheses
======================================

`M-('
     Put parentheses around next sexp(s) (`insert-parentheses').

`M-)'
     Move past next close parenthesis and re-indent
     (`move-over-close-and-reindent').

   The commands `M-(' (`insert-parentheses') and `M-)'
(`move-over-close-and-reindent') are designed to facilitate a style of
editing which keeps parentheses balanced at all times.  `M-(' inserts a
pair of parentheses, either together as in `()', or, if given an
argument, around the next several sexps.  It leaves point after the
open parenthesis.  The command `M-)' moves past the close parenthesis,
deleting any indentation preceding it (in this example there is none),
and indenting with <LFD> after it.

   For example, instead of typing `( F O O )', you can type `M-( F O
O', which has the same effect except for leaving the cursor before the
close parenthesis.

   `M-(' may insert a space before the open parenthesis, depending on
the syntax class of the preceding character.  Set
`parens-dont-require-spaces' to a non-`nil' value if you wish to
inhibit this.


File: emacs,  Node: Symbol Completion,  Next: Documentation,  Prev: Balanced Editing,  Up: Programs

Completion for Symbol Names
===========================

Usually completion happens in the minibuffer.  But one kind of
completion is available in all buffers: completion for symbol names.

   The character `M-<TAB>' runs a command to complete the partial
symbol before point against the set of meaningful symbol names.  Any
additional characters determined by the partial name are inserted at
point.

   If the partial name in the buffer has more than one possible
completion and they have no additional characters in common, a list of
all possible completions is displayed in another window.

   There are two ways of determining the set of legitimate symbol names
to complete against.  In most major modes, this uses a tags table
(*note Tags::); the legitimate symbol names are the tag names listed in
the tags table file.  The command which implements this is
`complete-tag'.

   In Emacs-Lisp mode, the name space for completion normally consists
of nontrivial symbols present in Emacs--those that have function
definitions, values or properties.  However, if there is an
open-parenthesis immediately before the beginning of the partial symbol,
only symbols with function definitions are considered as completions.
The command which implements this is `lisp-complete-symbol'.

   In Text mode and related modes, `M-<TAB>' completes words based on
the spell-checker's dictionary.  *Note Spelling::.


File: emacs,  Node: Documentation,  Next: Change Log,  Prev: Symbol Completion,  Up: Programs

Documentation Commands
======================

As you edit Lisp code to be run in Emacs, the commands `C-h f'
(`describe-function') and `C-h v' (`describe-variable') can be used to
print documentation of functions and variables that you want to call.
These commands use the minibuffer to read the name of a function or
variable to document, and display the documentation in a window.

   For extra convenience, these commands provide default arguments
based on the code in the neighborhood of point.  `C-h f' sets the
default to the function called in the innermost list containing point.
`C-h v' uses the symbol name around or adjacent to point as its default.

   Documentation on operating system commands, library functions and
system calls can be obtained with the `M-x manual-entry' command.  This
reads a topic as an argument, and displays the "man page" on that
topic.  `manual-entry' starts a background process that formats the
manual page, by running the `man' program.  The result goes in a buffer
named `*man TOPIC*'.  These buffers use a special major mode, Man mode,
that facilitates scrolling and examining other manual pages.  For
details, type `C-h m' while in a man page buffer.

   For a long man page, setting the faces properly can take substantial
time.  By default, Emacs uses faces in man pages if you are using X
Windows.  You can turn off use of faces in man pages by setting the
variable `Man-fontify-manpage-flag' to `nil'.

   If you insert the text of a man page into an Emacs buffer in some
other fashion, you can use the command `M-x Man-fontify-manpage' to
perform the same conversions that `M-x manual-entry' does.

   Eventually the GNU project hopes to replace most man pages with
better-organized manuals that you can browse with Info.  *Note Misc
Help::.  Since this process is only partially completed, it is still
useful to read manual pages.


File: emacs,  Node: Change Log,  Next: Tags,  Prev: Documentation,  Up: Programs

Change Logs
===========

The Emacs command `C-x 4 a' adds a new entry to the change log file for
the file you are editing (`add-change-log-entry-other-window').

   A change log file contains a chronological record of when and why you
have changed a program, consisting of a sequence of entries describing
individual changes.  Normally it is kept in a file called `ChangeLog'
in the same directory as the file you are editing, or one of its parent
directories.  A single `ChangeLog' file can record changes for all the
files in its directory and all its subdirectories.

   A change log entry starts with a header line that contains your name,
your email address (taken from the variable `user-mail-address'), and
the current date and time.  Aside from these header lines, every line
in the change log starts with a space or a tab.  The bulk of the entry
consists of "items", each of which starts with a line starting with
whitespace and a star.  Here are two entries, each with two items:

     Wed May  5 14:11:45 1993  Richard Stallman  <rms@gnu.ai.mit.edu>
     
             * man.el: Rename symbols `man-*' to `Man-*'.
             (manual-entry): Make prompt string clearer.
     
             * simple.el (blink-matching-paren-distance):
             Change default to 12,000.
     
     Tue May  4 12:42:19 1993  Richard Stallman  <rms@gnu.ai.mit.edu>
     
             * vc.el (minor-mode-map-alist): Don't use it if it's void.
             (vc-cancel-version): Doc fix.

   One entry can describe several changes; each change should have its
own item.  Normally there should be a blank line between items.  When
items are related (parts of the same change, in different places), group
them by leaving no blank line between them.  The second entry above
contains two items grouped in this way.

   `C-x 4 a' visits the change log file and creates a new entry unless
the most recent entry is for today's date and your name.  It also
creates a new item for the current file.  For many languages, it can
even guess the name of the function or other object that was changed.

   The change log file is visited in Change Log mode.  In this major
mode, each bunch of grouped items counts as one paragraph, and each
entry is considered a page.  This facilitates editing the entries.
<LFD> and auto-fill indent each new line like the previous line; this
is convenient for entering the contents of an entry.

   Version control systems are another way to keep track of changes in
your program and keep a change log.  *Note Log Entries::.


File: emacs,  Node: Tags,  Next: Emerge,  Prev: Change Log,  Up: Programs

Tags Tables
===========

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

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

   Each entry in the tags table records the name of one tag, the name
of the file that the tag is defined in (implicitly), and the position
in that file of the tag's definition.

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

* Menu:

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


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

Source File Tag Syntax
----------------------

   * In Lisp code, any function defined with `defun', any variable
     defined with `defvar' or `defconst', and in general the first
     argument of any expression that starts with `(def' in column zero,
     is a tag.

   * In Scheme code, tags include anything defined with `def' or with a
     construct whose name starts with `def'.  They also include
     variables set with `set!' at top level in the file.

   * In C code, any C function or typedef is a tag, and so are
     definitions of struct, union and enum.  Any `#define' is also a
     tag, unless `--no-defines' is specified when the tags table is
     constructed, which sometimes makes the tags file much smaller.  In
     C++ code, member functions are also recognized.

   * In Yacc or Bison input files, each rule defines as a tag the
     nonterminal it constructs.  The portions of the file that contain
     C code are parsed as C code.

   * In Fortran code, functions and subroutines are tags.

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

   * In Perl code, the tags are the procedures defined by the `sub'
     keyword.

   * In Prolog code, a tag name appears at the left margin.

   * In Erlang code, the tags are the functions, records, and macros
     defined in the file.

   * In assembler code, labels appearing at the beginning of a line,
     followed by a colon, are tags.

   * In LaTeX text, the argument of any of the commands `\chapter',
     `\section', `\subsection', `\subsubsection', `\eqno', `\label',
     `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
     `\index', is a tag.

     Other commands can make tags as well, if you specify them in the
     environment variable `TEXTAGS' before invoking `etags'.  The value
     of this environment variable should be a colon-separated list of
     commands names.  For example,

          TEXTAGS="def:newcommand:newenvironment"
          export TEXTAGS

     specifies (using Bourne shell syntax) that the commands `\def',
     `\newcommand' and `\newenvironment' also define tags.

   * You can also generate tags based on regexp matching (*note Create
     Tags Table::) for any text file.


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

Creating Tags Tables
--------------------

The `etags' program is used to create a tags table file.  It knows the
syntax of several languages, as described in *Note Tag Syntax::.  Here
is how to run `etags':

     etags INPUTFILES...

The `etags' program reads the specified files, and writes a tags table
named `TAGS' in the current working directory.  `etags' recognizes the
language used in an input file based on its file name and contents.
You can specify the language with the `--language=NAME' option,
described below.

   If the tags table data become outdated due to changes in the files
described in the table, the way to update the tags table is the same
way it was made in the first place.  It is not necessary to do this
often.

   If the tags table fails to record a tag, or records it for the wrong
file, then Emacs cannot possibly find its definition.  However, if the
position recorded in the tags table becomes a little bit wrong (due to
some editing in the file that the tag definition is in), the only
consequence is a slight delay in finding the tag.  Even if the stored
position is very wrong, Emacs will still find the tag, but it must
search the entire file for it.

   So you should update a tags table when you define new tags that you
want to have listed, or when you move tag definitions from one file to
another, or when changes become substantial.  Normally there is no need
to update the tags table after each edit, or even every day.

   One tags table can effectively include another.  Specify the included
tags file name with the `--include=FILE' option when creating the file
that is to include it.  The latter file then acts as if it contained
all the files specified in the included file, as well as the files it
directly contains.

   If you specify the source files with relative file names when you run
`etags', the tags file will contain file names relative to the
directory where the tags file was initially written.  This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
files.

   If you specify absolute file names as arguments to `etags', then the
tags file will contain absolute file names.  This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place.  Absolute file names start with
`/', or with `DEVICE:/' on MS-DOS and Windows.

   When you want to make a tags table from a great number of files, you
may have problems listing them on the command line, because some systems
have a limit on its length.  The simplest way to circumvent this limit
is to tell `etags' to read the file names from its standard input, by
typing a dash in place of the file names, like this:

     find . -name "*.[chCH]" -print | etags -

   Use the option `--language=NAME' to specify the language explicitly.
You can intermix these options with file names; each one applies to
the file names that follow it.  Specify `--language=auto' to tell
`etags' to resume guessing the language from the file names and file
contents.  Specify `--language=none' to turn off language-specific
processing entirely; then `etags' recognizes tags by regexp matching
alone.  `etags --help' prints the list of the languages `etags' knows,
and the file name rules for guessing the language.

   The `--regex' option provides a general way of recognizing tags
based on regexp matching.  You can freely intermix it with file names.
Each `--regex' option adds to the preceding ones, and applies only to
the following files.  The syntax is:

     --regex=/TAGREGEXP[/NAMEREGEXP]/

where TAGREGEXP is used to match the lines to tag.  It is always
anchored, that is, it behaves as if preceded by `^'.  If you want to
account for indentation, just match any initial number of blanks by
beginning your regular expression with `[ \t]*'.  In the regular
expressions, `\' quotes the next character, and `\t' stands for the tab
character.  Note that `etags' does not handle the other C escape
sequences for special characters.

   You should not match more characters with TAGREGEXP than that needed
to recognize what you want to tag.  If the match is such that more
characters than needed are unavoidably matched by TAGREGEXP, you may
find useful to add a NAMEREGEXP, in order to narrow the tag scope.  You
can find some examples below.

   The `-R' option deletes all the regexps defined with `--regex'
options.  It applies to the file names following it, as you can see
from the following example:

     etags --regex=/REG1/ voo.doo --regex=/REG2/ \
         bar.ber -R --lang=lisp los.er

Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
according to their contents.  `etags' also uses REG1 to recognize
additional tags in `voo.doo', and both REG1 and REG2 to recognize
additional tags in `bar.ber'.  `etags' uses the Lisp tags rules, and no
regexp matching, to recognize tags in `los.er'.

   Here are some more examples.  The regexps are quoted to protect them
from shell interpretation.

Tag the `DEFVAR' macros in the emacs source files:

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

Tag VHDL files (this example is a single long line, broken here for
formatting reasons):

     --language=none
     --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
     --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
     \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'

Tag Cobol files (every label starting in column seven):

     --language=none --regex='/.......[a-zA-Z0-9-]+\./'

Tag Postscript files (every label starting in column one):

     --language=none --regex='#/[^ \t{]+#/'

Tag TCL files (this last example shows the usage of a NAMEREGEXP):

     --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'

   For a list of the other available `etags' options, execute `etags
--help'.


File: emacs,  Node: Select Tags Table,  Next: Find Tag,  Prev: Create Tags Table,  Up: Tags

Selecting a Tags Table
----------------------

Emacs has at any time one "selected" tags table, and all the commands
for working with tags tables use the selected one.  To select a tags
table, type `M-x visit-tags-table', which reads the tags table file
name as an argument.  The name `TAGS' in the default directory is used
as the default file name.

   All this command does is store the file name in the variable
`tags-file-name'.  Emacs does not actually read in the tags table
contents until you try to use them.  Setting this variable yourself is
just as good as using `visit-tags-table'.  The variable's initial value
is `nil'; that value tells all the commands for working with tags tables
that they must ask for a tags table file name to use.

   Using `visit-tags-table' when a tags table is already loaded gives
you a choice: you can add the new tags table to the current list of
tags tables, or start a new list.  The tags commands use all the tags
tables in the current list.  If you start a new list, the new tags table
is used _instead_ of others.  If you add the new table to the current
list, it is used _as well as_ the others.  When the tags commands scan
the list of tags tables, they don't always start at the beginning of
the list; they start with the first tags table (if any) that describes
the current file, proceed from there to the end of the list, and then
scan from the beginning of the list until they have covered all the
tables in the list.

   You can specify a precise list of tags tables by setting the variable
`tags-table-list' to a list of strings, like this:

     (setq tags-table-list
           '("~/emacs" "/usr/local/lib/emacs/src"))

This tells the tags commands to look at the `TAGS' files in your
`~/emacs' directory and in the `/usr/local/lib/emacs/src' directory.
The order depends on which file you are in and which tags table
mentions that file, as explained above.

   Do not set both `tags-file-name' and `tags-table-list'.


File: emacs,  Node: Find Tag,  Next: Tags Search,  Prev: Select Tags Table,  Up: Tags

Finding a Tag
-------------

The most important thing that a tags table enables you to do is to find
the definition of a specific tag.

`M-. TAG <RET>'
     Find first definition of TAG (`find-tag').

`C-u M-.'
     Find next alternate definition of last tag specified.

`C-u - M-.'
     Go back to previous tag found.

`C-M-. PATTERN <RET>'
     Find a tag whose name matches PATTERN (`find-tag-regexp').

`C-u C-M-.'
     Find the next tag whose name matches the last pattern used.

`C-x 4 . TAG <RET>'
     Find first definition of TAG, but display it in another window
     (`find-tag-other-window').

`C-x 5 . TAG <RET>'
     Find first definition of TAG, and create a new frame to select the
     buffer (`find-tag-other-frame').

   `M-.' (`find-tag') is the command to find the definition of a
specified tag.  It searches through the tags table for that tag, as a
string, and then uses the tags table info to determine the file that the
definition is in and the approximate character position in the file of
the definition.  Then `find-tag' visits that file, moves point to the
approximate character position, and searches ever-increasing distances
away to find the tag definition.

   If an empty argument is given (just type <RET>), the sexp in the
buffer before or around point is used as the TAG argument.  *Note
Lists::, for info on sexps.

   You don't need to give `M-.' the full name of the tag; a part will
do.  This is because `M-.' finds tags in the table which contain TAG as
a substring.  However, it prefers an exact match to a substring match.
To find other tags that match the same substring, give `find-tag' a
numeric argument, as in `C-u M-.'; this does not read a tag name, but
continues searching the tags table's text for another tag containing
the same substring last used.  If you have a real <META> key, `M-0 M-.'
is an easier alternative to `C-u M-.'.

   Like most commands that can switch buffers, `find-tag' has a variant
that displays the new buffer in another window, and one that makes a
new frame for it.  The former is `C-x 4 .', which invokes the command
`find-tag-other-window'.  The latter is `C-x 5 .', which invokes
`find-tag-other-frame'.

   To move back to places you've found tags recently, use `C-u - M-.';
more generally, `M-.' with a negative numeric argument.  This command
can take you to another buffer.  `C-x 4 .' with a negative argument
finds the previous tag location in another window.

   The command `C-M-.' (`find-tag-regexp') visits the tags that match a
specified regular expression.  It is just like `M-.'  except that it
does regexp matching instead of substring matching.


File: emacs,  Node: Tags Search,  Next: List Tags,  Prev: Find Tag,  Up: Tags

Searching and Replacing with Tags Tables
----------------------------------------

The commands in this section visit and search all the files listed in
the selected tags table, one by one.  For these commands, the tags
table serves only to specify a sequence of files to search.

`M-x tags-search <RET> REGEXP <RET>'
     Search for REGEXP through the files in the selected tags table.

`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
     Perform a `query-replace-regexp' on each file in the selected tags
     table.

`M-,'
     Restart one of the commands above, from the current location of
     point (`tags-loop-continue').

   `M-x tags-search' reads a regexp using the minibuffer, then searches
for matches in all the files in the selected tags table, one file at a
time.  It displays the name of the file being searched so you can
follow its progress.  As soon as it finds an occurrence, `tags-search'
returns.

   Having found one match, you probably want to find all the rest.  To
find one more match, type `M-,' (`tags-loop-continue') to resume the
`tags-search'.  This searches the rest of the current buffer, followed
by the remaining files of the tags table.

   `M-x tags-query-replace' performs a single `query-replace-regexp'
through all the files in the tags table.  It reads a regexp to search
for and a string to replace with, just like ordinary `M-x
query-replace-regexp'.  It searches much like `M-x tags-search', but
repeatedly, processing matches according to your input.  *Note
Replace::, for more information on query replace.

   It is possible to get through all the files in the tags table with a
single invocation of `M-x tags-query-replace'.  But often it is useful
to exit temporarily, which you can do with any input event that has no
special query replace meaning.  You can resume the query replace
subsequently by typing `M-,'; this command resumes the last tags search
or replace command that you did.

   The commands in this section carry out much broader searches than the
`find-tag' family.  The `find-tag' commands search only for definitions
of tags that match your substring or regexp.  The commands
`tags-search' and `tags-query-replace' find every occurrence of the
regexp, as ordinary search commands and replace commands do in the
current buffer.

   These commands create buffers only temporarily for the files that
they have to search (those which are not already visited in Emacs
buffers).  Buffers in which no match is found are quickly killed; the
others continue to exist.

   It may have struck you that `tags-search' is a lot like `grep'.  You
can also run `grep' itself as an inferior of Emacs and have Emacs show
you the matching lines one by one.  This works much like running a
compilation; finding the source locations of the `grep' matches works
like finding the compilation errors.  *Note Compilation::.


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

Tags Table Inquiries
--------------------

`M-x list-tags <RET> FILE <RET>'
     Display a list of the tags defined in the program file `file'.

`M-x tags-apropos <RET> REGEXP <RET>'
     Display a list of all tags matching REGEXP.

   `M-x list-tags' reads the name of one of the files described by the
selected tags table, and displays a list of all the tags defined in
that file.  The "file name" argument is really just a string to compare
against the file names recorded in the tags table; it is read as a
string rather than as a file name.  Therefore, completion and
defaulting are not available, and you must enter the file name the same
way it appears in the tags table.  Do not include a directory as part of
the file name unless the file name recorded in the tags table includes a
directory.

   `M-x tags-apropos' is like `apropos' for tags (*note Apropos::).  It
reads a regexp, then finds all the tags in the selected tags table
whose entries match that regexp, and displays the tag names found.

   You can also perform completion in the buffer on the name space of
tag names in the current tags tables.  *Note Symbol Completion::.


File: emacs,  Node: Emerge,  Next: C Mode,  Prev: Tags,  Up: Programs

Merging Files with Emerge
=========================

It's not unusual for programmers to get their signals crossed and modify
the same program in two different directions.  To recover from this
confusion, you need to merge the two versions.  Emerge makes this
easier.  See also *Note Comparing Files::.

* Menu:

* Overview of Emerge::	    How to start Emerge.  Basic concepts.
* Submodes of Emerge::      Fast mode vs. Edit mode.
			      Skip Prefers mode and Auto Advance mode.
* State of Difference::	    You do the merge by specifying state A or B
			      for each difference.
* Merge Commands::	    Commands for selecting a difference,
			      changing states of differences, etc.
* Exiting Emerge::	    What to do when you've finished the merge.
* Combining in Emerge::	    How to keep both alternatives for a difference.
* Fine Points of Emerge::   Misc.


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

Overview of Emerge
------------------

To start Emerge, run one of these four commands:

`M-x emerge-files'
     Merge two specified files.

`M-x emerge-files-with-ancestor'
     Merge two specified files, with reference to a common ancestor.

`M-x emerge-buffers'
     Merge two buffers.

`M-x emerge-buffers-with-ancestor'
     Merge two buffers with reference to a common ancestor in a third
     buffer.

   The Emerge commands compare two files or buffers, and display the
comparison in three buffers: one for each input text (the "A buffer"
and the "B buffer"), and one (the "merge buffer") where merging takes
place.  The merge buffer shows the full merged text, not just the
differences.  Wherever the two input texts differ, you can choose which
one of them to include in the merge buffer.

   The Emerge commands that take input from existing buffers use only
the accessible portions of those buffers, if they are narrowed (*note
Narrowing::).

   If a common ancestor version is available, from which the two texts
to be merged were both derived, Emerge can use it to guess which
alternative is right.  Wherever one current version agrees with the
ancestor, Emerge presumes that the other current version is a deliberate
change which should be kept in the merged version.  Use the
`with-ancestor' commands if you want to specify a common ancestor text.
These commands read three file or buffer names--variant A, variant B,
and the common ancestor.

   After the comparison is done and the buffers are prepared, the
interactive merging starts.  You control the merging by typing special
"merge commands" in the merge buffer.  The merge buffer shows you a
full merged text, not just differences.  For each run of differences
between the input texts, you can choose which one of them to keep, or
edit them both together.

   The merge buffer uses a special major mode, Emerge mode, with
commands for making these choices.  But you can also edit the buffer
with ordinary Emacs commands.

   At any given time, the attention of Emerge is focused on one
particular difference, called the "selected" difference.  This
difference is marked off in the three buffers like this:

     vvvvvvvvvvvvvvvvvvvv
     TEXT THAT DIFFERS
     ^^^^^^^^^^^^^^^^^^^^

Emerge numbers all the differences sequentially and the mode line
always shows the number of the selected difference.

   Normally, the merge buffer starts out with the A version of the text.
But when the A version of a difference agrees with the common ancestor,
then the B version is initially preferred for that difference.

   Emerge leaves the merged text in the merge buffer when you exit.  At
that point, you can save it in a file with `C-x C-w'.  If you give a
numeric argument to `emerge-files' or `emerge-files-with-ancestor', it
reads the name of the output file using the minibuffer.  (This is the
last file name those commands read.)  Then exiting from Emerge saves
the merged text in the output file.

   Normally, Emerge commands save the output buffer in its file when you
exit.  If you abort Emerge with `C-]', the Emerge command does not save
the output buffer, but you can save it yourself if you wish.


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

Submodes of Emerge
------------------

You can choose between two modes for giving merge commands: Fast mode
and Edit mode.  In Fast mode, basic merge commands are single
characters, but ordinary Emacs commands are disabled.  This is
convenient if you use only merge commands.  In Edit mode, all merge
commands start with the prefix key `C-c C-c', and the normal Emacs
commands are also available.  This allows editing the merge buffer, but
slows down Emerge operations.

   Use `e' to switch to Edit mode, and `C-c C-c f' to switch to Fast
mode.  The mode line indicates Edit and Fast modes with `E' and `F'.

   Emerge has two additional submodes that affect how particular merge
commands work: Auto Advance mode and Skip Prefers mode.

   If Auto Advance mode is in effect, the `a' and `b' commands advance
to the next difference.  This lets you go through the merge faster as
long as you simply choose one of the alternatives from the input.  The
mode line indicates Auto Advance mode with `A'.

   If Skip Prefers mode is in effect, the `n' and `p' commands skip
over differences in states prefer-A and prefer-B (*note State of
Difference::).  Thus you see only differences for which neither version
is presumed "correct".  The mode line indicates Skip Prefers mode with
`S'.

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


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

State of a Difference
---------------------

In the merge buffer, a difference is marked with lines of `v' and `^'
characters.  Each difference has one of these seven states:

A
     The difference is showing the A version.  The `a' command always
     produces this state; the mode line indicates it with `A'.

B
     The difference is showing the B version.  The `b' command always
     produces this state; the mode line indicates it with `B'.

default-A
default-B
     The difference is showing the A or the B state by default, because
     you haven't made a choice.  All differences start in the default-A
     state (and thus the merge buffer is a copy of the A buffer),
     except those for which one alternative is "preferred" (see below).

     When you select a difference, its state changes from default-A or
     default-B to plain A or B.  Thus, the selected difference never has
     state default-A or default-B, and these states are never displayed
     in the mode line.

     The command `d a' chooses default-A as the default state, and `d
     b' chooses default-B.  This chosen default applies to all
     differences which you haven't ever selected and for which no
     alternative is preferred.  If you are moving through the merge
     sequentially, the differences you haven't selected are those
     following the selected one.  Thus, while moving sequentially, you
     can effectively make the A version the default for some sections
     of the merge buffer and the B version the default for others by
     using `d a' and `d b' between sections.

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

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

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

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

     The mode line displays this state as `comb'.


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

Merge Commands
--------------

Here are the Merge commands for Fast mode; in Edit mode, precede them
with `C-c C-c':

`p'
     Select the previous difference.

`n'
     Select the next difference.

`a'
     Choose the A version of this difference.

`b'
     Choose the B version of this difference.

`C-u N j'
     Select difference number N.

`.'
     Select the difference containing point.  You can use this command
     in the merge buffer or in the A or B buffer.

`q'
     Quit--finish the merge.

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

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

`e'
     Go into Edit mode.

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

`-'
     Specify part of a prefix numeric argument.

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

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

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

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

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

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

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

`m'
     Put point and mark around the difference.

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

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

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

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

`|'
     Reset horizontal scroll on all three windows.

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

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

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

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

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

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


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

Exiting Emerge
--------------

The `q' command (`emerge-quit') finishes the merge, storing the results
into the output file if you specified one.  It restores the A and B
buffers to their proper contents, or kills them if they were created by
Emerge and you haven't changed them.  It also disables the Emerge
commands in the merge buffer, since executing them later could damage
the contents of the various buffers.

   `C-]' aborts the merge.  This means exiting without writing the
output file.  If you didn't specify an output file, then there is no
real difference between aborting and finishing the merge.

   If the Emerge command was called from another Lisp program, then its
return value is `t' for successful completion, or `nil' if you abort.


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

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

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

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

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

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


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

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

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

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

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

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


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

C Mode
======

This section describes special features available in C, C++,
Objective-C and Java modes.

* Menu:

* Motion in C::
* Electric C::
* Hungry Delete::
* Other C Commands::
* Comments in C::


File: emacs,  Node: Motion in C,  Next: Electric C,  Up: C Mode

C Mode Motion Commands
----------------------

This section commands for moving point, in C mode and related modes.

`C-c C-u'
     Move point back to the containing preprocessor conditional,
     leaving the mark behind.  A prefix argument acts as a repeat
     count.  With a negative argument, move point forward to the end of
     the containing preprocessor conditional.  When going backwards,
     `#elif' is treated like `#else' followed by `#if'.  When going
     forwards, `#elif' is ignored.

`C-c C-p'
     Move point back over a preprocessor conditional, leaving the mark
     behind.  A prefix argument acts as a repeat count.  With a negative
     argument, move forward.

`C-c C-n'
     Move point forward across a preprocessor conditional, leaving the
     mark behind.  A prefix argument acts as a repeat count.  With a
     negative argument, move backward.

`M-a'
     Move point to the beginning of the innermost C statement.  If
     point is already at the beginning of a statement, move to the
     beginning of the preceding statement.  With prefix argument N,
     move back N - 1 statements.

     If point is within a string or comment, or next to a comment (only
     whitespace between them), this command moves by sentences instead
     of statements.

     When called from a program, this function takes two optional
     arguments: the numeric prefix argument, and a buffer position
     limit (don't move back before that place).

`M-e'
     Move point to the end of the innermost C statement.  If point is
     at the end of a statement, move to the end of the next statement.
     With prefix argument N, move forward N - 1 statements.

     If point is within a string or comment, or next to a comment (only
     whitespace between them), this command moves by sentences instead
     of statements.

     When called from a program, this function takes two optional
     arguments: the numeric prefix argument, and a buffer position
     limit (don't move past that place).

`M-x c-backward-into-nomenclature'
     Move point backward to beginning of a C++ nomenclature section or
     word.  With prefix argument N, move N times.  If N is negative,
     move forward.  C++ nomenclature means a symbol name in the style
     of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
     begins a section or word.

     In the GNU project, we recommend using underscores to separate
     words within an identifier in C or C++, rather than using case
     distinctions.

`M-x c-forward-into-nomenclature'
     Move point forward to end of a C++ nomenclature section or word.
     With prefix argument N, move N times.


File: emacs,  Node: Electric C,  Next: Hungry Delete,  Prev: Motion in C,  Up: C Mode

Electric C Characters
---------------------

In C mode and related modes, certain printing characters are
"electric"--in addition to inserting themselves, they also reindent the
current line and may insert newlines.  This feature is controlled by
the variable `c-auto-newline'.  The "electric" characters are `{', `}',
`:', `#', `;', `,', `<', `>', `/' and `*'.

   Electric characters insert newlines only when the "auto-newline"
feature is enabled (indicated by `/a' in the mode line after the mode
name).  This feature is controlled by the variable `c-auto-newline'.
You can turn this feature on or off with the command `C-c C-a':

`C-c C-a'
     Toggle the auto-newline feature (`c-toggle-auto-state').  With a
     prefix argument, this command turns the auto-newline feature on if
     the argument is positive, and off if it is negative.

   The colon character is electric because that is appropriate for a
single colon.  But when you want to insert a double colon in C++, the
electric behavior of colon is inconvenient.  You can insert a double
colon with no reindentation or newlines by typing `C-c :':

`C-c :'
     Insert a double colon scope operator at point, without reindenting
     the line or adding any newlines (`c-scope-operator').

   The electric `#' key reindents the line if it appears to be the
beginning of a preprocessor directive.  This happens when the value of
`c-electric-pound-behavior' is `(alignleft)'.  You can turn this
feature off by setting `c-electric-pound-behavior' to `nil'.

   The variable `c-hanging-braces-alist' controls the insertion of
newlines before and after inserted braces.  It is an association list
with elements of the following form: `(SYNTACTIC-SYMBOL . NL-LIST)'.
Most of the syntactic symbols that appear in `c-offsets-alist' are
meaningful here as well.

   The list NL-LIST may contain either of the symbols `before' or
`after', or both; or it may be `nil'.  When a brace is inserted, the
syntactic context it defines is looked up in `c-hanging-braces-alist';
if it is found, the NL-LIST is used to determine where newlines are
inserted: either before the brace, after, or both.  If not found, the
default is to insert a newline both before and after braces.

   The variable `c-hanging-colons-alist' controls the insertion of
newlines before and after inserted colons.  It is an association list
with elements of the following form: `(SYNTACTIC-SYMBOL . NL-LIST)'.
The list NL-LIST may contain either of the symbols `before' or `after',
or both; or it may be `nil'.

   When a colon is inserted, the syntactic symbol it defines is looked
up in this list, and if found, the NL-LIST is used to determine where
newlines are inserted: either before the brace, after, or both.  If the
syntactic symbol is not found in this list, no newlines are inserted.

   Electric characters can also delete newlines automatically when the
auto-newline feature is enabled.  This feature makes auto-newline more
acceptable, by deleting the newlines in the most common cases where you
do not want them.  Emacs can recognize several cases in which deleting a
newline might be desirable; by setting the variable `c-cleanup-list',
you can specify _which_ of these cases that should happen.  The
variable's value is a list of symbols, each describing one case for
possible deletion of a newline.  Here are the meaningful symbols, and
their meanings:

`brace-else-brace'
     Clean up `} else {' constructs by placing entire construct on a
     single line.  The clean-up occurs when you type the `{' after the
     `else', but only if there is nothing but white space between the
     braces and the `else'.

`empty-defun-braces'
     Clean up empty defun braces by placing the braces on the same
     line.  Clean-up occurs when you type the closing brace.

`defun-close-semi'
     Clean up the semicolon after a `struct' or similar type
     declaration, by placing the semicolon on the same line as the
     closing brace.  Clean-up occurs when you type the semicolon.

`list-close-comma'
     Clean up commas following braces in array and aggregate
     initializers.  Clean-up occurs when you type the comma.

`scope-operator'
     Clean up double colons which may designate a C++ scope operator, by
     placing the colons together.  Clean-up occurs when you type the
     second colon, but only when the two colons are separated by
     nothing but whitespace.


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

Hungry Delete Feature in C
--------------------------

When the "hungry-delete" feature is enabled (indicated by `/h' or `/ah'
in the mode line after the mode name), a single <DEL> command deletes
all preceding whitespace, not just one space.  To turn this feature on
or off, use `C-c C-d':

`C-c C-d'
     Toggle the hungry-delete feature (`c-toggle-hungry-state').  With a
     prefix argument, this command turns the hungry-delete feature on
     if the argument is positive, and off if it is negative.

`C-c C-t'
     Toggle the auto-newline and hungry-delete features, both at once
     (`c-toggle-auto-hungry-state').

   The variable `c-hungry-delete-key' controls whether the
hungry-delete feature is enabled.


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

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

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.

