This is ../info/emacs, produced by makeinfo version 4.0 from emacs.texi.
This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.1.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs). The extensible self-documenting text editor.
END-INFO-DIR-ENTRY
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1985,
1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001 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.1 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 freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: emacs, Node: TeX Print, Next: TeX Misc, Prev: LaTeX Editing, Up: TeX Mode
TeX Printing Commands
---------------------
You can invoke TeX as an inferior of Emacs on either the entire
contents of the buffer or just a region at a time. Running TeX in this
way on just one chapter is a good way to see what your changes look
like without taking the time to format the entire file.
`C-c C-r'
Invoke TeX on the current region, together with the buffer's header
(`tex-region').
`C-c C-b'
Invoke TeX on the entire current buffer (`tex-buffer').
`C-c <TAB>'
Invoke BibTeX on the current file (`tex-bibtex-file').
`C-c C-f'
Invoke TeX on the current file (`tex-file').
`C-c C-l'
Recenter the window showing output from the inferior TeX so that
the last line can be seen (`tex-recenter-output-buffer').
`C-c C-k'
Kill the TeX subprocess (`tex-kill-job').
`C-c C-p'
Print the output from the last `C-c C-r', `C-c C-b', or `C-c C-f'
command (`tex-print').
`C-c C-v'
Preview the output from the last `C-c C-r', `C-c C-b', or `C-c
C-f' command (`tex-view').
`C-c C-q'
Show the printer queue (`tex-show-print-queue').
You can pass the current buffer through an inferior TeX by means of
`C-c C-b' (`tex-buffer'). The formatted output appears in a temporary
file; to print it, type `C-c C-p' (`tex-print'). Afterward, you can
use `C-c C-q' (`tex-show-print-queue') to view the progress of your
output towards being printed. If your terminal has the ability to
display TeX output files, you can preview the output on the terminal
with `C-c C-v' (`tex-view').
You can specify the directory to use for running TeX by setting the
variable `tex-directory'. `"."' is the default value. If your
environment variable `TEXINPUTS' contains relative directory names, or
if your files contains `\input' commands with relative file names, then
`tex-directory' _must_ be `"."' or you will get the wrong results.
Otherwise, it is safe to specify some other directory, such as `"/tmp"'.
If you want to specify which shell commands are used in the inferior
TeX, you can do so by setting the values of the variables
`tex-run-command', `latex-run-command', `slitex-run-command',
`tex-dvi-print-command', `tex-dvi-view-command', and
`tex-show-queue-command'. You _must_ set the value of
`tex-dvi-view-command' for your particular terminal; this variable has
no default value. The other variables have default values that may (or
may not) be appropriate for your system.
Normally, the file name given to these commands comes at the end of
the command string; for example, `latex FILENAME'. In some cases,
however, the file name needs to be embedded in the command; an example
is when you need to provide the file name as an argument to one command
whose output is piped to another. You can specify where to put the
file name with `*' in the command string. For example,
(setq tex-dvi-print-command "dvips -f * | lpr")
The terminal output from TeX, including any error messages, appears
in a buffer called `*tex-shell*'. If TeX gets an error, you can switch
to this buffer and feed it input (this works as in Shell mode; *note
Interactive Shell::). Without switching to this buffer you can scroll
it so that its last line is visible by typing `C-c C-l'.
Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also
kills any TeX process still running.
You can also pass an arbitrary region through an inferior TeX by
typing `C-c C-r' (`tex-region'). This is tricky, however, because most
files of TeX input contain commands at the beginning to set parameters
and define macros, without which no later part of the file will format
correctly. To solve this problem, `C-c C-r' allows you to designate a
part of the file as containing essential commands; it is included before
the specified region as part of the input to TeX. The designated part
of the file is called the "header".
To indicate the bounds of the header in Plain TeX mode, you insert
two special strings in the file. Insert `%**start of header' before the
header, and `%**end of header' after it. Each string must appear
entirely on one line, but there may be other text on the line before or
after. The lines containing the two strings are included in the header.
If `%**start of header' does not appear within the first 100 lines of
the buffer, `C-c C-r' assumes that there is no header.
In LaTeX mode, the header begins with `\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-string' specifies
options for the TeX run. 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.
File: emacs, Node: TeX Misc, Prev: TeX Print, Up: TeX Mode
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::.
TeX encoding 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.
For managing all kinds of references for LaTeX, you can use RefTeX.
*Note RefTeX: (reftex)Top.
File: emacs, Node: Nroff Mode, Next: Formatted Text, Prev: TeX Mode, Up: Text
Nroff Mode
==========
Nroff mode is a mode like Text mode but modified to handle nroff
commands present in the text. Invoke `M-x nroff-mode' to enter this
mode. It differs from Text mode in only a few ways. All nroff command
lines are considered paragraph separators, so that filling will never
garble the nroff commands. Pages are separated by `.bp' commands.
Comments start with backslash-doublequote. Also, three special
commands are provided that are not in Text mode:
`M-n'
Move to the beginning of the next line that isn't an nroff command
(`forward-text-line'). An argument is a repeat count.
`M-p'
Like `M-n' but move up (`backward-text-line').
`M-?'
Displays in the echo area the number of text lines (lines that are
not nroff commands) in the region (`count-text-lines').
The other feature of Nroff mode is that you can turn on Electric
Nroff mode. This is a minor mode that you can turn on or off with `M-x
electric-nroff-mode' (*note Minor Modes::). When the mode is on, each
time you use <RET> to end a line that contains an nroff command that
opens a kind of grouping, the matching nroff command to close that
grouping is automatically inserted on the following line. For example,
if you are at the beginning of a line and type `. ( b <RET>', this
inserts the matching command `.)b' on a new line following point.
If you use Outline minor mode with Nroff mode (*note Outline Mode::),
heading lines are lines of the form `.H' followed by a number (the
header level).
Entering Nroff mode runs the hook `text-mode-hook', followed by the
hook `nroff-mode-hook' (*note Hooks::).
File: emacs, Node: Formatted Text, Prev: Nroff Mode, Up: Text
Editing Formatted Text
======================
"Enriched mode" is a minor mode for editing files that contain
formatted text in WYSIWYG fashion, as in a word processor. Currently,
formatted text in Enriched mode can specify fonts, colors, underlining,
margins, and types of filling and justification. In the future, we plan
to implement other formatting features as well.
Enriched mode is a minor mode (*note Minor Modes::). It is
typically used in conjunction with Text mode (*note Text Mode::), but
you can also use it with other major modes such as Outline mode and
Paragraph-Indent Text mode.
Potentially, Emacs can store formatted text files in various file
formats. Currently, only one format is implemented: "text/enriched"
format, which is defined by the MIME protocol. *Note Format
Conversion: (elisp)Format Conversion, for details of how Emacs
recognizes and converts file formats.
The Emacs distribution contains a formatted text file that can serve
as an example. Its name is `etc/enriched.doc'. It contains samples
illustrating all the features described in this section. It also
contains a list of ideas for future enhancements.
* Menu:
* Requesting Formatted Text:: Entering and exiting Enriched mode.
* Hard and Soft Newlines:: There are two different kinds of newlines.
* Editing Format Info:: How to edit text properties.
* Faces: Format Faces. Bold, italic, underline, etc.
* Color: Format Colors. Changing the color of text.
* Indent: Format Indentation. Changing the left and right margins.
* Justification: Format Justification.
Centering, setting text flush with the
left or right margin, etc.
* Other: Format Properties. The "special" text properties submenu.
* Forcing Enriched Mode:: How to force use of Enriched mode.
File: emacs, Node: Requesting Formatted Text, Next: Hard and Soft Newlines, Up: Formatted Text
Requesting to Edit Formatted Text
---------------------------------
Whenever you visit a file that Emacs saved in the text/enriched
format, Emacs automatically converts the formatting information in the
file into Emacs's own internal format (text properties), and turns on
Enriched mode.
To create a new file of formatted text, first visit the nonexistent
file, then type `M-x enriched-mode' before you start inserting text.
This command turns on Enriched mode. Do this before you begin inserting
text, to ensure that the text you insert is handled properly.
More generally, the command `enriched-mode' turns Enriched mode on
if it was off, and off if it was on. With a prefix argument, this
command turns Enriched mode on if the argument is positive, and turns
the mode off otherwise.
When you save a buffer while Enriched mode is enabled in it, Emacs
automatically converts the text to text/enriched format while writing it
into the file. When you visit the file again, Emacs will automatically
recognize the format, reconvert the text, and turn on Enriched mode
again.
Normally, after visiting a file in text/enriched format, Emacs
refills each paragraph to fit the specified right margin. You can turn
off this refilling, to save time, by setting the variable
`enriched-fill-after-visiting' to `nil' or to `ask'.
However, when visiting a file that was saved from Enriched mode,
there is no need for refilling, because Emacs saves the right margin
settings along with the text.
You can add annotations for saving additional text properties, which
Emacs normally does not save, by adding to `enriched-translations'.
Note that the text/enriched standard requires any non-standard
annotations to have names starting with `x-', as in `x-read-only'.
This ensures that they will not conflict with standard annotations that
may be added later.
File: emacs, Node: Hard and Soft Newlines, Next: Editing Format Info, Prev: Requesting Formatted Text, Up: Formatted Text
Hard and Soft Newlines
----------------------
In formatted text, Emacs distinguishes between two different kinds of
newlines, "hard" newlines and "soft" newlines.
Hard newlines are used to separate paragraphs, or items in a list, or
anywhere that there should always be a line break regardless of the
margins. The <RET> command (`newline') and `C-o' (`open-line') insert
hard newlines.
Soft newlines are used to make text fit between the margins. All the
fill commands, including Auto Fill, insert soft newlines--and they
delete only soft newlines.
Although hard and soft newlines look the same, it is important to
bear the difference in mind. Do not use <RET> to break lines in the
middle of filled paragraphs, or else you will get hard newlines that are
barriers to further filling. Instead, let Auto Fill mode break lines,
so that if the text or the margins change, Emacs can refill the lines
properly. *Note Auto Fill::.
On the other hand, in tables and lists, where the lines should always
remain as you type them, you can use <RET> to end lines. For these
lines, you may also want to set the justification style to `unfilled'.
*Note Format Justification::.
File: emacs, Node: Editing Format Info, Next: Format Faces, Prev: Hard and Soft Newlines, Up: Formatted Text
Editing Format Information
--------------------------
There are two ways to alter the formatting information for a
formatted text file: with keyboard commands, and with the mouse.
The easiest way to add properties to your document is by using the
Text Properties menu. You can get to this menu in two ways: from the
Edit menu in the menu bar, or with `C-Mouse-2' (hold the <CTRL> key and
press the middle mouse button).
Most of the items in the Text Properties menu lead to other submenus.
These are described in the sections that follow. Some items run
commands directly:
`Remove Properties'
Delete from the region all the text properties that the Text
Properties menu works with (`facemenu-remove-props').
`Remove All'
Delete _all_ text properties from the region
(`facemenu-remove-all').
`List Properties'
List all the text properties of the character following point
(`list-text-properties-at').
`Display Faces'
Display a list of all the defined faces.
`Display Colors'
Display a list of all the defined colors.
File: emacs, Node: Format Faces, Next: Format Colors, Prev: Editing Format Info, Up: Formatted Text
Faces in Formatted Text
-----------------------
The Faces submenu lists various Emacs faces including `bold',
`italic', and `underline'. Selecting one of these adds the chosen face
to the region. *Note Faces::. You can also specify a face with these
keyboard commands:
`M-g d'
Set the region, or the next inserted character, to the `default'
face (`facemenu-set-default').
`M-g b'
Set the region, or the next inserted character, to the `bold' face
(`facemenu-set-bold').
`M-g i'
Set the region, or the next inserted character, to the `italic'
face (`facemenu-set-italic').
`M-g l'
Set the region, or the next inserted character, to the
`bold-italic' face (`facemenu-set-bold-italic').
`M-g u'
Set the region, or the next inserted character, to the `underline'
face (`facemenu-set-underline').
`M-g o FACE <RET>'
Set the region, or the next inserted character, to the face FACE
(`facemenu-set-face').
If you use these commands with a prefix argument--or, in Transient
Mark mode, if the region is not active--then these commands specify a
face to use for your next self-inserting input. *Note Transient
Mark::. This applies to both the keyboard commands and the menu
commands.
Enriched mode defines two additional faces: `excerpt' and `fixed'.
These correspond to codes used in the text/enriched file format.
The `excerpt' face is intended for quotations. This face is the
same as `italic' unless you customize it (*note Face Customization::).
The `fixed' face means, "Use a fixed-width font for this part of the
text." This makes a visible difference only if you have specified a
variable-width font in the default face; however, even if the default
font is fixed-width, applying the `fixed' face to a part of the text
will cause that part of the text to appear in a fixed-width font, if
the file is ever displayed with a variable-width default font. This
applies to Emacs and to other systems that display text/enriched
format. So if you specifically want a certain part of the text to use
a fixed-width font, you should specify the `fixed' face for that part.
The `fixed' face is normally set up to use a different font from the
default, even if the default face is also fixed-width. Different
systems have different fonts installed, so you may need to customize
this. *Note Face Customization::.
If your terminal cannot display different faces, you will not be
able to see them, but you can still edit documents containing faces,
and even add faces and colors to documents. The faces you specify will
be visible when the file is viewed on a terminal that can display them.
File: emacs, Node: Format Colors, Next: Format Indentation, Prev: Format Faces, Up: Formatted Text
Colors in Formatted Text
------------------------
You can specify foreground and background colors for portions of the
text. There is a menu for specifying the foreground color and a menu
for specifying the background color. Each color menu lists all the
colors that you have used in Enriched mode in the current Emacs session.
If you specify a color with a prefix argument--or, in Transient Mark
mode, if the region is not active--then it applies to your next
self-inserting input. *Note Transient Mark::. Otherwise, the command
applies to the region.
Each color menu contains one additional item: `Other'. You can use
this item to specify a color that is not listed in the menu; it reads
the color name with the minibuffer. To display list of available colors
and their names, use the `Display Colors' menu item in the Text
Properties menu (*note Editing Format Info::).
Any color that you specify in this way, or that is mentioned in a
formatted text file that you read in, is added to both color menus for
the duration of the Emacs session.
There are no key bindings for specifying colors, but you can do so
with the extended commands `M-x facemenu-set-foreground' and `M-x
facemenu-set-background'. Both of these commands read the name of the
color with the minibuffer.
File: emacs, Node: Format Indentation, Next: Format Justification, Prev: Format Colors, Up: Formatted Text
Indentation in Formatted Text
-----------------------------
When editing formatted text, you can specify different amounts of
indentation for the right or left margin of an entire paragraph or a
part of a paragraph. The margins you specify automatically affect the
Emacs fill commands (*note Filling::) and line-breaking commands.
The Indentation submenu provides a convenient interface for
specifying these properties. The submenu contains four items:
`Indent More'
Indent the region by 4 columns (`increase-left-margin'). In
Enriched mode, this command is also available on `C-x <TAB>'; if
you supply a numeric argument, that says how many columns to add
to the margin (a negative argument reduces the number of columns).
`Indent Less'
Remove 4 columns of indentation from the region.
`Indent Right More'
Make the text narrower by indenting 4 columns at the right margin.
`Indent Right Less'
Remove 4 columns of indentation from the right margin.
You can use these commands repeatedly to increase or decrease the
indentation.
The most common way to use these commands is to change the
indentation of an entire paragraph. However, that is not the only use.
You can change the margins at any point; the new values take effect at
the end of the line (for right margins) or the beginning of the next
line (for left margins).
This makes it possible to format paragraphs with "hanging indents",
which means that the first line is indented less than subsequent lines.
To set up a hanging indent, increase the indentation of the region
starting after the first word of the paragraph and running until the end
of the paragraph.
Indenting the first line of a paragraph is easier. Set the margin
for the whole paragraph where you want it to be for the body of the
paragraph, then indent the first line by inserting extra spaces or tabs.
Sometimes, as a result of editing, the filling of a paragraph becomes
messed up--parts of the paragraph may extend past the left or right
margins. When this happens, use `M-q' (`fill-paragraph') to refill the
paragraph.
The variable `standard-indent' specifies how many columns these
commands should add to or subtract from the indentation. The default
value is 4. The overall default right margin for Enriched mode is
controlled by the variable `fill-column', as usual.
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: Format Justification, Next: Format Properties, Prev: Format Indentation, Up: Formatted Text
Justification in Formatted Text
-------------------------------
When editing formatted text, you can specify various styles of
justification for a paragraph. The style you specify automatically
affects the Emacs fill commands.
The Justification submenu provides a convenient interface for
specifying the style. The submenu contains five items:
`Flush Left'
This is the most common style of justification (at least for
English). Lines are aligned at the left margin but left uneven at
the right.
`Flush Right'
This aligns each line with the right margin. Spaces and tabs are
added on the left, if necessary, to make lines line up on the
right.
`Full'
This justifies the text, aligning both edges of each line.
Justified text looks very nice in a printed book, where the spaces
can all be adjusted equally, but it does not look as nice with a
fixed-width font on the screen. Perhaps a future version of Emacs
will be able to adjust the width of spaces in a line to achieve
elegant justification.
`Center'
This centers every line between the current margins.
`None'
This turns off filling entirely. Each line will remain as you
wrote it; the fill and auto-fill functions will have no effect on
text which has this setting. You can, however, still indent the
left margin. In unfilled regions, all newlines are treated as
hard newlines (*note Hard and Soft Newlines::) .
In Enriched mode, you can also specify justification from the
keyboard using the `M-j' prefix character:
`M-j l'
Make the region left-filled (`set-justification-left').
`M-j r'
Make the region right-filled (`set-justification-right').
`M-j f'
Make the region fully-justified (`set-justification-full').
`M-j c'
`M-S'
Make the region centered (`set-justification-center').
`M-j u'
Make the region unfilled (`set-justification-none').
Justification styles apply to entire paragraphs. All the
justification-changing commands operate on the paragraph containing
point, or, if the region is active, on all paragraphs which overlap the
region.
The default justification style is specified by the variable
`default-justification'. Its value should be one of the symbols
`left', `right', `full', `center', or `none'.
File: emacs, Node: Format Properties, Next: Forcing Enriched Mode, Prev: Format Justification, Up: Formatted Text
Setting Other Text Properties
-----------------------------
The Other Properties menu lets you add or remove three other useful
text properties: `read-only', `invisible' and `intangible'. The
`intangible' property disallows moving point within the text, the
`invisible' text property hides text from display, and the `read-only'
property disallows alteration of the text.
Each of these special properties has a menu item to add it to the
region. The last menu item, `Remove Special', removes all of these
special properties from the text in the region.
Currently, the `invisible' and `intangible' properties are _not_
saved in the text/enriched format. The `read-only' property is saved,
but it is not a standard part of the text/enriched format, so other
editors may not respect it.
File: emacs, Node: Forcing Enriched Mode, Prev: Format Properties, Up: Formatted Text
Forcing Enriched Mode
---------------------
Normally, Emacs knows when you are editing formatted text because it
recognizes the special annotations used in the file that you visited.
However, there are situations in which you must take special actions to
convert file contents or turn on Enriched mode:
* When you visit a file that was created with some other editor,
Emacs may not recognize the file as being in the text/enriched
format. In this case, when you visit the file you will see the
formatting commands rather than the formatted text. Type `M-x
format-decode-buffer' to translate it.
* When you _insert_ a file into a buffer, rather than visiting it.
Emacs does the necessary conversions on the text which you insert,
but it does not enable Enriched mode. If you wish to do that,
type `M-x enriched-mode'.
The command `format-decode-buffer' translates text in various
formats into Emacs's internal format. It asks you to specify the format
to translate from; however, normally you can type just <RET>, which
tells Emacs to guess the format.
If you wish to look at text/enriched file in its raw form, as a
sequence of characters rather than as formatted text, use the `M-x
find-file-literally' command. This visits a file, like `find-file',
but does not do format conversion. It also inhibits character code
conversion (*note Coding Systems::) and automatic uncompression (*note
Compressed Files::). To disable format conversion but allow character
code conversion and/or automatic uncompression if appropriate, use
`format-find-file' with suitable arguments.
File: emacs, Node: Programs, Next: Building, Prev: Text, Up: Top
Editing Programs
****************
Emacs provides many features to facilitate editing programs. Some
of these features can
* Find or move over top-level definitions (*note Defuns::).
* Apply the usual indentation conventions of the language (*note
Program Indent::).
* Insert, kill or align comments (*note Comments::).
* Balance parentheses (*note Parentheses::).
* Highlight program syntax (*note Font Lock::).
This chapter describes these features and many more.
* 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.
* Comments:: Inserting, killing, and aligning comments.
* Parentheses:: Commands that operate on parentheses.
* 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.
* Misc for Programs:: Other Emacs features useful for editing programs.
* C Modes:: Special commands of C, C++, Objective-C,
Java, and Pike modes.
* Fortran:: Fortran mode and its special features.
* Asm Mode:: Asm mode and its special features.
File: emacs, Node: Program Modes, Next: Defuns, Up: Programs
Major Modes for Programming Languages
=====================================
Emacs has specialized major modes for various programming languages.
*Note Major Modes::. A programming language major 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 of a function definition. It often customizes or
provides facilities for compiling and debugging programs as well.
Ideally, Emacs should provide a major mode for each programming
language that you might want to edit; if it doesn't have a mode for
your favorite language, you can contribute one. But often the mode for
one language can serve for other syntactically similar languages. The
major mode for language L is called `L-mode', and you can select it by
typing `M-x L-mode <RET>'. *Note Choosing Modes::.
The existing programming language major modes include Lisp, Scheme (a
variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (TeX's companion
for font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike,
PostScript, Prolog, Simula, Tcl, and VHDL. There is also a major mode
for makefiles, called Makefile mode. An alternative mode for Perl is
called CPerl mode. Modes are available for the scripting languages of
the common GNU and Unix shells, VMS DCL, and MS-DOS/MS-Windows `BAT'
files. There are also major modes for editing various sorts of
configuration files.
In most programming languages, indentation should vary from line to
line to illustrate the structure of the program. So the major modes
for programming languages arrange for <TAB> to update the indentation
of the current line. They also rebind <DEL> to treat a tab as if it
were the equivalent number of spaces; this lets you delete one column
of indentation without worrying whether the whitespace consists of
spaces or tabs. Use `C-b C-d' to delete a tab character before point,
in these modes.
Separate manuals are available for the modes for Ada (*note Ada
Mode: (ada-mode)Top.), C/C++/Objective C/Java/Corba IDL (*note CC Mode:
(ccmode)Top.) and the IDLWAVE modes (*note IDLWAVE: (idlwave)Top.).
Turning on a major mode runs a normal hook called the "mode hook",
which is the value of a Lisp variable. Each major mode has a mode
hook, and the hook's name is always made from the mode command's name
by adding `-hook'. For example, turning on C mode runs the hook
`c-mode-hook', while turning on Lisp mode runs the hook
`lisp-mode-hook'. The purpose of the mode hook is to give you a place
to set up customizations for that major mode. *Note Hooks::.
File: emacs, Node: Defuns, Next: Program Indent, Prev: Program Modes, Up: Programs
Top-Level Definitions, or Defuns
================================
In Emacs, a major definition at the top level in the buffer is
called a "defun". The name comes from Lisp, but in Emacs we use it for
all languages.
In most programming language modes, Emacs assumes that a defun is
any pair of parentheses (or braces, if the language uses braces this
way) that starts at the left margin. For example, in C, the body of a
function definition is normally a defun, because the open-brace that
begins it is normally at the left margin. A variable's initializer can
also count as a defun, if the open-brace that begins the initializer is
at the left margin.
However, some language modes provide their own code for recognizing
defuns in a way that suits the language syntax and conventions better.
* 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
Left Margin Convention
----------------------
In most major modes, Emacs assumes that any opening delimiter found
at the left margin is the start of a top-level definition, or defun.
Therefore, *never 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. Never put an open-brace or other opening
delimiter at the beginning of a line of C code unless it is at top
level.
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)
")
In the earliest days, the original Emacs found defuns by moving
upward a level of parentheses or braces until there were no more levels
to go up. This always required scanning all the way back to the
beginning of the buffer, even for a small function. To speed up the
operation, we changed Emacs to assume that any opening delimiter at the
left margin is the start of a defun. This heuristic is nearly always
right, and avoids the need to scan back to the beginning of the buffer.
However, it mandates following the convention described above.
File: emacs, Node: Moving by Defuns, Next: Imenu, Prev: Left Margin Paren, Up: Defuns
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
puts point at the beginning and mark at the end of the current defun.
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.
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
Imenu
-----
The Imenu facility offers a way to find the 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 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
Which Function Mode
-------------------
Which Function mode is a minor mode that displays the current
function name in the mode line, updating it as you move around in a
buffer.
To enable (or disable) Which Function mode, use the command `M-x
which-function-mode'. This command is global; it applies to all
buffers, both existing ones and those yet to be created. However, it
only takes effect in certain major modes, those listed in the value of
`which-func-modes'. If the value is `t', 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: Comments, Prev: Defuns, Up: Programs
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 properly
either a single line, a specified number of lines, or all of the lines
inside a single parenthetical grouping.
* Menu:
* Basic Indent:: Indenting a single line.
* Multi-line Indent:: Commands to reindent many lines at once.
* Lisp Indent:: Specifying how each Lisp function should be indented.
* C Indent:: Extra features for indenting C and related modes.
* Custom C Indent:: Controlling indentation style for C and related modes.
Emacs also provides a Lisp pretty-printer in the library `pp'. This
program reformats a Lisp object with indentation chosen to look nice.
File: emacs, Node: Basic Indent, Next: Multi-line Indent, Up: Program Indent
Basic Program Indentation Commands
----------------------------------
The basic indentation commands indent a single line according to the
usual conventions of the language you are editing.
`<TAB>'
Adjust indentation of current line.
`C-j'
Equivalent to <RET> followed by <TAB> (`newline-and-indent').
`<LINEFEED>'
This key, if the keyboard has it, is another way to enter `C-j'.
The basic indentation command is <TAB>, which gives the current line
the correct indentation as determined from the previous lines. The
function that <TAB> runs depends on the major mode; it is
`indent-for-tab-command' in Lisp mode, `c-indent-command' in C mode,
etc. These functions understand the syntax and conventions of
different languages, but they all do conceptually the same job: <TAB>
in any programming-language major mode inserts or deletes whitespace at
the beginning of the current line, independent of where point is in the
line. If point was inside the whitespace at the beginning of the line,
<TAB> puts it at the end of that whitespace; otherwise, <TAB> keeps
point fixed with respect to the characters around it.
Use `C-q <TAB>' to insert a tab at point.
When entering lines of new code, use `C-j' (`newline-and-indent'),
which is equivalent to a <RET> followed by a <TAB>. `C-j' at the end
of a line creates a blank line and then gives it the appropriate
indentation.
<TAB> indents lines that start within a parenthetical grouping each
under the preceding line (or the text after the parenthesis).
Therefore, if you manually give one of these lines a nonstandard
indentation, the lines below will tend to follow it. This behavior is
convenient in cases where you have overridden the standard result of
<TAB> because you find it unaesthetic for a particular line.
Remember that an open-parenthesis, open-brace or other opening
delimiter at the left margin is assumed by Emacs (including the
indentation routines) to be the start of a function. Therefore, you
must never have an opening delimiter in column zero that is not the
beginning of a function, not even inside a string. This restriction is
vital for making the indentation commands fast; you must simply accept
it. *Note Left Margin Paren::, for more information on this.
Normally, lines are indented with tabs and spaces. If you want Emacs
to use spaces only, see *Note Just Spaces::.
File: emacs, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Program Indent
Indenting Several Lines
-----------------------
When you wish to reindent several lines of code which have been
altered or moved to a different level in the parenthesis structure, you
have several commands available.
`C-M-q'
Reindent all the lines within one parenthetical
grouping(`indent-sexp').
`C-M-\'
Reindent all lines in the region (`indent-region').
`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.
You can reindent the contents of a single parenthetical grouping by
positioning point before the beginning of it and typing `C-M-q'
(`indent-sexp' in Lisp mode, `c-indent-exp' in C mode; also bound to
other suitable commands in other modes). The indentation of the line
where the grouping starts is not changed; therefore, this changes only
the relative indentation within the grouping, not its overall
indentation. To correct that as well, type <TAB> first.
Another way to specify the range to be reindented is with the
region. The command `C-M-\' (`indent-region') applies <TAB> to every
line whose first character is between point and mark.
If you like the relative indentation within a grouping, but not the
indentation of its first line, you can type `C-u <TAB>' to reindent the
whole grouping as a rigid unit. (This works in Lisp modes and C and
related 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, or C
preprocessor lines when in C mode.
You can also perform this operation on the region, using the command
`M-x indent-code-rigidly'. It 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 comment or a string, unless the region starts inside that
comment or string.
File: emacs, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Program Indent
Customizing Lisp Indentation
----------------------------
The indentation pattern for a Lisp expression can depend on the
function called by the expression. For each Lisp function, you can
choose among several predefined patterns of indentation, or define an
arbitrary one with a Lisp program.
The standard pattern of indentation is as follows: the second line
of the expression is indented under the first argument, if that is on
the same line as the beginning of the expression; otherwise, the second
line is indented underneath the function name. Each following line is
indented under the previous line whose nesting depth is the same.
If the variable `lisp-indent-offset' is non-`nil', it overrides the
usual indentation pattern for the second line of an expression, so that
such lines are always indented `lisp-indent-offset' more columns than
the containing list.
Certain functions override the standard pattern. Functions whose
names start with `def' treat the 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. There are four possibilities for this property:
`nil'
This is the same as no property--use the standard indentation
pattern.
`defun'
Handle this function like a `def' construct: treat the second line
as the start of a "body".
a number, NUMBER
The first NUMBER arguments of the function are "distinguished"
arguments; the rest are considered the body of the expression. A
line in the expression is indented according to whether the first
argument on it is distinguished or not. If the argument is part
of the body, the line is indented `lisp-body-indent' more columns
than the open-parenthesis starting the containing expression. If
the argument is distinguished and is either the first or second
argument, it is indented _twice_ that many extra columns. If the
argument is distinguished and not the first or second argument,
the line uses the standard pattern.
a symbol, SYMBOL
SYMBOL should be a function name; that function is called to
calculate the indentation of a line within this expression. The
function receives two arguments:
STATE
The value returned by `parse-partial-sexp' (a Lisp primitive
for indentation and nesting computation) when it parses up to
the beginning of this line.
POS
The position at which the line being indented begins.
It should return either a number, which is the number of columns of
indentation for that line, or a list whose car is such a number.
The difference between returning a number and returning a list is
that a number says that all following lines at the same nesting
level should be indented just like this one; a list says that
following lines might call for different indentations. This makes
a difference when the indentation is being computed by `C-M-q'; if
the value is a number, `C-M-q' need not recalculate indentation
for the following lines until the end of the list.