emacs/info/emacs-3

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

This is the `GNU Emacs Manual', updated for Emacs version 24.2.

Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "The GNU Manifesto,"
     "Distribution" and "GNU GENERAL PUBLIC LICENSE," with the
     Front-Cover texts being "A GNU Manual," and with the Back-Cover
     Texts as in (a) below.  A copy of the license is included in the
     section entitled "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

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


File: emacs,  Node: Coding Systems,  Next: Recognize Coding,  Prev: Select Input Method,  Up: International

22.6 Coding Systems
===================

Users of various languages have established many more-or-less standard
coding systems for representing them.  Emacs does not use these coding
systems internally; instead, it converts from various coding systems to
its own system when reading data, and converts the internal coding
system to other coding systems when writing data.  Conversion is
possible in reading or writing files, in sending or receiving from the
terminal, and in exchanging data with subprocesses.

   Emacs assigns a name to each coding system.  Most coding systems are
used for one language, and the name of the coding system starts with
the language name.  Some coding systems are used for several languages;
their names usually start with `iso'.  There are also special coding
systems, such as `no-conversion', `raw-text', and `emacs-internal'.

   A special class of coding systems, collectively known as
"codepages", is designed to support text encoded by MS-Windows and
MS-DOS software.  The names of these coding systems are `cpNNNN', where
NNNN is a 3- or 4-digit number of the codepage.  You can use these
encodings just like any other coding system; for example, to visit a
file encoded in codepage 850, type `C-x <RET> c cp850 <RET> C-x C-f
FILENAME <RET>'.

   In addition to converting various representations of non-ASCII
characters, a coding system can perform end-of-line conversion.  Emacs
handles three different conventions for how to separate lines in a file:
newline ("unix"), carriage-return linefeed ("dos"), and just
carriage-return ("mac").

`C-h C CODING <RET>'
     Describe coding system CODING (`describe-coding-system').

`C-h C <RET>'
     Describe the coding systems currently in use.

`M-x list-coding-systems'
     Display a list of all the supported coding systems.

   The command `C-h C' (`describe-coding-system') displays information
about particular coding systems, including the end-of-line conversion
specified by those coding systems.  You can specify a coding system
name as the argument; alternatively, with an empty argument, it
describes the coding systems currently selected for various purposes,
both in the current buffer and as the defaults, and the priority list
for recognizing coding systems (*note Recognize Coding::).

   To display a list of all the supported coding systems, type `M-x
list-coding-systems'.  The list gives information about each coding
system, including the letter that stands for it in the mode line (*note
Mode Line::).

   Each of the coding systems that appear in this list--except for
`no-conversion', which means no conversion of any kind--specifies how
and whether to convert printing characters, but leaves the choice of
end-of-line conversion to be decided based on the contents of each file.
For example, if the file appears to use the sequence carriage-return
linefeed to separate lines, DOS end-of-line conversion will be used.

   Each of the listed coding systems has three variants, which specify
exactly what to do for end-of-line conversion:

`...-unix'
     Don't do any end-of-line conversion; assume the file uses newline
     to separate lines.  (This is the convention normally used on Unix
     and GNU systems, and Mac OS X.)

`...-dos'
     Assume the file uses carriage-return linefeed to separate lines,
     and do the appropriate conversion.  (This is the convention
     normally used on Microsoft systems.(1))

`...-mac'
     Assume the file uses carriage-return to separate lines, and do the
     appropriate conversion.  (This was the convention used on the
     Macintosh system prior to OS X.)

   These variant coding systems are omitted from the
`list-coding-systems' display for brevity, since they are entirely
predictable.  For example, the coding system `iso-latin-1' has variants
`iso-latin-1-unix', `iso-latin-1-dos' and `iso-latin-1-mac'.

   The coding systems `unix', `dos', and `mac' are aliases for
`undecided-unix', `undecided-dos', and `undecided-mac', respectively.
These coding systems specify only the end-of-line conversion, and leave
the character code conversion to be deduced from the text itself.

   The coding system `raw-text' is good for a file which is mainly
ASCII text, but may contain byte values above 127 that are not meant to
encode non-ASCII characters.  With `raw-text', Emacs copies those byte
values unchanged, and sets `enable-multibyte-characters' to `nil' in
the current buffer so that they will be interpreted properly.
`raw-text' handles end-of-line conversion in the usual way, based on
the data encountered, and has the usual three variants to specify the
kind of end-of-line conversion to use.

   In contrast, the coding system `no-conversion' specifies no
character code conversion at all--none for non-ASCII byte values and
none for end of line.  This is useful for reading or writing binary
files, tar files, and other files that must be examined verbatim.  It,
too, sets `enable-multibyte-characters' to `nil'.

   The easiest way to edit a file with no conversion of any kind is with
the `M-x find-file-literally' command.  This uses `no-conversion', and
also suppresses other Emacs features that might convert the file
contents before you see them.  *Note Visiting::.

   The coding system `emacs-internal' (or `utf-8-emacs', which is
equivalent) means that the file contains non-ASCII characters stored
with the internal Emacs encoding.  This coding system handles
end-of-line conversion based on the data encountered, and has the usual
three variants to specify the kind of end-of-line conversion.

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

   (1) It is also specified for MIME `text/*' bodies and in other
network transport contexts.  It is different from the SGML reference
syntax record-start/record-end format, which Emacs doesn't support
directly.


File: emacs,  Node: Recognize Coding,  Next: Specify Coding,  Prev: Coding Systems,  Up: International

22.7 Recognizing Coding Systems
===============================

Whenever Emacs reads a given piece of text, it tries to recognize which
coding system to use.  This applies to files being read, output from
subprocesses, text from X selections, etc.  Emacs can select the right
coding system automatically most of the time--once you have specified
your preferences.

   Some coding systems can be recognized or distinguished by which byte
sequences appear in the data.  However, there are coding systems that
cannot be distinguished, not even potentially.  For example, there is no
way to distinguish between Latin-1 and Latin-2; they use the same byte
values with different meanings.

   Emacs handles this situation by means of a priority list of coding
systems.  Whenever Emacs reads a file, if you do not specify the coding
system to use, Emacs checks the data against each coding system,
starting with the first in priority and working down the list, until it
finds a coding system that fits the data.  Then it converts the file
contents assuming that they are represented in this coding system.

   The priority list of coding systems depends on the selected language
environment (*note Language Environments::).  For example, if you use
French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
Czech, you probably want Latin-2 to be preferred.  This is one of the
reasons to specify a language environment.

   However, you can alter the coding system priority list in detail
with the command `M-x prefer-coding-system'.  This command reads the
name of a coding system from the minibuffer, and adds it to the front
of the priority list, so that it is preferred to all others.  If you
use this command several times, each use adds one element to the front
of the priority list.

   If you use a coding system that specifies the end-of-line conversion
type, such as `iso-8859-1-dos', what this means is that Emacs should
attempt to recognize `iso-8859-1' with priority, and should use DOS
end-of-line conversion when it does recognize `iso-8859-1'.

   Sometimes a file name indicates which coding system to use for the
file.  The variable `file-coding-system-alist' specifies this
correspondence.  There is a special function
`modify-coding-system-alist' for adding elements to this list.  For
example, to read and write all `.txt' files using the coding system
`chinese-iso-8bit', you can execute this Lisp expression:

     (modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)

The first argument should be `file', the second argument should be a
regular expression that determines which files this applies to, and the
third argument says which coding system to use for these files.

   Emacs recognizes which kind of end-of-line conversion to use based on
the contents of the file: if it sees only carriage-returns, or only
carriage-return linefeed sequences, then it chooses the end-of-line
conversion accordingly.  You can inhibit the automatic use of
end-of-line conversion by setting the variable `inhibit-eol-conversion'
to non-`nil'.  If you do that, DOS-style files will be displayed with
the `^M' characters visible in the buffer; some people prefer this to
the more subtle `(DOS)' end-of-line type indication near the left edge
of the mode line (*note eol-mnemonic: Mode Line.).

   By default, the automatic detection of coding system is sensitive to
escape sequences.  If Emacs sees a sequence of characters that begin
with an escape character, and the sequence is valid as an ISO-2022
code, that tells Emacs to use one of the ISO-2022 encodings to decode
the file.

   However, there may be cases that you want to read escape sequences
in a file as is.  In such a case, you can set the variable
`inhibit-iso-escape-detection' to non-`nil'.  Then the code detection
ignores any escape sequences, and never uses an ISO-2022 encoding.  The
result is that all escape sequences become visible in the buffer.

   The default value of `inhibit-iso-escape-detection' is `nil'.  We
recommend that you not change it permanently, only for one specific
operation.  That's because some Emacs Lisp source files in the Emacs
distribution contain non-ASCII characters encoded in the coding system
`iso-2022-7bit', and they won't be decoded correctly when you visit
those files if you suppress the escape sequence detection.

   The variables `auto-coding-alist' and `auto-coding-regexp-alist' are
the strongest way to specify the coding system for certain patterns of
file names, or for files containing certain patterns, respectively.
These variables even override `-*-coding:-*-' tags in the file itself
(*note Specify Coding::).  For example, Emacs uses `auto-coding-alist'
for tar and archive files, to prevent it from being confused by a
`-*-coding:-*-' tag in a member of the archive and thinking it applies
to the archive file as a whole.

   Another way to specify a coding system is with the variable
`auto-coding-functions'.  For example, one of the builtin
`auto-coding-functions' detects the encoding for XML files.  Unlike the
previous two, this variable does not override any `-*-coding:-*-' tag.

   When you get new mail in Rmail, each message is translated
automatically from the coding system it is written in, as if it were a
separate file.  This uses the priority list of coding systems that you
have specified.  If a MIME message specifies a character set, Rmail
obeys that specification.  For reading and saving Rmail files
themselves, Emacs uses the coding system specified by the variable
`rmail-file-coding-system'.  The default value is `nil', which means
that Rmail files are not translated (they are read and written in the
Emacs internal character code).


File: emacs,  Node: Specify Coding,  Next: Output Coding,  Prev: Recognize Coding,  Up: International

22.8 Specifying a File's Coding System
======================================

If Emacs recognizes the encoding of a file incorrectly, you can reread
the file using the correct coding system with `C-x <RET> r'
(`revert-buffer-with-coding-system').  This command prompts for the
coding system to use.  To see what coding system Emacs actually used to
decode the file, look at the coding system mnemonic letter near the
left edge of the mode line (*note Mode Line::), or type `C-h C'
(`describe-coding-system').

   You can specify the coding system for a particular file in the file
itself, using the `-*-...-*-' construct at the beginning, or a local
variables list at the end (*note File Variables::).  You do this by
defining a value for the "variable" named `coding'.  Emacs does not
really have a variable `coding'; instead of setting a variable, this
uses the specified coding system for the file.  For example, `-*-mode:
C; coding: latin-1;-*-' specifies use of the Latin-1 coding system, as
well as C mode.  When you specify the coding explicitly in the file,
that overrides `file-coding-system-alist'.


File: emacs,  Node: Output Coding,  Next: Text Coding,  Prev: Specify Coding,  Up: International

22.9 Choosing Coding Systems for Output
=======================================

Once Emacs has chosen a coding system for a buffer, it stores that
coding system in `buffer-file-coding-system'.  That makes it the
default for operations that write from this buffer into a file, such as
`save-buffer' and `write-region'.  You can specify a different coding
system for further file output from the buffer using
`set-buffer-file-coding-system' (*note Text Coding::).

   You can insert any character Emacs supports into any Emacs buffer,
but most coding systems can only handle a subset of these characters.
Therefore, it's possible that the characters you insert cannot be
encoded with the coding system that will be used to save the buffer.
For example, you could visit a text file in Polish, encoded in
`iso-8859-2', and add some Russian words to it.  When you save that
buffer, Emacs cannot use the current value of
`buffer-file-coding-system', because the characters you added cannot be
encoded by that coding system.

   When that happens, Emacs tries the most-preferred coding system (set
by `M-x prefer-coding-system' or `M-x set-language-environment').  If
that coding system can safely encode all of the characters in the
buffer, Emacs uses it, and stores its value in
`buffer-file-coding-system'.  Otherwise, Emacs displays a list of
coding systems suitable for encoding the buffer's contents, and asks
you to choose one of those coding systems.

   If you insert the unsuitable characters in a mail message, Emacs
behaves a bit differently.  It additionally checks whether the
most-preferred coding system is recommended for use in MIME messages;
if not, it informs you of this fact and prompts you for another coding
system.  This is so you won't inadvertently send a message encoded in a
way that your recipient's mail software will have difficulty decoding.
(You can still use an unsuitable coding system if you enter its name at
the prompt.)

   When you send a mail message (*note Sending Mail::), Emacs has four
different ways to determine the coding system to use for encoding the
message text.  It tries the buffer's own value of
`buffer-file-coding-system', if that is non-`nil'.  Otherwise, it uses
the value of `sendmail-coding-system', if that is non-`nil'.  The third
way is to use the default coding system for new files, which is
controlled by your choice of language environment, if that is
non-`nil'.  If all of these three values are `nil', Emacs encodes
outgoing mail using the Latin-1 coding system.


File: emacs,  Node: Text Coding,  Next: Communication Coding,  Prev: Output Coding,  Up: International

22.10 Specifying a Coding System for File Text
==============================================

In cases where Emacs does not automatically choose the right coding
system for a file's contents, you can use these commands to specify one:

`C-x <RET> f CODING <RET>'
     Use coding system CODING to save or revisit the file in the
     current buffer (`set-buffer-file-coding-system').

`C-x <RET> c CODING <RET>'
     Specify coding system CODING for the immediately following command
     (`universal-coding-system-argument').

`C-x <RET> r CODING <RET>'
     Revisit the current file using the coding system CODING
     (`revert-buffer-with-coding-system').

`M-x recode-region <RET> RIGHT <RET> WRONG <RET>'
     Convert a region that was decoded using coding system WRONG,
     decoding it using coding system RIGHT instead.

   The command `C-x <RET> f' (`set-buffer-file-coding-system') sets the
file coding system for the current buffer--in other words, it says
which coding system to use when saving or reverting the visited file.
You specify which coding system using the minibuffer.  If you specify a
coding system that cannot handle all of the characters in the buffer,
Emacs warns you about the troublesome characters when you actually save
the buffer.

   You can also use this command to specify the end-of-line conversion
(*note end-of-line conversion: Coding Systems.) for encoding the
current buffer.  For example, `C-x <RET> f dos <RET>' will cause Emacs
to save the current buffer's text with DOS-style carriage-return
linefeed line endings.

   Another way to specify the coding system for a file is when you visit
the file.  First use the command `C-x <RET> c'
(`universal-coding-system-argument'); this command uses the minibuffer
to read a coding system name.  After you exit the minibuffer, the
specified coding system is used for _the immediately following command_.

   So if the immediately following command is `C-x C-f', for example,
it reads the file using that coding system (and records the coding
system for when you later save the file).  Or if the immediately
following command is `C-x C-w', it writes the file using that coding
system.  When you specify the coding system for saving in this way,
instead of with `C-x <RET> f', there is no warning if the buffer
contains characters that the coding system cannot handle.

   Other file commands affected by a specified coding system include
`C-x i' and `C-x C-v', as well as the other-window variants of `C-x
C-f'.  `C-x <RET> c' also affects commands that start subprocesses,
including `M-x shell' (*note Shell::).  If the immediately following
command does not use the coding system, then `C-x <RET> c' ultimately
has no effect.

   An easy way to visit a file with no conversion is with the `M-x
find-file-literally' command.  *Note Visiting::.

   The default value of the variable `buffer-file-coding-system'
specifies the choice of coding system to use when you create a new file.
It applies when you find a new file, and when you create a buffer and
then save it in a file.  Selecting a language environment typically sets
this variable to a good choice of default coding system for that
language environment.

   If you visit a file with a wrong coding system, you can correct this
with `C-x <RET> r' (`revert-buffer-with-coding-system').  This visits
the current file again, using a coding system you specify.

   If a piece of text has already been inserted into a buffer using the
wrong coding system, you can redo the decoding of it using `M-x
recode-region'.  This prompts you for the proper coding system, then
for the wrong coding system that was actually used, and does the
conversion.  It first encodes the region using the wrong coding system,
then decodes it again using the proper coding system.


File: emacs,  Node: Communication Coding,  Next: File Name Coding,  Prev: Text Coding,  Up: International

22.11 Coding Systems for Interprocess Communication
===================================================

This section explains how to specify coding systems for use in
communication with other processes.

`C-x <RET> x CODING <RET>'
     Use coding system CODING for transferring selections to and from
     other graphical applications (`set-selection-coding-system').

`C-x <RET> X CODING <RET>'
     Use coding system CODING for transferring _one_ selection--the
     next one--to or from another graphical application
     (`set-next-selection-coding-system').

`C-x <RET> p INPUT-CODING <RET> OUTPUT-CODING <RET>'
     Use coding systems INPUT-CODING and OUTPUT-CODING for subprocess
     input and output in the current buffer
     (`set-buffer-process-coding-system').

   The command `C-x <RET> x' (`set-selection-coding-system') specifies
the coding system for sending selected text to other windowing
applications, and for receiving the text of selections made in other
applications.  This command applies to all subsequent selections, until
you override it by using the command again.  The command `C-x <RET> X'
(`set-next-selection-coding-system') specifies the coding system for
the next selection made in Emacs or read by Emacs.

   The variable `x-select-request-type' specifies the data type to
request from the X Window System for receiving text selections from
other applications.  If the value is `nil' (the default), Emacs tries
`UTF8_STRING' and `COMPOUND_TEXT', in this order, and uses various
heuristics to choose the more appropriate of the two results; if none
of these succeed, Emacs falls back on `STRING'.  If the value of
`x-select-request-type' is one of the symbols `COMPOUND_TEXT',
`UTF8_STRING', `STRING', or `TEXT', Emacs uses only that request type.
If the value is a list of some of these symbols, Emacs tries only the
request types in the list, in order, until one of them succeeds, or
until the list is exhausted.

   The command `C-x <RET> p' (`set-buffer-process-coding-system')
specifies the coding system for input and output to a subprocess.  This
command applies to the current buffer; normally, each subprocess has its
own buffer, and thus you can use this command to specify translation to
and from a particular subprocess by giving the command in the
corresponding buffer.

   You can also use `C-x <RET> c' (`universal-coding-system-argument')
just before the command that runs or starts a subprocess, to specify
the coding system for communicating with that subprocess.  *Note Text
Coding::.

   The default for translation of process input and output depends on
the current language environment.

   The variable `locale-coding-system' specifies a coding system to use
when encoding and decoding system strings such as system error messages
and `format-time-string' formats and time stamps.  That coding system
is also used for decoding non-ASCII keyboard input on the X Window
System.  You should choose a coding system that is compatible with the
underlying system's text representation, which is normally specified by
one of the environment variables `LC_ALL', `LC_CTYPE', and `LANG'.
(The first one, in the order specified above, whose value is nonempty
is the one that determines the text representation.)


File: emacs,  Node: File Name Coding,  Next: Terminal Coding,  Prev: Communication Coding,  Up: International

22.12 Coding Systems for File Names
===================================

`C-x <RET> F CODING <RET>'
     Use coding system CODING for encoding and decoding file names
     (`set-file-name-coding-system').

   The command `C-x <RET> F' (`set-file-name-coding-system') specifies
a coding system to use for encoding file _names_.  It has no effect on
reading and writing the _contents_ of files.

   In fact, all this command does is set the value of the variable
`file-name-coding-system'.  If you set the variable to a coding system
name (as a Lisp symbol or a string), Emacs encodes file names using
that coding system for all file operations.  This makes it possible to
use non-ASCII characters in file names--or, at least, those non-ASCII
characters that the specified coding system can encode.

   If `file-name-coding-system' is `nil', Emacs uses a default coding
system determined by the selected language environment, and stored in
the `default-file-name-coding-system' variable.  In the default
language environment, non-ASCII characters in file names are not
encoded specially; they appear in the file system using the internal
Emacs representation.

   *Warning:* if you change `file-name-coding-system' (or the language
environment) in the middle of an Emacs session, problems can result if
you have already visited files whose names were encoded using the
earlier coding system and cannot be encoded (or are encoded
differently) under the new coding system.  If you try to save one of
these buffers under the visited file name, saving may use the wrong file
name, or it may encounter an error.  If such a problem happens, use `C-x
C-w' to specify a new file name for that buffer.

   If a mistake occurs when encoding a file name, use the command `M-x
recode-file-name' to change the file name's coding system.  This
prompts for an existing file name, its old coding system, and the
coding system to which you wish to convert.


File: emacs,  Node: Terminal Coding,  Next: Fontsets,  Prev: File Name Coding,  Up: International

22.13 Coding Systems for Terminal I/O
=====================================

`C-x <RET> t CODING <RET>'
     Use coding system CODING for terminal output
     (`set-terminal-coding-system').

`C-x <RET> k CODING <RET>'
     Use coding system CODING for keyboard input
     (`set-keyboard-coding-system').

   The command `C-x <RET> t' (`set-terminal-coding-system') specifies
the coding system for terminal output.  If you specify a character code
for terminal output, all characters output to the terminal are
translated into that coding system.

   This feature is useful for certain character-only terminals built to
support specific languages or character sets--for example, European
terminals that support one of the ISO Latin character sets.  You need to
specify the terminal coding system when using multibyte text, so that
Emacs knows which characters the terminal can actually handle.

   By default, output to the terminal is not translated at all, unless
Emacs can deduce the proper coding system from your terminal type or
your locale specification (*note Language Environments::).

   The command `C-x <RET> k' (`set-keyboard-coding-system'), or the
variable `keyboard-coding-system', specifies the coding system for
keyboard input.  Character-code translation of keyboard input is useful
for terminals with keys that send non-ASCII graphic characters--for
example, some terminals designed for ISO Latin-1 or subsets of it.

   By default, keyboard input is translated based on your system locale
setting.  If your terminal does not really support the encoding implied
by your locale (for example, if you find it inserts a non-ASCII
character if you type `M-i'), you will need to set
`keyboard-coding-system' to `nil' to turn off encoding.  You can do
this by putting

     (set-keyboard-coding-system nil)

in your init file.

   There is a similarity between using a coding system translation for
keyboard input, and using an input method: both define sequences of
keyboard input that translate into single characters.  However, input
methods are designed to be convenient for interactive use by humans, and
the sequences that are translated are typically sequences of ASCII
printing characters.  Coding systems typically translate sequences of
non-graphic characters.


File: emacs,  Node: Fontsets,  Next: Defining Fontsets,  Prev: Terminal Coding,  Up: International

22.14 Fontsets
==============

A font typically defines shapes for a single alphabet or script.
Therefore, displaying the entire range of scripts that Emacs supports
requires a collection of many fonts.  In Emacs, such a collection is
called a "fontset".  A fontset is defined by a list of font
specifications, each assigned to handle a range of character codes, and
may fall back on another fontset for characters that are not covered by
the fonts it specifies.

   Each fontset has a name, like a font.  However, while fonts are
stored in the system and the available font names are defined by the
system, fontsets are defined within Emacs itself.  Once you have
defined a fontset, you can use it within Emacs by specifying its name,
anywhere that you could use a single font.  Of course, Emacs fontsets
can use only the fonts that the system supports.  If some characters
appear on the screen as empty boxes or hex codes, this means that the
fontset in use for them has no font for those characters.  In this
case, or if the characters are shown, but not as well as you would
like, you may need to install extra fonts.  Your operating system may
have optional fonts that you can install; or you can install the GNU
Intlfonts package, which includes fonts for most supported scripts.(1)

   Emacs creates three fontsets automatically: the "standard fontset",
the "startup fontset" and the "default fontset".  The default fontset
is most likely to have fonts for a wide variety of non-ASCII
characters, and is the default fallback for the other two fontsets, and
if you set a default font rather than fontset.  However, it does not
specify font family names, so results can be somewhat random if you use
it directly.  You can specify use of a particular fontset by starting
Emacs with the `-fn' option.  For example,

     emacs -fn fontset-standard

You can also specify a fontset with the `Font' resource (*note X
Resources::).

   If no fontset is specified for use, then Emacs uses an ASCII font,
with `fontset-default' as a fallback for characters the font does not
cover.  The standard fontset is only used if explicitly requested,
despite its name.

   A fontset does not necessarily specify a font for every character
code.  If a fontset specifies no font for a certain character, or if it
specifies a font that does not exist on your system, then it cannot
display that character properly.  It will display that character as a
hex code or thin space or an empty box instead.  (*Note glyphless
characters: Text Display, for details.)

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

   (1) If you run Emacs on X, you may need to inform the X server about
the location of the newly installed fonts with commands such as:

      xset fp+ /usr/local/share/emacs/fonts
      xset fp rehash


File: emacs,  Node: Defining Fontsets,  Next: Modifying Fontsets,  Prev: Fontsets,  Up: International

22.15 Defining fontsets
=======================

When running on X, Emacs creates a standard fontset automatically
according to the value of `standard-fontset-spec'.  This fontset's name
is

     -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard

or just `fontset-standard' for short.

   On GNUstep and Mac OS X, the standard fontset is created using the
value of `ns-standard-fontset-spec', and on MS Windows it is created
using the value of `w32-standard-fontset-spec'.

   Bold, italic, and bold-italic variants of the standard fontset are
created automatically.  Their names have `bold' instead of `medium', or
`i' instead of `r', or both.

   Emacs generates a fontset automatically, based on any default ASCII
font that you specify with the `Font' resource or the `-fn' argument,
or the default font that Emacs found when it started.  This is the
"startup fontset" and its name is `fontset-startup'.  It does this by
replacing the CHARSET_REGISTRY field with `fontset', and replacing
CHARSET_ENCODING field with `startup', then using the resulting string
to specify a fontset.

   For instance, if you start Emacs with a font of this form,

     emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"

Emacs generates the following fontset and uses it for the initial X
window frame:

     -*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup

   The startup fontset will use the font that you specify, or a variant
with a different registry and encoding, for all the characters that are
supported by that font, and fallback on `fontset-default' for other
characters.

   With the X resource `Emacs.Font', you can specify a fontset name
just like an actual font name.  But be careful not to specify a fontset
name in a wildcard resource like `Emacs*Font'--that wildcard
specification matches various other resources, such as for menus, and
menus cannot handle fontsets.  *Note X Resources::.

   You can specify additional fontsets using X resources named
`Fontset-N', where N is an integer starting from 0.  The resource value
should have this form:

     FONTPATTERN, [CHARSET:FONT]...

FONTPATTERN should have the form of a standard X font name (see the
previous fontset-startup example), except for the last two fields.
They should have the form `fontset-ALIAS'.

   The fontset has two names, one long and one short.  The long name is
FONTPATTERN.  The short name is `fontset-ALIAS'.  You can refer to the
fontset by either name.

   The construct `CHARSET:FONT' specifies which font to use (in this
fontset) for one particular character set.  Here, CHARSET is the name
of a character set, and FONT is the font to use for that character set.
You can use this construct any number of times in defining one fontset.

   For the other character sets, Emacs chooses a font based on
FONTPATTERN.  It replaces `fontset-ALIAS' with values that describe the
character set.  For the ASCII character font, `fontset-ALIAS' is
replaced with `ISO8859-1'.

   In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard.  This is to prevent use of
auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not also useful, because it
is better to use the smaller font in its own size, which is what Emacs
does.

   Thus if FONTPATTERN is this,

     -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

     -*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

     -*-fixed-medium-r-normal-*-24-*-gb2312*-*

   You may not have any Chinese font matching the above font
specification.  Most X distributions include only Chinese fonts that
have `song ti' or `fangsong ti' in the FAMILY field.  In such a case,
`Fontset-N' can be specified as:

     Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
             chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have
`fixed' in the FAMILY field, and the font specification for Chinese
GB2312 characters has a wild card `*' in the FAMILY field.

   The function that processes the fontset resource value to create the
fontset is called `create-fontset-from-fontset-spec'.  You can also
call this function explicitly to create a fontset.

   *Note Fonts::, for more information about font naming.


File: emacs,  Node: Modifying Fontsets,  Next: Undisplayable Characters,  Prev: Defining Fontsets,  Up: International

22.16 Modifying Fontsets
========================

Fontsets do not always have to be created from scratch.  If only minor
changes are required it may be easier to modify an existing fontset.
Modifying `fontset-default' will also affect other fontsets that use it
as a fallback, so can be an effective way of fixing problems with the
fonts that Emacs chooses for a particular script.

   Fontsets can be modified using the function `set-fontset-font',
specifying a character, a charset, a script, or a range of characters
to modify the font for, and a font specification for the font to be
used.  Some examples are:

     ;; Use Liberation Mono for latin-3 charset.
     (set-fontset-font "fontset-default" 'iso-8859-3
                       "Liberation Mono")

     ;; Prefer a big5 font for han characters
     (set-fontset-font "fontset-default"
                       'han (font-spec :registry "big5")
                       nil 'prepend)

     ;; Use DejaVu Sans Mono as a fallback in fontset-startup
     ;; before resorting to fontset-default.
     (set-fontset-font "fontset-startup" nil "DejaVu Sans Mono"
                       nil 'append)

     ;; Use MyPrivateFont for the Unicode private use area.
     (set-fontset-font "fontset-default"  '(#xe000 . #xf8ff)
                       "MyPrivateFont")


File: emacs,  Node: Undisplayable Characters,  Next: Unibyte Mode,  Prev: Modifying Fontsets,  Up: International

22.17 Undisplayable Characters
==============================

There may be some non-ASCII characters that your terminal cannot
display.  Most text terminals support just a single character set (use
the variable `default-terminal-coding-system' to tell Emacs which one,
*note Terminal Coding::); characters that can't be encoded in that
coding system are displayed as `?' by default.

   Graphical displays can display a broader range of characters, but
you may not have fonts installed for all of them; characters that have
no font appear as a hollow box.

   If you use Latin-1 characters but your terminal can't display
Latin-1, you can arrange to display mnemonic ASCII sequences instead,
e.g. `"o' for o-umlaut.  Load the library `iso-ascii' to do this.

   If your terminal can display Latin-1, you can display characters
from other European character sets using a mixture of equivalent
Latin-1 characters and ASCII mnemonics.  Customize the variable
`latin1-display' to enable this.  The mnemonic ASCII sequences mostly
correspond to those of the prefix input methods.


File: emacs,  Node: Unibyte Mode,  Next: Charsets,  Prev: Undisplayable Characters,  Up: International

22.18 Unibyte Editing Mode
==========================

The ISO 8859 Latin-N character sets define character codes in the range
0240 to 0377 octal (160 to 255 decimal) to handle the accented letters
and punctuation needed by various European languages (and some
non-European ones).  Note that Emacs considers bytes with codes in this
range as raw bytes, not as characters, even in a unibyte buffer, i.e.
if you disable multibyte characters.  However, Emacs can still handle
these character codes as if they belonged to _one_ of the single-byte
character sets at a time.  To specify _which_ of these codes to use,
invoke `M-x set-language-environment' and specify a suitable language
environment such as `Latin-N'.

   For more information about unibyte operation, see *note Disabling
Multibyte::.

   Emacs can also display bytes in the range 160 to 255 as readable
characters, provided the terminal or font in use supports them.  This
works automatically.  On a graphical display, Emacs can also display
single-byte characters through fontsets, in effect by displaying the
equivalent multibyte characters according to the current language
environment.  To request this, set the variable
`unibyte-display-via-language-environment' to a non-`nil' value.  Note
that setting this only affects how these bytes are displayed, but does
not change the fundamental fact that Emacs treats them as raw bytes,
not as characters.

   If your terminal does not support display of the Latin-1 character
set, Emacs can display these characters as ASCII sequences which at
least give you a clear idea of what the characters are.  To do this,
load the library `iso-ascii'.  Similar libraries for other Latin-N
character sets could be implemented, but have not been so far.

   Normally non-ISO-8859 characters (decimal codes between 128 and 159
inclusive) are displayed as octal escapes.  You can change this for
non-standard "extended" versions of ISO-8859 character sets by using the
function `standard-display-8bit' in the `disp-table' library.

   There are two ways to input single-byte non-ASCII characters:

   * You can use an input method for the selected language environment.
     *Note Input Methods::.  When you use an input method in a unibyte
     buffer, the non-ASCII character you specify with it is converted
     to unibyte.

   * If your keyboard can generate character codes 128 (decimal) and up,
     representing non-ASCII characters, you can type those character
     codes directly.

     On a graphical display, you should not need to do anything special
     to use these keys; they should simply work.  On a text terminal,
     you should use the command `M-x set-keyboard-coding-system' or
     customize the variable `keyboard-coding-system' to specify which
     coding system your keyboard uses (*note Terminal Coding::).
     Enabling this feature will probably require you to use `ESC' to
     type Meta characters; however, on a console terminal or in
     `xterm', you can arrange for Meta to be converted to `ESC' and
     still be able type 8-bit characters present directly on the
     keyboard or using `Compose' or `AltGr' keys.  *Note User Input::.

   * For Latin-1 only, you can use the key `C-x 8' as a "compose
     character" prefix for entry of non-ASCII Latin-1 printing
     characters.  `C-x 8' is good for insertion (in the minibuffer as
     well as other buffers), for searching, and in any other context
     where a key sequence is allowed.

     `C-x 8' works by loading the `iso-transl' library.  Once that
     library is loaded, the <ALT> modifier key, if the keyboard has
     one, serves the same purpose as `C-x 8': use <ALT> together with
     an accent character to modify the following letter.  In addition,
     if the keyboard has keys for the Latin-1 "dead accent characters",
     they too are defined to compose with the following character, once
     `iso-transl' is loaded.

     Use `C-x 8 C-h' to list all the available `C-x 8' translations.


File: emacs,  Node: Charsets,  Next: Bidirectional Editing,  Prev: Unibyte Mode,  Up: International

22.19 Charsets
==============

In Emacs, "charset" is short for "character set".  Emacs supports most
popular charsets (such as `ascii', `iso-8859-1', `cp1250', `big5', and
`unicode'), in addition to some charsets of its own (such as `emacs',
`unicode-bmp', and `eight-bit').  All supported characters belong to
one or more charsets.

   Emacs normally "does the right thing" with respect to charsets, so
that you don't have to worry about them.  However, it is sometimes
helpful to know some of the underlying details about charsets.

   One example is font selection (*note Fonts::).  Each language
environment (*note Language Environments::) defines a "priority list"
for the various charsets.  When searching for a font, Emacs initially
attempts to find one that can display the highest-priority charsets.
For instance, in the Japanese language environment, the charset
`japanese-jisx0208' has the highest priority, so Emacs tries to use a
font whose `registry' property is `JISX0208.1983-0'.

   There are two commands that can be used to obtain information about
charsets.  The command `M-x list-charset-chars' prompts for a charset
name, and displays all the characters in that character set.  The
command `M-x describe-character-set' prompts for a charset name, and
displays information about that charset, including its internal
representation within Emacs.

   `M-x list-character-sets' displays a list of all supported charsets.
The list gives the names of charsets and additional information to
identity each charset; see the International Register of Coded
Character Sets (http://www.itscj.ipsj.or.jp/ISO-IR/) for more details.
In this list, charsets are divided into two categories: "normal
charsets" are listed first, followed by "supplementary charsets".  A
supplementary charset is one that is used to define another charset (as
a parent or a subset), or to provide backward-compatibility for older
Emacs versions.

   To find out which charset a character in the buffer belongs to, put
point before it and type `C-u C-x =' (*note International Chars::).


File: emacs,  Node: Bidirectional Editing,  Prev: Charsets,  Up: International

22.20 Bidirectional Editing
===========================

Emacs supports editing text written in scripts, such as Arabic and
Hebrew, whose natural ordering of horizontal text for display is from
right to left.  However, digits and Latin text embedded in these
scripts are still displayed left to right.  It is also not uncommon to
have small portions of text in Arabic or Hebrew embedded in an otherwise
Latin document; e.g., as comments and strings in a program source file.
For these reasons, text that uses these scripts is actually
"bidirectional": a mixture of runs of left-to-right and right-to-left
characters.

   This section describes the facilities and options provided by Emacs
for editing bidirectional text.

   Emacs stores right-to-left and bidirectional text in the so-called
"logical" (or "reading") order: the buffer or string position of the
first character you read precedes that of the next character.
Reordering of bidirectional text into the "visual" order happens at
display time.  As result, character positions no longer increase
monotonically with their positions on display.  Emacs implements the
Unicode Bidirectional Algorithm described in the Unicode Standard Annex
#9, for reordering of bidirectional text for display.

   The buffer-local variable `bidi-display-reordering' controls whether
text in the buffer is reordered for display.  If its value is
non-`nil', Emacs reorders characters that have right-to-left
directionality when they are displayed.  The default value is `t'.

   Each paragraph of bidirectional text can have its own "base
direction", either right-to-left or left-to-right.  (Paragraph
boundaries are empty lines, i.e. lines consisting entirely of
whitespace characters.)  Text in left-to-right paragraphs begins on the
screen at the left margin of the window and is truncated or continued
when it reaches the right margin.  By contrast, text in right-to-left
paragraphs is displayed starting at the right margin and is continued
or truncated at the left margin.

   Emacs determines the base direction of each paragraph dynamically,
based on the text at the beginning of the paragraph.  However,
sometimes a buffer may need to force a certain base direction for its
paragraphs.  The variable `bidi-paragraph-direction', if non-`nil',
disables the dynamic determination of the base direction, and instead
forces all paragraphs in the buffer to have the direction specified by
its buffer-local value.  The value can be either `right-to-left' or
`left-to-right'.  Any other value is interpreted as `nil'.

   Alternatively, you can control the base direction of a paragraph by
inserting special formatting characters in front of the paragraph.  The
special character `RIGHT-TO-LEFT MARK', or RLM, forces the
right-to-left direction on the following paragraph, while
`LEFT-TO-RIGHT MARK', or LRM forces the left-to-right direction.  (You
can use `C-x 8 RET' to insert these characters.)  In a GUI session, the
LRM and RLM characters display as very thin blank characters; on text
terminals they display as blanks.

   Because characters are reordered for display, Emacs commands that
operate in the logical order or on stretches of buffer positions may
produce unusual effects.  For example, `C-f' and `C-b' commands move
point in the logical order, so the cursor will sometimes jump when
point traverses reordered bidirectional text.  Similarly, a highlighted
region covering a contiguous range of character positions may look
discontinuous if the region spans reordered text.  This is normal and
similar to the behavior of other programs that support bidirectional
text.


File: emacs,  Node: Modes,  Next: Indentation,  Prev: International,  Up: Top

23 Major and Minor Modes
************************

Emacs contains many "editing modes" that alter its basic behavior in
useful ways.  These are divided into "major modes" and "minor modes".

   Major modes provide specialized facilities for working on a
particular file type, such as a C source file (*note Programs::), or a
particular type of non-file buffer, such as a shell buffer (*note
Shell::).  Major modes are mutually exclusive; each buffer has one and
only one major mode at any time.

   Minor modes are optional features which you can turn on or off, not
necessarily specific to a type of file or buffer.  For example, Auto
Fill mode is a minor mode in which <SPC> breaks lines between words as
you type (*note Auto Fill::).  Minor modes are independent of one
another, and of the selected major mode.

* Menu:

* Major Modes::         Text mode vs. Lisp mode vs. C mode...
* Minor Modes::         Each minor mode is a feature you can turn on
                          independently of any others.
* Choosing Modes::      How modes are chosen when visiting files.


File: emacs,  Node: Major Modes,  Next: Minor Modes,  Up: Modes

23.1 Major Modes
================

Every buffer possesses a major mode, which determines the editing
behavior of Emacs while that buffer is current.  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 user
option variable is in its default state.

   For editing text of a specific type that Emacs knows about, such as
Lisp code or English text, you typically use a more specialized major
mode, such as Lisp mode or Text mode.  Most major modes fall into three
major groups.  The first group contains modes for normal text, either
plain or with mark-up.  It includes Text mode, HTML mode, SGML mode,
TeX mode and Outline mode.  The second group contains modes for
specific programming languages.  These include Lisp mode (which has
several variants), C mode, Fortran mode, and others.  The third group
consists of major modes that are not associated directly with files;
they are used in buffers created for specific purposes by Emacs, such
as Dired mode for buffers made by Dired (*note Dired::), Message mode
for buffers made by `C-x m' (*note Sending Mail::), and Shell mode for
buffers used to communicate with an inferior shell process (*note
Interactive Shell::).

   Usually, the major mode is automatically set by Emacs, when you
first visit a file or create a buffer (*note Choosing Modes::).  You
can explicitly select a new major mode by using an `M-x' command.  Take
the name of the mode and add `-mode' to get the name of the command to
select that mode (e.g., `M-x lisp-mode' enters Lisp mode).

   The value of the buffer-local variable `major-mode' is a symbol with
the same name as the major mode command (e.g. `lisp-mode').  This
variable is set automatically; you should not change it yourself.

   The default value of `major-mode' determines the major mode to use
for files that do not specify a major mode, and for new buffers created
with `C-x b'.  Normally, this default value is the symbol
`fundamental-mode', which specifies Fundamental mode.  You can change
this default value via the Customization interface (*note Easy
Customization::), or by adding a line like this to your init file
(*note Init File::):

     (setq-default major-mode 'text-mode)

If the default value of `major-mode' is `nil', the major mode is taken
from the previously current buffer.

   Specialized major modes often change the meanings of certain keys to
do something more suitable for the mode.  For instance, programming
language modes bind <TAB> to indent the current line according to the
rules of the language (*note Indentation::).  The keys that are
commonly changed are <TAB>, <DEL>, and `C-j'.  Many modes also define
special commands of their own, usually bound in the prefix key `C-c'.
Major modes can also alter user options and variables; for instance,
programming language modes typically set a buffer-local value for the
variable `comment-start', which determines how source code comments are
delimited (*note Comments::).

   To view the documentation for the current major mode, including a
list of its key bindings, type `C-h m' (`describe-mode').

   Every major mode, apart from Fundamental mode, defines a "mode
hook", a customizable list of Lisp functions to run each time the mode
is enabled in a buffer.  *Note Hooks::, for more information about
hooks.  Each mode hook is named after its major mode, e.g. Fortran mode
has `fortran-mode-hook'.  Furthermore, all text-based major modes run
`text-mode-hook', and all programming language modes run
`prog-mode-hook', prior to running their own mode hooks.  Hook
functions can look at the value of the variable `major-mode' to see
which mode is actually being entered.

   Mode hooks are commonly used to enable minor modes (*note Minor
Modes::).  For example, you can put the following lines in your init
file to enable Flyspell minor mode in all text-based major modes (*note
Spelling::), and Eldoc minor mode in Emacs Lisp mode (*note Lisp Doc::):

     (add-hook 'text-mode-hook 'flyspell-mode)
     (add-hook 'emacs-lisp-mode-hook 'eldoc-mode)


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

23.2 Minor Modes
================

A minor mode is an optional editing mode that alters the behavior of
Emacs in some well-defined way.  Unlike major modes, any number of
minor modes can be in effect at any time.  Some minor modes are
"buffer-local", and can be turned on (enabled) in certain buffers and
off (disabled) in others.  Other minor modes are "global": while
enabled, they affect everything you do in the Emacs session, in all
buffers.  Most minor modes are disabled by default, but a few are
enabled by default.

   Most buffer-local minor modes say in the mode line when they are
enabled, just after the major mode indicator.  For example, `Fill' in
the mode line means that Auto Fill mode is enabled.  *Note Mode Line::.

   Like major modes, each minor mode is associated with a "mode
command", whose name consists of the mode name followed by `-mode'.
For instance, the mode command for Auto Fill mode is `auto-fill-mode'.
But unlike a major mode command, which simply enables the mode, the
mode command for a minor mode can either enable or disable it:

   * If you invoke the mode command directly with no prefix argument
     (either via `M-x', or by binding it to a key and typing that key;
     *note Key Bindings::), that "toggles" the minor mode.  The minor
     mode is turned on if it was off, and turned off if it was on.

   * If you invoke the mode command with a prefix argument, the minor
     mode is unconditionally turned off if that argument is zero or
     negative; otherwise, it is unconditionally turned on.

   * If the mode command is called via Lisp, the minor mode is
     unconditionally turned on if the argument is omitted or `nil'.
     This makes it easy to turn on a minor mode from a major mode's mode
     hook (*note Major Modes::).  A non-`nil' argument is handled like
     an interactive prefix argument, as described above.

   Most minor modes also have a "mode variable", with the same name as
the mode command.  Its value is non-`nil' if the mode is enabled, and
`nil' if it is disabled.  In general, you should not try to enable or
disable the mode by changing the value of the mode variable directly in
Lisp; you should run the mode command instead.  However, setting the
mode variable through the Customize interface (*note Easy
Customization::) will always properly enable or disable the mode, since
Customize automatically runs the mode command for you.

   The following is a list of some buffer-local minor modes:

   * Abbrev mode automatically expands text based on pre-defined
     abbreviation definitions.  *Note Abbrevs::.

   * Auto Fill mode inserts newlines as you type to prevent lines from
     becoming too long.  *Note Filling::.

   * Auto Save mode saves the buffer contents periodically to reduce the
     amount of work you can lose in case of a crash.  *Note Auto Save::.

   * Enriched mode enables editing and saving of formatted text.  *Note
     Enriched Text::.

   * Flyspell mode automatically highlights misspelled words.  *Note
     Spelling::.

   * Font-Lock mode automatically highlights certain textual units
     found in programs.  It is enabled globally by default, but you can
     disable it in individual buffers.  *Note Faces::.

   * Linum mode displays each line's line number in the window's left
     margin.

   * Outline minor mode provides similar facilities to the major mode
     called Outline mode.  *Note Outline Mode::.

   * Overwrite mode causes ordinary printing characters to replace
     existing text instead of shoving it to the right.  For example, if
     point is in front of the `B' in `FOOBAR', then in Overwrite mode
     typing a `G' changes it to `FOOGAR', instead of producing
     `FOOGBAR' as usual.  In Overwrite mode, the command `C-q' inserts
     the next character whatever it may be, even if it is a digit--this
     gives you a way to insert a character instead of replacing an
     existing character.  The mode command, `overwrite-mode', is bound
     to the <Insert> key.

   * Binary Overwrite mode is a variant of Overwrite mode for editing
     binary files; it treats newlines and tabs like other characters, so
     that they overwrite other characters and can be overwritten by
     them.  In Binary Overwrite mode, digits after `C-q' specify an
     octal character code, as usual.

   * Visual Line mode performs "word wrapping", causing long lines to be
     wrapped at word boundaries.  *Note Visual Line Mode::.

And here are some useful global minor modes:

   * Column Number mode enables display of the current column number in
     the mode line.  *Note Mode Line::.

   * Delete Selection mode causes text insertion to first delete the
     text in the region, if the region is active.  *Note Using Region::.

   * Icomplete mode displays an indication of available completions when
     you are in the minibuffer and completion is active.  *Note
     Completion Options::.

   * Line Number mode enables display of the current line number in the
     mode line.  It is enabled by default.  *Note Mode Line::.

   * Menu Bar mode gives each frame a menu bar.  It is enabled by
     default.  *Note Menu Bars::.

   * Scroll Bar mode gives each window a scroll bar.  It is enabled by
     default, but the scroll bar is only displayed on graphical
     terminals.  *Note Scroll Bars::.

   * Tool Bar mode gives each frame a tool bar.  It is enabled by
     default, but the tool bar is only displayed on graphical
     terminals.  *Note Tool Bars::.

   * Transient Mark mode highlights the region, and makes many Emacs
     commands operate on the region when the mark is active.  It is
     enabled by default.  *Note Mark::.


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

23.3 Choosing File Modes
========================

When you visit a file, Emacs chooses a major mode automatically.
Normally, it makes the choice based on the file name--for example,
files whose names end in `.c' are normally edited in C mode--but
sometimes it chooses the major mode based on special text in the file.
This special text can also be used to enable buffer-local minor modes.

   Here is the exact procedure:

   First, Emacs checks whether the file contains file-local mode
variables.  *Note File Variables::.  If there is a file-local variable
that specifies a major mode, then Emacs uses that major mode, ignoring
all other criteria.  There are several methods to specify a major mode
using a file-local variable; the simplest is to put the mode name in
the first nonblank line, preceded and followed by `-*-'.  Other text
may appear on the line as well.  For example,

     ; -*-Lisp-*-

tells Emacs to use Lisp mode.  Note how the semicolon is used to make
Lisp treat this line as a comment.  You could equivalently write

     ; -*- mode: Lisp;-*-

You can also use file-local variables to specify buffer-local minor
modes, by using `eval' specifications.  For example, this first
nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode:

     ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-

Note, however, that it is usually inappropriate to enable minor modes
this way, since most minor modes represent individual user preferences.
If you personally want to use a minor mode for a particular file type,
it is better to enable the minor mode via a major mode hook (*note
Major Modes::).

   Second, if there is no file variable specifying a major mode, Emacs
checks whether the file's contents begin with `#!'.  If so, that
indicates that the file 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).  Therefore,
Emacs tries to use the interpreter name to choose a mode.  For
instance, a file that begins with `#!/usr/bin/perl' is opened in Perl
mode.  The variable `interpreter-mode-alist' specifies the
correspondence between interpreter program names and major modes.

   When the first line starts with `#!', you usually cannot use the
`-*-' feature on the first line, because the system would get confused
when running the interpreter.  So Emacs looks for `-*-' on the second
line in such files as well as on the first line.  The same is true for
man pages which start with the magic string `'\"' to specify a list of
troff preprocessors.

   Third, Emacs tries to determine the major mode by looking at the
text at the start of the buffer, based on the variable
`magic-mode-alist'.  By default, this variable is `nil' (an empty
list), so Emacs skips this step; however, you can customize it in your
init file (*note Init File::).  The value should be a list of elements
of the form

     (REGEXP . MODE-FUNCTION)

where REGEXP is a regular expression (*note Regexps::), and
MODE-FUNCTION is a major mode command.  If the text at the beginning of
the file matches REGEXP, Emacs chooses the major mode specified by
MODE-FUNCTION.

   Alternatively, an element of `magic-mode-alist' may have the form

     (MATCH-FUNCTION . MODE-FUNCTION)

where MATCH-FUNCTION is a Lisp function that is called at the beginning
of the buffer; if the function returns non-`nil', Emacs set the major
mode with MODE-FUNCTION.

   Fourth--if Emacs still hasn't found a suitable major mode--it looks
at the file's name.  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 must be used 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
MODE-FUNCTION, Emacs discards the suffix that matched REGEXP and
searches the list again for another match.

   On GNU/Linux and other systems with case-sensitive file names, Emacs
performs a case-sensitive search through `auto-mode-alist'; if this
search fails, it performs a second case-insensitive search through the
alist.  To suppress the second search, change the variable
`auto-mode-case-fold' to `nil'.  On systems with case-insensitive file
names, such as Microsoft Windows, Emacs performs a single
case-insensitive search through `auto-mode-alist'.

   Finally, if Emacs _still_ hasn't found a major mode to use, it
compares the text at the start of the buffer to the variable
`magic-fallback-mode-alist'.  This variable works like
`magic-mode-alist', described above, except that is consulted only
after `auto-mode-alist'.  By default, `magic-fallback-mode-alist'
contains forms that check for image files, HTML/XML/SGML files, and
PostScript files.

   If you have changed the major mode of a buffer, you can return to
the major mode Emacs would have chosen automatically, by typing `M-x
normal-mode'.  This is the same function that `find-file' calls to
choose the major mode.  It also processes the file's `-*-' line or
local variables list (if any).  *Note File Variables::.

   The commands `C-x C-w' and `set-visited-file-name' change to a new
major mode if the new file name implies a mode (*note Saving::).  (`C-x
C-s' does this too, if the buffer wasn't visiting a file.)  However,
this does not happen if the buffer contents specify a major mode, and
certain "special" major modes do not allow the mode to change.  You can
turn off this mode-changing feature by setting
`change-major-mode-with-file-name' to `nil'.


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

24 Indentation
**************

"Indentation" refers to inserting or adjusting "whitespace characters"
(space and/or tab characters) at the beginning of a line of text.  This
chapter documents indentation commands and options which are common to
Text mode and related modes, as well as programming language modes.
*Note Program Indent::, for additional documentation about indenting in
programming modes.

   The simplest way to perform indentation is the <TAB> key.  In most
major modes, this runs the command `indent-for-tab-command'.  (In C and
related modes, <TAB> runs the command `c-indent-line-or-region', which
behaves similarly).

<TAB>
     Insert whitespace, or indent the current line, in a
     mode-appropriate way (`indent-for-tab-command').  If the region is
     active, indent all the lines within it.

   The exact behavior of <TAB> depends on the major mode.  In Text mode
and related major modes, <TAB> normally inserts some combination of
space and tab characters to advance point to the next tab stop (*note
Tab Stops::).  For this purpose, the position of the first
non-whitespace character on the preceding line is treated as an
additional tab stop, so you can use <TAB> to "align" point with the
preceding line.  If the region is active (*note Using Region::), <TAB>
acts specially: it indents each line in the region so that its first
non-whitespace character is aligned with the preceding line.

   In programming modes, <TAB> indents the current line of code in a
way that makes sense given the code in the preceding lines.  If the
region is active, all the lines in the region are indented this way.
If point was initially within the current line's indentation, it is
repositioned to the first non-whitespace character on the line.

   If you just want to insert a tab character in the buffer, type `C-q
<TAB>' (*note Inserting Text::).

* Menu:

* Indentation Commands::  More commands for performing indentation.
* Tab Stops::             Stop points for indentation in Text modes.
* Just Spaces::           Using only space characters for indentation.
* Indent Convenience::    Optional indentation features.


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

24.1 Indentation Commands
=========================

Apart from the <TAB> (`indent-for-tab-command') command, Emacs provides
a variety of commands to perform indentation in other ways.

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

`C-M-o'
     Split the current line at point (`split-line').  The text on the
     line after point becomes a new line, indented to the same column
     where point is located.  This command first moves point forward
     over any spaces and tabs.  Afterward, point is positioned before
     the inserted newline.

`M-m'
     Move (forward or back) to the first non-whitespace character on the
     current line (`back-to-indentation').  If there are no
     non-whitespace characters on the line, move to the end of the line.

`M-i'
     Indent whitespace at point, up to the next tab stop
     (`tab-to-tab-stop').  *Note Tab Stops::.

`M-x indent-relative'
     Insert whitespace at point, until point is aligned with the first
     non-whitespace character on the previous line (actually, the last
     non-blank line).  If point is already farther right than that, run
     `tab-to-tab-stop' instead--unless called with a numeric argument,
     in which case do nothing.

`M-^'
     Merge the previous and the current line (`delete-indentation').
     This "joins" the two lines cleanly, by replacing any indentation at
     the front of the current line, together with the line boundary,
     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 opening and
     closing parentheses, or if the junction follows another newline.

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

`C-M-\'
     Indent all the lines in the region, as though you had typed <TAB>
     at the beginning of each line (`indent-region').

     If a numeric argument is supplied, indent every line in the region
     to that column number.

`C-x <TAB>'
     Shift each line in the region by a fixed distance, to the right or
     left (`indent-rigidly').  The distance to move is determined by
     the numeric argument (positive to move rightward, negative to move
     leftward).

     This command can be used to remove all indentation from the lines
     in the region, by invoking it with a large negative argument, e.g.
     `C-u -1000 C-x <TAB>'.


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

24.2 Tab Stops
==============

Emacs defines certain column numbers to be "tab stops".  These are used
as stopping points by <TAB> when inserting whitespace in Text mode and
related modes (*note Indentation::), and by commands like `M-i' (*note
Indentation Commands::).  By default, tab stops are located every 8
columns.  These positions are stored in the variable `tab-stop-list',
whose value is a list of column numbers in increasing order.

   Instead of customizing the variable `tab-stop-list' directly, a
convenient way to view and set tab stops is via the command `M-x
edit-tab-stops'.  This switches to a buffer containing a description of
the tab stop settings, which looks like this:

             :       :       :       :       :       :
     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 numbers on the
next two lines are present just to indicate where the colons are.

   You can edit this buffer to specify different tab stops by placing
colons on the desired columns.  The buffer uses Overwrite mode (*note
Minor Modes::).  When you are done, type `C-c C-c' to make the new tab
stops take effect.  Normally, the new tab stop settings apply to all
buffers.  However, if you have made the `tab-stop-list' variable local
to the buffer where you called `M-x edit-tab-stops' (*note Locals::),
then the new tab stop settings apply only to that buffer.  To save the
tab stop settings for future Emacs sessions, use the Customize
interface to save the value of `tab-stop-list' (*note Easy
Customization::).

   Note that the tab stops discussed in this section have nothing to do
with how tab characters are displayed in the buffer.  Tab characters
are always displayed as empty spaces extending to the next "display tab
stop".  *Note Text Display::.


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

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

Normally, indentation commands insert (or remove) an optimal mix of
space characters and tab characters to align to the desired column.
Tab characters are displayed as a stretch of empty space extending to
the next "display tab stop".  By default, there is one display tab stop
every `tab-width' columns (the default is 8).  *Note Text Display::.

   If you prefer, all indentation can be made from spaces only.  To
request this, set the buffer-local variable `indent-tabs-mode' to
`nil'.  *Note Locals::, for information about setting buffer-local
variables.  Note, however, that `C-q <TAB>' always inserts a tab
character, regardless of the value of `indent-tabs-mode'.

   One reason to set `indent-tabs-mode' to `nil' is that not all
editors display tab characters in the same way.  Emacs users, too, may
have different customized values of `tab-width'.  By using spaces only,
you can make sure that your file always looks the same.  If you only
care about how it looks within Emacs, another way to tackle this
problem is to set the `tab-width' variable in a file-local variable
(*note File Variables::).

   There are also commands to convert tabs to spaces or vice versa,
always preserving the columns of all non-whitespace text.  `M-x tabify'
scans the region for sequences of spaces, and converts sequences of at
least two 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: Indent Convenience,  Prev: Just Spaces,  Up: Indentation

24.4 Convenience Features for Indentation
=========================================

The variable `tab-always-indent' tweaks the behavior of the <TAB>
(`indent-for-tab-command') command.  The default value, `t', gives the
behavior described in *note Indentation::.  If you change the value to
the symbol `complete', then <TAB> first tries to indent the current
line, and if the line was already indented, it tries to complete the
text at point (*note Symbol Completion::).  If the value is `nil', then
<TAB> indents the current line only if point is at the left margin or
in the line's indentation; otherwise, it inserts a tab character.

   Electric Indent mode is a global minor mode that automatically
indents the line after every <RET> you type.  To toggle this minor
mode, type `M-x electric-indent-mode'.


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

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

This chapter describes Emacs commands that act on "text", by which we
mean sequences of characters in a human language (as opposed to, say, a
computer programming language).  These commands act in ways that take
into account the syntactic and stylistic conventions of human
languages: conventions involving words, sentences, paragraphs, and
capital letters.  There are also commands for "filling", which means
rearranging the lines of a paragraph to be approximately equal in
length.  These commands, 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 ordinary text, 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.  Org mode extends Outline mode and turn Emacs into a
full-fledged organizer: you can manage TODO lists, store notes and
publish them in many formats.

   Emacs has other major modes for text which contains "embedded"
commands, such as TeX and LaTeX (*note TeX Mode::); HTML and SGML
(*note HTML Mode::); XML (*note The nXML Mode Manual: (nxml-mode)Top.);
and Groff and Nroff (*note Nroff Mode::).

   If you need to edit pictures made out of text characters (commonly
referred to as "ASCII art"), use Picture mode, a special major mode for
editing such pictures.  *Note Picture Mode::.

   The "automatic typing" features may be useful when writing text.
*note The Autotype Manual: (autotype)Top.

* 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::        Editing outlines.
* Org Mode::            The Emacs organizer.
* TeX Mode::            Editing TeX and LaTeX files.
* HTML Mode::           Editing HTML and SGML files.
* Nroff Mode::          Editing input to the nroff formatter.
* Enriched Text::       Editing text "enriched" with fonts, colors, etc.
* Text Based Tables::   Commands for editing text-based tables.
* Two-Column::          Splitting text columns into separate windows.


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

25.1 Words
==========

Emacs defines several commands for moving over or operating on words:

`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 others
     (`transpose-words').

   Notice how these keys form a series that parallels the
character-based `C-f', `C-b', `C-d', <DEL> and `C-t'.  `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>-based key sequences are
analogous to the key sequences `C-f' and `C-b', which move over single
characters.  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.  For
instance, if point is after the space in `FOO, BAR', it kills `FOO, '.
If you wish to kill just `FOO', and not the comma and the space, use
`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.

   To operate on words with an operation which acts on the region, use
the command `M-@' (`mark-word').  This command sets the mark where
`M-f' would move to.  *Note Marking Objects::, for more information
about this command.

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

   In addition, see *note Position Info:: for the `M-='
(`count-words-region') and `M-x count-words' commands, which count and
report the number of words in the region or buffer.


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

25.2 Sentences
==============

The Emacs commands for manipulating sentences and paragraphs are mostly
on Meta keys, 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' (`backward-sentence') and `M-e'
(`forward-sentence') move to the beginning and end of the current
sentence, respectively.  Their bindings 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' move over successive sentences if repeated.

   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,
`M-a' and `M-e' have a corresponding kill command: `M-k'
(`kill-sentence') kills from point to the end of the sentence.  With a
positive numeric argument N, it kills the next N sentences; with a
negative argument -N, it kills back to the beginning of the Nth
preceding sentence.

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

   The sentence commands assume that you follow the American typist's
convention of putting two spaces at the end of a sentence.  That is, a
sentence ends 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.  It is useful to follow this convention,
because it allows the Emacs sentence commands to distinguish between
periods that end a sentence and periods that indicate abbreviations.

   If you want to use just one space between sentences, you can set the
variable `sentence-end-double-space' to `nil' to make the sentence
commands stop for single spaces.  However, this has a drawback: there
is no way to distinguish between periods that end sentences and those
that indicate abbreviations.  For convenient and reliable editing, we
therefore recommend you follow the two-space convention.  The variable
`sentence-end-double-space' also affects filling (*note Fill
Commands::).

   The variable `sentence-end' controls how to recognize the end of a
sentence.  If non-`nil', its value should be a regular expression,
which is used to match the last few characters of a sentence, together
with the whitespace following the sentence (*note Regexps::).  If the
value is `nil', the default, then Emacs computes sentence ends
according to various criteria such as the value of
`sentence-end-double-space'.

   Some languages, such as Thai, do not use periods to indicate the end
of a sentence.  Set the variable `sentence-end-without-period' to `t'
in such cases.


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

25.3 Paragraphs
===============

The Emacs commands for manipulating paragraphs are also on 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-{' (`backward-paragraph') moves to the beginning of the current
or previous paragraph (see below for the definition of a paragraph).
`M-}' (`forward-paragraph') moves to the end of the current or next
paragraph.  If there is a blank line before the paragraph, `M-{' moves
to the blank line.

   When you wish to operate on a paragraph, type `M-h'
(`mark-paragraph') to set the region around it.  For example, `M-h C-w'
kills the paragraph around or after point.  `M-h' puts point at the
beginning and mark at the end of the paragraph point was in.  If point
is between paragraphs (in a run of blank lines, or at a boundary),
`M-h' sets the region around the paragraph following point.  If there
are blank lines preceding the first line of the paragraph, one of these
blank lines is included in the region.  If the region is already
active, the command sets the mark without changing point, and each
subsequent `M-h' further advances the mark by one paragraph.

   The definition of a paragraph depends on the major mode.  In
Fundamental mode, as well as Text mode and related modes, a paragraph
is separated each neighboring paragraph another by one or more "blank
lines"--lines that are either empty, or consist solely of space, tab
and/or formfeed characters.  In programming language modes, paragraphs
are usually defined in a similar way, so that you can use the paragraph
commands even though there are no paragraphs as such in a program.

   Note that an indented line is _not_ itself a paragraph break in Text
mode.  If you want indented lines to separate paragraphs, use
Paragraph-Indent Text mode instead.  *Note Text Mode::.

   If you set a fill prefix, then paragraphs are delimited by all lines
which don't start with the fill prefix.  *Note Filling::.

   The precise definition of a paragraph boundary is controlled by the
variables `paragraph-separate' and `paragraph-start'.  The value of
`paragraph-start' is a regular expression that should match lines that
either start or separate paragraphs (*note Regexps::).  The value of
`paragraph-separate' is another regular expression that should match
lines that separate paragraphs without being part of any paragraph (for
example, blank lines).  Lines that start a new paragraph and are
contained in it must match only `paragraph-start', not
`paragraph-separate'.  For example, in Fundamental mode,
`paragraph-start' is `"\f\\|[ \t]*$"', and `paragraph-separate' is
`"[ \t\f]*$"'.


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

25.4 Pages
==========

Within some text files, text is divided into "pages" delimited by the
"formfeed character" (ASCII code 12, also denoted as <control-L>),
which is displayed in Emacs as the escape sequence `^L' (*note Text
Display::).  Traditionally, when such text files are printed to
hardcopy, each formfeed character forces a page break.  Most Emacs
commands treat it just like any other character, so you can insert it
with `C-q C-l', delete it with <DEL>, etc.  In addition, Emacs provides
commands to move over pages and operate on them.

`M-x what-page'
     Display the page number of point, and the line number within that
     page.

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

   `M-x what-page' counts pages from the beginning of the file, and
counts lines within the page, showing both numbers in the echo area.

   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 (after that page delimiter at the front), and the mark
at the end of the page (after the page delimiter at the end).

   `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' specifies which page to go to,
relative to the current one.  Zero means the current page, one the next
page, and -1 the previous one.

   The `C-x l' command (`count-lines-page') is good for deciding where
to break a page in two.  It displays 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 regular expression that matches the beginning of a line that
separates pages (*note Regexps::).  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

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

* Menu:

* Auto Fill::      Auto Fill mode breaks long lines automatically.
* Fill Commands::  Commands to refill paragraphs and center lines.
* Fill Prefix::    Filling paragraphs that are indented or in a comment, etc.
* Adaptive Fill::  How Emacs can determine the fill prefix automatically.


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

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

"Auto Fill" mode is a buffer-local minor mode (*note Minor Modes::) 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.

   The mode command `M-x auto-fill-mode' toggles Auto Fill mode in the
current buffer.  With a positive numeric argument, it enables Auto Fill
mode, and with a negative argument it disables it.  If `auto-fill-mode'
is called from Lisp with an omitted or `nil' argument, it enables Auto
Fill mode.  To enable Auto Fill mode automatically in certain major
modes, add `auto-fill-mode' to the mode hooks (*note Major Modes::).
When Auto Fill mode is enabled, the mode indicator `Fill' appears in
the mode line (*note Mode Line::).

   Auto Fill mode breaks lines automatically at spaces whenever they
get longer than the desired width.  This line breaking occurs 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 C-j'
respectively.  Also, `C-o' inserts a newline without line breaking.

   When Auto Fill mode breaks a line, it tries to obey the "adaptive
fill prefix": if a fill prefix can be deduced from the first and/or
second line of the current paragraph, it is inserted into the new line
(*note Adaptive Fill::).  Otherwise the new line is indented, as though
you had typed <TAB> on it (*note Indentation::).  In a programming
language mode, if a line is broken in the middle of a comment, the
comment is split by inserting new comment delimiters as appropriate.

   Auto Fill mode does not refill entire paragraphs; it breaks lines
but does not merge lines.  Therefore, editing in the middle of a
paragraph can result in a paragraph that is not correctly filled.  To
fill it, call the explicit fill commands (*note Fill Commands::).


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

25.5.2 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-o M-s'
     Center a line.

   The command `M-q' (`fill-paragraph') "fills" the current paragraph.
It redistributes the line breaks within the paragraph, and deletes any
excess space and tab characters occurring within the paragraph, in such
a way that the lines end up fitting within a certain maximum width.

   Normally, `M-q' acts on the paragraph where point is, but if point
is between paragraphs, it acts on the paragraph after point.  If the
region is active, it acts instead on the text in the region.  You can
also call `M-x fill-region' to specifically fill the text in the region.

   `M-q' and `fill-region' use the usual Emacs criteria 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 as a single paragraph.  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' tells 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'.)

   The maximum line width for filling is specified by the buffer-local
variable `fill-column'.  The default value (*note Locals::) is 70.  The
easiest way to set `fill-column' in the current buffer 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.

   The command `M-o 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.  This binding is made by Text mode
and is available only in that and related modes (*note Text Mode::).

   By default, Emacs considers 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, not the end of a sentence.  Accordingly, the
fill commands will not break a line after a period followed by just one
space.  If you set the variable `sentence-end-double-space' to `nil',
the fill commands will break a line after a period followed by one
space, and put just one space after each period.  *Note Sentences::,
for other effects and possible drawbacks of this.

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

   To specify additional conditions where line-breaking is not allowed,
customize the abnormal hook variable `fill-nobreak-predicate' (*note
Hooks::).  Each function in this hook is called with no arguments, with
point positioned where Emacs is considering breaking a line.  If a
function returns a non-`nil' value, Emacs will not break the line
there.  Two functions you can use are `fill-single-word-nobreak-p'
(don't break after the first word of a sentence or before the last) and
`fill-french-nobreak-p' (don't break after `(' or before `)', `:' or
`?').


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

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

The "fill prefix" feature allows paragraphs to be filled so that each
line starts with a special string of characters (such as a sequence of
spaces, giving an indented paragraph).  You can specify a fill prefix
explicitly; otherwise, Emacs tries to deduce one automatically (*note
Adaptive Fill::).

`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 for the current buffer, move to a line that
starts with the desired prefix, put point at the end of the prefix, and
type `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 of the paragraph before filling, and insert it on
each line after filling.  (The beginning of the first line of the
paragraph is left unchanged, since often that is intentionally
different.)  Auto Fill mode also inserts the fill prefix automatically
when it makes a new line (*note Auto Fill::).  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 Enriched Indentation::.


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

25.5.4 Adaptive Filling
-----------------------

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 propagated to all lines of the
paragraph.

   If the paragraph has two or more lines, the fill prefix is taken from
the paragraph's second line, but only if it appears on the first line as
well.

   If a paragraph has just one line, fill commands _may_ take a prefix
from that line.  The decision is complicated because there are three
reasonable things to do in such a case:

   * Use the first line's prefix on all the lines of the paragraph.

   * Indent subsequent lines with whitespace, so that they line up
     under the text that follows the prefix on the first line, but
     don't actually copy the prefix from the first line.

   * Don't do anything special with the second and following lines.

   All three of these styles of formatting are commonly used.  So the
fill commands try to determine what you would like, based on the prefix
that appears and on the major mode.  Here is how.

   If the prefix found on the first line matches
`adaptive-fill-first-line-regexp', or if it appears to be a
comment-starting sequence (this depends on the major mode), then the
prefix found is used for filling the paragraph, provided it would not
act as a paragraph starter on subsequent lines.

   Otherwise, the prefix found is converted to an equivalent number of
spaces, and those spaces are used as the fill prefix for the rest of the
lines, provided they would not act as a paragraph starter on subsequent
lines.

   In Text mode, and other modes where only blank lines and page
delimiters separate paragraphs, the prefix chosen by adaptive filling
never acts as a paragraph starter, so it can always be used for filling.

   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 that match this regular expression are used.  If you set the
variable `adaptive-fill-mode' to `nil', the fill prefix is never chosen
automatically.

   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', `adaptive-fill-regexp' gets a chance to
find a prefix.


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

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

   `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
comparable to 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

25.7 Text Mode
==============

Text mode is a major mode for editing files of text in a human
language.  Files which have names ending in the extension `.txt' are
usually opened in Text mode (*note Choosing Modes::).  To explicitly
switch to Text mode, type `M-x text-mode'.

   In Text mode, only blank lines and page delimiters separate
paragraphs.  As a result, paragraphs can be indented, and adaptive
filling determines what indentation to use when filling a paragraph.
*Note Adaptive Fill::.

   In Text mode, the <TAB> (`indent-for-tab-command') command usually
inserts whitespace up to the next tab stop, instead of indenting the
current line.  *Note Indentation::, for details.

   Text mode turns off the features concerned with comments except when
you explicitly invoke them.  It changes the syntax table so that
single-quotes are considered part of words (e.g. `don't' is considered
one word).  However, if a word starts with a single-quote, it is
treated as a prefix for the purposes of capitalization (e.g. `M-c'
converts `'hello'' into `'Hello'', as expected).

   If you indent the first lines of paragraphs, then you should use
Paragraph-Indent Text mode (`M-x paragraph-indent-text-mode') rather
than Text mode.  In that mode, you do not need to have blank lines
between paragraphs, because the first-line indentation is sufficient to
start a paragraph; however paragraphs in which every line is indented
are not supported.  Use `M-x paragraph-indent-minor-mode' to enable an
equivalent minor mode for situations where you shouldn't change the
major mode--in mail composition, for instance.

   Text mode binds `M-<TAB>' to `ispell-complete-word'.  This command
performs completion of the partial word in the buffer before point,
using the spelling dictionary as the space of possible words.  *Note
Spelling::.  If your window manager defines `M-<TAB>' to switch
windows, you can type `<ESC> <TAB>' or `C-M-i' instead.

   Entering Text mode runs the mode hook `text-mode-hook' (*note Major
Modes::).

   The following sections describe several major modes that are
"derived" from Text mode.  These derivatives share most of the features
of Text mode described above.  In particular, derivatives of Text mode
run `text-mode-hook' prior to running their own mode hooks.


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

25.8 Outline Mode
=================

Outline mode is a major mode derived from Text mode, which is
specialized for editing outlines.  It provides commands to navigate
between entries in the outline structure, and commands to make parts of
a buffer temporarily invisible, so that the outline structure may be
more easily viewed.  Type `M-x outline-mode' to switch to Outline mode.
Entering Outline mode runs the hook `text-mode-hook' followed by the
hook `outline-mode-hook' (*note Hooks::).

   When you use an Outline mode command to make a line invisible (*note
Outline Visibility::), the line disappears from the screen.  An
ellipsis (three periods in a row) is displayed at the end of the
previous visible line, to indicate the hidden text.  Multiple
consecutive invisible lines produce just one ellipsis.

   Editing commands that operate on lines, such as `C-n' and `C-p',
treat the text of the invisible line as part of the previous visible
line.  Killing the ellipsis at the end of a visible line really kills
all the following invisible text associated with the ellipsis.

   Outline minor mode is a buffer-local minor mode which provides the
same commands as the major mode, Outline mode, but can be used in
conjunction with other major modes.  You can type `M-x
outline-minor-mode' to toggle Outline minor mode in the current buffer,
or use a file-local variable setting to enable it in a specific file
(*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.)

* Menu:

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


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

25.8.1 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 asterisk (`*')
characters; the number of asterisks determines the depth of the heading
in the outline structure.  Thus, a heading line with one `*' is a major
topic; all the heading lines with two `*'s between it and the next
one-`*' 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'.  (The recommended ways to do
this are in a major mode function or with a file local variable.)  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'.

   You can explicitly specify a 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.  The recommended ways to set
this variable are in a major mode command or with a file local variable.


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

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

   `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

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

Outline mode provides several commands for temporarily hiding or
revealing parts of the buffer, based on the outline structure.  These
commands are not undoable; their effects are simply not recorded by the
undo mechanism, so you can undo right past them (*note Undo::).

   Many of these commands act on the "current" heading line.  If point
is on a heading line, that is the current heading line; if point is on
a body line, the current heading line is the nearest preceding header
line.

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

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

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

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

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

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

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

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

   The simplest of these commands are `C-c C-c' (`hide-entry'), which
hides the body lines directly following the current heading line, and
`C-c C-e' (`show-entry'), which reveals them.  Subheadings and their
bodies are not affected.

   The commands `C-c C-d' (`hide-subtree') and `C-c C-s'
(`show-subtree') are more powerful.  They apply to the current heading
line's "subtree": its body, all of its subheadings, both direct and
indirect, and all of their bodies.

   The command `C-c C-l' (`hide-leaves') hides the body of the current
heading line as well as all the bodies in its subtree; the subheadings
themselves are left visible.  The command `C-c C-k' (`show-branches')
reveals the subheadings, if they had previously been hidden (e.g. by
`C-c C-d').  The command `C-c C-i' (`show-children') is a weaker
version of this; it reveals just the direct subheadings, i.e. those one
level down.

   The command `C-c C-o' (`hide-other') hides everything except the
entry that point is in, plus its parents (the headers leading up from
there to top level in the outline) and the top level headings.

   The remaining commands affect the whole buffer.  `C-c C-t'
(`hide-body') makes all body lines invisible, so that you see just the
outline structure (as a special exception, it will not hide lines at
the top of the file, preceding the first header line, even though these
are technically body lines).  `C-c C-a' (`show-all') makes all lines
visible.  `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.

   When incremental search finds text that is hidden by Outline mode,
it makes that part of the buffer visible.  If you exit the search at
that position, the text remains visible.  You can also automatically
make text visible as you navigate in it by using Reveal mode (`M-x
reveal-mode'), a buffer-local minor mode.


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

25.8.4 Viewing One Outline in Multiple Views
--------------------------------------------

You can display two views of a single outline at the same time, in
different windows.  To do this, 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.


File: emacs,  Node: Foldout,  Prev: Outline Views,  Up: Outline Mode

25.8.5 Folding Editing
----------------------

The Foldout package extends Outline mode and Outline minor mode with
"folding" commands.  The idea of folding is that you zoom in on a
nested portion of the outline, while hiding its relatives at higher
levels.

   Consider an Outline mode buffer with all the text and subheadings
under level-1 headings hidden.  To look at what is hidden under one of
these headings, you could use `C-c C-e' (`M-x show-entry') to expose
the body, or `C-c C-i' to expose the child (level-2) headings.

   With Foldout, you use `C-c C-z' (`M-x foldout-zoom-subtree').  This
exposes the body and child subheadings, and narrows the buffer so that
only the level-1 heading, the body and the level-2 headings are
visible.  Now to look under one of the level-2 headings, position the
cursor on it and use `C-c C-z' again.  This exposes the level-2 body
and its level-3 child subheadings and narrows the buffer again.  Zooming
in on successive subheadings can be done as much as you like.  A string
in the mode line shows how deep you've gone.

   When zooming in on a heading, to see only the child subheadings
specify a numeric argument: `C-u C-c C-z'.  The number of levels of
children can be specified too (compare `M-x show-children'), e.g. `M-2
C-c C-z' exposes two levels of child subheadings.  Alternatively, the
body can be specified with a negative argument: `M-- C-c C-z'.  The
whole subtree can be expanded, similarly to `C-c C-s' (`M-x
show-subtree'), by specifying a zero argument: `M-0 C-c C-z'.

   While you're zoomed in, you can still use Outline mode's exposure and
hiding functions without disturbing Foldout.  Also, since the buffer is
narrowed, "global" editing actions will only affect text under the
zoomed-in heading.  This is useful for restricting changes to a
particular chapter or section of your document.

   To unzoom (exit) a fold, use `C-c C-x' (`M-x foldout-exit-fold').
This hides all the text and subheadings under the top-level heading and
returns you to the previous view of the buffer.  Specifying a numeric
argument exits that many levels of folds.  Specifying a zero argument
exits all folds.

   To cancel the narrowing of a fold without hiding the text and
subheadings, specify a negative argument.  For example, `M--2 C-c C-x'
exits two folds and leaves the text and subheadings exposed.

   Foldout mode also provides mouse commands for entering and exiting
folds, and for showing and hiding text:

`C-M-Mouse-1' zooms in on the heading clicked on
          single click: expose body.

          double click: expose subheadings.

          triple click: expose body and subheadings.

          quad click: expose entire subtree.

`C-M-Mouse-2' exposes text under the heading clicked on
          single click: expose body.

          double click: expose subheadings.

          triple click: expose body and subheadings.

          quad click: expose entire subtree.

`C-M-Mouse-3' hides text under the heading clicked on or exits fold
          single click: hide subtree.

          double click: exit fold and hide text.

          triple click: exit fold without hiding text.

          quad click: exit all folds and hide text.

   You can specify different modifier keys (instead of `Control-Meta-')
by setting `foldout-mouse-modifiers'; but if you have already loaded
the `foldout.el' library, you must reload it in order for this to take
effect.

   To use the Foldout package, you can type `M-x load-library <RET>
foldout <RET>'; or you can arrange for to do that automatically by
putting the following in your init file:

     (eval-after-load "outline" '(require 'foldout))


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

25.9 Org Mode
=============

Org mode is a variant of Outline mode for using Emacs as an organizer
and/or authoring system.  Files with names ending in the extension
`.org' are opened in Org mode (*note Choosing Modes::).  To explicitly
switch to Org mode, type `M-x org-mode'.

   In Org mode, as in Outline mode, each entry has a heading line that
starts with one or more `*' characters.  *Note Outline Format::.  In
addition, any line that begins with the `#' character is treated as a
comment.

   Org mode provides commands for easily viewing and manipulating the
outline structure.  The simplest of these commands is <TAB>
(`org-cycle').  If invoked on a heading line, it cycles through the
different visibility states of the subtree: (i) showing only that
heading line, (ii) showing only the heading line and the heading lines
of its direct children, if any, and (iii) showing the entire subtree.
If invoked in a body line, the global binding for <TAB> is executed.

   Typing <S-TAB> (`org-shifttab') anywhere in an Org mode buffer
cycles the visibility of the entire outline structure, between (i)
showing only top-level heading lines, (ii) showing all heading lines
but no body lines, and (iii) showing everything.

   You can move an entire entry up or down in the buffer, including its
body lines and subtree (if any), by typing `M-<up>' (`org-metaup') or
`M-<down>' (`org-metadown') on the heading line.  Similarly, you can
promote or demote a heading line with `M-<left>' (`org-metaleft') and
`M-<right>' (`org-metaright').  These commands execute their global
bindings if invoked on a body line.

   The following subsections give basic instructions for using Org mode
as an organizer and as an authoring system.  For details, *note The Org
Mode Manual: (org)Top.

* Menu:

* Org Organizer::   Managing TODO lists and agendas.
* Org Authoring::   Exporting Org buffers to various formats.


File: emacs,  Node: Org Organizer,  Next: Org Authoring,  Up: Org Mode

25.9.1 Org as an organizer
--------------------------

You can tag an Org entry as a "TODO" item by typing `C-c C-t'
(`org-todo') anywhere in the entry.  This adds the keyword `TODO' to
the heading line.  Typing `C-c C-t' again switches the keyword to
`DONE'; another `C-c C-t' removes the keyword entirely, and so forth.
You can customize the keywords used by `C-c C-t' via the variable
`org-todo-keywords'.

   Apart from marking an entry as TODO, you can attach a date to it, by
typing `C-c C-s' (`org-schedule') in the entry.  This prompts for a
date by popping up the Emacs Calendar (*note Calendar/Diary::), and
then adds the tag `SCHEDULED', together with the selected date, beneath
the heading line.  The command `C-c C-d' (`org-deadline') has the same
effect, except that it uses the tag `DEADLINE'.

   Once you have some TODO items planned in an Org file, you can add
that file to the list of "agenda files" by typing `C-c ['
(`org-agenda-file-to-front').  Org mode is designed to let you easily
maintain multiple agenda files, e.g. for organizing different aspects
of your life.  The list of agenda files is stored in the variable
`org-agenda-files'.

   To view items coming from your agenda files, type `M-x org-agenda'.
This command prompts for what you want to see: a list of things to do
this week, a list of TODO items with specific keywords, etc.  *Note
Agenda Views: (org)Agenda Views, for details.


File: emacs,  Node: Org Authoring,  Prev: Org Organizer,  Up: Org Mode

25.9.2 Org as an authoring system
---------------------------------

You may want to format your Org notes nicely and to prepare them for
export and publication.  To export the current buffer, type `C-c C-e'
(`org-export') anywhere in an Org buffer.  This command prompts for an
export format; currently supported formats include HTML, LaTeX,
OpenDocument (`.odt'), and PDF.  Some formats, such as PDF, require
certain system tools to be installed.

   To export several files at once to a specific directory, either
locally or over the network, you must define a list of projects through
the variable `org-publish-project-alist'.  See its documentation for
details.

   Org supports a simple markup scheme for applying text formatting to
exported documents:

     - This text is /emphasized/
     - This text is *in bold*
     - This text is _underlined_
     - This text uses =a teletype font=

     #+begin_quote
     ``This is a quote.''
     #+end_quote

     #+begin_example
     This is an example.
     #+end_example

   For further details, see *note Exporting: (org)Exporting. and *note
Publishing: (org)Publishing.


File: emacs,  Node: TeX Mode,  Next: HTML Mode,  Prev: Org Mode,  Up: Text

25.10 TeX Mode
==============

Emacs provides special major modes for editing files written in TeX and
its related formats.  TeX is a powerful text formatter written by
Donald Knuth; like GNU Emacs, it is free software.  LaTeX is a
simplified input format for TeX, implemented using TeX macros.  DocTeX
is a special file format in which the LaTeX sources are written,
combining sources with documentation.  SliTeX is an obsolete special
form of LaTeX.(1)

   TeX mode has four variants: Plain TeX mode, LaTeX mode, DocTeX mode,
and SliTeX mode.  These distinct major modes differ only slightly, and
are designed for editing the four different formats.  Emacs selects the
appropriate mode by looking at the contents of the buffer.  (This is
done by the `tex-mode' command, which is normally called automatically
when you visit a TeX-like file.  *Note Choosing Modes::.)  If the
contents are insufficient to determine this, Emacs chooses the mode
specified by the variable `tex-default-mode'; its default value is
`latex-mode'.  If Emacs does not guess right, you can select the
correct variant of TeX mode using the command `M-x plain-tex-mode', `M-x
latex-mode', `M-x slitex-mode', or `doctex-mode'.

   The following sections document the features of TeX mode and its
variants.  There are several other TeX-related Emacs packages, which
are not documented in this manual:

   * BibTeX mode is a major mode for BibTeX files, which are commonly
     used for keeping bibliographic references for LaTeX documents.  For
     more information, see the documentation string for the command
     `bibtex-mode'.

   * The RefTeX package provides a minor mode which can be used with
     LaTeX mode to manage bibliographic references.  *Note The RefTeX
     Manual: (reftex)Top.

   * The AUCTeX package provides more advanced features for editing TeX
     and its related formats, including the ability to preview TeX
     equations within Emacs buffers.  Unlike BibTeX mode and the RefTeX
     package, AUCTeX is not distributed with Emacs by default.  It can
     be downloaded via the Package Menu (*note Packages::); once
     installed, see *note The AUCTeX Manual: (auctex)Top.

* Menu:

* TeX Editing::   Special commands for editing in TeX mode.
* LaTeX Editing:: Additional commands for LaTeX input files.
* TeX Print::     Commands for printing part of a file with TeX.
* TeX Misc::      Customization of TeX mode, and related features.

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

   (1) It has been replaced by the `slides' document class, which comes
with LaTeX.


File: emacs,  Node: TeX Editing,  Next: LaTeX Editing,  Up: TeX Mode

25.10.1 TeX Editing Commands
----------------------------

`"'
     Insert, according to context, either ```' or `"' or `'''
     (`tex-insert-quote').

`C-j'
     Insert a paragraph break (two newlines) and check the previous
     paragraph for unbalanced braces or dollar signs
     (`tex-terminate-paragraph').

`M-x tex-validate-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; instead, quotations
begin with ```' and end with `'''.  TeX mode therefore binds the `"'
key to the `tex-insert-quote' command.  This inserts ```' after
whitespace or an open brace, `"' after a backslash, and `''' after any
other character.

   As a special exception, if you type `"' when the text before point
is either ```' or `''', Emacs replaces that preceding text with a
single `"' character.  You can therefore type `""' to insert `"',
should you ever need to do so.  (You can also use `C-q "' to insert
this character.)

   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.  `C-j'
(`tex-terminate-paragraph') checks the paragraph before point, and
inserts two newlines to start a new paragraph.  It outputs a message in
the echo area if any mismatch is found.  `M-x tex-validate-region'
checks a region, paragraph by paragraph.  The errors are listed in an
`*Occur*' buffer; you can use the usual Occur mode commands in that
buffer, such as `C-c C-c', to visit a particular mismatch (*note Other
Repeating Search::).

   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

25.10.2 LaTeX Editing Commands
------------------------------

LaTeX mode provides 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 innermost LaTeX block not yet closed
     (`tex-close-latex-block').

   In LaTeX input, `\begin' and `\end' tags are used to group blocks of
text.  To insert a block, type `C-c C-o' (`tex-latex-block').  This
prompts for a block type, and inserts the appropriate matching `\begin'
and `\end' tags, leaving a blank line between the two and moving point
there.

   When entering the block type argument to `C-c C-o', you can use the
usual completion commands (*note Completion::).  The default completion
list contains the standard LaTeX block types.  If you want additional
block types for completion, customize the list variable
`latex-block-names'.

   In LaTeX input, `\begin' and `\end' tags must balance.  You can use
`C-c C-e' (`tex-close-latex-block') to insert an `\end' tag which
matches the last unmatched `\begin'.  It also indents the `\end' to
match the corresponding `\begin', and inserts a newline after the
`\end' tag if point is at the beginning of a line.  The minor mode
`latex-electric-env-pair-mode' automatically inserts an `\end' or
`\begin' tag for you when you type the corresponding one.


File: emacs,  Node: TeX Print,  Next: TeX Misc,  Prev: LaTeX Editing,  Up: TeX Mode

25.10.3 TeX Printing Commands
-----------------------------

You can invoke TeX as an subprocess of Emacs, supplying either the
entire contents of the buffer or just part of it (e.g. one chapter of a
larger document).

`C-c C-b'
     Invoke TeX on the entire current buffer (`tex-buffer').

`C-c C-r'
     Invoke TeX on the current region, together with the buffer's header
     (`tex-region').

`C-c C-f'
     Invoke TeX on the current file (`tex-file').

`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-p'
     Print the output from the last `C-c C-b', `C-c C-r', or `C-c C-f'
     command (`tex-print').

`C-c <TAB>'
     Invoke BibTeX on the current file (`tex-bibtex-file').

`C-c C-l'
     Recenter the window showing output from 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-c'
     Invoke some other compilation command on the entire current buffer
     (`tex-compile').

   To pass the current buffer through TeX, type `C-c C-b'
(`tex-buffer').  The formatted output goes in a temporary file,
normally a `.dvi' file.  Afterwards, you can type `C-c C-v'
(`tex-view') to launch an external program, such as `xdvi', to view
this output file.  You can also type `C-c C-p' (`tex-print') to print a
hardcopy of the output file.

   By default, `C-c C-b' runs TeX in the current directory.  The output
of TeX also goes in this directory.  To run TeX in a different
directory, change the variable `tex-directory' to the desired directory
name.  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"'.

   The buffer's TeX variant determines what shell command `C-c C-b'
actually runs.  In Plain TeX mode, it is specified by the variable
`tex-run-command', which defaults to `"tex"'.  In LaTeX mode, it is
specified by `latex-run-command', which defaults to `"latex"'.  The
shell command that `C-c C-v' runs to view the `.dvi' output is
determined by the variable `tex-dvi-view-command', regardless of the
TeX variant.  The shell command that `C-c C-p' runs to print the output
is determined by the variable `tex-dvi-print-command'.

   Normally, Emacs automatically appends the output file name to the
shell command strings described in the preceding paragraph.  For
example, if `tex-dvi-view-command' is `"xdvi"', `C-c C-v' runs `xdvi
OUTPUT-FILE-NAME'.  In some cases, however, the file name needs to be
embedded in the command, e.g. if 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 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 `\documentclass' or
`\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 for cross references, use `C-c
C-f' (`tex-file') which runs TeX on the current buffer's file, in that
file's directory.  Before running TeX, it offers to save any modified
buffers.  Generally, you need to use (`tex-file') twice to get the
cross-references right.

   The value of the variable `tex-start-options' specifies options for
the TeX run.

   The value of the variable `tex-start-commands' specifies TeX
commands for starting TeX.  The default value causes TeX to run in
nonstop mode.  To run TeX interactively, set the variable to `""'.

   Large TeX documents are often split into several files--one main
file, plus subfiles.  Running TeX on a subfile typically does not work;
you have to run it on the main file.  In order to make `tex-file'
useful when you are editing a subfile, you can set the variable
`tex-main-file' to the name of the main file.  Then `tex-file' runs TeX
on that file.

   The most convenient way to use `tex-main-file' is to specify it in a
local variable list in each of the subfiles.  *Note File Variables::.

   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.

   To invoke some other compilation program on the current TeX buffer,
type `C-c C-c' (`tex-compile').  This command knows how to pass
arguments to many common programs, including `pdflatex', `yap', `xdvi',
and `dvips'.  You can select your desired compilation program using the
standard completion keys (*note Completion::).


File: emacs,  Node: TeX Misc,  Prev: TeX Print,  Up: TeX Mode

25.10.4 TeX Mode Miscellany
---------------------------

Entering any variant of TeX mode runs the hooks `text-mode-hook' and
`tex-mode-hook'.  Then it runs either `plain-tex-mode-hook',
`latex-mode-hook', or `slitex-mode-hook', whichever is appropriate.
Starting the TeX shell runs the hook `tex-shell-hook'.  *Note Hooks::.

   The commands `M-x iso-iso2tex', `M-x iso-tex2iso', `M-x
iso-iso2gtex' and `M-x iso-gtex2iso' can be used to convert between
Latin-1 encoded files and TeX-encoded equivalents.


File: emacs,  Node: HTML Mode,  Next: Nroff Mode,  Prev: TeX Mode,  Up: Text

25.11 SGML and HTML Modes
=========================

The major modes for SGML and HTML provide indentation support and
commands for operating on tags.  HTML mode is a slightly customized
variant of SGML mode.

`C-c C-n'
     Interactively specify a special character and insert the SGML
     `&'-command for that character (`sgml-name-char').

`C-c C-t'
     Interactively specify a tag and its attributes (`sgml-tag').  This
     command asks you for a tag name and for the attribute values, then
     inserts both the opening tag and the closing tag, leaving point
     between them.

     With a prefix argument N, the command puts the tag around the N
     words already present in the buffer after point.  Whenever a
     region is active, it puts the tag around the region (when Transient
     Mark mode is off, it does this when a numeric argument of -1 is
     supplied.)

`C-c C-a'
     Interactively insert attribute values for the current tag
     (`sgml-attributes').

`C-c C-f'
     Skip across a balanced tag group (which extends from an opening tag
     through its corresponding closing tag) (`sgml-skip-tag-forward').
     A numeric argument acts as a repeat count.

`C-c C-b'
     Skip backward across a balanced tag group (which extends from an
     opening tag through its corresponding closing tag)
     (`sgml-skip-tag-backward').  A numeric argument acts as a repeat
     count.

`C-c C-d'
     Delete the tag at or after point, and delete the matching tag too
     (`sgml-delete-tag').  If the tag at or after point is an opening
     tag, delete the closing tag too; if it is a closing tag, delete the
     opening tag too.

`C-c ? TAG <RET>'
     Display a description of the meaning of tag TAG (`sgml-tag-help').
     If the argument TAG is empty, describe the tag at point.

`C-c /'
     Insert a close tag for the innermost unterminated tag
     (`sgml-close-tag').  If called within a tag or a comment, close it
     instead of inserting a close tag.

`C-c 8'
     Toggle a minor mode in which Latin-1 characters insert the
     corresponding SGML commands that stand for them, instead of the
     characters themselves (`sgml-name-8bit-mode').

`C-c C-v'
     Run a shell command (which you must specify) to validate the
     current buffer as SGML (`sgml-validate').

`C-c TAB'
     Toggle the visibility of existing tags in the buffer.  This can be
     used as a cheap preview (`sgml-tags-invisible').

   The major mode for editing XML documents is called nXML mode.  This
is a powerful major mode that can recognize many existing XML schema
and use them to provide completion of XML elements via `C-<RET>' or
`M-<TAB>', as well as "on-the-fly" XML validation with error
highlighting.  To enable nXML mode in an existing buffer, type `M-x
nxml-mode', or, equivalently, `M-x xml-mode'.  Emacs uses nXML mode for
files which have the extension `.xml'.  For XHTML files, which have the
extension `.xhtml', Emacs uses HTML mode by default; you can make it
use nXML mode by customizing the variable `auto-mode-alist' (*note
Choosing Modes::).  nXML mode is described in its own manual: *Note
nXML Mode: (nxml-mode)Top.

   You may choose to use the less powerful SGML mode for editing XML,
since XML is a strict subset of SGML.  To enable SGML mode in an
existing buffer, type `M-x sgml-mode'.  On enabling SGML mode, Emacs
examines the buffer to determine whether it is XML; if so, it sets the
variable `sgml-xml-mode' to a non-`nil' value.  This causes SGML mode's
tag insertion commands, described above, to always insert explicit
closing tags as well.


File: emacs,  Node: Nroff Mode,  Next: Enriched Text,  Prev: HTML Mode,  Up: Text

25.12 Nroff Mode
================

Nroff mode, a major mode derived from Text mode, is specialized for
editing nroff files (e.g. Unix man pages).  Type `M-x nroff-mode' to
enter this mode.  Entering Nroff mode runs the hook `text-mode-hook',
then `nroff-mode-hook' (*note Hooks::).

   In Nroff mode, nroff command lines are treated as paragraph
separators, pages are separated by `.bp' commands, and comments start
with backslash-doublequote.  It also defines these commands:

`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-?'
     Displays in the echo area the number of text lines (lines that are
     not nroff commands) in the region (`count-text-lines').

   Electric Nroff mode is a buffer-local minor mode that can be used
with Nroff mode.  To toggle this minor mode, type `M-x
electric-nroff-mode' (*note Minor Modes::).  When the mode is on, each
time you type <RET> to end a line containing an nroff command that
opens a kind of grouping, the nroff command to close that grouping is
automatically inserted on the following line.

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


File: emacs,  Node: Enriched Text,  Next: Text Based Tables,  Prev: Nroff Mode,  Up: Text

25.13 Enriched Text
===================

Enriched mode is a minor mode for editing formatted text files in a
WYSIWYG ("what you see is what you get") fashion.  When Enriched mode
is enabled, you can apply various formatting properties to the text in
the buffer, such as fonts and colors; upon saving the buffer, those
properties are saved together with the text, using the MIME
`text/enriched' file format.

   Enriched mode is typically used with Text mode (*note Text Mode::).
It is _not_ compatible with Font Lock mode, which is used by many major
modes, including most programming language modes, for syntax
highlighting (*note Font Lock::).  Unlike Enriched mode, Font Lock mode
assigns text properties automatically, based on the current buffer
contents; those properties are not saved to disk.

   The file `etc/enriched.doc' in the Emacs distribution serves as an
example of the features of Enriched mode.

* Menu:

* Enriched Mode::           Entering and exiting Enriched mode.
* Hard and Soft Newlines::  There are two different kinds of newlines.
* Editing Format Info::     How to edit text properties.
* Enriched Faces::          Bold, italic, underline, etc.
* Enriched Indentation::    Changing the left and right margins.
* Enriched Justification::  Centering, setting text flush with the
                              left or right margin, etc.
* Enriched Properties::     The "special" text properties submenu.


File: emacs,  Node: Enriched Mode,  Next: Hard and Soft Newlines,  Up: Enriched Text

25.13.1 Enriched Mode
---------------------

Enriched mode is a buffer-local minor mode (*note Minor Modes::).  When
you visit a file that has been saved in the `text/enriched' format,
Emacs automatically enables Enriched mode, and applies the formatting
information in the file to the buffer text.  When you save a buffer
with Enriched mode enabled, it is saved using the `text/enriched'
format, including the formatting information.

   To create a new file of formatted text, visit the nonexistent file
and type `M-x enriched-mode'.  This command actually toggles Enriched
mode.  With a prefix argument, it enables Enriched mode if the argument
is positive, and disables Enriched mode otherwise.  If you disable
Enriched mode, Emacs no longer saves the buffer using the
`text/enriched' format; any formatting properties that have been added
to the buffer remain in the buffer, but they are not saved to disk.

   Enriched mode does not save all Emacs text properties, only those
specified in the variable `enriched-translations'.  These include
properties for fonts, colors, indentation, and justification.

   If you visit a file and Emacs fails to recognize that it is in the
`text/enriched' format, type `M-x format-decode-buffer'.  This command
prompts for a file format, and re-reads the file in that format.
Specifying the `text/enriched' format automatically enables Enriched
mode.

   To view a `text/enriched' file in raw form (as plain text with
markup tags rather than formatted text), use `M-x find-file-literally'
(*note Visiting::).

   *Note Format Conversion: (elisp)Format Conversion, for details of
how Emacs recognizes and converts file formats like `text/enriched'.
*Note Text Properties: (elisp)Text Properties, for more information
about text properties.


File: emacs,  Node: Hard and Soft Newlines,  Next: Editing Format Info,  Prev: Enriched Mode,  Up: Enriched Text

25.13.2 Hard and Soft Newlines
------------------------------

In Enriched mode, Emacs distinguishes between two different kinds of
newlines, "hard" newlines and "soft" newlines.  You can also enable or
disable this feature in other buffers, by typing `M-x
use-hard-newlines'.

   Hard newlines are used to separate paragraphs, or anywhere there
needs to be a line break regardless of how the text is filled; soft
newlines are used for filling.  The <RET> (`newline') and `C-o'
(`open-line') commands insert hard newlines.  The fill commands,
including Auto Fill (*note Auto Fill::), insert only soft newlines and
delete only soft newlines, leaving hard newlines alone.

   Thus, when editing with Enriched mode, you should not use <RET> or
`C-o' to break lines in the middle of filled paragraphs.  Use Auto Fill
mode or explicit fill commands (*note Fill Commands::) instead.  Use
<RET> or `C-o' where line breaks should always remain, such as in
tables and lists.  For such lines, you may also want to set the
justification style to `unfilled' (*note Enriched Justification::).


File: emacs,  Node: Editing Format Info,  Next: Enriched Faces,  Prev: Hard and Soft Newlines,  Up: Enriched Text

25.13.3 Editing Format Information
----------------------------------

The easiest way to alter properties is with the Text Properties menu.
You can get to this menu from the Edit menu in the menu bar (*note Menu
Bar::), or with `C-Mouse-2' (*note Menu Mouse Clicks::).  Some of the
commands in the Text Properties menu are listed below (you can also
invoke them with `M-x'):

`Remove Face Properties'
     Remove face properties from the region
     (`facemenu-remove-face-props').

`Remove Text Properties'
     Remove all text properties from the region, including face
     properties (`facemenu-remove-all').

`Describe Properties'
     List all text properties and other information about the character
     following point (`describe-text-properties').

`Display Faces'
     Display a list of defined faces (`list-faces-display').  *Note
     Faces::.

`Display Colors'
     Display a list of defined colors (`list-colors-display').  *Note
     Colors::.

The other menu entries are described in the following sections.


File: emacs,  Node: Enriched Faces,  Next: Enriched Indentation,  Prev: Editing Format Info,  Up: Enriched Text

25.13.4 Faces in Enriched Text
------------------------------

The following commands can be used to add or remove faces (*note
Faces::).  Each applies to the text in the region if the mark is
active, and to the next self-inserting character if the mark is
inactive.  With a prefix argument, each command applies to the next
self-inserting character even if the region is active.

`M-o d'
     Remove all `face' properties (`facemenu-set-default').

`M-o b'
     Apply the `bold' face (`facemenu-set-bold').

`M-o i'
     Apply the `italic' face (`facemenu-set-italic').

`M-o l'
     Apply the `bold-italic' face (`facemenu-set-bold-italic').

`M-o u'
     Apply the `underline' face (`facemenu-set-underline').

`M-o o FACE <RET>'
     Apply the face FACE (`facemenu-set-face').

`M-x facemenu-set-foreground'
     Prompt for a color (*note Colors::), and apply it as a foreground
     color.

`M-x facemenu-set-background'
     Prompt for a color, and apply it as a background color.

These command are also available via the Text Properties menu.

   A self-inserting character normally inherits the face properties
(and most other text properties) from the preceding character in the
buffer.  If you use one of the above commands to specify the face for
the next self-inserting character, that character will not inherit the
faces properties from the preceding character, but it will still
inherit other text properties.

   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; by default, it appears the
same as `italic'.  The `fixed' face specifies fixed-width text; by
default, it appears the same as `bold'.


File: emacs,  Node: Enriched Indentation,  Next: Enriched Justification,  Prev: Enriched Faces,  Up: Enriched Text

25.13.5 Indentation in Enriched Text
------------------------------------

In Enriched mode, you can specify different amounts of indentation for
the right or left margin of a paragraph or a part of a paragraph.
These margins also affect fill commands such as `M-q' (*note Filling::).

   The Indentation submenu of Text Properties offers commands for
specifying indentation:

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

   The variable `standard-indent' specifies how many columns these
commands should add to or subtract from the indentation.  The default
value is 4.  The default right margin for Enriched mode is controlled
by the variable `fill-column', as usual.

   You can also type `C-c [' (`set-left-margin') and `C-c ]'
(`set-right-margin') to set the left and right margins.  You can
specify the margin width with a numeric argument; otherwise these
commands prompt for a value via the minibuffer.

   The fill prefix, if any, works in addition to the specified paragraph
indentation: `C-x .' does not include the specified indentation's
whitespace in the new value for the fill prefix, and the fill commands
look for the fill prefix after the indentation on each line.  *Note
Fill Prefix::.


File: emacs,  Node: Enriched Justification,  Next: Enriched Properties,  Prev: Enriched Indentation,  Up: Enriched Text

25.13.6 Justification in Enriched Text
--------------------------------------

In Enriched mode, you can use the following commands to specify various
"justification styles" for filling.  These commands apply to the
paragraph containing point, or, if the region is active, to all
paragraphs overlapping the region.

`M-j l'
     Align lines to the left margin (`set-justification-left').

`M-j r'
     Align lines to the right margin (`set-justification-right').

`M-j b'
     Align lines to both margins, inserting spaces in the middle of the
     line to achieve this (`set-justification-full').

`M-j c'
`M-S'
     Center lines between the margins (`set-justification-center').

`M-j u'
     Turn off filling entirely (`set-justification-none').  The fill
     commands do nothing on text with this setting.  You can, however,
     still indent the left margin.

   You can also specify justification styles using the Justification
submenu in the Text Properties menu.    The default justification style
is specified by the per-buffer variable `default-justification'.  Its
value should be one of the symbols `left', `right', `full', `center', or
`none'.


File: emacs,  Node: Enriched Properties,  Prev: Enriched Justification,  Up: Enriched Text

25.13.7 Setting Other Text Properties
-------------------------------------

The Special Properties submenu of Text Properties has entries for
adding or removing three other text properties: `read-only', (which
disallows alteration of the text), `invisible' (which hides text), and
`intangible' (which disallows moving point within the text).  The
`Remove Special' menu item removes all of these special properties from
the text in the region.

   The `invisible' and `intangible' properties are not saved.


File: emacs,  Node: Text Based Tables,  Next: Two-Column,  Prev: Enriched Text,  Up: Text

25.14 Editing Text-based Tables
===============================

The `table' package provides commands to easily edit text-based tables.
Here is an example of what such a table looks like:

     +-----------------+--------------------------------+-----------------+
     |     Command     |          Description           |   Key Binding   |
     +-----------------+--------------------------------+-----------------+
     |  forward-char   |Move point right N characters   |       C-f       |
     |                 |(left if N is negative).        |                 |
     |                 |                                |                 |
     +-----------------+--------------------------------+-----------------+
     |  backward-char  |Move point left N characters    |       C-b       |
     |                 |(right if N is negative).       |                 |
     |                 |                                |                 |
     +-----------------+--------------------------------+-----------------+

   When Emacs recognizes such a stretch of text as a table (*note Table
Recognition::), editing the contents of each table cell will
automatically resize the table, whenever the contents become too large
to fit in the cell.  You can use the commands defined in the following
sections for navigating and editing the table layout.

   Type `M-x table-fixed-width-mode' to toggle the automatic table
resizing feature.

* Menu:

* Table Definition::          What is a text based table.
* Table Creation::            How to create a table.
* Table Recognition::         How to activate and deactivate tables.
* Cell Commands::             Cell-oriented commands in a table.
* Cell Justification::        Justifying cell contents.
* Table Rows and Columns::    Inserting and deleting rows and columns.
* Table Conversion::          Converting between plain text and tables.
* Table Misc::                Table miscellany.


File: emacs,  Node: Table Definition,  Next: Table Creation,  Up: Text Based Tables

25.14.1 What is a Text-based Table?
-----------------------------------

A "table" consists of a rectangular text area which is divided into
"cells".  Each cell must be at least one character wide and one
character high, not counting its border lines.  A cell can be
subdivided into more cells, but they cannot overlap.

   Cell border lines are drawn with three special characters, specified
by the following variables:

`table-cell-vertical-char'
     The character used for vertical lines.  The default is `|'.

`table-cell-horizontal-chars'
     The characters used for horizontal lines.  The default is `"-="'.

`table-cell-intersection-char'
     The character used for the intersection of horizontal and vertical
     lines.  The default is `+'.

The following are examples of _invalid_ tables:

        +-----+       +--+    +-++--+
        |     |       |  |    | ||  |
        |     |       |  |    | ||  |
        +--+  |    +--+--+    +-++--+
        |  |  |    |  |  |    +-++--+
        |  |  |    |  |  |    | ||  |
        +--+--+    +--+--+    +-++--+
           a          b          c

From left to right:

  a. Overlapped cells or non-rectangular cells are not allowed.

  b. The border must be rectangular.

  c. Cells must have a minimum width/height of one character.


File: emacs,  Node: Table Creation,  Next: Table Recognition,  Prev: Table Definition,  Up: Text Based Tables

25.14.2 Creating a Table
------------------------

To create a text-based table from scratch, type `M-x table-insert'.
This command prompts for the number of table columns, the number of
table rows, cell width and cell height.  The cell width and cell height
do not include the cell borders; each can be specified as a single
integer (which means each cell is given the same width/height), or as a
sequence of integers separated by spaces or commas (which specify the
width/height of the individual table columns/rows, counting from left
to right for table columns and from top to bottom for table rows).  The
specified table is then inserted at point.

   The table inserted by `M-x table-insert' contains special text
properties, which tell Emacs to treat it specially as a text-based
table.  If you save the buffer to a file and visit it again later,
those properties are lost, and the table appears to Emacs as an
ordinary piece of text.  See the next section, for how to convert it
back into a table.


File: emacs,  Node: Table Recognition,  Next: Cell Commands,  Prev: Table Creation,  Up: Text Based Tables

25.14.3 Table Recognition
-------------------------

Existing text-based tables in a buffer, which lack the special text
properties applied by `M-x table-insert', are not treated specially as
tables.  To apply those text properties, type `M-x table-recognize'.
This command scans the current buffer, "recognizes" valid table cells,
and applies the relevant text properties.  Conversely, type `M-x
table-unrecognize' to "unrecognize" all tables in the current buffer,
removing the special text properties and converting tables back to
plain text.

   You can also use the following commands to selectively recognize or
unrecognize tables:

`M-x table-recognize-region'
     Recognize tables within the current region.

`M-x table-unrecognize-region'
     Unrecognize tables within the current region.

`M-x table-recognize-table'
     Recognize the table at point and activate it.

`M-x table-unrecognize-table'
     Deactivate the table at point.

`M-x table-recognize-cell'
     Recognize the cell at point and activate it.

`M-x table-unrecognize-cell'
     Deactivate the cell at point.

   *Note Table Conversion::, for another way to recognize a table.


File: emacs,  Node: Cell Commands,  Next: Cell Justification,  Prev: Table Recognition,  Up: Text Based Tables

25.14.4 Commands for Table Cells
--------------------------------

The commands `M-x table-forward-cell' and `M-x table-backward-cell'
move point from the current cell to an adjacent cell.  The order is
cyclic: when point is in the last cell of a table, `M-x
table-forward-cell' moves to the first cell.  Likewise, when point is
on the first cell, `M-x table-backward-cell' moves to the last cell.

   `M-x table-span-cell' prompts for a direction--right, left, above,
or below--and merges the current cell with the adjacent cell in that
direction.  This command signals an error if the merge would result in
an illegitimate cell layout.

   `M-x table-split-cell' splits the current cell vertically or
horizontally, prompting for the direction with the minibuffer.  To
split in a specific direction, use `M-x table-split-cell-vertically'
and `M-x table-split-cell-horizontally'.  When splitting vertically,
the old cell contents are automatically split between the two new
cells.  When splitting horizontally, you are prompted for how to divide
the cell contents, if the cell is non-empty; the options are `split'
(divide the contents at point), `left' (put all the contents in the
left cell), and `right' (put all the contents in the right cell).

   The following commands enlarge or shrink a cell.  By default, they
resize by one row or column; if a numeric argument is supplied, that
specifies the number of rows or columns to resize by.

`M-x table-heighten-cell'
     Enlarge the current cell vertically.

`M-x table-shorten-cell'
     Shrink the current cell vertically.

`M-x table-widen-cell'
     Enlarge the current cell horizontally.

`M-x table-narrow-cell'
     Shrink the current cell horizontally.


File: emacs,  Node: Cell Justification,  Next: Table Rows and Columns,  Prev: Cell Commands,  Up: Text Based Tables

25.14.5 Cell Justification
--------------------------

The command `M-x table-justify' imposes "justification" on one or more
cells in a text-based table.  Justification determines how the text in
the cell is aligned, relative to the edges of the cell.  Each cell in a
table can be separately justified.

   `M-x table-justify' first prompts for what to justify; the options
are `cell' (just the current cell), `column' (all cells in the current
table column) and `row' (all cells in the current table row).  The
command then prompts for the justification style; the options are
`left', `center', `right', `top', `middle', `bottom', or `none'
(meaning no vertical justification).

   Horizontal and vertical justification styles are specified
independently, and both types can be in effect simultaneously; for
instance, you can call `M-x table-justify' twice, once to specify
`right' justification and once to specify `bottom' justification, to
align the contents of a cell to the bottom right.

   The justification style is stored in the buffer as a text property,
and is lost when you kill the buffer or exit Emacs.  However, the table
recognition commands, such as `M-x table-recognize' (*note Table
Recognition::), attempt to determine and re-apply each cell's
justification style, by examining its contents.  To disable this
feature, change the variable `table-detect-cell-alignment' to `nil'.


File: emacs,  Node: Table Rows and Columns,  Next: Table Conversion,  Prev: Cell Justification,  Up: Text Based Tables

25.14.6 Table Rows and Columns
------------------------------

`M-x table-insert-row' inserts a row of cells before the current table
row.  The current row, together with point, is pushed down past the new
row.  To insert a row after the last row at the bottom of a table,
invoke this command with point below the table, just below the bottom
edge.  You can insert more than one row at a time by using a numeric
prefix argument.

   Similarly, `M-x table-insert-column' inserts a column of cells to
the left of the current table column.  To insert a column to the right
side of the rightmost column, invoke this command with point to the
right of the rightmost column, outside the table.  A numeric prefix
argument specifies the number of columns to insert.

   `M-x table-delete-column' deletes the column of cells at point.
Similarly, `M-x table-delete-row' deletes the row of cells at point.  A
numeric prefix argument to either command specifies the number of
columns or rows to delete.


File: emacs,  Node: Table Conversion,  Next: Table Misc,  Prev: Table Rows and Columns,  Up: Text Based Tables

25.14.7 Converting Between Plain Text and Tables
------------------------------------------------

The command `M-x table-capture' captures plain text in a region and
turns it into a table.  Unlike `M-x table-recognize' (*note Table
Recognition::), the original text does not need to have a table
appearance; it only needs to have a logical table-like structure.

   For example, suppose we have the following numbers, which are
divided into three lines and separated horizontally by commas:

     1, 2, 3, 4
     5, 6, 7, 8
     , 9, 10

Invoking `M-x table-capture' on that text produces this table:

     +-----+-----+-----+-----+
     |1    |2    |3    |4    |
     +-----+-----+-----+-----+
     |5    |6    |7    |8    |
     +-----+-----+-----+-----+
     |     |9    |10   |     |
     +-----+-----+-----+-----+

   `M-x table-release' does the opposite: it converts a table back to
plain text, removing its cell borders.

   One application of this pair of commands is to edit a text in
layout.  Look at the following three paragraphs (the latter two are
indented with header lines):

     table-capture is a powerful command.
     Here are some things it can do:

     Parse Cell Items   Using row and column delimiter regexps,
                        it parses the specified text area and
                        extracts cell items into a table.

Applying `table-capture' to a region containing the above text, with
empty strings for the column and row delimiter regexps, creates a table
with a single cell like the following one.

     +----------------------------------------------------------+
     |table-capture is a powerful command.                      |
     |Here are some things it can do:                           |
     |                                                          |
     |Parse Cell Items   Using row and column delimiter regexps,|
     |                   it parses the specified text area and  |
     |                   extracts cell items into a table.      |
     +----------------------------------------------------------+

We can then use the cell splitting commands (*note Cell Commands::) to
subdivide the table so that each paragraph occupies a cell:

     +----------------------------------------------------------+
     |table-capture is a powerful command.                      |
     |Here are some things it can do:                           |
     +-----------------+----------------------------------------+
     |Parse Cell Items | Using row and column delimiter regexps,|
     |                 | it parses the specified text area and  |
     |                 | extracts cell items into a table.      |
     +-----------------+----------------------------------------+

Each cell can now be edited independently without affecting the layout
of other cells.  When finished, we can invoke `M-x table-release' to
convert the table back to plain text.


File: emacs,  Node: Table Misc,  Prev: Table Conversion,  Up: Text Based Tables

25.14.8 Table Miscellany
------------------------

The command `table-query-dimension' reports the layout of the table and
table cell at point.  Here is an example of its output:

     Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5

This indicates that the current cell is 21 characters wide and 6 lines
high, the table is 67 characters wide and 16 lines high with 2 columns
and 3 rows, and a total of 5 cells.

   `M-x table-insert-sequence' inserts a string into each cell.  Each
string is a part of a sequence i.e. a series of increasing integer
numbers.

   `M-x table-generate-source' generates a table formatted for a
specific markup language.  It asks for a language (which must be one of
`html', `latex', or `cals'), a destination buffer in which to put the
result, and a table caption, and then inserts the generated table into
the specified buffer.  The default destination buffer is `table.LANG',
where LANG is the language you specified.


File: emacs,  Node: Two-Column,  Prev: Text Based Tables,  Up: Text

25.15 Two-Column Editing
========================

Two-column mode lets you conveniently edit two side-by-side columns of
text.  It uses two side-by-side windows, each showing its own buffer.
There are three ways to enter two-column mode:

`<F2> 2' or `C-x 6 2'
     Enter two-column mode with the current buffer on the left, and on
     the right, a buffer whose name is based on the current buffer's
     name (`2C-two-columns').  If the right-hand buffer doesn't already
     exist, it starts out empty; the current buffer's contents are not
     changed.

     This command is appropriate when the current buffer is empty or
     contains just one column and you want to add another column.

`<F2> s' or `C-x 6 s'
     Split the current buffer, which contains two-column text, into two
     buffers, and display them side by side (`2C-split').  The current
     buffer becomes the left-hand buffer, but the text in the right-hand
     column is moved into the right-hand buffer.  The current column
     specifies the split point.  Splitting starts with the current line
     and continues to the end of the buffer.

     This command is appropriate when you have a buffer that already
     contains two-column text, and you wish to separate the columns
     temporarily.

`<F2> b BUFFER <RET>'
`C-x 6 b BUFFER <RET>'
     Enter two-column mode using the current buffer as the left-hand
     buffer, and using buffer BUFFER as the right-hand buffer
     (`2C-associate-buffer').

   `<F2> s' or `C-x 6 s' looks for a column separator, which is a
string that appears on each line between the two columns.  You can
specify the width of the separator with a numeric argument to `<F2> s';
that many characters, before point, constitute the separator string.
By default, the width is 1, so the column separator is the character
before point.

   When a line has the separator at the proper place, `<F2> s' puts the
text after the separator into the right-hand buffer, and deletes the
separator.  Lines that don't have the column separator at the proper
place remain unsplit; they stay in the left-hand buffer, and the
right-hand buffer gets an empty line to correspond.  (This is the way
to write a line that "spans both columns while in two-column mode":
write it in the left-hand buffer, and put an empty line in the
right-hand buffer.)

   The command `C-x 6 <RET>' or `<F2> <RET>' (`2C-newline') inserts a
newline in each of the two buffers at corresponding positions.  This is
the easiest way to add a new line to the two-column text while editing
it in split buffers.

   When you have edited both buffers as you wish, merge them with `<F2>
1' or `C-x 6 1' (`2C-merge').  This copies the text from the right-hand
buffer as a second column in the other buffer.  To go back to
two-column editing, use `<F2> s'.

   Use `<F2> d' or `C-x 6 d' to dissociate the two buffers, leaving
each as it stands (`2C-dissociate').  If the other buffer, the one not
current when you type `<F2> d', is empty, `<F2> d' kills it.


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

26 Editing Programs
*******************

This chapter describes Emacs features for facilitating editing
programs.  Some of the things these features can do are:

   * Find or move over top-level definitions (*note Defuns::).

   * Apply the usual indentation conventions of the language (*note
     Program Indent::).

   * Balance parentheses (*note Parentheses::).

   * Insert, kill or align comments (*note Comments::).

   * Highlight program syntax (*note Font Lock::).

* Menu:

* Program Modes::       Major modes for editing programs.
* Defuns::              Commands to operate on major top-level parts
                          of a program.
* Program Indent::      Adjusting indentation to show the nesting.
* Parentheses::         Commands that operate on parentheses.
* Comments::            Inserting, killing, and aligning comments.
* Documentation::       Getting documentation of functions you plan to call.
* Hideshow::            Displaying blocks selectively.
* Symbol Completion::   Completion on symbol names of your program or language.
* Glasses::             Making identifiersLikeThis more readable.
* Semantic::            Suite of editing tools based on source code parsing.
* Misc for Programs::   Other Emacs features useful for editing programs.
* C Modes::             Special commands of C, C++, Objective-C, Java,
                          IDL, Pike and AWK modes.
* Asm Mode::            Asm mode and its special features.

* Fortran::             Fortran mode and its special features.


File: emacs,  Node: Program Modes,  Next: Defuns,  Up: Programs

26.1 Major Modes for Programming Languages
==========================================

Emacs has specialized major modes (*note Major Modes::) for many
programming languages.  A programming language mode typically specifies
the syntax of expressions, the customary rules for indentation, how to
do syntax highlighting for the language, and how to find the beginning
or end of a function definition.  It often has features for compiling
and debugging programs as well.  The major mode for each language is
named after the language; for instance, the major mode for the C
programming language is `c-mode'.

   Emacs has programming language modes for Lisp, Scheme, the
Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi,
Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont (TeX's
companion for font creation), Modula2, Objective-C, Octave, Pascal,
Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL.
An alternative mode for Perl is called CPerl mode.  Modes are also
available for the scripting languages of the common GNU and Unix
shells, VMS DCL, and MS-DOS/MS-Windows `BAT' files, and for makefiles,
DNS master files, and various sorts of configuration files.

   Ideally, Emacs should have a major mode for each programming
language that you might want to edit.  If it doesn't have a mode for
your favorite language, the mode might be implemented in a package not
distributed with Emacs (*note Packages::); or you can contribute one.

   In most programming languages, indentation should vary from line to
line to illustrate the structure of the program.  Therefore, in most
programming language modes, typing <TAB> updates the indentation of the
current line (*note Program Indent::).  Furthermore, <DEL> is usually
bound to `backward-delete-char-untabify', which deletes backward
treating each tab as if it were the equivalent number of spaces, so
that you can delete one column of indentation without worrying whether
the whitespace consists of spaces or tabs.

   Entering a programming language mode runs the custom Lisp functions
specified in the hook variable `prog-mode-hook', followed by those
specified in the mode's own mode hook (*note Major Modes::).  For
instance, entering C mode runs the hooks `prog-mode-hook' and
`c-mode-hook'.  *Note Hooks::, for information about hooks.

   Separate manuals are available for the modes for Ada (*note Ada
Mode: (ada-mode)Top.), C/C++/Objective C/Java/Corba IDL/Pike/AWK (*note
CC Mode: (ccmode)Top.), and IDLWAVE (*note IDLWAVE: (idlwave)Top.).


File: emacs,  Node: Defuns,  Next: Program Indent,  Prev: Program Modes,  Up: Programs

26.2 Top-Level Definitions, or Defuns
=====================================

In Emacs, a major definition at the top level in the buffer, such as a
function, is called a "defun".  The name comes from Lisp, but in Emacs
we use it for all languages.

* Menu:

* Left Margin Paren::   An open-paren or similar opening delimiter
                          starts a defun if it is at the left margin.
* Moving by Defuns::    Commands to move over or mark a major definition.
* Imenu::               Making buffer indexes as menus.
* Which Function::      Which Function mode shows which function you are in.


File: emacs,  Node: Left Margin Paren,  Next: Moving by Defuns,  Up: Defuns

26.2.1 Left Margin Convention
-----------------------------

Many programming-language modes assume by default that any opening
delimiter found at the left margin is the start of a top-level
definition, or defun.  Therefore, *don't put an opening delimiter at
the left margin unless it should have that significance*.  For
instance, never put an open-parenthesis at the left margin in a Lisp
file unless it is the start of a top-level list.

   The convention speeds up many Emacs operations, which would
otherwise have to scan back to the beginning of the buffer to analyze
the syntax of the code.

   If you don't follow this convention, not only will you have trouble
when you explicitly use the commands for motion by defuns; other
features that use them will also give you trouble.  This includes the
indentation commands (*note Program Indent::) and Font Lock mode (*note
Font Lock::).

   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.  This will not affect the
contents of the string, but will prevent that opening delimiter from
starting a defun.  Here's an example:

       (insert "Foo:
     \(bar)
     ")

   To help you catch violations of this convention, Font Lock mode
highlights confusing opening delimiters (those that ought to be quoted)
in bold red.

   If you need to override this convention, you can do so by setting
the variable `open-paren-in-column-0-is-defun-start'.  If this user
option is set to `t' (the default), opening parentheses or braces at
column zero always start defuns.  When it is `nil', defuns are found by
searching for parens or braces at the outermost level.

   Usually, you should leave this option at its default value of `t'.
If your buffer contains parentheses or braces in column zero which
don't start defuns, and it is somehow impractical to remove these
parentheses or braces, it might be helpful to set the option to `nil'.
Be aware that this might make scrolling and display in large buffers
quite sluggish.  Furthermore, the parentheses and braces must be
correctly matched throughout the buffer for it to work properly.


File: emacs,  Node: Moving by Defuns,  Next: Imenu,  Prev: Left Margin Paren,  Up: Defuns

26.2.2 Moving by Defuns
-----------------------

These commands move point or set up the region based on top-level major
definitions, also called "defuns".

`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 repeat one of these commands, or use a positive numeric argument,
each repetition moves to the next defun in the direction of motion.

   `C-M-a' with a negative argument -N moves forward N times to the
next beginning of a defun.  This is not exactly the same place that
`C-M-e' with argument N would move to; the end of this defun is not
usually exactly the same place as the beginning of the following defun.
(Whitespace, comments, and perhaps declarations can separate them.)
Likewise, `C-M-e' with a negative argument moves back to an end of a
defun, which is not quite the same as `C-M-a' with a positive argument.

   To operate on the current defun, use `C-M-h' (`mark-defun'), which
sets the mark at the end of the current defun and puts point at its
beginning.  *Note Marking Objects::.  This is the easiest way to get
ready to kill the defun in order to move it to a different place in the
file.  If you use the command while point is between defuns, it uses
the following defun.  If you use the command while the mark is already
active, it sets the mark but does not move point; furthermore, each
successive use of `C-M-h' extends the end of the region to include one
more defun.

   In C mode, `C-M-h' runs the function `c-mark-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.  This is an example of
how major modes adjust the standard key bindings so that they do their
standard jobs in a way better fitting a particular language.  Other
major modes may replace any or all of these key bindings for that
purpose.


File: emacs,  Node: Imenu,  Next: Which Function,  Prev: Moving by Defuns,  Up: Defuns

26.2.3 Imenu
------------

The Imenu facility offers a way to find the major definitions in a file
by name.  It is also useful in text formatter major modes, where it
treats each chapter, section, etc., as a definition.  (*Note Tags::,
for a more powerful feature that handles multiple files together.)

   If you type `M-x imenu', it reads the name of a definition using the
minibuffer, then moves point to that definition.  You can use
completion to specify the name; the command always displays the whole
list of valid names.

   Alternatively, you can bind the command `imenu' to a mouse click.
Then it displays mouse menus for you to select a definition name.  You
can also add the buffer's index to the menu bar by calling
`imenu-add-menubar-index'.  If you want to have this menu bar item
available for all buffers in a certain major mode, you can do this by
adding `imenu-add-menubar-index' to its mode hook.  But if you have
done that, you will have to wait a little while each time you visit a
file in that mode, while Emacs finds all the definitions in that buffer.

   When you change the contents of a buffer, if you add or delete
definitions, you can update the buffer's index based on the new
contents by invoking the `*Rescan*' item in the menu.  Rescanning
happens automatically if you set `imenu-auto-rescan' to a non-`nil'
value.  There is no need to rescan because of small changes in the text.

   You can customize the way the menus are sorted by setting the
variable `imenu-sort-function'.  By default, names are ordered as they
occur in the buffer; if you want alphabetic sorting, use the symbol
`imenu--sort-by-name' as the value.  You can also define your own
comparison function by writing Lisp code.

   Imenu provides the information to guide Which Function mode (*note
Which Function::).  The Speedbar can also use it (*note Speedbar::).


File: emacs,  Node: Which Function,  Prev: Imenu,  Up: Defuns

26.2.4 Which Function Mode
--------------------------

Which Function mode is a global minor mode (*note Minor Modes::) which
displays the current function name in the mode line, updating it as you
move around in a buffer.

   To either enable or disable Which Function mode, use the command
`M-x which-function-mode'.  Although Which Function mode is a global
minor mode, it takes effect only in certain major modes: those listed
in the variable `which-func-modes'.  If the value of `which-func-modes'
is `t' rather than a list of modes, then Which Function mode applies to
all major modes that know how to support it--in other words, all the
major modes that support Imenu.


File: emacs,  Node: Program Indent,  Next: Parentheses,  Prev: Defuns,  Up: Programs

26.3 Indentation for Programs
=============================

The best way to keep a program properly indented is to use Emacs to
reindent it as you change it.  Emacs has commands to indent either a
single line, a specified number of lines, or all of the lines inside a
single parenthetical grouping.

   *Note Indentation::, for general information about indentation.  This
section describes indentation features specific to programming language
modes.

* 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 and related modes.
* Custom C Indent::     Controlling indentation style for C and related modes.

   Emacs also provides a Lisp pretty-printer in the `pp' package, which
reformats Lisp objects with nice-looking indentation.


File: emacs,  Node: Basic Indent,  Next: Multi-line Indent,  Up: Program Indent

26.3.1 Basic Program Indentation Commands
-----------------------------------------

`<TAB>'
     Adjust indentation of current line (`indent-for-tab-command').

`C-j'
     Insert a newline, then adjust indentation of following line
     (`newline-and-indent').

   The basic indentation command is <TAB> (`indent-for-tab-command'),
which was documented in *note Indentation::.  In programming language
modes, <TAB> indents the current line, based on the indentation and
syntactic content of the preceding lines; if the region is active,
<TAB> indents each line within the region, not just the current line.

   The command `C-j' (`newline-and-indent'), which was documented in
*note Indentation Commands::, does the same as <RET> followed by <TAB>:
it inserts a new line, then adjusts the line's indentation.

   When indenting a line that starts within a parenthetical grouping,
Emacs usually places the start of the line under the preceding line
within the group, or under the text after the parenthesis.  If you
manually give one of these lines a nonstandard indentation (e.g. for
aesthetic purposes), the lines below will follow it.

   The indentation commands for most programming language modes assume
that a open-parenthesis, open-brace or other opening delimiter at the
left margin is the start of a function.  If the code you are editing
violates this assumption--even if the delimiters occur in strings or
comments--you must set `open-paren-in-column-0-is-defun-start' to `nil'
for indentation to work properly.  *Note Left Margin Paren::.


File: emacs,  Node: Multi-line Indent,  Next: Lisp Indent,  Prev: Basic Indent,  Up: Program Indent

26.3.2 Indenting Several Lines
------------------------------

Sometimes, you may want to reindent several lines of code at a time.
One way to do this is to use the mark; when the mark is active and the
region is non-empty, <TAB> indents every line in the region.
Alternatively, the command `C-M-\' (`indent-region') indents every line
in the region, whether or not the mark is active (*note Indentation
Commands::).

   In addition, Emacs provides the following commands for indenting
large chunks of code:

`C-M-q'
     Reindent all the lines within one parenthetical grouping.

`C-u <TAB>'
     Shift an entire parenthetical grouping rigidly sideways so that its
     first line is properly indented.

`M-x indent-code-rigidly'
     Shift all the lines in the region rigidly sideways, but do not
     alter lines that start inside comments and strings.

   To reindent the contents of a single parenthetical grouping,
position point before the beginning of the grouping and type `C-M-q'.
This changes the relative indentation within the grouping, without
affecting its overall indentation (i.e. the indentation of the line
where the grouping starts).  The function that `C-M-q' runs depends on
the major mode; it is `indent-pp-sexp' in Lisp mode, `c-indent-exp' in
C mode, etc.  To correct the overall indentation as well, type <TAB>
first.

   If you like the relative indentation within a grouping but not the
indentation of its first line, move point to that first line and type
`C-u <TAB>'.  In Lisp, C, and some other major modes, <TAB> with a
numeric argument reindents the current line as usual, then reindents by
the same amount all the lines in the parenthetical grouping starting on
the current line.  It is clever, though, and does not alter lines that
start inside strings.  Neither does it alter C preprocessor lines when
in C mode, but it does reindent any continuation lines that may be
attached to them.

   The command `M-x indent-code-rigidly' rigidly shifts all the lines
in the region sideways, like `indent-rigidly' does (*note Indentation
Commands::).  It doesn't alter the indentation of lines that start
inside a string, unless the region also starts inside that string.  The
prefix arg specifies the number of columns to indent.


File: emacs,  Node: Lisp Indent,  Next: C Indent,  Prev: Multi-line Indent,  Up: Program Indent

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

   Certain functions override the standard pattern.  Functions whose
names start with `def' treat the second lines as the start of a "body",
by indenting the second line `lisp-body-indent' additional columns
beyond the open-parenthesis that starts the expression.

   You can override the standard pattern in various ways for individual
functions, according to the `lisp-indent-function' property of the
function name.  This is normally done for macro definitions, using the
`declare' construct.  *Note Defining Macros: (elisp)Defining Macros.


File: emacs,  Node: C Indent,  Next: Custom C Indent,  Prev: Lisp Indent,  Up: Program Indent

26.3.4 Commands for C Indentation
---------------------------------

Here are special features 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 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 (or the equivalent number of spaces,
     if `indent-tabs-mode' is `nil').

     Any other value (not `nil' or `t') means always reindent the line,
     and also insert a tab if within a comment or a string.

   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

26.3.5 Customizing C Indentation
--------------------------------

C mode and related modes use a flexible mechanism for customizing
indentation.  C mode indents a source line in two steps: first it
classifies the line syntactically according to its contents and
context; second, it determines the indentation offset associated by
your selected "style" with the syntactic construct and adds this onto
the indentation of the "anchor statement".

`C-c . <RET> STYLE <RET>'
     Select a predefined style STYLE (`c-set-style').

   A "style" is a named collection of customizations that can be used
in C mode and the related modes.  *note Styles: (ccmode)Styles, for a
complete description.  Emacs comes with several predefined styles,
including `gnu', `k&r', `bsd', `stroustrup', `linux', `python', `java',
`whitesmith', `ellemtel', and `awk'.  Some of these styles are
primarily intended for one language, but any of them can be used with
any of the languages supported by these modes.  To find out what a
style looks like, select it and reindent some code, e.g., by typing
<C-M-q> at the start of a function definition.

   To choose a style for the current buffer, use the command `C-c .'.
Specify a style name as an argument (case is not significant).  This
command affects the current buffer only, and it affects only future
invocations of the indentation commands; it does not reindent the code
already in the buffer.  To reindent the whole buffer in the new style,
you can type `C-x h C-M-\'.

   You can also set the variable `c-default-style' to specify the
default style for various major modes.  Its value should be either the
style's name (a string) or an alist, in which each element specifies
one major mode and which indentation style to use for it.  For example,

     (setq c-default-style
           '((java-mode . "java")
             (awk-mode . "awk")
             (other . "gnu")))

specifies explicit choices for Java and AWK modes, and the default
`gnu' style for the other C-like modes.  (These settings are actually
the defaults.)  This variable takes effect when you select one of the
C-like major modes; thus, if you specify a new default style for Java
mode, you can make it take effect in an existing Java mode buffer by
typing `M-x java-mode' there.

   The `gnu' style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.

   *Note Indentation Engine Basics: (ccmode)Indentation Engine Basics,
and *note Customizing Indentation: (ccmode)Customizing Indentation, for
more information on customizing indentation for C and related modes,
including how to override parts of an existing style and how to define
your own styles.

   As an alternative to specifying a style, you can tell Emacs to guess
a style by typing `M-x c-guess' in a sample code buffer.  You can then
apply the guessed style to other buffers with `M-x c-guess-install'.
*Note Guessing the Style: (ccmode)Guessing the Style, for details.


File: emacs,  Node: Parentheses,  Next: Comments,  Prev: Program Indent,  Up: Programs

26.4 Commands for Editing with Parentheses
==========================================

This section describes the commands and features that take advantage of
the parenthesis structure in a program, or help you keep it balanced.

   When talking about these facilities, the term "parenthesis" also
includes braces, brackets, or whatever delimiters are defined to match
in pairs.  The major mode controls which delimiters are significant,
through the syntax table (*note Syntax Tables: (elisp)Syntax Tables.).
In Lisp, only parentheses count; in C, these commands apply to braces
and brackets too.

   You can use `M-x check-parens' to find any unbalanced parentheses
and unbalanced string quotes in the buffer.

* Menu:

* Expressions::         Expressions with balanced parentheses.
* Moving by Parens::    Commands for moving up, down and across
                          in the structure of parentheses.
* Matching::            Insertion of a close-delimiter flashes matching open.


File: emacs,  Node: Expressions,  Next: Moving by Parens,  Up: Parentheses

26.4.1 Expressions with Balanced Parentheses
--------------------------------------------

Each programming language mode has its own definition of a "balanced
expression".  Balanced expressions typically include individual
symbols, numbers, and string constants, as well as pieces of code
enclosed in a matching pair of delimiters.  The following commands deal
with balanced expressions (in Emacs, such expressions are referred to
internally as "sexps"(1)).

`C-M-f'
     Move forward over a balanced expression (`forward-sexp').

`C-M-b'
     Move backward over a balanced expression (`backward-sexp').

`C-M-k'
     Kill balanced expression forward (`kill-sexp').

`C-M-t'
     Transpose expressions (`transpose-sexps').

`C-M-@'
`C-M-<SPC>'
     Put mark after following expression (`mark-sexp').

   To move forward over a balanced expression, use `C-M-f'
(`forward-sexp').  If the first significant character after point is an
opening delimiter (e.g. `(', `[' or `{' in C), this command moves past
the matching closing delimiter.  If the character begins a symbol,
string, or number, the command moves over that.

   The command `C-M-b' (`backward-sexp') moves backward over a balanced
expression--like `C-M-f', but in the reverse direction.  If the
expression is preceded by any prefix characters (single-quote,
backquote and comma, in Lisp), the command moves back over them as well.

   `C-M-f' or `C-M-b' with an argument repeats that operation the
specified number of times; with a negative argument means to move in
the opposite direction.  In most modes, these two commands move across
comments as if they were whitespace.  Note that their keys, `C-M-f' and
`C-M-b', are analogous to `C-f' and `C-b', which move by characters
(*note Moving Point::), and `M-f' and `M-b', which move by words (*note
Words::).

   To kill a whole balanced expression, type `C-M-k' (`kill-sexp').
This kills the text that `C-M-f' would move over.

   `C-M-t' (`transpose-sexps') switches the positions of the previous
balanced expression and the next one.  It is analogous to the `C-t'
command, which transposes characters (*note Transpose::).  An argument
to `C-M-t' serves as a repeat count, moving the previous expression
over that many following ones.  A negative argument moves the previous
balanced expression backwards across those before it.  An argument of
zero, rather than doing nothing, transposes the balanced expressions
ending at or after point and the mark.

   To operate on balanced expressions with a command which acts on the
region, type `C-M-<SPC>' (`mark-sexp').  This sets the mark where
`C-M-f' would move to.  While the mark is active, each successive call
to this command extends the region by shifting the mark by one
expression.  Positive or negative numeric arguments move the mark
forward or backward by the specified number of expressions.  The alias
`C-M-@' is equivalent to `C-M-<SPC>'.  *Note Marking Objects::, for
more information about this and related commands.

   In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions because there can be multiple
possibilities at a given position.  For example, C mode does not treat
`foo + bar' as a single expression, even though it _is_ one C
expression; instead, it recognizes `foo' as one expression and `bar' as
another, with the `+' as punctuation between them.  However, C mode
recognizes `(foo + bar)' as a single expression, because of the
parentheses.

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

   (1) The word "sexp" is used to refer to an expression in Lisp.


File: emacs,  Node: Moving by Parens,  Next: Matching,  Prev: Expressions,  Up: Parentheses

26.4.2 Moving in the Parenthesis Structure
------------------------------------------

The following commands move over groupings delimited by parentheses (or
whatever else serves as delimiters in the language you are working
with).  They ignore strings and comments, including any parentheses
within them, and also ignore parentheses that are "quoted" with an
escape character.  These commands are mainly intended for editing
programs, but can be useful for editing any text containing
parentheses.  They are referred to internally as "list" commands
because in Lisp these groupings are lists.

   These commands assume that the starting point is not inside a string
or a comment.  If you invoke them from inside a string or comment, the
results are unreliable.

`C-M-n'
     Move forward over a parenthetical group (`forward-list').

`C-M-p'
     Move backward over a parenthetical group (`backward-list').

`C-M-u'
     Move up in parenthesis structure (`backward-up-list').

`C-M-d'
     Move down in parenthesis structure (`down-list').

   The "list" commands `C-M-n' (`forward-list') and `C-M-p'
(`backward-list') move forward or backward over one (or N)
parenthetical groupings.

   `C-M-n' and `C-M-p' try to stay at the same level in the parenthesis
structure.  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 the direction of motion, so that the command
moves forward and up one or more levels.

   To move _down_ in the parenthesis 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 to go down.


File: emacs,  Node: Matching,  Prev: Moving by Parens,  Up: Parentheses

26.4.3 Matching Parentheses
---------------------------

Emacs has a number of "parenthesis matching" features, which make it
easy to see how and whether parentheses (or other delimiters) match up.

   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, Emacs displays some of the text near it in the echo area.
Either way, you can tell which grouping you are closing off.  If the
opening delimiter and closing delimiter are mismatched--such as in
`[x)'--a warning message is displayed in the echo area.

   Three variables control the display of matching parentheses:

   * `blink-matching-paren' turns the feature on or off: `nil' disables
     it, but the default is `t' to enable it.

   * `blink-matching-delay' says how many seconds to leave the cursor
     on the matching opening delimiter, before bringing it back to the
     real location of point.  This may be an integer or floating-point
     number; the default is 1.

   * `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 distance, Emacs stops scanning and nothing is
     displayed.  The default is 102400.

   Show Paren mode, a global minor mode, provides a more powerful kind
of automatic matching.  Whenever point is before an opening delimiter
or after a closing delimiter, both that delimiter and its opposite
delimiter are highlighted.  To toggle Show Paren mode, type `M-x
show-paren-mode'.

   Electric Pair mode, a global minor mode, provides a way to easily
insert matching delimiters.  Whenever you insert an opening delimiter,
the matching closing delimiter is automatically inserted as well,
leaving point between the two.  To toggle Electric Pair mode, type `M-x
electric-pair-mode'.


File: emacs,  Node: Comments,  Next: Documentation,  Prev: Parentheses,  Up: Programs

26.5 Manipulating Comments
==========================

Because comments are such an important part of programming, Emacs
provides special commands for editing and inserting comments.  It can
also do spell checking on comments with Flyspell Prog mode (*note
Spelling::).

   Some major modes have special rules for indenting different kinds of
comments.  For example, in Lisp code, comments starting with two
semicolons are indented as if they were lines of code, while those
starting with three semicolons are supposed to be aligned to the left
margin and are often used for sectioning purposes.  Emacs understand
these conventions; for instance, typing <TAB> on a comment line will
indent the comment to the appropriate position.

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

* Menu:

* Comment Commands::    Inserting, killing, and aligning comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.


File: emacs,  Node: Comment Commands,  Next: Multi-Line Comments,  Up: Comments

26.5.1 Comment Commands
-----------------------

The following commands operate on comments:

`M-;'
     Insert or realign comment on current line; if the region is active,
     comment or uncomment the region instead (`comment-dwim').

`C-u M-;'
     Kill comment on current line (`comment-kill').

`C-x ;'
     Set comment column (`comment-set-column').

`C-M-j'
`M-j'
     Like <RET> followed by inserting and aligning a comment
     (`comment-indent-new-line').  *Note Multi-Line Comments::.

`M-x comment-region'
`C-c C-c' (in C-like modes)
     Add comment delimiters to all the lines in the region.

   The command to create or align a comment is `M-;' (`comment-dwim').
The word "dwim" is an acronym for "Do What I Mean"; it indicates that
this command can be used for many different jobs relating to comments,
depending on the situation where you use it.

   When a region is active (*note Mark::), `M-;' either adds comment
delimiters to the region, or removes them.  If every line in the region
is already a comment, it "uncomments" each of those lines by removing
their comment delimiters.  Otherwise, it adds comment delimiters to
enclose the text in the region.

   If you supply a prefix argument to `M-;' when a region is active,
that specifies the number of comment delimiters to add or delete.  A
positive argument N adds N delimiters, while a negative argument -N
removes N delimiters.

   If the region is not active, and there is no existing comment on the
current line, `M-;' adds a new comment to the current line.  If the
line is blank (i.e. empty or containing only whitespace characters),
the comment is indented to the same position where <TAB> would indent
to (*note Basic Indent::).  If the line is non-blank, the comment is
placed after the last non-whitespace character on the line; normally,
Emacs tries putting it at the column specified by the variable
`comment-column' (*note Options for Comments::), but if the line
already extends past that column, it puts the comment at some suitable
position, usually separated from the non-comment text by at least one
space.  In each case, Emacs places point after the comment's starting
delimiter, so that you can start typing the comment text right away.

   You can also use `M-;' to align an existing comment.  If a line
already contains the comment-start string, `M-;' realigns it to the
conventional alignment and moves point after the comment's starting
delimiter.  As an exception, comments starting in column 0 are not
moved.  Even when an existing comment is properly aligned, `M-;' is
still useful for moving directly to the start of the comment text.

   `C-u M-;' (`comment-dwim' with a prefix argument) kills any comment
on the current line, along with the whitespace before it.  Since the
comment is saved to the kill ring, you can reinsert it on another line
by moving to the end of that line, doing `C-y', and then `M-;' to
realign the comment.  You can achieve the same effect as `C-u M-;' by
typing `M-x comment-kill' (`comment-dwim' actually calls `comment-kill'
as a subroutine when it is given a prefix argument).

   The command `M-x comment-region' is equivalent to calling `M-;' on
an active region, except that it always acts on the region, even if the
mark is inactive.  In C mode and related modes, this command is bound
to `C-c C-c'.  The command `M-x uncomment-region' uncomments each line
in the region; a numeric prefix argument specifies the number of
comment delimiters to remove (negative arguments specify the number of
comment to delimiters to add).

   For C-like modes, you can configure the exact effect of `M-;' by
setting the variables `c-indent-comment-alist' and
`c-indent-comments-syntactically-p'.  For example, on a line ending in
a closing brace, `M-;' puts the comment one space after the brace
rather than at `comment-column'.  For full details see *note Comment
Commands: (ccmode)Comment Commands.


File: emacs,  Node: Multi-Line Comments,  Next: Options for Comments,  Prev: Comment Commands,  Up: Comments

26.5.2 Multiple Lines of Comments
---------------------------------

If you are typing a comment and wish to continue it to another line,
type `M-j' or `C-M-j' (`comment-indent-new-line').  This breaks the
current line, and inserts the necessary comment delimiters and
indentation to continue the comment.

   For languages with closing comment delimiters (e.g. `*/' in C), the
exact behavior of `M-j' depends on the value of the variable
`comment-multi-line'.  If the value is `nil', the command closes the
comment on the old line and starts a new comment on the new line.
Otherwise, it opens a new line within the current comment delimiters.

   When Auto Fill mode is on, going past the fill column while typing a
comment also continues the comment, in the same way as an explicit
invocation of `M-j'.

   To turn existing lines into comment lines, use `M-;' with the region
active, or use `M-x comment-region' (*note Comment Commands::).

   You can configure C Mode such that when you type a `/' at the start
of a line in a multi-line block comment, this closes the comment.
Enable the `comment-close-slash' clean-up for this.  *Note Clean-ups:
(ccmode)Clean-ups.


File: emacs,  Node: Options for Comments,  Prev: Multi-Line Comments,  Up: Comments

26.5.3 Options Controlling Comments
-----------------------------------

As mentioned in *note Comment Commands::, when the `M-j' command adds a
comment to a line, it tries to place the comment at the column
specified by the buffer-local variable `comment-column'.  You can set
either the local value or the default value of this buffer-local
variable in the usual way (*note Locals::).  Alternatively, you can
type `C-x ;' (`comment-set-column') to set the value of
`comment-column' in the current buffer to the column where point is
currently located.  `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.

   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
`"\\(//+\\|/\\*+\\)\\s *"', which matches extra stars and spaces after
the `/*' itself, and accepts C++ style comments also.  (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 Regexp Backslash::.)

   When a comment command makes a new comment, it inserts the value of
`comment-start' as an opening comment delimiter.  It also inserts the
value of `comment-end' after point, as a closing comment delimiter.
For example, in Lisp mode, `comment-start' is `";"' and `comment-end'
is `""' (the empty string).  In C mode, `comment-start' is `"/* "' and
`comment-end' is `" */"'.

   The variable `comment-padding' specifies a string that the
commenting commands should insert between the comment delimiter(s) and
the comment text.  The default, `" "', specifies a single space.
Alternatively, the value can be a number, which specifies that number
of spaces, or `nil', which means no spaces at all.

   The variable `comment-multi-line' controls how `M-j' and Auto Fill
mode continue comments over multiple lines.  *Note Multi-Line
Comments::.

   The variable `comment-indent-function' should contain a function
that will be called to compute the alignment 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: Documentation,  Next: Hideshow,  Prev: Comments,  Up: Programs

26.6 Documentation Lookup
=========================

Emacs provides several features you can use to look up the
documentation of functions, variables and commands that you plan to use
in your program.

* Menu:

* Info Lookup::         Looking up library functions and commands in Info files.
* Man Page::            Looking up man pages of library functions and commands.
* Lisp Doc::            Looking up Emacs Lisp functions, etc.


File: emacs,  Node: Info Lookup,  Next: Man Page,  Up: Documentation

26.6.1 Info Documentation Lookup
--------------------------------

For major modes that apply to languages which have documentation in
Info, you can use `C-h S' (`info-lookup-symbol') to view the Info
documentation for a symbol used in the program.  You specify the symbol
with the minibuffer; the default is the symbol appearing in the buffer
at point.  For example, in C mode this looks for the symbol in the C
Library Manual.  The command only works if the appropriate manual's
Info files are installed.

   The major mode determines where to look for documentation for the
symbol--which Info files to look in, and which indices to search.  You
can also use `M-x info-lookup-file' to look for documentation for a
file name.

   If you use `C-h S' in a major mode that does not support it, it asks
you to specify the "symbol help mode".  You should enter a command such
as `c-mode' that would select a major mode which `C-h S' does support.


File: emacs,  Node: Man Page,  Next: Lisp Doc,  Prev: Info Lookup,  Up: Documentation

26.6.2 Man Page Lookup
----------------------

On Unix, the main form of on-line documentation was the "manual page"
or "man page".  In the GNU operating system, we aim to replace man
pages with better-organized manuals that you can browse with Info
(*note Misc Help::).  This process is not finished, so it is still
useful to read manual pages.

   You can read the man page for an operating system command, library
function, or system call, with the `M-x man' command.  This prompts for
a topic, with completion (*note Completion::), and runs the `man'
program to format the corresponding man page.  If the system permits,
it runs `man' asynchronously, so that you can keep on editing while the
page is being formatted.  The result goes in a buffer named `*Man
TOPIC*'.  These buffers use a special major mode, Man mode, that
facilitates scrolling and jumping to other manual pages.  For details,
type `C-h m' while in a Man mode buffer.

   Each man page belongs to one of ten or more "sections", each named
by a digit or by a digit and a letter.  Sometimes there are man pages
with the same name in different sections.  To read a man page from a
specific section, type `TOPIC(SECTION)' or `SECTION TOPIC' when `M-x
manual-entry' prompts for the topic.  For example, the man page for the
C library function `chmod' is in section 2, but there is a shell
command of the same name, whose man page is in section 1; to view the
former, type `M-x manual-entry <RET> chmod(2) <RET>'.

   If you do not specify a section, `M-x man' normally displays only
the first man page found.  On some systems, the `man' program accepts a
`-a' command-line option, which tells it to display all the man pages
for the specified topic.  To make use of this, change the value of the
variable `Man-switches' to `"-a"'.  Then, in the Man mode buffer, you
can type `M-n' and `M-p' to switch between man pages in different
sections.  The mode line shows how many manual pages are available.

   An alternative way of reading manual pages is the `M-x woman'
command.  Unlike `M-x man', it does not run any external programs to
format and display the man pages; the formatting is done by Emacs, so
it works on systems such as MS-Windows where the `man' program may be
unavailable.  It prompts for a man page, and displays it in a buffer
named `*WoMan SECTION TOPIC'.

   `M-x woman' computes the completion list for manpages the first time
you invoke the command.  With a numeric argument, it recomputes this
list; this is useful if you add or delete manual pages.

   If you type a name of a manual page and `M-x woman' finds that
several manual pages by the same name exist in different sections, it
pops up a window with possible candidates asking you to choose one of
them.

   For more information about setting up and using `M-x woman', see
*note WoMan: (woman)Top.


File: emacs,  Node: Lisp Doc,  Prev: Man Page,  Up: Documentation

26.6.3 Emacs Lisp Documentation Lookup
--------------------------------------

When editing Emacs Lisp code, you can use the commands `C-h f'
(`describe-function') and `C-h v' (`describe-variable') to view the
built-in documentation for the Lisp functions and variables that you
want to use.  *Note Name Help::.

   Eldoc is a buffer-local minor mode that helps with looking up Lisp
documention.  When it is enabled, the echo area displays some useful
information whenever there is a Lisp function or variable at point; for
a function, it shows the argument list, and for a variable it shows the
first line of the variable's documentation string.  To toggle Eldoc
mode, type `M-x eldoc-mode'.  Eldoc mode can be used with the Emacs
Lisp and Lisp Interaction major modes.


File: emacs,  Node: Hideshow,  Next: Symbol Completion,  Prev: Documentation,  Up: Programs

26.7 Hideshow minor mode
========================

Hideshow mode is a buffer-local minor mode that allows you to
selectively display portions of a program, which are referred to as
"blocks".  Type `M-x hs-minor-mode' to toggle this minor mode (*note
Minor Modes::).

   When you use Hideshow mode to hide a block, the block disappears
from the screen, to be replaced by an ellipsis (three periods in a
row).  Just what constitutes a block depends on the major mode.  In C
mode and related modes, blocks are delimited by braces, while in Lisp
mode they are delimited by parentheses.  Multi-line comments also count
as blocks.

   Hideshow mode provides the following commands:

`C-c @ C-h'
     Hide the current block (`hs-hide-block').

`C-c @ C-s'
     Show the current block (`hs-show-block').

`C-c @ C-c'
     Either hide or show the current block (`hs-toggle-hiding').

`S-Mouse-2'
     Toggle hiding for the block you click on
     (`hs-mouse-toggle-hiding').

`C-c @ C-M-h'
     Hide all top-level blocks (`hs-hide-all').

`C-c @ C-M-s'
     Show all blocks in the buffer (`hs-show-all').

`C-c @ C-l'
     Hide all blocks N levels below this block (`hs-hide-level').

   These variables can be used to customize Hideshow mode:

`hs-hide-comments-when-hiding-all'
     If non-`nil', `C-c @ C-M-h' (`hs-hide-all') hides comments too.

`hs-isearch-open'
     This variable specifies the conditions under which incremental
     search should unhide a hidden block when matching text occurs
     within the block.  Its value should be either `code' (unhide only
     code blocks), `comment' (unhide only comments), `t' (unhide both
     code blocks and comments), or `nil' (unhide neither code blocks
     nor comments).  The default value is `code'.


File: emacs,  Node: Symbol Completion,  Next: Glasses,  Prev: Hideshow,  Up: Programs

26.8 Completion for Symbol Names
================================

Completion is normally done in the minibuffer (*note Completion::), but
you can also complete symbol names in ordinary Emacs buffers.

   In programming language modes, type `C-M-i' or `M-<TAB>' to complete
the partial symbol before point.  On graphical displays, the `M-<TAB>'
key is usually reserved by the window manager for switching graphical
windows, so you should type `C-M-i' or `<ESC> <TAB>' instead.

   In most programming language modes, `C-M-i' (or `M-<TAB>') invokes
the command `completion-at-point', which generates its completion list
in a flexible way.  If Semantic mode is enabled, it tries to use the
Semantic parser data for completion (*note Semantic::).  If Semantic
mode is not enabled or fails at performing completion, it tries to
complete using the selected tags table (*note Tags::).  If in Emacs
Lisp mode, it performs completion using the function, variable, or
property names defined in the current Emacs session.

   In all other respects, in-buffer symbol completion behaves like
minibuffer completion.  For instance, if Emacs cannot complete to a
unique symbol, it displays a list of completion alternatives in another
window.  *Note Completion::.

   In Text mode and related modes, `M-<TAB>' completes words based on
the spell-checker's dictionary.  *Note Spelling::.


File: emacs,  Node: Glasses,  Next: Semantic,  Prev: Symbol Completion,  Up: Programs

26.9 Glasses minor mode
=======================

Glasses mode is a buffer-local minor mode that makes it easier to read
mixed-case (or "CamelCase") symbols like `unReadableSymbol', by
altering how they are displayed.  By default, it displays extra
underscores between each lower-case letter and the following capital
letter.  This does not alter the buffer text, only how it is displayed.

   To toggle Glasses mode, type `M-x glasses-mode' (*note Minor
Modes::).  When Glasses mode is enabled, the minor mode indicator `o^o'
appears in the mode line.  For more information about Glasses mode,
type `C-h P glasses <RET>'.


File: emacs,  Node: Semantic,  Next: Misc for Programs,  Prev: Glasses,  Up: Programs

26.10 Semantic
==============

Semantic is a package that provides language-aware editing commands
based on `source code parsers'.  This section provides a brief
description of Semantic; for full details, see *note Semantic:
(semantic)Top.

   Most of the "language aware" features in Emacs, such as Font Lock
mode (*note Font Lock::), rely on "rules of thumb"(1) that usually give
good results but are never completely exact.  In contrast, the parsers
used by Semantic have an exact understanding of programming language
syntax.  This allows Semantic to provide search, navigation, and
completion commands that are powerful and precise.

   To begin using Semantic, type `M-x semantic-mode' or click on the
menu item named `Source Code Parsers (Semantic)' in the `Tools' menu.
This enables Semantic mode, a global minor mode.

   When Semantic mode is enabled, Emacs automatically attempts to
parses each file you visit.  Currently, Semantic understands C, C++,
Scheme, Javascript, Java, HTML, and Make.  Within each parsed buffer,
the following commands are available:

`C-c , j'
     Prompt for the name of a function defined in the current file, and
     move point there (`semantic-complete-jump-local').

`C-c , J'
     Prompt for the name of a function defined in any file Emacs has
     parsed, and move point there (`semantic-complete-jump').

`C-c , <SPC>'
     Display a list of possible completions for the symbol at point
     (`semantic-complete-analyze-inline').  This also activates a set
     of special key bindings for choosing a completion: <RET> accepts
     the current completion, `M-n' and `M-p' cycle through possible
     completions, <TAB> completes as far as possible and then cycles,
     and `C-g' or any other key aborts completion.

`C-c , l'
     Display a list of the possible completions of the symbol at point,
     in another window (`semantic-analyze-possible-completions').

In addition to the above commands, the Semantic package provides a
variety of other ways to make use of parser information.  For instance,
you can use it to display a list of completions when Emacs is idle.
*Note Semantic: (semantic)Top, for details.

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

   (1) Regular expressions and syntax tables.


File: emacs,  Node: Misc for Programs,  Next: C Modes,  Prev: Semantic,  Up: Programs

26.11 Other Features Useful for Editing Programs
================================================

Some Emacs commands that aren't designed specifically for editing
programs are useful for that nonetheless.

   The Emacs commands that operate on words, sentences and paragraphs
are useful for editing code.  Most symbols names contain words (*note
Words::), while sentences can be found in strings and comments (*note
Sentences::).  As for paragraphs, they are defined in most programming
language modes to begin and end at blank lines (*note Paragraphs::).
Therefore, judicious use of blank lines to make the program clearer
will also provide useful chunks of text for the paragraph commands to
work on.  Auto Fill mode, if enabled in a programming language major
mode, indents the new lines which it creates.

   Electric Layout mode (`M-x electric-layout-mode') is a global minor
mode that automatically inserts newlines when you type certain
characters; for example, `{', `}' and `;' in Javascript mode.

   Apart from Hideshow mode (*note Hideshow::), another way to
selectively display parts of a program is to use the selective display
feature (*note Selective Display::).  Programming modes often also
support Outline minor mode (*note Outline Mode::), which can be used
with the Foldout package (*note Foldout::).

   The "automatic typing" features may be useful for writing programs.
*Note Autotyping: (autotype)Top.


File: emacs,  Node: C Modes,  Next: Asm Mode,  Prev: Misc for Programs,  Up: Programs

26.12 C and Related Modes
=========================

This section gives a brief description of the special features
available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
(These are called "C mode and related modes".)  *Note CC Mode:
(ccmode)Top, for more details.

* Menu:

* Motion in C::                 Commands to move by C statements, etc.
* Electric C::                  Colon and other chars can automatically reindent.
* Hungry Delete::               A more powerful DEL command.
* Other C Commands::            Filling comments, viewing expansion of macros,
                                and other neat features.


File: emacs,  Node: Motion in C,  Next: Electric C,  Up: C Modes

26.12.1 C Mode Motion Commands
------------------------------

This section describes commands for moving point, in C mode and related
modes.

`C-M-a'
`C-M-e'
     Move point to the beginning or end of the current function or
     top-level definition.  In languages with enclosing scopes (such as
     C++'s classes) the "current function" is the immediate one,
     possibly inside a scope.  Otherwise it is the one defined by the
     least enclosing braces.  (By contrast, `beginning-of-defun' and
     `end-of-defun' search for braces in column zero.)  *Note Moving by
     Defuns::.

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

     `#elif' is equivalent to `#else' followed by `#if', so the
     function will stop at a `#elif' when going backward, but not when
     going forward.

`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
     (`c-beginning-of-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.

     In comments or in strings which span more than one line, this
     command moves by sentences instead of statements.

`M-e'
     Move point to the end of the innermost C statement or sentence;
     like `M-a' except that it moves in the other direction
     (`c-end-of-statement').


File: emacs,  Node: Electric C,  Next: Hungry Delete,  Prev: Motion in C,  Up: C Modes

26.12.2 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 optionally also insert newlines.  The "electric"
characters are `{', `}', `:', `#', `;', `,', `<', `>', `/', `*', `(',
and `)'.

   You might find electric indentation inconvenient if you are editing
chaotically indented code.  If you are new to CC Mode, you might find
it disconcerting.  You can toggle electric action with the command `C-c
C-l'; when it is enabled, `/l' appears in the mode line after the mode
name:

`C-c C-l'
     Toggle electric action (`c-toggle-electric-state').  With a
     positive prefix argument, this command enables electric action,
     with a negative one it disables it.

   Electric characters insert newlines only when, in addition to the
electric state, the "auto-newline" feature is enabled (indicated by
`/la' in the mode line after the mode name).  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-newline').  With a
     prefix argument, this command turns the auto-newline feature on if
     the argument is positive, and off if it is negative.

   Usually the CC Mode style configures the exact circumstances in
which Emacs inserts auto-newlines.  You can also configure this
directly.  *Note Custom Auto-newlines: (ccmode)Custom Auto-newlines.


File: emacs,  Node: Hungry Delete,  Next: Other C Commands,  Prev: Electric C,  Up: C Modes

26.12.3 Hungry Delete Feature in C
----------------------------------

If you want to delete an entire block of whitespace at point, you can
use "hungry deletion".  This deletes all the contiguous whitespace
either before point or after point in a single operation.  "Whitespace"
here includes tabs and newlines, but not comments or preprocessor
commands.

`C-c C-<DEL>'
`C-c <DEL>'
     Delete the entire block of whitespace preceding point
     (`c-hungry-delete-backwards').

`C-c C-d'
`C-c C-<DELETE>'
`C-c <DELETE>'
     Delete the entire block of whitespace after point
     (`c-hungry-delete-forward').

   As an alternative to the above commands, you can enable "hungry
delete mode".  When this feature is enabled (indicated by `/h' in the
mode line after the mode name), a single <DEL> deletes all preceding
whitespace, not just one space, and a single `C-c C-d' (but _not_ plain
<DELETE>) deletes all following whitespace.

`M-x c-toggle-hungry-state'
     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.

   The variable `c-hungry-delete-key' controls whether the
hungry-delete feature is enabled.


File: emacs,  Node: Other C Commands,  Prev: Hungry Delete,  Up: C Modes

26.12.4 Other Commands for C Mode
---------------------------------

`C-c C-w'
`M-x subword-mode'
     Enable (or disable) "subword mode".  In subword mode, Emacs's word
     commands recognize upper case letters in `StudlyCapsIdentifiers'
     as word boundaries.  This is indicated by the flag `/w' on the
     mode line after the mode name (e.g. `C/law').  You can even use
     `M-x subword-mode' in non-CC Mode buffers.

     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-context-line-break'
     This command inserts a line break and indents the new line in a
     manner appropriate to the context.  In normal code, it does the
     work of `C-j' (`newline-and-indent'), in a C preprocessor line it
     additionally inserts a `\' at the line break, and within comments
     it's like `M-j' (`c-indent-new-comment-line').

     `c-context-line-break' isn't bound to a key by default, but it
     needs a binding to be useful.  The following code will bind it to
     `C-j'.  We use `c-initialization-hook' here to make sure the
     keymap is loaded before we try to change it.

          (defun my-bind-clb ()
            (define-key c-mode-base-map "\C-j"
                        'c-context-line-break))
          (add-hook 'c-initialization-hook 'my-bind-clb)

`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 information directs how
     the line is indented.

`M-x cwarn-mode'
`M-x global-cwarn-mode'
     CWarn minor mode highlights certain suspicious C and C++
     constructions:

        * Assignments inside expressions.

        * Semicolon following immediately after `if', `for', and `while'
          (except after a `do ... while' statement);

        * C++ functions with reference parameters.

     You can enable the mode for one buffer with the command `M-x
     cwarn-mode', or for all suitable buffers with the command `M-x
     global-cwarn-mode' or by customizing the variable
     `global-cwarn-mode'.  You must also enable Font Lock mode to make
     it work.

`M-x hide-ifdef-mode'
     Hide-ifdef minor mode hides selected code within `#if' and
     `#ifdef' preprocessor blocks.  If you change the variable
     `hide-ifdef-shadow' to `t', Hide-ifdef minor mode "shadows"
     preprocessor blocks by displaying them with a less prominent face,
     instead of hiding them entirely.  See the documentation string of
     `hide-ifdef-mode' for more information.

`M-x ff-find-related-file'
     Find a file "related" in a special way to the file visited by the
     current buffer.  Typically this will be the header file
     corresponding to a C/C++ source file, or vice versa.  The variable
     `ff-related-file-alist' specifies how to compute related file
     names.


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

26.13 Asm Mode
==============

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

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

`C-j'
     Insert a newline and then indent using `tab-to-tab-stop'.

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

`;'
     Insert or align a comment.

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


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

26.14 Fortran Mode
==================

Fortran mode is meant for editing "fixed form" (and also "tab format")
source code (normally Fortran 77).  For editing more modern "free form"
source code (Fortran 90, 95, 2003, 2008), use F90 mode (`f90-mode').
Emacs normally uses Fortran mode for files with extension `.f', `.F' or
`.for', and F90 mode for the extensions `.f90', `.f95', `.f03' and
`.f08'.  Customize `auto-mode-alist' to add more extensions.  GNU
Fortran supports both free and fixed form.  This manual mainly
documents Fortran mode, but the corresponding F90 mode features are
mentioned when relevant.

   Fortran mode provides special motion commands for Fortran statements
and subprograms, and indentation commands that understand Fortran
conventions of nesting, line numbers and continuation statements.
Fortran mode has support for Auto Fill mode that breaks long lines into
proper Fortran continuation lines.  Fortran mode also supports Hideshow
minor mode (*note Hideshow::), and Imenu (*note Imenu::).

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

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

* Menu:

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


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

26.14.1 Motion Commands
-----------------------

In addition to the normal commands for moving by and operating on
"defuns" (Fortran subprograms--functions and subroutines, as well as
modules for F90 mode, using the commands `fortran-end-of-subprogram'
and `fortran-beginning-of-subprogram'), Fortran mode provides special
commands to move by statements and other program units.

`C-c C-n'
     Move to the beginning of the next statement
     (`fortran-next-statement'/`f90-next-statement').

`C-c C-p'
     Move to the beginning of the previous statement
     (`fortran-previous-statement'/`f90-previous-statement').  If there
     is no previous statement (i.e. if called from the first statement
     in the buffer), move to the start of the buffer.

`C-c C-e'
     Move point forward to the start of the next code block, or the end
     of the current one, whichever comes first (`f90-next-block').  A
     code block is a subroutine, `if'-`endif' statement, and so forth.
     This command exists for F90 mode only, not Fortran mode.  With a
     numeric argument, it moves forward that many blocks.

`C-c C-a'
     Move point backward to the previous block (`f90-previous-block').
     This is like `f90-next-block', but moves backwards.

`C-M-n'
     Move to the end of the current code block
     (`fortran-end-of-block'/`f90-end-of-block').  With a numeric
     argument, move forward that number of blocks.  The mark is set
     before moving point.  The F90 mode version of this command checks
     for consistency of block types and labels (if present), but it
     does not check the outermost block since that may be incomplete.

`C-M-p'
     Move to the start of the current code block
     (`fortran-beginning-of-block'/`f90-beginning-of-block'). This is
     like `fortran-end-of-block', but moves backwards.

   The commands `fortran-beginning-of-subprogram' and
`fortran-end-of-subprogram' move to the start or end of the current
subprogram, respectively.  The commands `fortran-mark-do' and
`fortran-mark-if' mark the end of the current `do' or `if' block, and
move point to the start.


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

26.14.2 Fortran Indentation
---------------------------

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

* Menu:

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


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

26.14.2.1 Fortran Indentation and Filling Commands
..................................................

`C-M-j'
     Break the current line at point and set up a continuation line
     (`fortran-split-line').

`M-^'
     Join this line to the previous line (`fortran-join-line').

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

`M-q'
     Fill a comment block or statement (using `fortran-fill-paragraph'
     or `fortran-fill-statement').

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

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

   `M-^' or `C-c C-d' runs the command `fortran-join-line', which joins
a continuation line back to the previous line, roughly as the inverse
of `fortran-split-line'.  The point must be on a continuation line when
this command is invoked.

   `M-q' in Fortran mode fills the comment block or statement that
point is in.  This removes any excess statement continuations.


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

26.14.2.2 Continuation Lines
............................

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

   Fortran mode can use either style of continuation line.  When you
enter Fortran mode, it tries to deduce the proper continuation style
automatically from the buffer contents.  It does this by scanning up to
`fortran-analyze-depth' (default 100) lines from the start of the
buffer.  The first line that begins with either a tab character or six
spaces determines the choice.  If the scan fails (for example, if the
buffer is new and therefore empty), the value of
`fortran-tab-mode-default' (`nil' for fixed form, and non-`nil' for tab
format) is used.  `/t' (`fortran-tab-mode-string') in the mode line
indicates tab format is selected.  Fortran mode sets the value of
`indent-tabs-mode' accordingly.

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

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


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

26.14.2.3 Line Numbers
......................

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

   Line numbers of four digits or less are normally indented one space.
The variable `fortran-line-number-indent' controls this; it specifies
the maximum indentation a line number can have.  The default value of
the variable is 1.  Fortran mode tries to prevent line number digits
passing column 4, reducing the indentation below the specified maximum
if necessary.  If `fortran-line-number-indent' has the value 5, line
numbers are right-justified to end in column 4.

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


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

26.14.2.4 Syntactic Conventions
...............................

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

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

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

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

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


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

26.14.2.5 Variables for Fortran Indentation
...........................................

Several additional variables control how Fortran indentation works:

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

`fortran-if-indent'
     Extra indentation within each level of `if', `select case', or
     `where' statements (default 3).

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

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

`fortran-check-all-num-for-matching-do'
     In Fortran 77, a numbered `do' statement is ended by any statement
     with a matching line number.  It is common (but not compulsory) to
     use a `continue' statement for this purpose.  If this variable has
     a non-`nil' value, indenting any numbered statement must check for
     a `do' that ends there.  If you always end `do' statements with a
     `continue' line (or if you use the more modern `enddo'), then you
     can speed up indentation by setting this variable to `nil' (the
     default).

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

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

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

   The following section describes the variables controlling the
indentation of comments.


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

26.14.3 Fortran Comments
------------------------

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

   Fortran mode can also handle the Fortran 90 comment syntax where
comments start with `!' and can follow other text.  Because only some
Fortran 77 compilers accept this syntax, Fortran mode will not insert
such comments unless you have said in advance to do so.  To do this,
set the variable `fortran-comment-line-start' to `"!"'.  If you use an
unusual value, you may need to change `fortran-comment-line-start-skip'.

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

`C-x ;'
     Applies to nonstandard `!' comments only (`comment-set-column').

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

   `M-;' in Fortran mode runs the standard `comment-dwim'.  This
recognizes any kind of existing comment and aligns its text
appropriately; if there is no existing comment, a comment is inserted
and aligned.  Inserting and aligning comments are not the same in
Fortran mode as in other modes.

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

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

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

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

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

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

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

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

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

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


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

26.14.4 Auto Fill in Fortran Mode
---------------------------------

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

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

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


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

26.14.5 Checking Columns in Fortran
-----------------------------------

In standard Fortran 77, anything beyond column 72 is ignored.  Most
compilers provide an option to change this (for example,
`-ffixed-line-length-N' in gfortran).  Customize the variable
`fortran-line-length' to change the line length in Fortran mode.
Anything beyond this point is font-locked as a comment.  (Unless it is
inside a string: strings that extend beyond `fortran-line-length' will
confuse font-lock.)

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

`C-c C-w'
     Split the current window horizontally temporarily so that it is
     `fortran-line-length' columns wide
     (`fortran-window-create-momentarily').  This may help you avoid
     making lines longer than the limit imposed by your Fortran
     compiler.

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

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

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

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

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

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

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

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


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

26.14.6 Fortran Keyword Abbrevs
-------------------------------

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

   The built-in abbrevs are unusual in one way: they all start with a
semicolon.  For example, one built-in Fortran abbrev is `;c' for
`continue'.  If you insert `;c' and then insert a punctuation character
such as a space or a newline, the `;c' expands automatically to
`continue', provided Abbrev mode is enabled.

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


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

27 Compiling and Testing Programs
*********************************

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

* Menu:

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


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

27.1 Running Compilations under Emacs
=====================================

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

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

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

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

   To run `make' or another compilation command, type `M-x compile'.
This reads a shell command line using the minibuffer, and then executes
the command by running a shell as a subprocess (or "inferior process")
of Emacs.  The output is inserted in a buffer named `*compilation*'.
The current buffer's default directory is used as the working directory
for the execution of the command; normally, therefore, compilation
takes place in this directory.

   The default compilation command is `make -k', which is usually
correct for programs compiled using the `make' utility (the `-k' flag
tells `make' to continue compiling as much as possible after an error).
*Note Make: (make)Top.  If you have done `M-x compile' before, the
command that you specified is automatically stored in the variable
`compile-command'; this is used as the default the next time you type
`M-x compile'.  A file can also specify a file-local value for
`compile-command' (*note File Variables::).

   Starting a compilation displays the `*compilation*' buffer in
another window but does not select it.  While the compilation is
running, the word `run' is shown in the major mode indicator for the
`*compilation*' buffer, and the word `Compiling' appears in all mode
lines.  You do not have to keep the `*compilation*' buffer visible
while compilation is running; it continues in any case.  When the
compilation ends, for whatever reason, the mode line of the
`*compilation*' buffer changes to say `exit' (followed by the exit
code: `[0]' for a normal exit), or `signal' (if a signal terminated the
process).

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

   If you change the variable `compilation-scroll-output' to a
non-`nil' value, the `*compilation*' buffer scrolls automatically to
follow the output.  If the value is `first-error', scrolling stops when
the first error appears, leaving point at that error.  For any other
non-`nil' value, scrolling continues until there is no more output.

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

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

   To run two compilations at once, start the first one, then rename
the `*compilation*' buffer (perhaps using `rename-uniquely'; *note Misc
Buffer::), then switch buffers and start the other compilation.  This
will create a new `*compilation*' buffer.

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


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

27.2 Compilation Mode
=====================

The `*compilation*' buffer uses a major mode called Compilation mode.
Compilation mode turns each error message in the buffer into a
hyperlink; you can move point to it and type <RET>, or click on it with
the mouse (*note Mouse References::), to visit the "locus" of the error
message in a separate window.  The locus is the specific position in a
file where that error occurred.

   If you change the variable `compilation-auto-jump-to-first-error' to
a non-`nil' value, Emacs automatically visits the locus of the first
error message that appears in the `*compilation*' buffer.

   Compilation mode provides the following additional commands.  These
commands can also be used in `*grep*' buffers, where the hyperlinks are
search matches rather than error messages (*note Grep Searching::).

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

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

`M-n'
     Move point to the next error message or match, without visiting its
     locus (`compilation-next-error').

`M-p'
     Move point to the previous error message or match, without visiting
     its locus (`compilation-previous-error').

`M-}'
     Move point to the next error message or match occurring in a
     different file (`compilation-next-file').

`M-{'
     Move point to the previous error message or match occurring in a
     different file (`compilation-previous-file').

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

   To visit errors sequentially, type `C-x `' (`next-error'), or
equivalently `M-g M-n' or `M-g n'.  This command can be invoked from
any buffer, not just a Compilation mode buffer.  The first time you
invoke it after a compilation, it visits the locus of the first error
message.  Each subsequent `C-x `' visits the next error, in a similar
fashion.  If you visit a specific error with <RET> or a mouse click in
the `*compilation*' buffer, subsequent `C-x `' commands advance from
there.  When `C-x `' finds no more error messages to visit, it signals
an error.  `C-u C-x `' starts again from the beginning of the
compilation buffer, and visits the first locus.

   `M-g M-p' or `M-g p' (`previous-error') iterates through errors in
the opposite direction.

   The `next-error' and `previous-error' commands don't just act on the
errors or matches listed in `*compilation*' and `*grep*' buffers; they
also know how to iterate through error or match lists produced by other
commands, such as `M-x occur' (*note Other Repeating Search::).  If you
are already in a buffer containing error messages or matches, those are
the ones that are iterated through; otherwise, Emacs looks for a buffer
containing error messages or matches amongst the windows of the
selected frame, then for one that `next-error' or `previous-error'
previously iterated through, and finally amongst all other buffers.  If
the buffer chosen for iterating through is not currently displayed in a
window, it will be displayed.

   By default, the `next-error' and `previous-error' commands skip less
important messages.  The variable `compilation-skip-threshold' controls
this.  The default value, 1, means to skip anything less important than
a warning.  A value of 2 means to skip anything less important than an
error, while 0 means not to skip any messages.

   When Emacs visits the locus of an error message, it momentarily
highlights the relevant source line.  The duration of this highlight is
determined by the variable `next-error-highlight'.

   If the `*compilation*' buffer is shown in a window with a left
fringe (*note Fringes::), the locus-visiting commands put an arrow in
the fringe, pointing to the current error message.  If the window has
no left fringe, such as on a text terminal, these commands scroll the
window so that the current message is at the top of the window.  If you
change the variable `compilation-context-lines' to an integer value N,
these commands scroll the window so that the current error message is N
lines from the top, whether or not there is a fringe; the default
value, `nil', gives the behavior described above.

   To parse messages from the compiler, Compilation mode uses the
variable `compilation-error-regexp-alist' which lists various error
message formats and tells Emacs how to extract the locus from each.  A
similar variable, `grep-regexp-alist', tells Emacs how to parse output
from a `grep' command (*note Grep Searching::).

   Compilation mode also defines the keys <SPC> and <DEL> to scroll by
screenfuls; `M-n' (`compilation-next-error') and `M-p'
(`compilation-previous-error') to move to the next or previous error
message; and `M-{' (`compilation-next-file') and `M-}'
(`compilation-previous-file') to move to the next or previous error
message for a different source file.

   You can type `C-c C-f' to toggle Next Error Follow mode.  In this
minor mode, ordinary cursor motion in the compilation buffer
automatically updates the source buffer, i.e. moving the cursor over an
error message causes the locus of that error to be displayed.

   The features of Compilation mode are also available in a minor mode
called Compilation Minor mode.  This lets you parse error messages in
any buffer, not just a normal compilation output buffer.  Type `M-x
compilation-minor-mode' to enable the minor mode.  For instance, in an
Rlogin buffer (*note Remote Host::), Compilation minor mode
automatically accesses remote source files by FTP (*note File Names::).


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

27.3 Subshells for Compilation
==============================

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

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

And here's how to do it in csh:

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

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

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

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

     nohup COMMAND; sleep 1

   On the MS-DOS "operating system", asynchronous subprocesses are not
supported, so `M-x compile' runs the compilation command synchronously
(i.e. you must wait until the command finishes before you can do
anything else in Emacs).  *Note MS-DOS::.


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

27.4 Searching with Grep under Emacs
====================================

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

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

`M-x grep-find'
`M-x find-grep'
`M-x rgrep'
     Run `grep' via `find', and collect output in the `*grep*' buffer.

`M-x zrgrep'
     Run `zgrep' and collect output in the `*grep*' buffer.

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

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

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

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

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

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

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

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

   These commands build the shell commands based on the variables
`grep-template' (for `lgrep') and `grep-find-template' (for `rgrep').
The files to search can use aliases defined in the variable
`grep-files-aliases'.

   Directories listed in the variable `grep-find-ignored-directories'
are automatically skipped by `M-x rgrep'.  The default value includes
the data directories used by various version control systems.


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

27.5 Finding Syntax Errors On The Fly
=====================================

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

   To enable Flymake mode, type `M-x flymake-mode'.  You can jump to
the errors that it finds by using `M-x flymake-goto-next-error' and
`M-x flymake-goto-prev-error'.  To display any error messages
associated with the current line, type `M-x
flymake-display-err-menu-for-current-line'.

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


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

27.6 Running Debuggers Under Emacs
==================================

The GUD (Grand Unified Debugger) library provides an Emacs interface to
a wide variety of symbolic debuggers.  It can run the GNU Debugger
(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python
debugger PDB, and the Java Debugger JDB.

   Emacs provides a special interface to GDB, which uses extra Emacs
windows to display the state of the debugged program.  *Note GDB
Graphical Interface::.

   Emacs also has a built-in debugger for Emacs Lisp programs.  *Note
The Lisp Debugger: (elisp)Debugging.

* Menu:

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


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

27.6.1 Starting GUD
-------------------

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

`M-x gdb'
     Run GDB as a subprocess, and interact with it via an IDE-like Emacs
     interface.  *Note GDB Graphical Interface::, for more information
     about this command.

`M-x gud-gdb'
     Run GDB, using a GUD interaction buffer for input and output to the
     GDB subprocess (*note Debugger Operation::).  If such a buffer
     already exists, switch to it; otherwise, create the buffer and
     switch to it.

     The other commands in this list do the same, for other debugger
     programs.

`M-x perldb'
     Run the Perl interpreter in debug mode.

`M-x jdb'
     Run the Java debugger.

`M-x pdb'
     Run the Python debugger.

`M-x dbx'
     Run the DBX debugger.

`M-x xdb'
     Run the XDB debugger.

`M-x sdb'
     Run the SDB debugger.

   Each of these commands reads a command line to invoke the debugger,
using the minibuffer.  The minibuffer's initial contents contain the
standard executable name and options for the debugger, and sometimes
also a guess for the name of the executable file you want to debug.
Shell wildcards and variables are not allowed in this command line.
Emacs assumes that the first command argument which does not start with
a `-' is the executable file name.

   Tramp provides a facility for remote debugging, whereby both the
debugger and the program being debugged are on the same remote host.
*Note Running a debugger on a remote host: (tramp)Running a debugger on
a remote host, for details.  This is separate from GDB's remote
debugging feature, where the program and the debugger run on different
machines (*note Debugging Remote Programs: (gdb)Remote Debugging.).


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

27.6.2 Debugger Operation
-------------------------

The "GUD interaction buffer" is an Emacs buffer which is used to send
text commands to a debugger subprocess, and record its output.  This is
the basic interface for interacting with a debugger, used by `M-x
gud-gdb' and other commands listed in *note Starting GUD::.  The `M-x
gdb' command extends this interface with additional specialized buffers
for controlling breakpoints, stack frames, and other aspects of the
debugger state (*note GDB Graphical Interface::).

   The GUD interaction buffer uses a variant of Shell mode, so the
Emacs commands defined by Shell mode are available (*note Shell
Mode::).  Completion is available for most debugger commands (*note
Completion::), and you can use the usual Shell mode history commands to
repeat them.  *Note Commands of GUD::, for special commands that can be
used in the GUD interaction buffer.

   As you debug a program, Emacs displays the relevant source files by
visiting them in Emacs buffers, with an arrow in the left fringe
indicating the current execution line.  (On a text terminal, the arrow
appears as `=>', overlaid on the first two text columns.)  Moving point
in such a buffer does not move the arrow.  You are free to edit these
source files, but note that inserting or deleting lines will throw off
the arrow's positioning, as Emacs has no way to figure out which edited
source line corresponds to the line reported by the debugger
subprocess.  To update this information, you typically have to
recompile and restart the program.

   GUD Tooltip mode is a global minor mode that adds tooltip support to
GUD.  To toggle this mode, type `M-x gud-tooltip-mode'.  It is disabled
by default.  If enabled, you can move the mouse cursor over a variable
to show its value in a tooltip (*note Tooltips::); this takes effect in
the GUD interaction buffer, and in all source buffers with major modes
listed in the variable `gud-tooltip-modes'.  If the variable
`gud-tooltip-echo-area' is non-`nil', values are shown in the echo area
instead of a tooltip.

   When using GUD Tooltip mode with `M-x gud-gdb', you should note that
displaying an expression's value in GDB can sometimes expand a macro,
potentially causing side effects in the debugged program.  If you use
the `M-x gdb' interface, this problem does not occur, as there is
special code to avoid side-effects; furthermore, you can display macro
definitions associated with an identifier when the program is not
executing.


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

27.6.3 Commands of GUD
----------------------

GUD provides commands for setting and clearing breakpoints, selecting
stack frames, and stepping through the program.

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

   `C-x <SPC>' (`gud-break'), when called in a source buffer, sets a
debugger breakpoint on the current source line.  This command is
available only after starting GUD.  If you call it in a buffer that is
not associated with any debugger subprocess, it signals a error.

   The following commands are available both in the GUD interaction
buffer and globally, but with different key bindings.  The keys
starting with `C-c' are available only in the GUD interaction buffer,
while those starting with `C-x C-a' are available globally.  Some of
these commands are also available via the tool bar; some are not
supported by certain debuggers.

`C-c C-l'
`C-x C-a C-l'
     Display, in another window, the last source line referred to in the
     GUD interaction buffer (`gud-refresh').

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

`C-c C-n'
`C-x C-a C-n'
     Execute the next single line of code, stepping across function
     calls without stopping inside the functions (`gud-next').

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

27.6.4 GUD Customization
------------------------

On startup, GUD runs one of the following hooks: `gdb-mode-hook', if
you are using GDB; `dbx-mode-hook', if you are using DBX;
`sdb-mode-hook', if you are using SDB; `xdb-mode-hook', if you are
using XDB; `perldb-mode-hook', for Perl debugging mode;
`pdb-mode-hook', for PDB; `jdb-mode-hook', for JDB.  *Note Hooks::.

   The `gud-def' Lisp macro (*note Defining Macros: (elisp)Defining
Macros.) provides a convenient way to define an Emacs command that
sends a particular command string to the debugger, and set up a key
binding for in the GUD interaction buffer:

     (gud-def FUNCTION CMDSTRING BINDING DOCSTRING)

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

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

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

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

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

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

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

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

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

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


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

27.6.5 GDB Graphical Interface
------------------------------

The command `M-x gdb' starts GDB in an IDE-like interface, with
specialized buffers for controlling breakpoints, stack frames, and
other aspects of the debugger state.  It also provides additional ways
to control the debugging session with the mouse, such as clicking in
the fringe of a source buffer to set a breakpoint there.

   To run GDB using just the GUD interaction buffer interface, without
these additional features, use `M-x gud-gdb' (*note Starting GUD::).
You must use this if you want to debug multiple programs within one
Emacs session, as that is currently unsupported by `M-x gdb'.

   Internally, `M-x gdb' informs GDB that its "screen size" is
unlimited; for correct operation, you must not change GDB's screen
height and width values during the debugging session.

* Menu:

* GDB User Interface Layout::   Control the number of displayed buffers.
* Source Buffers::              Use the mouse in the fringe/margin to
                                control your program.
* Breakpoints Buffer::          A breakpoint control panel.
* Threads Buffer::              Displays your threads.
* Stack Buffer::                Select a frame from the call stack.
* Other GDB Buffers::           Other buffers for controlling the GDB state.
* Watch Expressions::           Monitor variable values in the speedbar.
* Multithreaded Debugging::     Debugging programs with several threads.


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

27.6.5.1 GDB User Interface Layout
..................................

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

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

     +--------------------------------+--------------------------------+
     |   GUD interaction buffer       |   Locals/Registers buffer      |
     |--------------------------------+--------------------------------+
     |   Primary Source buffer        |   I/O buffer for debugged pgm  |
     |--------------------------------+--------------------------------+
     |   Stack buffer                 |   Breakpoints/Threads buffer   |
     +--------------------------------+--------------------------------+

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

   If you ever change the window layout, you can restore the "many
windows" layout by typing `M-x gdb-restore-windows'.  To toggle between
the many windows layout and a simple layout with just the GUD
interaction buffer and a source file, type `M-x gdb-many-windows'.

   You may also specify additional GDB-related buffers to display,
either in the same frame or a different one.  Select the buffers you
want by typing `M-x gdb-display-BUFFERTYPE-buffer' or `M-x
gdb-frame-BUFFERTYPE-buffer', where BUFFERTYPE is the relevant buffer
type, such as `breakpoints'.  You can do the same with the menu bar,
with the `GDB-Windows' and `GDB-Frames' sub-menus of the `GUD' menu.

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


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

27.6.5.2 Source Buffers
.......................

`Mouse-1' (in fringe)
     Set or clear a breakpoint on that line.

`C-Mouse-1' (in fringe)
     Enable or disable a breakpoint on that line.

`Mouse-3' (in fringe)
     Continue execution to that line.

`C-Mouse-3' (in fringe)
     Jump to that line.

   On a graphical display, you can click `Mouse-1' in the fringe of a
source buffer, to set a breakpoint on that line (*note Fringes::).  A
red dot appears in the fringe, where you clicked.  If a breakpoint
already exists there, the click removes it.  A `C-Mouse-1' click
enables or disables an existing breakpoint; a breakpoint that is
disabled, but not unset, is indicated by a gray dot.

   On a text terminal, or when fringes are disabled, enabled
breakpoints are indicated with a `B' character in the left margin of
the window.  Disabled breakpoints are indicated with `b'.  (The margin
is only displayed if a breakpoint is present.)

   A solid arrow in the left fringe of a source buffer indicates the
line of the innermost frame where the debugged program has stopped. A
hollow arrow indicates the current execution line of a higher-level
frame.  If you drag the arrow in the fringe with `Mouse-1', that causes
execution to advance to the line where you release the button.
Alternatively, you can click `Mouse-3' in the fringe to advance to that
line.  You can click `C-Mouse-3' in the fringe to jump to that line
without executing the intermediate lines.  This command allows you to
go backwards, which can be useful for running through code that has
already executed, in order to examine its execution in more detail.


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

27.6.5.3 Breakpoints Buffer
...........................

The GDB Breakpoints buffer shows the breakpoints, watchpoints and
catchpoints in the debugger session.  *Note Breakpoints:
(gdb)Breakpoints.  It provides the following commands, which mostly
apply to the "current breakpoint" (the breakpoint which point is on):

`<SPC>'
     Enable/disable current breakpoint (`gdb-toggle-breakpoint').  On a
     graphical display, this changes the color of the dot in the fringe
     of the source buffer at that line.  The dot is red when the
     breakpoint is enabled, and gray when it is disabled.

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

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

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

   When `gdb-many-windows' is non-`nil', the GDB Breakpoints buffer
shares its window with the GDB Threads buffer.  To switch from one to
the other click with `Mouse-1' on the relevant button in the header
line.  If `gdb-show-threads-by-default' is non-`nil', the GDB Threads
buffer is the one shown by default.


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

27.6.5.4 Threads Buffer
.......................

The GDB Threads buffer displays a summary of the threads in the
debugged program.  *Note Threads: (gdb)Threads.  To select a thread,
move point there and type <RET> (`gdb-select-thread'), or click on it
with `Mouse-2'.  This also displays the associated source buffer, and
updates the contents of the other GDB buffers.

   You can customize variables under `gdb-buffers' group to select
fields included in GDB Threads buffer.

`gdb-thread-buffer-verbose-names'
     Show long thread names like `Thread 0x4e2ab70 (LWP 1983)'.

`gdb-thread-buffer-arguments'
     Show arguments of thread top frames.

`gdb-thread-buffer-locations'
     Show file information or library names.

`gdb-thread-buffer-addresses'
     Show addresses for thread frames in threads buffer.

   To view information for several threads simultaneously, use the
following commands from the GDB Threads buffer.

`d'
     Display disassembly buffer for the thread at current line
     (`gdb-display-disassembly-for-thread').

`f'
     Display the GDB Stack buffer for the thread at current line
     (`gdb-display-stack-for-thread').

`l'
     Display the GDB Locals buffer for the thread at current line
     (`gdb-display-locals-for-thread').

`r'
     Display the GDB Registers buffer for the thread at current line
     (`gdb-display-registers-for-thread').

Their upper-case counterparts, `D', `F' ,`L' and `R', display the
corresponding buffer in a new frame.

   When you create a buffer showing information about some specific
thread, it becomes bound to that thread and keeps showing actual
information while you debug your program.  The mode indicator for each
GDB buffer shows the number of thread it is showing information about.
The thread number is also included in the buffer name of bound buffers.

   Further commands are available in the GDB Threads buffer which
depend on the mode of GDB that is used for controlling execution of
your program.  *Note Multithreaded Debugging::.



Local Variables:
coding: iso-8859-1
End: