mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-14 09:39:42 +00:00
3802 lines
150 KiB
Plaintext
3802 lines
150 KiB
Plaintext
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1985,86,87,93,94,95,97,99,2000 Free Software Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@node Programs, Building, Text, Top
|
|
@chapter Editing Programs
|
|
@cindex Lisp editing
|
|
@cindex C editing
|
|
@cindex program editing
|
|
|
|
Emacs has many commands designed to understand the syntax of programming
|
|
languages such as Lisp and C. These commands can
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
|
|
@item
|
|
Move over or mark top-level expressions---@dfn{defuns}, in Lisp;
|
|
functions, in C (@pxref{Defuns}).
|
|
@item
|
|
Show how parentheses balance (@pxref{Matching}).
|
|
@item
|
|
Insert, kill or align comments (@pxref{Comments}).
|
|
@item
|
|
Follow the usual indentation conventions of the language
|
|
(@pxref{Program Indent}).
|
|
@end itemize
|
|
|
|
The commands for words, sentences and paragraphs are very useful in
|
|
editing code even though their canonical application is for editing
|
|
human language text. Most symbols contain words (@pxref{Words});
|
|
sentences can be found in strings and comments (@pxref{Sentences}).
|
|
Paragraphs per se don't exist in code, but the paragraph commands are
|
|
useful anyway, because programming language major modes define
|
|
paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
|
|
Judicious use of blank lines to make the program clearer will also
|
|
provide useful chunks of text for the paragraph commands to work
|
|
on.
|
|
|
|
@cindex selective display
|
|
@cindex outline
|
|
@cindex folding
|
|
@findex outline-minor-mode
|
|
@cindex outlines
|
|
The selective display feature is useful for looking at the overall
|
|
structure of a function (@pxref{Selective Display}). This feature
|
|
causes only the lines that are indented less than a specified amount to
|
|
appear on the screen. Programming modes often support Outline minor
|
|
mode (@pxref{Outline Mode}). The Foldout package provides
|
|
folding-editor features (@pxref{Foldout}).
|
|
|
|
The `automatic typing' features may be useful when writing programs.
|
|
@xref{,Autotyping,, autotype, Autotyping}.
|
|
|
|
@menu
|
|
* Program Modes:: Major modes for editing programs.
|
|
* Lists:: Expressions with balanced parentheses.
|
|
* List Commands:: The commands for working with list and sexps.
|
|
* Defuns:: Each program is made up of separate functions.
|
|
There are editing commands to operate on them.
|
|
* Program Indent:: Adjusting indentation to show the nesting.
|
|
* Matching:: Insertion of a close-delimiter flashes matching open.
|
|
* Comments:: Inserting, killing, and aligning comments.
|
|
* Balanced Editing:: Inserting two matching parentheses at once, etc.
|
|
* Symbol Completion:: Completion on symbol names of your program or language.
|
|
* Which Function:: Which Function mode shows which function you are in.
|
|
* Hideshow:: Displaying blocks selectively.
|
|
* Glasses:: Making identifiersLikeThis more readable.
|
|
* Documentation:: Getting documentation of functions you plan to call.
|
|
* Change Log:: Maintaining a change history for your program.
|
|
* Authors:: Maintaining an @file{AUTHORS} file.
|
|
* Tags:: Go direct to any function in your program in one
|
|
command. Tags remembers which file it is in.
|
|
* Imenu:: Making buffer indexes as menus.
|
|
* Emerge:: A convenient way of merging two versions of a program.
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Program Modes
|
|
@section Major Modes for Programming Languages
|
|
|
|
@cindex modes for programming languages
|
|
@cindex Perl mode
|
|
@cindex Icon mode
|
|
@cindex Awk mode
|
|
@cindex Makefile mode
|
|
@cindex Tcl mode
|
|
@cindex CPerl mode
|
|
@cindex DSSSL mode
|
|
@cindex Octave mode
|
|
@cindex Metafont mode
|
|
@cindex Modula2 mode
|
|
@cindex Prolog mode
|
|
@cindex Simula mode
|
|
@cindex VHDL mode
|
|
@cindex M4 mode
|
|
@cindex Shell-script mode
|
|
@cindex Delphi mode
|
|
@cindex PostScript mode
|
|
Emacs also has major modes for the programming languages Lisp, Scheme
|
|
(a variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
|
|
Awk, C, C++, Delphi (Object Pascal), Fortran (free and fixed format),
|
|
Icon, IDLWAVE,
|
|
Java, Metafont (@TeX{}'s companion for font creation), Modula2,
|
|
Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula,
|
|
VHDL, CORBA IDL, and Tcl.
|
|
There is also a major mode for makefiles, called Makefile
|
|
mode. An alternative mode for Perl is called CPerl mode. Modes
|
|
are available for scripts for the common Unix shells, VMS DCL and
|
|
MS-DOS/MS-Windows `BAT' files. In a similar fashion to programming
|
|
languages, modes are provided for editing various sorts of configuration
|
|
files.
|
|
|
|
Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
|
|
Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
|
|
(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
|
|
(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
|
|
|
|
Ideally, a major mode should be implemented for each programming
|
|
language that you might want to edit with Emacs; but often the mode for
|
|
one language can serve for other syntactically similar languages. The
|
|
language modes that exist are those that someone decided to take the
|
|
trouble to write.
|
|
|
|
There are several forms of Lisp mode, which differ in the way they
|
|
interface to Lisp execution. @xref{Executing Lisp}.
|
|
|
|
Each of the programming language major modes defines the @key{TAB} key
|
|
to run an indentation function that knows the indentation conventions of
|
|
that language and updates the current line's indentation accordingly.
|
|
For example, in C mode @key{TAB} is bound to @code{c-indent-line}.
|
|
@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
|
|
thus, it too indents in a mode-specific fashion.
|
|
|
|
@kindex DEL @r{(programming modes)}
|
|
@findex backward-delete-char-untabify
|
|
In most programming languages, indentation is likely to vary from line to
|
|
line. So the major modes for those languages rebind @key{DEL} to treat a
|
|
tab as if it were the equivalent number of spaces (using the command
|
|
@code{backward-delete-char-untabify}). This makes it possible to rub out
|
|
indentation one column at a time without worrying whether it is made up of
|
|
spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point,
|
|
in these modes.
|
|
|
|
Programming language modes define paragraphs to be separated only by
|
|
blank lines, so that the paragraph commands remain useful. Auto Fill mode,
|
|
if enabled in a programming language major mode, indents the new lines
|
|
which it creates.
|
|
|
|
@cindex mode hook
|
|
@vindex c-mode-hook
|
|
@vindex lisp-mode-hook
|
|
@vindex emacs-lisp-mode-hook
|
|
@vindex lisp-interaction-mode-hook
|
|
@vindex scheme-mode-hook
|
|
Turning on a major mode runs a normal hook called the @dfn{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 @samp{-hook}. For example, turning on C mode runs the hook
|
|
@code{c-mode-hook}, while turning on Lisp mode runs the hook
|
|
@code{lisp-mode-hook}. @xref{Hooks}.
|
|
|
|
@node Lists
|
|
@section Lists and Sexps
|
|
|
|
@cindex Control-Meta
|
|
By convention, Emacs keys for dealing with balanced expressions are
|
|
usually Control-Meta characters. They tend to be analogous in
|
|
function to their Control and Meta equivalents. These commands are
|
|
usually thought of as pertaining to expressions in programming
|
|
languages, but can be useful with any language in which some sort of
|
|
parentheses exist (including human languages).
|
|
|
|
@cindex list
|
|
@cindex sexp
|
|
@cindex expression
|
|
@cindex parentheses, moving across
|
|
@cindex matching parenthesis, moving to
|
|
These commands fall into two classes. Some deal only with @dfn{lists}
|
|
(parenthetical groupings). They see nothing except parentheses, brackets,
|
|
braces (whichever ones must balance in the language you are working with),
|
|
and escape characters that might be used to quote those.
|
|
|
|
The other commands deal with expressions or @dfn{sexps}. The word `sexp'
|
|
is derived from @dfn{s-expression}, the ancient term for an expression in
|
|
Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
|
|
refers to an expression in whatever language your program is written in.
|
|
Each programming language has its own major mode, which customizes the
|
|
syntax tables so that expressions in that language count as sexps.
|
|
|
|
Sexps typically include symbols, numbers, and string constants, as well
|
|
as anything contained in parentheses, brackets or braces.
|
|
|
|
In languages that use prefix and infix operators, such as C, it is not
|
|
possible for all expressions to be sexps. For example, C mode does not
|
|
recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression;
|
|
it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
|
|
@samp{+} as punctuation between them. This is a fundamental ambiguity:
|
|
both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
|
|
move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
|
|
single sexp in C mode.
|
|
|
|
Some languages have obscure forms of expression syntax that nobody
|
|
has bothered to make Emacs understand properly.
|
|
|
|
@node List Commands
|
|
@section List And Sexp Commands
|
|
|
|
@c doublewidecommands
|
|
@table @kbd
|
|
@item C-M-f
|
|
Move forward over a sexp (@code{forward-sexp}).
|
|
@item C-M-b
|
|
Move backward over a sexp (@code{backward-sexp}).
|
|
@item C-M-k
|
|
Kill sexp forward (@code{kill-sexp}).
|
|
@item C-M-@key{DEL}
|
|
Kill sexp backward (@code{backward-kill-sexp}).
|
|
@item C-M-u
|
|
Move up and backward in list structure (@code{backward-up-list}).
|
|
@item C-M-d
|
|
Move down and forward in list structure (@code{down-list}).
|
|
@item C-M-n
|
|
Move forward over a list (@code{forward-list}).
|
|
@item C-M-p
|
|
Move backward over a list (@code{backward-list}).
|
|
@item C-M-t
|
|
Transpose expressions (@code{transpose-sexps}).
|
|
@item C-M-@@
|
|
Put mark after following expression (@code{mark-sexp}).
|
|
@end table
|
|
|
|
@kindex C-M-f
|
|
@kindex C-M-b
|
|
@findex forward-sexp
|
|
@findex backward-sexp
|
|
To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
|
|
the first significant character after point is an opening delimiter
|
|
(@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
|
|
moves past the matching closing delimiter. If the character begins a
|
|
symbol, string, or number, @kbd{C-M-f} moves over that.
|
|
|
|
The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
|
|
sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
|
|
directions reversed. If there are any prefix characters (single-quote,
|
|
backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
|
|
over them as well. The sexp commands move across comments as if they
|
|
were whitespace in most modes.
|
|
|
|
@kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
|
|
specified number of times; with a negative argument, it moves in the
|
|
opposite direction.
|
|
|
|
@kindex C-M-k
|
|
@findex kill-sexp
|
|
@kindex C-M-DEL
|
|
@findex backward-kill-sexp
|
|
Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp})
|
|
or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills
|
|
the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}}
|
|
kills the characters that @kbd{C-M-b} would move over.
|
|
|
|
@kindex C-M-n
|
|
@kindex C-M-p
|
|
@findex forward-list
|
|
@findex backward-list
|
|
The @dfn{list commands} move over lists, as the sexp commands do, but skip
|
|
blithely over any number of other kinds of sexps (symbols, strings, etc.).
|
|
They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
|
|
(@code{backward-list}). The main reason they are useful is that they
|
|
usually ignore comments (since the comments usually do not contain any
|
|
lists).@refill
|
|
|
|
@kindex C-M-u
|
|
@kindex C-M-d
|
|
@findex backward-up-list
|
|
@findex down-list
|
|
@kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
|
|
that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u}
|
|
(@code{backward-up-list}).
|
|
@kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
|
|
positive argument serves as a repeat count; a negative argument reverses
|
|
direction of motion and also requests repetition, so it moves forward and
|
|
up one or more levels.@refill
|
|
|
|
To move @emph{down} in list structure, use @kbd{C-M-d}
|
|
(@code{down-list}). In Lisp mode, where @samp{(} is the only opening
|
|
delimiter, this is nearly the same as searching for a @samp{(}. An
|
|
argument specifies the number of levels of parentheses to go down.
|
|
|
|
@cindex transposition
|
|
@kindex C-M-t
|
|
@findex transpose-sexps
|
|
A somewhat random-sounding command which is nevertheless handy is
|
|
@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp
|
|
across the next one. An argument serves as a repeat count, and a
|
|
negative argument drags backwards (thus canceling out the effect of
|
|
@kbd{C-M-t} with a positive argument). An argument of zero, rather than
|
|
doing nothing, transposes the sexps ending after point and the mark.
|
|
|
|
@kindex C-M-@@
|
|
@findex mark-sexp
|
|
To set the region around the next sexp in the buffer, use @kbd{C-M-@@}
|
|
(@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f}
|
|
would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In
|
|
particular, a negative argument is useful for putting the mark at the
|
|
beginning of the previous sexp.
|
|
|
|
The list and sexp commands' understanding of syntax is completely
|
|
controlled by the syntax table. Any character can, for example, be
|
|
declared to be an opening delimiter and act like an open parenthesis.
|
|
@xref{Syntax}.
|
|
|
|
@node Defuns
|
|
@section Defuns
|
|
@cindex defuns
|
|
|
|
In Emacs, a parenthetical grouping at the top level in the buffer is
|
|
called a @dfn{defun}. The name derives from the fact that most top-level
|
|
lists in a Lisp file are instances of the special form @code{defun}, but
|
|
any top-level parenthetical grouping counts as a defun in Emacs parlance
|
|
regardless of what its contents are, and regardless of the programming
|
|
language in use. For example, in C, the body of a function definition is a
|
|
defun.
|
|
|
|
@c doublewidecommands
|
|
@table @kbd
|
|
@item C-M-a
|
|
Move to beginning of current or preceding defun
|
|
(@code{beginning-of-defun}).
|
|
@item C-M-e
|
|
Move to end of current or following defun (@code{end-of-defun}).
|
|
@item C-M-h
|
|
Put region around whole current or following defun (@code{mark-defun}).
|
|
@end table
|
|
|
|
@kindex C-M-a
|
|
@kindex C-M-e
|
|
@kindex C-M-h
|
|
@findex beginning-of-defun
|
|
@findex end-of-defun
|
|
@findex mark-defun
|
|
The commands to move to the beginning and end of the current defun are
|
|
@kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
|
|
|
|
@findex c-mark-function
|
|
If you wish to operate on the current defun, use @kbd{C-M-h}
|
|
(@code{mark-defun}) which puts point at the beginning and mark at the end
|
|
of the current or next defun. For example, this is the easiest way to get
|
|
ready to move the defun to a different place in the text. In C mode,
|
|
@kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the
|
|
same as @code{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. @xref{Marking Objects}.
|
|
|
|
@cindex open-parenthesis in leftmost column
|
|
@cindex ( in leftmost column
|
|
Emacs assumes that any open-parenthesis found in the leftmost column
|
|
is the start of a defun. Therefore, @strong{never put an
|
|
open-parenthesis at the left margin in a Lisp file unless it is the
|
|
start of a top-level list. Never put an open-brace or other opening
|
|
delimiter at the beginning of a line of C code unless it starts the body
|
|
of a function.} The most likely problem case is when you want an
|
|
opening delimiter at the start of a line inside a string. To avoid
|
|
trouble, put an escape character (@samp{\}, in C and Emacs Lisp,
|
|
@samp{/} in some other Lisp dialects) before the opening delimiter. It
|
|
will not affect the contents of the string.
|
|
|
|
In the remotest past, the original Emacs found defuns by moving upward a
|
|
level of parentheses until there were no more levels to go up. This always
|
|
required scanning all the way back to the beginning of the buffer, even for
|
|
a small function. To speed up the operation, Emacs was changed to assume
|
|
that any @samp{(} (or other character assigned the syntactic class of
|
|
opening-delimiter) at the left margin is the start of a defun. This
|
|
heuristic is nearly always right and avoids the costly scan; however,
|
|
it mandates the convention described above.
|
|
|
|
@node Program Indent
|
|
@section Indentation for Programs
|
|
@cindex 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.
|
|
@end menu
|
|
|
|
Emacs also provides a Lisp pretty-printer in the library @code{pp}.
|
|
This program reformats a Lisp object with indentation chosen to look nice.
|
|
|
|
@node Basic Indent
|
|
@subsection Basic Program Indentation Commands
|
|
|
|
@c WideCommands
|
|
@table @kbd
|
|
@item @key{TAB}
|
|
Adjust indentation of current line.
|
|
@item C-j
|
|
Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
|
|
@end table
|
|
|
|
@kindex TAB @r{(programming modes)}
|
|
@findex c-indent-line
|
|
@findex lisp-indent-line
|
|
The basic indentation command is @key{TAB}, which gives the current line
|
|
the correct indentation as determined from the previous lines. The
|
|
function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
|
|
in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
|
|
understand different syntaxes for different languages, but they all do
|
|
about the same thing. @key{TAB} in any programming-language major mode
|
|
inserts or deletes whitespace at the beginning of the current line,
|
|
independent of where point is in the line. If point is inside the
|
|
whitespace at the beginning of the line, @key{TAB} leaves it at the end of
|
|
that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
|
|
the characters around it.
|
|
|
|
Use @kbd{C-q @key{TAB}} to insert a tab at point.
|
|
|
|
@kindex C-j
|
|
@findex newline-and-indent
|
|
When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}),
|
|
which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates
|
|
a blank line and then gives it the appropriate indentation.
|
|
|
|
@key{TAB} indents the second and following lines of the body of a
|
|
parenthetical grouping each under the preceding one; therefore, if you
|
|
alter one line's indentation to be nonstandard, the lines below will
|
|
tend to follow it. This behavior is convenient in cases where you have
|
|
overridden the standard result of @key{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. @xref{Defuns}, for more
|
|
information on this.
|
|
|
|
@node Multi-line Indent
|
|
@subsection Indenting Several Lines
|
|
|
|
When you wish to reindent several lines of code which have been altered
|
|
or moved to a different level in the list structure, you have several
|
|
commands available.
|
|
|
|
@table @kbd
|
|
@item C-M-q
|
|
Reindent all the lines within one list (@code{indent-sexp}).
|
|
@item C-u @key{TAB}
|
|
Shift an entire list rigidly sideways so that its first line
|
|
is properly indented.
|
|
@item C-M-\
|
|
Reindent all lines in the region (@code{indent-region}).
|
|
@end table
|
|
|
|
@kindex C-M-q
|
|
@findex indent-sexp
|
|
You can reindent the contents of a single list by positioning point
|
|
before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
|
|
Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable
|
|
commands in other modes). The indentation of the line the sexp starts on
|
|
is not changed; therefore, only the relative indentation within the list,
|
|
and not its position, is changed. To correct the position as well, type a
|
|
@key{TAB} before the @kbd{C-M-q}.
|
|
|
|
@kindex C-u TAB
|
|
If the relative indentation within a list is correct but the
|
|
indentation of its first line is not, go to that line and type @kbd{C-u
|
|
@key{TAB}}. @key{TAB} with a numeric argument reindents the current
|
|
line as usual, then reindents by the same amount all the lines in the
|
|
grouping starting on the current line. In other words, it reindents the
|
|
whole grouping rigidly as a unit. It is clever, though, and does not
|
|
alter lines that start inside strings, or C preprocessor lines when in C
|
|
mode.
|
|
|
|
Another way to specify the range to be reindented is with the region.
|
|
The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to
|
|
every line whose first character is between point and mark.
|
|
|
|
@node Lisp Indent
|
|
@subsection Customizing Lisp Indentation
|
|
@cindex 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.
|
|
|
|
@vindex lisp-indent-offset
|
|
If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
|
|
the usual indentation pattern for the second line of an expression, so that
|
|
such lines are always indented @code{lisp-indent-offset} more columns than
|
|
the containing list.
|
|
|
|
@vindex lisp-body-indent
|
|
The standard pattern is overridden for certain functions. Functions
|
|
whose names start with @code{def} always indent the second line by
|
|
@code{lisp-body-indent} extra columns beyond the open-parenthesis
|
|
starting the expression.
|
|
|
|
The standard pattern can be overridden in various ways for individual
|
|
functions, according to the @code{lisp-indent-function} property of the
|
|
function name. There are four possibilities for this property:
|
|
|
|
@table @asis
|
|
@item @code{nil}
|
|
This is the same as no property; the standard indentation pattern is used.
|
|
@item @code{defun}
|
|
The pattern used for function names that start with @code{def} is used for
|
|
this function also.
|
|
@item a number, @var{number}
|
|
The first @var{number} arguments of the function are
|
|
@dfn{distinguished} arguments; the rest are considered the @dfn{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 @code{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 @emph{twice} that many extra columns.
|
|
If the argument is distinguished and not the first or second argument,
|
|
the standard pattern is followed for that line.
|
|
@item a symbol, @var{symbol}
|
|
@var{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:
|
|
@table @asis
|
|
@item @var{state}
|
|
The value returned by @code{parse-partial-sexp} (a Lisp primitive for
|
|
indentation and nesting computation) when it parses up to the
|
|
beginning of this line.
|
|
@item @var{pos}
|
|
The position at which the line being indented begins.
|
|
@end table
|
|
@noindent
|
|
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 @kbd{C-M-q}; if the value is a
|
|
number, @kbd{C-M-q} need not recalculate indentation for the following
|
|
lines until the end of the list.
|
|
@end table
|
|
|
|
@node C Indent
|
|
@subsection Commands for C Indentation
|
|
|
|
Here are the commands for indentation in C mode and related modes:
|
|
|
|
@table @code
|
|
@item C-c C-q
|
|
@kindex C-c C-q @r{(C mode)}
|
|
@findex c-indent-defun
|
|
Reindent the current top-level function definition or aggregate type
|
|
declaration (@code{c-indent-defun}).
|
|
|
|
@item C-M-q
|
|
@kindex C-M-q @r{(C mode)}
|
|
@findex c-indent-exp
|
|
Reindent each line in the balanced expression that follows point
|
|
(@code{c-indent-exp}). A prefix argument inhibits error checking and
|
|
warning messages about invalid syntax.
|
|
|
|
@item @key{TAB}
|
|
@findex c-indent-command
|
|
Reindent the current line, and/or in some cases insert a tab character
|
|
(@code{c-indent-command}).
|
|
|
|
If @code{c-tab-always-indent} is @code{t}, this command always reindents
|
|
the current line and does nothing else. This is the default.
|
|
|
|
If that variable is @code{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 @code{indent-tabs-mode} is @code{nil}).
|
|
|
|
Any other value (not @code{nil} or @code{t}) means always reindent the
|
|
line, and also insert a tab if within a comment, a string, or a
|
|
preprocessor directive.
|
|
|
|
@item C-u @key{TAB}
|
|
Reindent the current line according to its syntax; also rigidly reindent
|
|
any other lines of the expression that starts on the current line.
|
|
@xref{Multi-line Indent}.
|
|
@end table
|
|
|
|
To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
|
|
first selects the whole buffer as the region, then reindents that
|
|
region.
|
|
|
|
To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
|
|
to the front of the block and then reindents it all.
|
|
|
|
@node Custom C Indent
|
|
@subsection Customizing C Indentation
|
|
|
|
C mode and related modes use a simple yet flexible mechanism for
|
|
customizing indentation. The mechanism works in two steps: first it
|
|
classifies the line syntactically according to its contents and context;
|
|
second, it associates each kind of syntactic construct with an
|
|
indentation offset which you can customize.
|
|
|
|
@menu
|
|
* Syntactic Analysis::
|
|
* Indentation Calculation::
|
|
* Changing Indent Style::
|
|
* Syntactic Symbols::
|
|
* Variables for C Indent::
|
|
* C Indent Styles::
|
|
@end menu
|
|
|
|
@node Syntactic Analysis
|
|
@subsubsection Step 1---Syntactic Analysis
|
|
@cindex syntactic analysis
|
|
|
|
In the first step, the C indentation mechanism looks at the line
|
|
before the one you are currently indenting and determines the syntactic
|
|
components of the construct on that line. It builds a list of these
|
|
syntactic components, each of which contains a @dfn{syntactic symbol}
|
|
and sometimes also a buffer position. Some syntactic symbols describe
|
|
grammatical elements, for example @code{statement} and
|
|
@code{substatement}; others describe locations amidst grammatical
|
|
elements, for example @code{class-open} and @code{knr-argdecl}.
|
|
|
|
Conceptually, a line of C code is always indented relative to the
|
|
indentation of some line higher up in the buffer. This is represented
|
|
by the buffer positions in the syntactic component list.
|
|
|
|
Here is an example. Suppose we have the following code in a C++ mode
|
|
buffer (the line numbers don't actually appear in the buffer):
|
|
|
|
@example
|
|
1: void swap (int& a, int& b)
|
|
2: @{
|
|
3: int tmp = a;
|
|
4: a = b;
|
|
5: b = tmp;
|
|
6: @}
|
|
@end example
|
|
|
|
If you type @kbd{C-c C-s} (which runs the command
|
|
@code{c-show-syntactic-information}) on line 4, it shows the result of
|
|
the indentation mechanism for that line:
|
|
|
|
@example
|
|
((statement . 32))
|
|
@end example
|
|
|
|
This indicates that the line is a statement and it is indented
|
|
relative to buffer position 32, which happens to be the @samp{i} in
|
|
@code{int} on line 3. If you move the cursor to line 3 and type
|
|
@kbd{C-c C-s}, it displays this:
|
|
|
|
@example
|
|
((defun-block-intro . 28))
|
|
@end example
|
|
|
|
This indicates that the @code{int} line is the first statement in a
|
|
block, and is indented relative to buffer position 28, which is the
|
|
brace just after the function header.
|
|
|
|
@noindent
|
|
Here is another example:
|
|
|
|
@example
|
|
1: int add (int val, int incr, int doit)
|
|
2: @{
|
|
3: if (doit)
|
|
4: @{
|
|
5: return (val + incr);
|
|
6: @}
|
|
7: return (val);
|
|
8: @}
|
|
@end example
|
|
|
|
@noindent
|
|
Typing @kbd{C-c C-s} on line 4 displays this:
|
|
|
|
@example
|
|
((substatement-open . 43))
|
|
@end example
|
|
|
|
This says that the brace @emph{opens} a substatement block. By the
|
|
way, a @dfn{substatement} indicates the line after an @code{if},
|
|
@code{else}, @code{while}, @code{do}, @code{switch}, @code{for},
|
|
@code{try}, @code{catch}, @code{finally}, or @code{synchronized}
|
|
statement.
|
|
|
|
@cindex syntactic component
|
|
@cindex syntactic symbol
|
|
@vindex c-syntactic-context
|
|
Within the C indentation commands, after a line has been analyzed
|
|
syntactically for indentation, the variable @code{c-syntactic-context}
|
|
contains a list that describes the results. Each element in this list
|
|
is a @dfn{syntactic component}: a cons cell containing a syntactic
|
|
symbol and (optionally) its corresponding buffer position. There may be
|
|
several elements in a component list; typically only one element has a
|
|
buffer position.
|
|
|
|
@node Indentation Calculation
|
|
@subsubsection Step 2---Indentation Calculation
|
|
@cindex Indentation Calculation
|
|
|
|
The C indentation mechanism calculates the indentation for the current
|
|
line using the list of syntactic components, @code{c-syntactic-context},
|
|
derived from syntactic analysis. Each component is a cons cell that
|
|
contains a syntactic symbol and may also contain a buffer position.
|
|
|
|
Each component contributes to the final total indentation of the line
|
|
in two ways. First, the syntactic symbol identifies an element of
|
|
@code{c-offsets-alist}, which is an association list mapping syntactic
|
|
symbols into indentation offsets. Each syntactic symbol's offset adds
|
|
to the total indentation. Second, if the component includes a buffer
|
|
position, the column number of that position adds to the indentation.
|
|
All these offsets and column numbers, added together, give the total
|
|
indentation.
|
|
|
|
The following examples demonstrate the workings of the C indentation
|
|
mechanism:
|
|
|
|
@example
|
|
1: void swap (int& a, int& b)
|
|
2: @{
|
|
3: int tmp = a;
|
|
4: a = b;
|
|
5: b = tmp;
|
|
6: @}
|
|
@end example
|
|
|
|
Suppose that point is on line 3 and you type @key{TAB} to reindent the
|
|
line. As explained above (@pxref{Syntactic Analysis}), the syntactic
|
|
component list for that line is:
|
|
|
|
@example
|
|
((defun-block-intro . 28))
|
|
@end example
|
|
|
|
In this case, the indentation calculation first looks up
|
|
@code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose
|
|
that it finds the integer 2; it adds this to the running total
|
|
(initialized to zero), yielding a updated total indentation of 2 spaces.
|
|
|
|
The next step is to find the column number of buffer position 28.
|
|
Since the brace at buffer position 28 is in column zero, this adds 0 to
|
|
the running total. Since this line has only one syntactic component,
|
|
the total indentation for the line is 2 spaces.
|
|
|
|
@example
|
|
1: int add (int val, int incr, int doit)
|
|
2: @{
|
|
3: if (doit)
|
|
4: @{
|
|
5: return(val + incr);
|
|
6: @}
|
|
7: return(val);
|
|
8: @}
|
|
@end example
|
|
|
|
If you type @key{TAB} on line 4, the same process is performed, but
|
|
with different data. The syntactic component list for this line is:
|
|
|
|
@example
|
|
((substatement-open . 43))
|
|
@end example
|
|
|
|
Here, the indentation calculation's first job is to look up the
|
|
symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume
|
|
that the offset for this symbol is 2. At this point the running total
|
|
is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43,
|
|
which is the @samp{i} in @code{if} on line 3. This character is in
|
|
column 2 on that line. Adding this yields a total indentation of 4
|
|
spaces.
|
|
|
|
@vindex c-strict-syntax-p
|
|
If a syntactic symbol in the analysis of a line does not appear in
|
|
@code{c-offsets-alist}, it is ignored; if in addition the variable
|
|
@code{c-strict-syntax-p} is non-@code{nil}, it is an error.
|
|
|
|
@node Changing Indent Style
|
|
@subsubsection Changing Indentation Style
|
|
|
|
There are two ways to customize the indentation style for the C-like
|
|
modes. First, you can select one of several predefined styles, each of
|
|
which specifies offsets for all the syntactic symbols. For more
|
|
flexibility, you can customize the handling of individual syntactic
|
|
symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic
|
|
symbols.
|
|
|
|
@table @kbd
|
|
@item M-x c-set-style @key{RET} @var{style} @key{RET}
|
|
Select predefined indentation style @var{style}. Type @kbd{?} when
|
|
entering @var{style} to see a list of supported styles; to find out what
|
|
a style looks like, select it and reindent some C code.
|
|
|
|
@item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET}
|
|
Set the indentation offset for syntactic symbol @var{symbol}
|
|
(@code{c-set-offset}). The second argument @var{offset} specifies the
|
|
new indentation offset.
|
|
@end table
|
|
|
|
The @code{c-offsets-alist} variable controls the amount of
|
|
indentation to give to each syntactic symbol. Its value is an
|
|
association list, and each element of the list has the form
|
|
@code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets
|
|
for various syntactic symbols, you can customize indentation in fine
|
|
detail. To change this alist, use @code{c-set-offset} (see below).
|
|
|
|
Each offset value in @code{c-offsets-alist} can be an integer, a
|
|
function or variable name, a list, or one of the following symbols: @code{+},
|
|
@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative
|
|
multiples of the variable @code{c-basic-offset}. Thus, if you want to
|
|
change the levels of indentation to be 3 spaces instead of 2 spaces, set
|
|
@code{c-basic-offset} to 3.
|
|
|
|
Using a function as the offset value provides the ultimate flexibility
|
|
in customizing indentation. The function is called with a single
|
|
argument containing the @code{cons} of the syntactic symbol and
|
|
the buffer position, if any. The function should return an integer
|
|
offset.
|
|
|
|
If the offset value is a list, its elements are processed according
|
|
to the rules above until a non-@code{nil} value is found. That value is
|
|
then added to the total indentation in the normal manner. The primary
|
|
use for this is to combine the results of several functions.
|
|
|
|
@kindex C-c C-o @r{(C mode)}
|
|
@findex c-set-offset
|
|
The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to
|
|
set offsets, both interactively or in your @file{~/.emacs} file. First
|
|
specify the syntactic symbol, then the offset you want. @xref{Syntactic
|
|
Symbols}, for a list of valid syntactic symbols and their meanings.
|
|
|
|
@node Syntactic Symbols
|
|
@subsubsection Syntactic Symbols
|
|
|
|
Here is a table of valid syntactic symbols for indentation in C and
|
|
related modes, with their syntactic meanings. Normally, most of these
|
|
symbols are assigned offsets in @code{c-offsets-alist}.
|
|
|
|
@table @code
|
|
@item string
|
|
Inside a multi-line string.
|
|
|
|
@item c
|
|
Inside a multi-line C style block comment.
|
|
|
|
@item defun-open
|
|
On a brace that opens a function definition.
|
|
|
|
@item defun-close
|
|
On a brace that closes a function definition.
|
|
|
|
@item defun-block-intro
|
|
In the first line in a top-level defun.
|
|
|
|
@item class-open
|
|
On a brace that opens a class definition.
|
|
|
|
@item class-close
|
|
On a brace that closes a class definition.
|
|
|
|
@item inline-open
|
|
On a brace that opens an in-class inline method.
|
|
|
|
@item inline-close
|
|
On a brace that closes an in-class inline method.
|
|
|
|
@item extern-lang-open
|
|
On a brace that opens an external language block.
|
|
|
|
@item extern-lang-close
|
|
On a brace that closes an external language block.
|
|
|
|
@item func-decl-cont
|
|
The region between a function definition's argument list and the defun
|
|
opening brace (excluding K&R function definitions). In C, you cannot
|
|
put anything but whitespace and comments between them; in C++ and Java,
|
|
@code{throws} declarations and other things can appear in this context.
|
|
|
|
@item knr-argdecl-intro
|
|
On the first line of a K&R C argument declaration.
|
|
|
|
@item knr-argdecl
|
|
In one of the subsequent lines in a K&R C argument declaration.
|
|
|
|
@item topmost-intro
|
|
On the first line in a topmost construct definition.
|
|
|
|
@item topmost-intro-cont
|
|
On the topmost definition continuation lines.
|
|
|
|
@item member-init-intro
|
|
On the first line in a member initialization list.
|
|
|
|
@item member-init-cont
|
|
On one of the subsequent member initialization list lines.
|
|
|
|
@item inher-intro
|
|
On the first line of a multiple inheritance list.
|
|
|
|
@item inher-cont
|
|
On one of the subsequent multiple inheritance lines.
|
|
|
|
@item block-open
|
|
On a statement block open brace.
|
|
|
|
@item block-close
|
|
On a statement block close brace.
|
|
|
|
@item brace-list-open
|
|
On the opening brace of an @code{enum} or @code{static} array list.
|
|
|
|
@item brace-list-close
|
|
On the closing brace of an @code{enum} or @code{static} array list.
|
|
|
|
@item brace-list-intro
|
|
On the first line in an @code{enum} or @code{static} array list.
|
|
|
|
@item brace-list-entry
|
|
On one of the subsequent lines in an @code{enum} or @code{static} array
|
|
list.
|
|
|
|
@item brace-entry-open
|
|
On one of the subsequent lines in an @code{enum} or @code{static} array
|
|
list, when the line begins with an open brace.
|
|
|
|
@item statement
|
|
On an ordinary statement.
|
|
|
|
@item statement-cont
|
|
On a continuation line of a statement.
|
|
|
|
@item statement-block-intro
|
|
On the first line in a new statement block.
|
|
|
|
@item statement-case-intro
|
|
On the first line in a @code{case} ``block.''
|
|
|
|
@item statement-case-open
|
|
On the first line in a @code{case} block starting with brace.
|
|
|
|
@item inexpr-statement
|
|
On a statement block inside an expression. This is used for a GNU
|
|
extension to the C language, and for Pike special functions that take a
|
|
statement block as an argument.
|
|
|
|
@item inexpr-class
|
|
On a class definition inside an expression. This is used for anonymous
|
|
classes and anonymous array initializers in Java.
|
|
|
|
@item substatement
|
|
On the first line after an @code{if}, @code{while}, @code{for},
|
|
@code{do}, or @code{else}.
|
|
|
|
@item substatement-open
|
|
On the brace that opens a substatement block.
|
|
|
|
@item case-label
|
|
On a @code{case} or @code{default} label.
|
|
|
|
@item access-label
|
|
On a C++ @code{private}, @code{protected}, or @code{public} access label.
|
|
|
|
@item label
|
|
On any ordinary label.
|
|
|
|
@item do-while-closure
|
|
On the @code{while} that ends a @code{do}-@code{while} construct.
|
|
|
|
@item else-clause
|
|
On the @code{else} of an @code{if}-@code{else} construct.
|
|
|
|
@item catch-clause
|
|
On the @code{catch} and @code{finally} lines in
|
|
@code{try}@dots{}@code{catch} constructs in C++ and Java.
|
|
|
|
@item comment-intro
|
|
On a line containing only a comment introduction.
|
|
|
|
@item arglist-intro
|
|
On the first line in an argument list.
|
|
|
|
@item arglist-cont
|
|
On one of the subsequent argument list lines when no arguments follow on
|
|
the same line as the arglist opening parenthesis.
|
|
|
|
@item arglist-cont-nonempty
|
|
On one of the subsequent argument list lines when at least one argument
|
|
follows on the same line as the arglist opening parenthesis.
|
|
|
|
@item arglist-close
|
|
On the closing parenthesis of an argument list.
|
|
|
|
@item stream-op
|
|
On one of the lines continuing a stream operator construct.
|
|
|
|
@item inclass
|
|
On a construct that is nested inside a class definition. The
|
|
indentation is relative to the open brace of the class definition.
|
|
|
|
@item inextern-lang
|
|
On a construct that is nested inside an external language block.
|
|
|
|
@item inexpr-statement
|
|
On the first line of statement block inside an expression. This is used
|
|
for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}.
|
|
It is also used for the special functions that takes a statement block
|
|
as an argument in Pike.
|
|
|
|
@item inexpr-class
|
|
On the first line of a class definition inside an expression. This is
|
|
used for anonymous classes and anonymous array initializers in Java.
|
|
|
|
@item cpp-macro
|
|
On the start of a cpp macro.
|
|
|
|
@item friend
|
|
On a C++ @code{friend} declaration.
|
|
|
|
@item objc-method-intro
|
|
On the first line of an Objective-C method definition.
|
|
|
|
@item objc-method-args-cont
|
|
On one of the lines continuing an Objective-C method definition.
|
|
|
|
@item objc-method-call-cont
|
|
On one of the lines continuing an Objective-C method call.
|
|
|
|
@item inlambda
|
|
Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only
|
|
used in Pike.
|
|
|
|
@item lambda-intro-cont
|
|
On a line continuing the header of a lambda function, between the
|
|
@code{lambda} keyword and the function body. Only used in Pike.
|
|
@end table
|
|
|
|
@node Variables for C Indent
|
|
@subsubsection Variables for C Indentation
|
|
|
|
This section describes additional variables which control the
|
|
indentation behavior of C mode and related mode.
|
|
|
|
@table @code
|
|
@item c-offsets-alist
|
|
@vindex c-offsets-alist
|
|
Association list of syntactic symbols and their indentation offsets.
|
|
You should not set this directly, only with @code{c-set-offset}.
|
|
@xref{Changing Indent Style}, for details.
|
|
|
|
@item c-style-alist
|
|
@vindex c-style-alist
|
|
Variable for defining indentation styles; see below.
|
|
|
|
@item c-basic-offset
|
|
@vindex c-basic-offset
|
|
Amount of basic offset used by @code{+} and @code{-} symbols in
|
|
@code{c-offsets-alist}.@refill
|
|
|
|
@item c-special-indent-hook
|
|
@vindex c-special-indent-hook
|
|
Hook for user-defined special indentation adjustments. This hook is
|
|
called after a line is indented by C mode and related modes.
|
|
@end table
|
|
|
|
The variable @code{c-style-alist} specifies the predefined indentation
|
|
styles. Each element has form @code{(@var{name}
|
|
@var{variable-setting}@dots{})}, where @var{name} is the name of the
|
|
style. Each @var{variable-setting} has the form @code{(@var{variable}
|
|
. @var{value})}; @var{variable} is one of the customization variables
|
|
used by C mode, and @var{value} is the value for that variable when
|
|
using the selected style.
|
|
|
|
When @var{variable} is @code{c-offsets-alist}, that is a special case:
|
|
@var{value} is appended to the front of the value of @code{c-offsets-alist}
|
|
instead of replacing that value outright. Therefore, it is not necessary
|
|
for @var{value} to specify each and every syntactic symbol---only those
|
|
for which the style differs from the default.
|
|
|
|
The indentation of lines containing only comments is also affected by
|
|
the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}).
|
|
|
|
@node C Indent Styles
|
|
@subsubsection C Indentation Styles
|
|
@cindex c indentation styles
|
|
|
|
A @dfn{C style} is a collection of indentation style customizations.
|
|
Emacs comes with several predefined indentation styles for C and related
|
|
modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup},
|
|
@code{linux}, @code{python}, @code{java}, @code{whitesmith},
|
|
@code{ellemtel}, @code{cc-mode}, and @code{user}.
|
|
|
|
@findex c-set-style
|
|
@vindex c-default-style
|
|
To choose the style you want, use the command @kbd{M-x c-set-style}.
|
|
Specify a style name as an argument (case is not significant in C style
|
|
names). The chosen style only affects newly visited buffers, not those
|
|
you are already editing. You can also set the variable
|
|
@code{c-default-style} to specify the style for various major modes.
|
|
Its value should be an alist, in which each element specifies one major
|
|
mode and which indentation style to use for it. For example,
|
|
|
|
@example
|
|
(setq c-default-style
|
|
'((java-mode . "java") (other . "gnu")))
|
|
@end example
|
|
|
|
@noindent
|
|
specifies an explicit choice for Java mode, and the default @samp{gnu}
|
|
style for the other C-like modes.
|
|
|
|
The style @code{gnu} defines the formatting recommend by the GNU
|
|
Project; it is the default, so as to encourage the indentation we
|
|
recommend. If you make changes in variables such as
|
|
@code{c-basic-offset} and @code{c-offsets-alist} in your @file{~/.emacs}
|
|
file, they will however take precedence.
|
|
|
|
@findex c-add-style
|
|
To define a new C indentation style, call the function
|
|
@code{c-add-style}:
|
|
|
|
@example
|
|
(c-add-style @var{name} @var{values} @var{use-now})
|
|
@end example
|
|
|
|
@noindent
|
|
Here @var{name} is the name of the new style (a string), and
|
|
@var{values} is an alist whose elements have the form
|
|
@code{(@var{variable} . @var{value})}. The variables you specify should
|
|
be among those documented in @ref{Variables for C Indent}.
|
|
|
|
If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new
|
|
style after defining it.
|
|
|
|
@node Matching
|
|
@section Automatic Display Of Matching Parentheses
|
|
@cindex matching parentheses
|
|
@cindex parentheses, displaying matches
|
|
|
|
The Emacs parenthesis-matching feature is designed to show
|
|
automatically how parentheses match in the text. Whenever you type a
|
|
self-inserting character that is a closing delimiter, the cursor moves
|
|
momentarily to the location of the matching opening delimiter, provided
|
|
that is on the screen. If it is not on the screen, some text near it is
|
|
displayed in the echo area. Either way, you can tell what grouping is
|
|
being closed off.
|
|
|
|
In Lisp, automatic matching applies only to parentheses. In C, it
|
|
applies to braces and brackets too. Emacs knows which characters to regard
|
|
as matching delimiters based on the syntax table, which is set by the major
|
|
mode. @xref{Syntax}.
|
|
|
|
If the opening delimiter and closing delimiter are mismatched---such as
|
|
in @samp{[x)}---a warning message is displayed in the echo area. The
|
|
correct matches are specified in the syntax table.
|
|
|
|
@vindex blink-matching-paren
|
|
@vindex blink-matching-paren-distance
|
|
@vindex blink-matching-delay
|
|
Three variables control parenthesis match display.
|
|
@code{blink-matching-paren} turns the feature on or off; @code{nil}
|
|
turns it off, but the default is @code{t} to turn match display on.
|
|
@code{blink-matching-delay} says how many seconds to wait; the default
|
|
is 1, but on some systems it is useful to specify a fraction of a
|
|
second. @code{blink-matching-paren-distance} specifies how many
|
|
characters back to search to find the matching opening delimiter. If
|
|
the match is not found in that far, scanning stops, and nothing is
|
|
displayed. This is to prevent scanning for the matching delimiter from
|
|
wasting lots of time when there is no match. The default is 12,000.
|
|
|
|
@cindex Show Paren mode
|
|
@findex show-paren-mode
|
|
When using X Windows, you can request a more powerful alternative kind
|
|
of automatic parenthesis matching by enabling Show Paren mode. This
|
|
mode turns off the usual kind of matching parenthesis display and
|
|
instead uses highlighting to show what matches. Whenever point is after
|
|
a close parenthesis, the close parenthesis and its matching open
|
|
parenthesis are both highlighted; otherwise, if point is before an open
|
|
parenthesis, the matching close parenthesis is highlighted. (There is
|
|
no need to highlight the open parenthesis after point because the cursor
|
|
appears on top of that character.) Use the command @kbd{M-x
|
|
show-paren-mode} to enable or disable this mode.
|
|
|
|
@node Comments
|
|
@section Manipulating Comments
|
|
@cindex comments
|
|
|
|
Because comments are such an important part of programming, Emacs
|
|
provides special commands for editing and inserting comments.
|
|
|
|
@menu
|
|
* Comment Commands::
|
|
* Multi-Line Comments::
|
|
* Options for Comments::
|
|
@end menu
|
|
|
|
@node Comment Commands
|
|
@subsection Comment Commands
|
|
|
|
@kindex M-;
|
|
@cindex indentation for comments
|
|
@findex indent-for-comment
|
|
@findex comment-dwim
|
|
|
|
The comment commands insert, kill and align comments.
|
|
|
|
@c WideCommands
|
|
@table @kbd
|
|
@item M-;
|
|
Call the comment command that is appropriate for the context
|
|
(@code{comment-dwim}).
|
|
@item M-x indent-for-comment
|
|
Insert or align comment.
|
|
@item C-x ;
|
|
Set comment column (@code{set-comment-column}).
|
|
@item C-u - C-x ;
|
|
Kill comment on current line (@code{comment-kill}).
|
|
@item C-M-j
|
|
Like @key{RET} followed by inserting and aligning a comment
|
|
(@code{indent-new-comment-line}).
|
|
@item M-x comment-region
|
|
Add or remove comment delimiters on all the lines in the region.
|
|
@end table
|
|
|
|
The command that creates a comment is @kbd{M-x indent-for-comment}.
|
|
If there is no comment already on the line, a new comment is created,
|
|
aligned at a specific column called the @dfn{comment column}. The comment
|
|
is created by inserting the string Emacs thinks comments should start with
|
|
(the value of @code{comment-start}; see below). Point is left after that
|
|
string. If the text of the line extends past the comment column, then the
|
|
indentation is done to a suitable boundary (usually, at least one space is
|
|
inserted). If the major mode has specified a string to terminate comments,
|
|
that is inserted after point, to keep the syntax valid.
|
|
|
|
@kbd{M-x indent-for-comment} can also be used to align an existing
|
|
comment. If a line already contains the string that starts comments,
|
|
then @kbd{M-x indent-for-comment} just moves point after it and
|
|
reindents it to the conventional place. Exception: comments starting in
|
|
column 0 are not moved.
|
|
|
|
@kbd{M-;} (@code{comment-dwim}) conveniently combines
|
|
@code{indent-for-comment} with @code{comment-region} and
|
|
@code{uncomment-region}, described below in @ref{Multi-Line Comments},
|
|
as appropriate for the current context. If the region is active and the
|
|
Transient Mark mode is on (@pxref{Transient Mark}), @kbd{M-;} invokes
|
|
@code{comment-region}, unless the region consists only of comments, in
|
|
which case it invokes @code{uncomment-region}. Otherwise, if the
|
|
current line is empty, @kbd{M-;} inserts a comment and indents it. If
|
|
the current line is not empty, @kbd{M-;} invokes @code{comment-kill} if
|
|
a numeric argument was given, else it reindents the comment on the
|
|
current line. (The @dfn{dwim} in @code{comment-dwim} is an acronym for
|
|
``Do What I Mean''.)
|
|
|
|
Some major modes have special rules for indenting certain kinds of
|
|
comments in certain contexts. For example, in Lisp code, comments which
|
|
start with two semicolons are indented as if they were lines of code,
|
|
instead of at the comment column. Comments which start with three
|
|
semicolons are supposed to start at the left margin. Emacs understands
|
|
these conventions by indenting a double-semicolon comment using @key{TAB},
|
|
and by not changing the indentation of a triple-semicolon comment at all.
|
|
|
|
@example
|
|
;; 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.
|
|
@end example
|
|
|
|
In C code, a comment preceded on its line by nothing but whitespace
|
|
is indented like a line of code.
|
|
|
|
Even when an existing comment is properly aligned, @kbd{M-;} is still
|
|
useful for moving directly to the start of the comment.
|
|
|
|
@kindex C-u - C-x ;
|
|
@findex kill-comment
|
|
@findex comment-kill
|
|
@kbd{C-u - C-x ;} (@code{comment-kill}) kills the comment on the current line,
|
|
if there is one. The indentation before the start of the comment is killed
|
|
as well. If there does not appear to be a comment in the line, nothing is
|
|
done. To reinsert the comment on another line, move to the end of that
|
|
line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
|
|
@kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
|
|
with a negative argument. That command is programmed so that when it
|
|
receives a negative argument it calls @code{comment-kill}. However,
|
|
@code{comment-kill} is a valid command which you could bind directly to a
|
|
key if you wanted to. (For compatibility with previous versions,
|
|
@code{kill-comment} is provided as an alias to @code{comment-kill}.)
|
|
|
|
@node Multi-Line Comments
|
|
@subsection Multiple Lines of Comments
|
|
|
|
@kindex C-M-j
|
|
@cindex blank lines in programs
|
|
@findex indent-new-comment-line
|
|
If you are typing a comment and wish to continue it on another line,
|
|
you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}).
|
|
This terminates the comment you are typing, creates a new blank line
|
|
afterward, and begins a new comment indented under the old one. When
|
|
Auto Fill mode is on, going past the fill column while typing a comment
|
|
causes the comment to be continued in just this fashion. If point is
|
|
not at the end of the line when @kbd{C-M-j} is typed, the text on
|
|
the rest of the line becomes part of the new comment line.
|
|
|
|
@findex comment-region
|
|
To turn existing lines into comment lines, use the @kbd{M-x
|
|
comment-region} command. It adds comment delimiters to the lines that start
|
|
in the region, thus commenting them out. With a negative argument, it
|
|
does the opposite---it deletes comment delimiters from the lines in the
|
|
region.
|
|
|
|
With a positive argument, @code{comment-region} duplicates the last
|
|
character of the comment start sequence it adds; the argument specifies
|
|
how many copies of the character to insert. Thus, in Lisp mode,
|
|
@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
|
|
the comment delimiter is a way of calling attention to the comment. It
|
|
can also affect how the comment is indented. In Lisp, for proper
|
|
indentation, you should use an argument of two, if between defuns, and
|
|
three, if within a defun.
|
|
|
|
@vindex comment-padding
|
|
The variable @code{comment-padding} specifies how many spaces
|
|
@code{comment-region} should insert on each line between the
|
|
comment delimiter and the line's original text. The default is 1.
|
|
|
|
@node Options for Comments
|
|
@subsection Options Controlling Comments
|
|
|
|
@vindex comment-column
|
|
@kindex C-x ;
|
|
@findex set-comment-column
|
|
The comment column is stored in the variable @code{comment-column}. You
|
|
can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
|
|
(@code{set-comment-column}) sets the comment column to the column point is
|
|
at. @kbd{C-u C-x ;} sets the comment column to match the last comment
|
|
before point in the buffer, and then does a @kbd{M-;} to align the
|
|
current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
|
|
runs the function @code{comment-kill} as described above.
|
|
|
|
The variable @code{comment-column} is per-buffer: setting the variable
|
|
in the normal fashion affects only the current buffer, but there is a
|
|
default value which you can change with @code{setq-default}.
|
|
@xref{Locals}. Many major modes initialize this variable for the
|
|
current buffer.
|
|
|
|
@vindex comment-start-skip
|
|
The comment commands recognize comments based on the regular
|
|
expression that is the value of the variable @code{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 @code{@t{"/\\*+
|
|
*"}}, which matches extra stars and spaces after the @samp{/*} itself.
|
|
(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
|
|
the string, which is needed to deny the first star its special meaning
|
|
in regexp syntax. @xref{Regexps}.)
|
|
|
|
@vindex comment-start
|
|
@vindex comment-end
|
|
When a comment command makes a new comment, it inserts the value of
|
|
@code{comment-start} to begin it. The value of @code{comment-end} is
|
|
inserted after point, so that it will follow the text that you will insert
|
|
into the comment. In C mode, @code{comment-start} has the value
|
|
@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
|
|
|
|
@vindex comment-multi-line
|
|
The variable @code{comment-multi-line} controls how @kbd{C-M-j}
|
|
(@code{indent-new-comment-line}) behaves when used inside a comment. If
|
|
@code{comment-multi-line} is @code{nil}, as it normally is, then the
|
|
comment on the starting line is terminated and a new comment is started
|
|
on the new following line. If @code{comment-multi-line} is not
|
|
@code{nil}, then the new following line is set up as part of the same
|
|
comment that was found on the starting line. This is done by not
|
|
inserting a terminator on the old line, and not inserting a starter on
|
|
the new line. In languages where multi-line comments work, the choice
|
|
of value for this variable is a matter of taste.
|
|
|
|
@vindex comment-indent-function
|
|
The variable @code{comment-indent-function} should contain a function
|
|
that will be called to compute the indentation for a newly inserted
|
|
comment or for aligning an existing comment. It is set differently by
|
|
various major modes. The function is called with no arguments, but with
|
|
point at the beginning of the comment, or at the end of a line if a new
|
|
comment is to be inserted. It should return the column in which the
|
|
comment ought to start. For example, in Lisp mode, the indent hook
|
|
function bases its decision on how many semicolons begin an existing
|
|
comment, and on the code in the preceding lines.
|
|
|
|
@node Balanced Editing
|
|
@section Editing Without Unbalanced Parentheses
|
|
|
|
@table @kbd
|
|
@item M-(
|
|
Put parentheses around next sexp(s) (@code{insert-parentheses}).
|
|
@item M-)
|
|
Move past next close parenthesis and reindent
|
|
(@code{move-past-close-and-reindent}).
|
|
@end table
|
|
|
|
@kindex M-(
|
|
@kindex M-)
|
|
@findex insert-parentheses
|
|
@findex move-past-close-and-reindent
|
|
The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
|
|
(@code{move-past-close-and-reindent}) are designed to facilitate a style
|
|
of editing which keeps parentheses balanced at all times. @kbd{M-(}
|
|
inserts a pair of parentheses, either together as in @samp{()}, or, if
|
|
given an argument, around the next several sexps. It leaves point after
|
|
the open parenthesis. The command @kbd{M-)} moves past the close
|
|
parenthesis, deleting any indentation preceding it, and indenting with
|
|
@kbd{C-j} after it.
|
|
|
|
For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
|
|
F O O}, which has the same effect except for leaving the cursor before
|
|
the close parenthesis.
|
|
|
|
@vindex parens-require-spaces
|
|
@kbd{M-(} may insert a space before the open parenthesis, depending on
|
|
the syntax class of the preceding character. Set
|
|
@code{parens-require-spaces} to @code{nil} value if you wish to inhibit
|
|
this.
|
|
|
|
@findex check-parens
|
|
@cindex unbalanced parentheses and quotes
|
|
You can use @kbd{M-x check-parens} to find any unbalanced parentheses
|
|
and unbalanced quotes in strings in a buffer.
|
|
|
|
@node Symbol Completion
|
|
@section Completion for Symbol Names
|
|
@cindex completion (symbol names)
|
|
|
|
Usually completion happens in the minibuffer. But one kind of completion
|
|
is available in all buffers: completion for symbol names.
|
|
|
|
@kindex M-TAB
|
|
The character @kbd{M-@key{TAB}} runs a command to complete the partial
|
|
symbol before point against the set of meaningful symbol names. Any
|
|
additional characters determined by the partial name are inserted at
|
|
point.
|
|
|
|
If the partial name in the buffer has more than one possible completion
|
|
and they have no additional characters in common, a list of all possible
|
|
completions is displayed in another window.
|
|
|
|
@cindex completion using tags
|
|
@cindex tags completion
|
|
@cindex Info index completion
|
|
@findex complete-symbol
|
|
In most programming language major modes, @kbd{M-@key{TAB}} runs the
|
|
command @code{complete-symbol}, which provides two kinds of completion.
|
|
Normally it does completion based on a tags table (@pxref{Tags}); with a
|
|
numeric argument (regardless of the value), it does completion based on
|
|
the names listed in the Info file indexes for your language. Thus, to
|
|
complete the name of a symbol defined in your own program, use
|
|
@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
|
|
library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
|
|
completion works only if there is an Info file for the standard library
|
|
functions of your language, and only if it is installed at your site.
|
|
|
|
@cindex Lisp symbol completion
|
|
@cindex completion in Lisp
|
|
@findex lisp-complete-symbol
|
|
In Emacs-Lisp mode, the name space for completion normally consists of
|
|
nontrivial symbols present in Emacs---those that have function
|
|
definitions, values or properties. However, if there is an
|
|
open-parenthesis immediately before the beginning of the partial symbol,
|
|
only symbols with function definitions are considered as completions.
|
|
The command which implements this is @code{lisp-complete-symbol}.
|
|
|
|
In Text mode and related modes, @kbd{M-@key{TAB}} completes words
|
|
based on the spell-checker's dictionary. @xref{Spelling}.
|
|
|
|
@node Which Function
|
|
@section Which Function Mode
|
|
|
|
Which Function mode is a minor mode that displays the current function
|
|
name in the mode line, as you move around in a buffer.
|
|
|
|
@findex which-function-mode
|
|
@vindex which-func-modes
|
|
To enable (or disable) Which Function mode, use the command @kbd{M-x
|
|
which-function-mode}. This command is global; it applies to all
|
|
buffers, both existing ones and those yet to be created. However, this
|
|
only affects certain major modes, those listed in the value of
|
|
@code{which-func-modes}. (If the value is @code{t}, then Which Function
|
|
mode applies to all major modes that know how to support it---which are
|
|
the major modes that support Imenu.)
|
|
|
|
@node Hideshow
|
|
@section Hideshow minor mode
|
|
|
|
@findex hs-minor-mode
|
|
Hideshow minor mode provides selective display of blocks. Use @kbd{M-x
|
|
hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the
|
|
hook for major modes with which you want to use it and which support it.
|
|
|
|
Blocks are defined dependent on the mode. In C mode or C++ mode, they
|
|
are delimited by braces, while in Lisp-ish modes they are delimited by
|
|
parens. Multi-line comments can also be hidden.
|
|
|
|
@findex hs-hide-all
|
|
@findex hs-hide-block
|
|
@findex hs-show-all
|
|
@findex hs-show-block
|
|
@findex hs-show-region
|
|
@findex hs-hide-level
|
|
@findex hs-minor-mode
|
|
@kindex C-c h
|
|
@kindex C-c s
|
|
@kindex C-c H
|
|
@kindex C-c S
|
|
@kindex C-c R
|
|
@kindex C-c L
|
|
@kindex S-mouse-2
|
|
The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}),
|
|
@kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x
|
|
hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R}
|
|
(@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level})
|
|
with obvious functions and @kbd{S-mouse-2} toggles hiding of a block
|
|
with the mouse.
|
|
|
|
@vindex hs-hide-comments-when-hiding-all
|
|
@vindex hs-show-hidden-short-form
|
|
@vindex hs-isearch-open
|
|
@vindex hs-special-modes-alist
|
|
Hideshow is customized by the variables
|
|
@table @code
|
|
@item hs-hide-comments-when-hiding-all
|
|
Specifies whether @kbd{hs-hide-all} should hide comments too.
|
|
@item hs-show-hidden-short-form
|
|
Specifies whether or not the last line in a form is omitted (saving
|
|
screen space).
|
|
@item hs-isearch-open
|
|
Specifies what kind of hidden blocks to open in Isearch mode.
|
|
@item hs-special-modes-alist
|
|
Initializes Hideshow variables for different modes.
|
|
@end table
|
|
|
|
@node Glasses
|
|
@section Glasses minor mode
|
|
@cindex Glasses mode
|
|
@cindex identifiers, unreadable
|
|
@cindex StudlyCaps
|
|
@findex glasses-mode
|
|
|
|
Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} readable
|
|
by displaying underscores between all the pairs of lower and upper
|
|
English letters or by emboldening the capitals. The text is not
|
|
altered, only the display, so that you can use this mode on code written
|
|
with such a convention for separating words in identifiers without
|
|
modifying the code. It can be customized under the group
|
|
@samp{glasses}. You can use it by adding @code{glasses-mode} to the
|
|
mode hook of appropriate programming modes.
|
|
|
|
|
|
@node Documentation
|
|
@section Documentation Commands
|
|
|
|
As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
|
|
(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
|
|
be used to print documentation of functions and variables that you want to
|
|
call. These commands use the minibuffer to read the name of a function or
|
|
variable to document, and display the documentation in a window.
|
|
|
|
For extra convenience, these commands provide default arguments based on
|
|
the code in the neighborhood of point. @kbd{C-h f} sets the default to the
|
|
function called in the innermost list containing point. @kbd{C-h v} uses
|
|
the symbol name around or adjacent to point as its default.
|
|
|
|
@cindex Eldoc mode
|
|
@findex eldoc-mode
|
|
For Emacs Lisp code, you can also use Eldoc mode. This minor mode
|
|
constantly displays in the echo area the argument list for the function
|
|
being called at point. (In other words, it finds the function call that
|
|
point is contained in, and displays the argument list of that function.)
|
|
Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
|
|
the command @kbd{M-x eldoc-mode} to enable or disable this feature.
|
|
|
|
@findex info-lookup-symbol
|
|
@findex info-lookup-file
|
|
@kindex C-h C-i
|
|
For C, Lisp, and other languages, you can use @kbd{C-h C-i}
|
|
(@code{info-lookup-symbol}) to view the Info documentation for a symbol.
|
|
You specify the symbol with the minibuffer; by default, it uses the
|
|
symbol that appears in the buffer at point. The major mode determines
|
|
where to look for documentation for the symbol---which Info files and
|
|
which indices. You can also use @kbd{M-x info-lookup-file} to look for
|
|
documentation for a file name. Currently the modes supported by
|
|
Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
|
|
Makefile, Octave, Perl, Scheme and Texinfo. The relevant Info files
|
|
mostly must be obtained separately, typically from the appropriate GNU
|
|
package.
|
|
|
|
@findex manual-entry
|
|
@cindex manual pages
|
|
You can read the ``man page'' for an operating system command, library
|
|
function, or system call, with the @kbd{M-x manual-entry} command. It
|
|
runs the @code{man} program to format the man page, and runs it
|
|
asynchronously if your system permits, so that you can keep on editing
|
|
while the page is being formatted. (MS-DOS and MS-Windows 3 do not
|
|
permit asynchronous subprocesses, so on these systems you cannot edit
|
|
while Emacs waits for @code{man} to exit.) The result goes in a buffer
|
|
named @samp{*Man @var{topic}*}. These buffers use a special major mode,
|
|
Man mode, that facilitates scrolling and examining other manual pages.
|
|
For details, type @kbd{C-h m} while in a man page buffer.
|
|
|
|
@cindex sections of manual pages
|
|
Man pages are subdivided into @dfn{sections}, and some man pages have
|
|
identical names, but belong to different sections. To read a man page
|
|
from a certain section, type @kbd{@var{topic}(@var{section})} or
|
|
@kbd{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts for
|
|
the topic. For example, to read the man page for the C library function
|
|
@code{chmod} (as opposed to a command by the same name), type @kbd{M-x
|
|
manual-entry @key{RET} chmod(2v) @key{RET}} (assuming @code{chmod} is in
|
|
section @code{2v}).
|
|
|
|
If you do not specify a section, the results depend on how the
|
|
@code{man} command works on your system. Some of them display only the
|
|
first man page they find, others display all the man pages, and you can
|
|
page between them with the @kbd{M-n} and @kbd{M-p} keys. The mode line
|
|
shows how many manual pages are available in the Man buffer.
|
|
|
|
@vindex Man-fontify-manpage-flag
|
|
For a long man page, setting the faces properly can take substantial
|
|
time. By default, Emacs uses faces in man pages if Emacs can display
|
|
different fonts or colors. You can turn off use of faces in man pages
|
|
by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
|
|
|
|
@findex Man-fontify-manpage
|
|
If you insert the text of a man page into an Emacs buffer in some
|
|
other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
|
|
perform the same conversions that @kbd{M-x manual-entry} does.
|
|
|
|
@findex woman
|
|
@cindex manual pages, on MS-DOS/MS-Windows
|
|
An alternative way of reading manual pages is the @kbd{M-x woman}
|
|
command@footnote{The name of the command, @code{woman}, is an acronym
|
|
for ``w/o (without) man'', since it doesn't use the @code{man}
|
|
program.}. Unlike @kbd{M-x man}, it does not run any external programs
|
|
to format and display the man pages, instead it does that entirely in
|
|
Emacs Lisp. Thus, it is useful on systems such as MS-Windows, where the
|
|
@code{man} program and the programs it runs are not readily available.
|
|
When invoked, @kbd{M-x woman} prompts for a name of a manual page and
|
|
provides completion based on the list of manual pages that are installed
|
|
on your machine; the list of available manual pages is computed
|
|
automatically the first time you invoke @code{woman}. The word at point
|
|
in the current buffer is used to suggest the default name of the manual
|
|
page.
|
|
|
|
With a numeric argument, @kbd{M-x woman} recomputes the list of the
|
|
manual pages used for completion. This is useful if you add or delete
|
|
manual pages.
|
|
|
|
If you type a name of a manual page and @kbd{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.
|
|
|
|
@vindex woman-manpath
|
|
By default, @kbd{M-x woman} looks up the manual pages in directories
|
|
listed by the @code{MANPATH} environment variable. (If @code{MANPATH}
|
|
is not set, @code{woman} uses a suitable default value, which can be
|
|
customized.) More precisely, @code{woman} looks for subdirectories that
|
|
match the shell wildcard @file{man*} in each one of these directories,
|
|
and tries to find the manual pages in those subdirectories. When first
|
|
invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list
|
|
of directory names and stores that list in the @code{woman-manpath}
|
|
variable. By changing the value of this variable, you can customize the
|
|
list of directories where @code{woman} looks for manual pages.
|
|
|
|
@vindex woman-path
|
|
In addition, you can augment the list of directories searched by
|
|
@code{woman} by setting the value of the @code{woman-path} variable.
|
|
This variable should hold a list of specific directories which
|
|
@code{woman} should search, in addition to those in
|
|
@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
|
|
@code{woman-path} are searched for the manual pages, not for @file{man*}
|
|
subdirectories.
|
|
|
|
@findex woman-find-file
|
|
Occasionally, you might need to display manual pages that are not in
|
|
any of the directories listed by @code{woman-manpath} and
|
|
@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
|
|
name of a manual page file, with completion, and then formats and
|
|
displays that file like @kbd{M-x woman} does.
|
|
|
|
@vindex woman-dired-keys
|
|
First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W}
|
|
key to run the @code{woman-find-file} command on the current line's
|
|
file. You can disable this by setting the variable
|
|
@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the
|
|
Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current
|
|
line's archive member.
|
|
|
|
For more information about setting up and using @kbd{M-x woman}, see
|
|
@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
|
|
Manual}.
|
|
|
|
Eventually the GNU project hopes to replace most man pages with
|
|
better-organized manuals that you can browse with Info. @xref{Misc
|
|
Help}. Since this process is only partially completed, it is still
|
|
useful to read manual pages.
|
|
|
|
@node Change Log
|
|
@section Change Logs
|
|
|
|
@cindex change log
|
|
@kindex C-x 4 a
|
|
@findex add-change-log-entry-other-window
|
|
The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
|
|
file for the file you are editing
|
|
(@code{add-change-log-entry-other-window}). If that file is actually a
|
|
backup file, it makes an entry appropriate for the file's parent. This
|
|
is useful for making log entries by comparing a version with deleted
|
|
functions.
|
|
|
|
A change log file contains a chronological record of when and why you
|
|
have changed a program, consisting of a sequence of entries describing
|
|
individual changes. Normally it is kept in a file called
|
|
@file{ChangeLog} in the same directory as the file you are editing, or
|
|
one of its parent directories. A single @file{ChangeLog} file can
|
|
record changes for all the files in its directory and all its
|
|
subdirectories.
|
|
|
|
A change log entry starts with a header line that contains your name,
|
|
your email address (taken from the variable @code{user-mail-address}),
|
|
and the current date and time. Aside from these header lines, every
|
|
line in the change log starts with a space or a tab. The bulk of the
|
|
entry consists of @dfn{items}, each of which starts with a line starting
|
|
with whitespace and a star. Here are two entries, both dated in May
|
|
1993, each with two items:
|
|
|
|
@iftex
|
|
@medbreak
|
|
@end iftex
|
|
@smallexample
|
|
1993-05-25 Richard Stallman <rms@@gnu.org>
|
|
|
|
* man.el: Rename symbols `man-*' to `Man-*'.
|
|
(manual-entry): Make prompt string clearer.
|
|
|
|
* simple.el (blink-matching-paren-distance):
|
|
Change default to 12,000.
|
|
|
|
1993-05-24 Richard Stallman <rms@@gnu.org>
|
|
|
|
* vc.el (minor-mode-map-alist): Don't use it if it's void.
|
|
(vc-cancel-version): Doc fix.
|
|
@end smallexample
|
|
|
|
One entry can describe several changes; each change should have its
|
|
own item. Normally there should be a blank line between items. When
|
|
items are related (parts of the same change, in different places), group
|
|
them by leaving no blank line between them. The second entry above
|
|
contains two items grouped in this way.
|
|
|
|
@vindex add-log-keep-changes-together
|
|
@kbd{C-x 4 a} visits the change log file and creates a new entry
|
|
unless the most recent entry is for today's date and your name. It also
|
|
creates a new item for the current file. For many languages, it can
|
|
even guess the name of the function or other object that was changed.
|
|
When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4
|
|
a} adds to any existing entry for the file rather than starting a new
|
|
entry.
|
|
|
|
@vindex change-log-version-info-enabled
|
|
@vindex change-log-version-number-regexp-list
|
|
@cindex file version in change log entries
|
|
If the value of the variable @code{change-log-version-info-enabled} is
|
|
non-nil, the file's version number is automatically added to change log
|
|
entries. The search for the file's version number is performed based on
|
|
regular expressions from the variable
|
|
@code{change-log-version-number-regexp-list}, which can be customized
|
|
(versions of files that are under version control systems are known to
|
|
Emacs through the version-control interface).
|
|
|
|
@cindex Change Log mode
|
|
@findex change-log-mode
|
|
The change log file is visited in Change Log mode. In this major
|
|
mode, each bunch of grouped items counts as one paragraph, and each
|
|
entry is considered a page. This facilitates editing the entries.
|
|
@kbd{C-j} and auto-fill indent each new line like the previous line;
|
|
this is convenient for entering the contents of an entry.
|
|
|
|
@findex change-log-merge
|
|
The command @kbd{M-x change-log-merge} can be used to merge other log
|
|
files into a buffer in Change Log Mode, preserving the date ordering
|
|
of entries with either the current or old-style date formats.
|
|
|
|
@findex change-log-redate
|
|
@cindex converting change log date style
|
|
Versions of Emacs before 20.1 used a different format for the time of
|
|
the change log entry:
|
|
|
|
@smallexample
|
|
Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The @kbd{M-x change-log-redate} command converts all the old-style date
|
|
entries in the change log file visited in the current buffer to the new
|
|
format, so that all entries are kept in unified format. This is handy
|
|
when the entries are contributed by many different people some of whom
|
|
still use old versions of Emacs.
|
|
|
|
Version control systems are another way to keep track of changes in your
|
|
program and keep a change log. @xref{Log Buffer}.
|
|
|
|
@node Authors
|
|
@section @file{AUTHORS} files
|
|
@cindex @file{AUTHORS} file
|
|
|
|
Programs which have many contributors usually include a file named
|
|
@file{AUTHORS} in their distribution, which lists the individual
|
|
contributions. Emacs has a special command for maintaining the
|
|
@file{AUTHORS} file that is part of the Emacs distribution.
|
|
|
|
@findex authors
|
|
The @kbd{M-x authors} command prompts for the name of the root of the
|
|
Emacs source directory. It then scans @file{ChageLog} files and Lisp
|
|
source files under that directory for information about authors of
|
|
individual packages and people who made changes in source files, and
|
|
puts the information it gleans into a buffer named @samp{*Authors*}.
|
|
You can then edit the contents of that buffer and merge it with the
|
|
exisiting @file{AUTHORS} file.
|
|
|
|
@node Tags
|
|
@section Tags Tables
|
|
@cindex tags table
|
|
|
|
A @dfn{tags table} is a description of how a multi-file program is
|
|
broken up into files. It lists the names of the component files and the
|
|
names and positions of the functions (or other named subunits) in each
|
|
file. Grouping the related files makes it possible to search or replace
|
|
through all the files with one command. Recording the function names
|
|
and positions makes possible the @kbd{M-.} command which finds the
|
|
definition of a function by looking up which of the files it is in.
|
|
|
|
Tags tables are stored in files called @dfn{tags table files}. The
|
|
conventional name for a tags table file is @file{TAGS}.
|
|
|
|
Each entry in the tags table records the name of one tag, the name of the
|
|
file that the tag is defined in (implicitly), and the position in that file
|
|
of the tag's definition.
|
|
|
|
Just what names from the described files are recorded in the tags table
|
|
depends on the programming language of the described file. They
|
|
normally include all functions and subroutines, and may also include
|
|
global variables, data types, and anything else convenient. Each name
|
|
recorded is called a @dfn{tag}.
|
|
|
|
@cindex C++ class browser, tags
|
|
@cindex tags, C++
|
|
@cindex class browser, C++
|
|
@cindex Ebrowse
|
|
The Ebrowse is a separate facility tailored for C++, with tags and a
|
|
class browser. @xref{,,, ebrowse, Ebrowse User's Manual}.
|
|
|
|
@menu
|
|
* Tag Syntax:: Tag syntax for various types of code and text files.
|
|
* Create Tags Table:: Creating a tags table with @code{etags}.
|
|
* Etags Regexps:: Create arbitrary tags using regular expressions.
|
|
* Select Tags Table:: How to visit a tags table.
|
|
* Find Tag:: Commands to find the definition of a specific tag.
|
|
* Tags Search:: Using a tags table for searching and replacing.
|
|
* List Tags:: Listing and finding tags defined in a file.
|
|
@end menu
|
|
|
|
@node Tag Syntax
|
|
@subsection Source File Tag Syntax
|
|
|
|
Here is how tag syntax is defined for the most popular languages:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
In C code, any C function or typedef is a tag, and so are definitions of
|
|
@code{struct}, @code{union} and @code{enum}. You can tag function
|
|
declarations and external variables in addition to function definitions
|
|
by giving the @samp{--declarations} option to @code{etags}.
|
|
@code{#define} macro definitions and @code{enum} constants are also
|
|
tags, unless you specify @samp{--no-defines} when making the tags table.
|
|
Similarly, global variables are tags, unless you specify
|
|
@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
|
|
can make the tags table file much smaller.
|
|
|
|
@item
|
|
In C++ code, in addition to all the tag constructs of C code, member
|
|
functions are also recognized, and optionally member variables if you
|
|
use the @samp{--members} option. Tags for variables and functions in
|
|
classes are named @samp{@var{class}::@var{variable}} and
|
|
@samp{@var{class}::@var{function}}. @code{operator} functions tags are
|
|
named, for example @samp{operator+}.
|
|
|
|
@item
|
|
In Java code, tags include all the constructs recognized in C++, plus
|
|
the @code{interface}, @code{extends} and @code{implements} constructs.
|
|
Tags for variables and functions in classes are named
|
|
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
|
|
|
|
@item
|
|
In La@TeX{} text, the argument of any of the commands @code{\chapter},
|
|
@code{\section}, @code{\subsection}, @code{\subsubsection},
|
|
@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
|
|
@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
|
|
tag.@refill
|
|
|
|
Other commands can make tags as well, if you specify them in the
|
|
environment variable @env{TEXTAGS} before invoking @code{etags}. The
|
|
value of this environment variable should be a colon-separated list of
|
|
command names. For example,
|
|
|
|
@example
|
|
TEXTAGS="def:newcommand:newenvironment"
|
|
export TEXTAGS
|
|
@end example
|
|
|
|
@noindent
|
|
specifies (using Bourne shell syntax) that the commands @samp{\def},
|
|
@samp{\newcommand} and @samp{\newenvironment} also define tags.
|
|
|
|
@item
|
|
In Lisp code, any function defined with @code{defun}, any variable
|
|
defined with @code{defvar} or @code{defconst}, and in general the first
|
|
argument of any expression that starts with @samp{(def} in column zero, is
|
|
a tag.
|
|
|
|
@item
|
|
In Scheme code, tags include anything defined with @code{def} or with a
|
|
construct whose name starts with @samp{def}. They also include variables
|
|
set with @code{set!} at top level in the file.
|
|
@end itemize
|
|
|
|
Several other languages are also supported:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
In Ada code, functions, procedures, packages, tasks, and types are
|
|
tags. Use the @samp{--packages-only} option to create tags for packages
|
|
only.
|
|
|
|
@item
|
|
In assembler code, labels appearing at the beginning of a line,
|
|
followed by a colon, are tags.
|
|
|
|
@item
|
|
In Bison or Yacc input files, each rule defines as a tag the nonterminal
|
|
it constructs. The portions of the file that contain C code are parsed
|
|
as C code.
|
|
|
|
@item
|
|
In Cobol code, tags are paragraph names; that is, any word starting in
|
|
column 8 and followed by a period.
|
|
|
|
@item
|
|
In Erlang code, the tags are the functions, records, and macros defined
|
|
in the file.
|
|
|
|
@item
|
|
In Fortran code, functions, subroutines and blockdata are tags.
|
|
|
|
@item
|
|
In Objective C code, tags include Objective C definitions for classes,
|
|
class categories, methods, and protocols.
|
|
|
|
@item
|
|
In Pascal code, the tags are the functions and procedures defined in
|
|
the file.
|
|
|
|
@item
|
|
In Perl code, the tags are the procedures defined by the @code{sub},
|
|
@code{my} and @code{local} keywords. Use @samp{--globals} if you want
|
|
to tag global variables.
|
|
|
|
@item
|
|
In PostScript code, the tags are the functions.
|
|
|
|
@item
|
|
In Prolog code, a tag name appears at the left margin.
|
|
|
|
@item
|
|
In Python code, @code{def} or @code{class} at the beginning of a line
|
|
generate a tag.
|
|
@end itemize
|
|
|
|
You can also generate tags based on regexp matching (@pxref{Etags
|
|
Regexps}) to handle other formats and languages.
|
|
|
|
@node Create Tags Table
|
|
@subsection Creating Tags Tables
|
|
@cindex @code{etags} program
|
|
|
|
The @code{etags} program is used to create a tags table file. It knows
|
|
the syntax of several languages, as described in
|
|
@iftex
|
|
the previous section.
|
|
@end iftex
|
|
@ifinfo
|
|
@ref{Tag Syntax}.
|
|
@end ifinfo
|
|
Here is how to run @code{etags}:
|
|
|
|
@example
|
|
etags @var{inputfiles}@dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
The @code{etags} program reads the specified files, and writes a tags
|
|
table named @file{TAGS} in the current working directory. You can
|
|
intermix compressed and plain text source file names. @code{etags}
|
|
knows about the most common compression formats, and does the right
|
|
thing. So you can compress all your source files and have @code{etags}
|
|
look for compressed versions of its file name arguments, if it does not
|
|
find uncompressed versions. Under MS-DOS, @code{etags} also looks for
|
|
file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
|
|
command line and @samp{mycode.c} does not exist.
|
|
|
|
@code{etags} recognizes the language used in an input file based on
|
|
its file name and contents. You can specify the language with the
|
|
@samp{--language=@var{name}} option, described below.
|
|
|
|
If the tags table data become outdated due to changes in the files
|
|
described in the table, the way to update the tags table is the same way it
|
|
was made in the first place. It is not necessary to do this often.
|
|
|
|
If the tags table fails to record a tag, or records it for the wrong
|
|
file, then Emacs cannot possibly find its definition. However, if the
|
|
position recorded in the tags table becomes a little bit wrong (due to
|
|
some editing in the file that the tag definition is in), the only
|
|
consequence is a slight delay in finding the tag. Even if the stored
|
|
position is very wrong, Emacs will still find the tag, but it must
|
|
search the entire file for it.
|
|
|
|
So you should update a tags table when you define new tags that you want
|
|
to have listed, or when you move tag definitions from one file to another,
|
|
or when changes become substantial. Normally there is no need to update
|
|
the tags table after each edit, or even every day.
|
|
|
|
One tags table can effectively include another. Specify the included
|
|
tags file name with the @samp{--include=@var{file}} option when creating
|
|
the file that is to include it. The latter file then acts as if it
|
|
contained all the files specified in the included file, as well as the
|
|
files it directly contains.
|
|
|
|
If you specify the source files with relative file names when you run
|
|
@code{etags}, the tags file will contain file names relative to the
|
|
directory where the tags file was initially written. This way, you can
|
|
move an entire directory tree containing both the tags file and the
|
|
source files, and the tags file will still refer correctly to the source
|
|
files.
|
|
|
|
If you specify absolute file names as arguments to @code{etags}, then
|
|
the tags file will contain absolute file names. This way, the tags file
|
|
will still refer to the same files even if you move it, as long as the
|
|
source files remain in the same place. Absolute file names start with
|
|
@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
|
|
|
|
When you want to make a tags table from a great number of files, you
|
|
may have problems listing them on the command line, because some systems
|
|
have a limit on its length. The simplest way to circumvent this limit
|
|
is to tell @code{etags} to read the file names from its standard input,
|
|
by typing a dash in place of the file names, like this:
|
|
|
|
@smallexample
|
|
find . -name "*.[chCH]" -print | etags -
|
|
@end smallexample
|
|
|
|
Use the option @samp{--language=@var{name}} to specify the language
|
|
explicitly. You can intermix these options with file names; each one
|
|
applies to the file names that follow it. Specify
|
|
@samp{--language=auto} to tell @code{etags} to resume guessing the
|
|
language from the file names and file contents. Specify
|
|
@samp{--language=none} to turn off language-specific processing
|
|
entirely; then @code{etags} recognizes tags by regexp matching alone
|
|
(@pxref{Etags Regexps}).
|
|
|
|
@samp{etags --help} prints the list of the languages @code{etags}
|
|
knows, and the file name rules for guessing the language. It also prints
|
|
a list of all the available @code{etags} options, together with a short
|
|
explanation.
|
|
|
|
@node Etags Regexps
|
|
@subsection Etags Regexps
|
|
|
|
The @samp{--regex} option provides a general way of recognizing tags
|
|
based on regexp matching. You can freely intermix it with file names.
|
|
Each @samp{--regex} option adds to the preceding ones, and applies only
|
|
to the following files. The syntax is:
|
|
|
|
@smallexample
|
|
--regex=/@var{tagregexp}[/@var{nameregexp}]/
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @var{tagregexp} is used to match the lines to tag. It is always
|
|
anchored, that is, it behaves as if preceded by @samp{^}. If you want
|
|
to account for indentation, just match any initial number of blanks by
|
|
beginning your regular expression with @samp{[ \t]*}. In the regular
|
|
expressions, @samp{\} quotes the next character, and @samp{\t} stands
|
|
for the tab character. Note that @code{etags} does not handle the other
|
|
C escape sequences for special characters.
|
|
|
|
@cindex interval operator (in regexps)
|
|
The syntax of regular expressions in @code{etags} is the same as in
|
|
Emacs, augmented with the @dfn{interval operator}, which works as in
|
|
@code{grep} and @code{ed}. The syntax of an interval operator is
|
|
@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
|
|
expression at least @var{m} times and up to @var{n} times.
|
|
|
|
You should not match more characters with @var{tagregexp} than that
|
|
needed to recognize what you want to tag. If the match is such that
|
|
more characters than needed are unavoidably matched by @var{tagregexp}
|
|
(as will usually be the case), you should add a @var{nameregexp}, to
|
|
pick out just the tag. This will enable Emacs to find tags more
|
|
accurately and to do completion on tag names more reliably. You can
|
|
find some examples below.
|
|
|
|
The option @samp{--ignore-case-regex} (or @samp{-c}) is like
|
|
@samp{--regex}, except that the regular expression provided will be
|
|
matched without regard to case, which is appropriate for various
|
|
programming languages.
|
|
|
|
The @samp{-R} option deletes all the regexps defined with
|
|
@samp{--regex} options. It applies to the file names following it, as
|
|
you can see from the following example:
|
|
|
|
@smallexample
|
|
etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
|
|
bar.ber -R --lang=lisp los.er
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here @code{etags} chooses the parsing language for @file{voo.doo} and
|
|
@file{bar.ber} according to their contents. @code{etags} also uses
|
|
@var{reg1} to recognize additional tags in @file{voo.doo}, and both
|
|
@var{reg1} and @var{reg2} to recognize additional tags in
|
|
@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
|
|
matching, to recognize tags in @file{los.er}.
|
|
|
|
A regular expression can be bound to a given language, by prepending
|
|
it with @samp{@{lang@}}. When you do this, @code{etags} will use the
|
|
regular expression only for files of that language. @samp{etags --help}
|
|
prints the list of languages recognised by @code{etags}. The following
|
|
example tags the @code{DEFVAR} macros in the Emacs source files.
|
|
@code{etags} applies this regular expression to C files only:
|
|
|
|
@smallexample
|
|
--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This feature is particularly useful when storing a list of regular
|
|
expressions in a file. The following option syntax instructs
|
|
@code{etags} to read two files of regular expressions. The regular
|
|
expressions contained in the second file are matched without regard to
|
|
case.
|
|
|
|
@smallexample
|
|
--regex=@@first-file --ignore-case-regex=@@second-file
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A regex file contains one regular expressions per line. Empty lines,
|
|
and lines beginning with space or tab are ignored. When the first
|
|
character in a line is @samp{@@}, @code{etags} assumes that the rest of
|
|
the line is the name of a file of regular expressions. This means that
|
|
such files can be nested. All the other lines are taken to be regular
|
|
expressions. For example, one can create a file called
|
|
@samp{emacs.tags} with the following contents (the first line in the
|
|
file is a comment):
|
|
|
|
@smallexample
|
|
-- This is for GNU Emacs source files
|
|
@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and then use it like this:
|
|
|
|
@smallexample
|
|
etags --regex=@@emacs.tags *.[ch] */*.[ch]
|
|
@end smallexample
|
|
|
|
Here are some more examples. The regexps are quoted to protect them
|
|
from shell interpretation.
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Tag Octave files:
|
|
|
|
@smallexample
|
|
etags --language=none \
|
|
--regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
|
|
--regex='/###key \(.*\)/\1/' \
|
|
--regex='/[ \t]*global[ \t].*/' \
|
|
*.m
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note that tags are not generated for scripts so that you have to add a
|
|
line by yourself of the form `###key <script-name>' if you want to jump
|
|
to it.
|
|
|
|
@item
|
|
Tag Tcl files:
|
|
|
|
@smallexample
|
|
etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
|
|
@end smallexample
|
|
|
|
@item
|
|
Tag VHDL files:
|
|
|
|
@smallexample
|
|
--language=none \
|
|
--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
|
|
--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
|
|
\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@node Select Tags Table
|
|
@subsection Selecting a Tags Table
|
|
|
|
@vindex tags-file-name
|
|
@findex visit-tags-table
|
|
Emacs has at any time one @dfn{selected} tags table, and all the commands
|
|
for working with tags tables use the selected one. To select a tags table,
|
|
type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
|
|
argument. The name @file{TAGS} in the default directory is used as the
|
|
default file name.
|
|
|
|
All this command does is store the file name in the variable
|
|
@code{tags-file-name}. Emacs does not actually read in the tags table
|
|
contents until you try to use them. Setting this variable yourself is just
|
|
as good as using @code{visit-tags-table}. The variable's initial value is
|
|
@code{nil}; that value tells all the commands for working with tags tables
|
|
that they must ask for a tags table file name to use.
|
|
|
|
Using @code{visit-tags-table} when a tags table is already loaded
|
|
gives you a choice: you can add the new tags table to the current list
|
|
of tags tables, or start a new list. The tags commands use all the tags
|
|
tables in the current list. If you start a new list, the new tags table
|
|
is used @emph{instead} of others. If you add the new table to the
|
|
current list, it is used @emph{as well as} the others. When the tags
|
|
commands scan the list of tags tables, they don't always start at the
|
|
beginning of the list; they start with the first tags table (if any)
|
|
that describes the current file, proceed from there to the end of the
|
|
list, and then scan from the beginning of the list until they have
|
|
covered all the tables in the list.
|
|
|
|
@vindex tags-table-list
|
|
You can specify a precise list of tags tables by setting the variable
|
|
@code{tags-table-list} to a list of strings, like this:
|
|
|
|
@c keep this on two lines for formatting in smallbook
|
|
@example
|
|
@group
|
|
(setq tags-table-list
|
|
'("~/emacs" "/usr/local/lib/emacs/src"))
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This tells the tags commands to look at the @file{TAGS} files in your
|
|
@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
|
|
directory. The order depends on which file you are in and which tags
|
|
table mentions that file, as explained above.
|
|
|
|
Do not set both @code{tags-file-name} and @code{tags-table-list}.
|
|
|
|
@node Find Tag
|
|
@subsection Finding a Tag
|
|
|
|
The most important thing that a tags table enables you to do is to find
|
|
the definition of a specific tag.
|
|
|
|
@table @kbd
|
|
@item M-.@: @var{tag} @key{RET}
|
|
Find first definition of @var{tag} (@code{find-tag}).
|
|
@item C-u M-.
|
|
Find next alternate definition of last tag specified.
|
|
@item C-u - M-.
|
|
Go back to previous tag found.
|
|
@item C-M-. @var{pattern} @key{RET}
|
|
Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
|
|
@item C-u C-M-.
|
|
Find the next tag whose name matches the last pattern used.
|
|
@item C-x 4 .@: @var{tag} @key{RET}
|
|
Find first definition of @var{tag}, but display it in another window
|
|
(@code{find-tag-other-window}).
|
|
@item C-x 5 .@: @var{tag} @key{RET}
|
|
Find first definition of @var{tag}, and create a new frame to select the
|
|
buffer (@code{find-tag-other-frame}).
|
|
@item M-*
|
|
Pop back to where you previously invoked @kbd{M-.} and friends.
|
|
@end table
|
|
|
|
@kindex M-.
|
|
@findex find-tag
|
|
@kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
|
|
a specified tag. It searches through the tags table for that tag, as a
|
|
string, and then uses the tags table info to determine the file that the
|
|
definition is in and the approximate character position in the file of
|
|
the definition. Then @code{find-tag} visits that file, moves point to
|
|
the approximate character position, and searches ever-increasing
|
|
distances away to find the tag definition.
|
|
|
|
If an empty argument is given (just type @key{RET}), the sexp in the
|
|
buffer before or around point is used as the @var{tag} argument.
|
|
@xref{Lists}, for info on sexps.
|
|
|
|
You don't need to give @kbd{M-.} the full name of the tag; a part
|
|
will do. This is because @kbd{M-.} finds tags in the table which
|
|
contain @var{tag} as a substring. However, it prefers an exact match
|
|
to a substring match. To find other tags that match the same
|
|
substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
|
|
M-.}; this does not read a tag name, but continues searching the tags
|
|
table's text for another tag containing the same substring last used.
|
|
If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
|
|
alternative to @kbd{C-u M-.}.
|
|
|
|
@kindex C-x 4 .
|
|
@findex find-tag-other-window
|
|
@kindex C-x 5 .
|
|
@findex find-tag-other-frame
|
|
Like most commands that can switch buffers, @code{find-tag} has a
|
|
variant that displays the new buffer in another window, and one that
|
|
makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
|
|
the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
|
|
which invokes @code{find-tag-other-frame}.
|
|
|
|
To move back to places you've found tags recently, use @kbd{C-u -
|
|
M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
|
|
command can take you to another buffer. @kbd{C-x 4 .} with a negative
|
|
argument finds the previous tag location in another window.
|
|
|
|
@kindex M-*
|
|
@findex pop-tag-mark
|
|
@vindex find-tag-marker-ring-length
|
|
As well as going back to places you've found tags recently, you can go
|
|
back to places @emph{from where} you found them. Use @kbd{M-*}, which
|
|
invokes the command @code{pop-tag-mark}, for this. Typically you would
|
|
find and study the definition of something with @kbd{M-.} and then
|
|
return to where you were with @kbd{M-*}.
|
|
|
|
Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
|
|
a depth determined by the variable @code{find-tag-marker-ring-length}.
|
|
|
|
@findex find-tag-regexp
|
|
@kindex C-M-.
|
|
The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
|
|
match a specified regular expression. It is just like @kbd{M-.} except
|
|
that it does regexp matching instead of substring matching.
|
|
|
|
@node Tags Search
|
|
@subsection Searching and Replacing with Tags Tables
|
|
|
|
The commands in this section visit and search all the files listed in the
|
|
selected tags table, one by one. For these commands, the tags table serves
|
|
only to specify a sequence of files to search.
|
|
|
|
@table @kbd
|
|
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
|
|
Search for @var{regexp} through the files in the selected tags
|
|
table.
|
|
@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
|
|
Perform a @code{query-replace-regexp} on each file in the selected tags table.
|
|
@item M-,
|
|
Restart one of the commands above, from the current location of point
|
|
(@code{tags-loop-continue}).
|
|
@end table
|
|
|
|
@findex tags-search
|
|
@kbd{M-x tags-search} reads a regexp using the minibuffer, then
|
|
searches for matches in all the files in the selected tags table, one
|
|
file at a time. It displays the name of the file being searched so you
|
|
can follow its progress. As soon as it finds an occurrence,
|
|
@code{tags-search} returns.
|
|
|
|
@kindex M-,
|
|
@findex tags-loop-continue
|
|
Having found one match, you probably want to find all the rest. To find
|
|
one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
|
|
@code{tags-search}. This searches the rest of the current buffer, followed
|
|
by the remaining files of the tags table.@refill
|
|
|
|
@findex tags-query-replace
|
|
@kbd{M-x tags-query-replace} performs a single
|
|
@code{query-replace-regexp} through all the files in the tags table. It
|
|
reads a regexp to search for and a string to replace with, just like
|
|
ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
|
|
tags-search}, but repeatedly, processing matches according to your
|
|
input. @xref{Replace}, for more information on query replace.
|
|
|
|
@vindex tags-case-fold-search
|
|
@cindex case-sensitivity, and tags search
|
|
You can control the case-sensitivity of tags search commands by
|
|
customizing the value of the variable @code{tags-case-fold-search}. The
|
|
default is to use the same setting as the value of
|
|
@code{case-fold-search} (@pxref{Search Case}).
|
|
|
|
It is possible to get through all the files in the tags table with a
|
|
single invocation of @kbd{M-x tags-query-replace}. But often it is
|
|
useful to exit temporarily, which you can do with any input event that
|
|
has no special query replace meaning. You can resume the query replace
|
|
subsequently by typing @kbd{M-,}; this command resumes the last tags
|
|
search or replace command that you did.
|
|
|
|
The commands in this section carry out much broader searches than the
|
|
@code{find-tag} family. The @code{find-tag} commands search only for
|
|
definitions of tags that match your substring or regexp. The commands
|
|
@code{tags-search} and @code{tags-query-replace} find every occurrence
|
|
of the regexp, as ordinary search commands and replace commands do in
|
|
the current buffer.
|
|
|
|
These commands create buffers only temporarily for the files that they
|
|
have to search (those which are not already visited in Emacs buffers).
|
|
Buffers in which no match is found are quickly killed; the others
|
|
continue to exist.
|
|
|
|
It may have struck you that @code{tags-search} is a lot like
|
|
@code{grep}. You can also run @code{grep} itself as an inferior of
|
|
Emacs and have Emacs show you the matching lines one by one. This works
|
|
much like running a compilation; finding the source locations of the
|
|
@code{grep} matches works like finding the compilation errors.
|
|
@xref{Compilation}.
|
|
|
|
@node List Tags
|
|
@subsection Tags Table Inquiries
|
|
|
|
@table @kbd
|
|
@item M-x list-tags @key{RET} @var{file} @key{RET}
|
|
Display a list of the tags defined in the program file @var{file}.
|
|
@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
|
|
Display a list of all tags matching @var{regexp}.
|
|
@end table
|
|
|
|
@findex list-tags
|
|
@kbd{M-x list-tags} reads the name of one of the files described by
|
|
the selected tags table, and displays a list of all the tags defined in
|
|
that file. The ``file name'' argument is really just a string to
|
|
compare against the file names recorded in the tags table; it is read as
|
|
a string rather than as a file name. Therefore, completion and
|
|
defaulting are not available, and you must enter the file name the same
|
|
way it appears in the tags table. Do not include a directory as part of
|
|
the file name unless the file name recorded in the tags table includes a
|
|
directory.
|
|
|
|
@findex tags-apropos
|
|
@kbd{M-x tags-apropos} is like @code{apropos} for tags
|
|
(@pxref{Apropos}). It reads a regexp, then finds all the tags in the
|
|
selected tags table whose entries match that regexp, and displays the
|
|
tag names found.
|
|
@vindex tags-apropos-additional-actions
|
|
You can display additional output with @kbd{M-x tags-apropos} by customizing
|
|
the variable @code{tags-apropos-additional-actions}. See its
|
|
documentation for details.
|
|
@vindex tags-apropos-verbose
|
|
Setting the variable @code{tags-apropos-verbose} to a non-nil value
|
|
causes @kbd{M-x tags-apropos} to display the names of the tags files
|
|
together with the tag names.
|
|
@vindex tags-tag-face
|
|
The face @code{tags-tag-face} can be used to customize the appearance of
|
|
tags in the output of @kbd{M-x tags-apropos}.
|
|
|
|
You can also perform completion in the buffer on the name space of tag
|
|
names in the current tags tables. @xref{Symbol Completion}.
|
|
|
|
@node Imenu
|
|
@section Imenu
|
|
@cindex indexes of buffer contents
|
|
@cindex buffer content indexes
|
|
@cindex tags
|
|
|
|
The Imenu facility provides mode-specific indexes of the contents of
|
|
single buffers and provides selection from a menu. Selecting a menu
|
|
item takes you to the indexed point in the buffer, in a similar way to
|
|
the Tags facility. Indexing is typically by names of program routines
|
|
and variables but in Texinfo mode, for instance, node names are indexed.
|
|
Most major modes for which it is appropriate have Imenu support.
|
|
|
|
@findex imenu
|
|
@findex imenu-add-menu-bar-index
|
|
@kbd{M-x imenu} builds the index if necessary and presents you with an
|
|
electric buffer menu from which to select an entry (with completion).
|
|
If you bind @code{imenu} to a mouse event (@pxref{Mouse Buttons}) and
|
|
invoke it that way, the index will appear as a popup menu; there is no
|
|
such binding by default. You can add an index menubar on the menubar
|
|
with @kbd{imenu-add-menu-bar-index}.
|
|
|
|
Some major modes provide facilities for invoking Imenu; otherwise you
|
|
could add @code{imenu-add-menu-bar-index} to a major mode's hook to
|
|
generate an index for each buffer created in that mode. (If you do
|
|
that, it takes sime time to generate the index when finding a file,
|
|
depending on the file's size and the complexity of the indexing function
|
|
for that mode.)
|
|
|
|
@vindex imenu-auto-rescan
|
|
The index should be regenerated (via the @samp{*Rescan*} menu item) when
|
|
indexable items are added to or deleted from the buffer. Rescanning is
|
|
done when a menu selction is requested if the option
|
|
@code{imenu-auto-rescan} is set. By default buffer positions are in
|
|
terms of markers, so that changing non-indexable text doesn't require
|
|
rescanning.
|
|
|
|
@vindex imenu-sort-function
|
|
The way the menus are sorted can be customized via the option
|
|
@code{imenu-sort-function}. By default names are ordered as they occur
|
|
in the buffer; alphabetic sorting is provided as an alternative.
|
|
|
|
Imenu provides the information used by Which Function mode (@pxref{Which
|
|
Function}). It may also be used by Speedbar (@pxref{Speedbar}).
|
|
|
|
@node Emerge, C Modes, Imenu, Programs
|
|
@section Merging Files with Emerge
|
|
@cindex Emerge
|
|
@cindex merging files
|
|
|
|
It's not unusual for programmers to get their signals crossed and modify
|
|
the same program in two different directions. To recover from this
|
|
confusion, you need to merge the two versions. Emerge makes this
|
|
easier. See also @ref{Comparing Files}, for commands to compare
|
|
in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
|
|
|
|
@menu
|
|
* Overview of Emerge:: How to start Emerge. Basic concepts.
|
|
* Submodes of Emerge:: Fast mode vs. Edit mode.
|
|
Skip Prefers mode and Auto Advance mode.
|
|
* State of Difference:: You do the merge by specifying state A or B
|
|
for each difference.
|
|
* Merge Commands:: Commands for selecting a difference,
|
|
changing states of differences, etc.
|
|
* Exiting Emerge:: What to do when you've finished the merge.
|
|
* Combining in Emerge:: How to keep both alternatives for a difference.
|
|
* Fine Points of Emerge:: Misc.
|
|
@end menu
|
|
|
|
@node Overview of Emerge
|
|
@subsection Overview of Emerge
|
|
|
|
To start Emerge, run one of these four commands:
|
|
|
|
@table @kbd
|
|
@item M-x emerge-files
|
|
@findex emerge-files
|
|
Merge two specified files.
|
|
|
|
@item M-x emerge-files-with-ancestor
|
|
@findex emerge-files-with-ancestor
|
|
Merge two specified files, with reference to a common ancestor.
|
|
|
|
@item M-x emerge-buffers
|
|
@findex emerge-buffers
|
|
Merge two buffers.
|
|
|
|
@item M-x emerge-buffers-with-ancestor
|
|
@findex emerge-buffers-with-ancestor
|
|
Merge two buffers with reference to a common ancestor in a third
|
|
buffer.
|
|
@end table
|
|
|
|
@cindex merge buffer (Emerge)
|
|
@cindex A and B buffers (Emerge)
|
|
The Emerge commands compare two files or buffers, and display the
|
|
comparison in three buffers: one for each input text (the @dfn{A buffer}
|
|
and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
|
|
takes place. The merge buffer shows the full merged text, not just the
|
|
differences. Wherever the two input texts differ, you can choose which
|
|
one of them to include in the merge buffer.
|
|
|
|
The Emerge commands that take input from existing buffers use only the
|
|
accessible portions of those buffers, if they are narrowed
|
|
(@pxref{Narrowing}).
|
|
|
|
If a common ancestor version is available, from which the two texts to
|
|
be merged were both derived, Emerge can use it to guess which
|
|
alternative is right. Wherever one current version agrees with the
|
|
ancestor, Emerge presumes that the other current version is a deliberate
|
|
change which should be kept in the merged version. Use the
|
|
@samp{with-ancestor} commands if you want to specify a common ancestor
|
|
text. These commands read three file or buffer names---variant A,
|
|
variant B, and the common ancestor.
|
|
|
|
After the comparison is done and the buffers are prepared, the
|
|
interactive merging starts. You control the merging by typing special
|
|
@dfn{merge commands} in the merge buffer. The merge buffer shows you a
|
|
full merged text, not just differences. For each run of differences
|
|
between the input texts, you can choose which one of them to keep, or
|
|
edit them both together.
|
|
|
|
The merge buffer uses a special major mode, Emerge mode, with commands
|
|
for making these choices. But you can also edit the buffer with
|
|
ordinary Emacs commands.
|
|
|
|
At any given time, the attention of Emerge is focused on one
|
|
particular difference, called the @dfn{selected} difference. This
|
|
difference is marked off in the three buffers like this:
|
|
|
|
@example
|
|
vvvvvvvvvvvvvvvvvvvv
|
|
@var{text that differs}
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
@end example
|
|
|
|
@noindent
|
|
Emerge numbers all the differences sequentially and the mode
|
|
line always shows the number of the selected difference.
|
|
|
|
Normally, the merge buffer starts out with the A version of the text.
|
|
But when the A version of a difference agrees with the common ancestor,
|
|
then the B version is initially preferred for that difference.
|
|
|
|
Emerge leaves the merged text in the merge buffer when you exit. At
|
|
that point, you can save it in a file with @kbd{C-x C-w}. If you give a
|
|
numeric argument to @code{emerge-files} or
|
|
@code{emerge-files-with-ancestor}, it reads the name of the output file
|
|
using the minibuffer. (This is the last file name those commands read.)
|
|
Then exiting from Emerge saves the merged text in the output file.
|
|
|
|
Normally, Emerge commands save the output buffer in its file when you
|
|
exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
|
|
save the output buffer, but you can save it yourself if you wish.
|
|
|
|
@node Submodes of Emerge
|
|
@subsection Submodes of Emerge
|
|
|
|
You can choose between two modes for giving merge commands: Fast mode
|
|
and Edit mode. In Fast mode, basic merge commands are single
|
|
characters, but ordinary Emacs commands are disabled. This is
|
|
convenient if you use only merge commands. In Edit mode, all merge
|
|
commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
|
|
commands are also available. This allows editing the merge buffer, but
|
|
slows down Emerge operations.
|
|
|
|
Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
|
|
Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
|
|
and @samp{F}.
|
|
|
|
Emerge has two additional submodes that affect how particular merge
|
|
commands work: Auto Advance mode and Skip Prefers mode.
|
|
|
|
If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
|
|
advance to the next difference. This lets you go through the merge
|
|
faster as long as you simply choose one of the alternatives from the
|
|
input. The mode line indicates Auto Advance mode with @samp{A}.
|
|
|
|
If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
|
|
skip over differences in states prefer-A and prefer-B (@pxref{State of
|
|
Difference}). Thus you see only differences for which neither version
|
|
is presumed ``correct.'' The mode line indicates Skip Prefers mode with
|
|
@samp{S}.
|
|
|
|
@findex emerge-auto-advance-mode
|
|
@findex emerge-skip-prefers-mode
|
|
Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
|
|
clear Auto Advance mode. Use @kbd{s s}
|
|
(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
|
|
These commands turn on the mode with a positive argument, turns it off
|
|
with a negative or zero argument, and toggle the mode with no argument.
|
|
|
|
@node State of Difference
|
|
@subsection State of a Difference
|
|
|
|
In the merge buffer, a difference is marked with lines of @samp{v} and
|
|
@samp{^} characters. Each difference has one of these seven states:
|
|
|
|
@table @asis
|
|
@item A
|
|
The difference is showing the A version. The @kbd{a} command always
|
|
produces this state; the mode line indicates it with @samp{A}.
|
|
|
|
@item B
|
|
The difference is showing the B version. The @kbd{b} command always
|
|
produces this state; the mode line indicates it with @samp{B}.
|
|
|
|
@item default-A
|
|
@itemx default-B
|
|
The difference is showing the A or the B state by default, because you
|
|
haven't made a choice. All differences start in the default-A state
|
|
(and thus the merge buffer is a copy of the A buffer), except those for
|
|
which one alternative is ``preferred'' (see below).
|
|
|
|
When you select a difference, its state changes from default-A or
|
|
default-B to plain A or B. Thus, the selected difference never has
|
|
state default-A or default-B, and these states are never displayed in
|
|
the mode line.
|
|
|
|
The command @kbd{d a} chooses default-A as the default state, and @kbd{d
|
|
b} chooses default-B. This chosen default applies to all differences
|
|
which you haven't ever selected and for which no alternative is preferred.
|
|
If you are moving through the merge sequentially, the differences you
|
|
haven't selected are those following the selected one. Thus, while
|
|
moving sequentially, you can effectively make the A version the default
|
|
for some sections of the merge buffer and the B version the default for
|
|
others by using @kbd{d a} and @kbd{d b} between sections.
|
|
|
|
@item prefer-A
|
|
@itemx prefer-B
|
|
The difference is showing the A or B state because it is
|
|
@dfn{preferred}. This means that you haven't made an explicit choice,
|
|
but one alternative seems likely to be right because the other
|
|
alternative agrees with the common ancestor. Thus, where the A buffer
|
|
agrees with the common ancestor, the B version is preferred, because
|
|
chances are it is the one that was actually changed.
|
|
|
|
These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
|
|
|
|
@item combined
|
|
The difference is showing a combination of the A and B states, as a
|
|
result of the @kbd{x c} or @kbd{x C} commands.
|
|
|
|
Once a difference is in this state, the @kbd{a} and @kbd{b} commands
|
|
don't do anything to it unless you give them a numeric argument.
|
|
|
|
The mode line displays this state as @samp{comb}.
|
|
@end table
|
|
|
|
@node Merge Commands
|
|
@subsection Merge Commands
|
|
|
|
Here are the Merge commands for Fast mode; in Edit mode, precede them
|
|
with @kbd{C-c C-c}:
|
|
|
|
@table @kbd
|
|
@item p
|
|
Select the previous difference.
|
|
|
|
@item n
|
|
Select the next difference.
|
|
|
|
@item a
|
|
Choose the A version of this difference.
|
|
|
|
@item b
|
|
Choose the B version of this difference.
|
|
|
|
@item C-u @var{n} j
|
|
Select difference number @var{n}.
|
|
|
|
@item .
|
|
Select the difference containing point. You can use this command in the
|
|
merge buffer or in the A or B buffer.
|
|
|
|
@item q
|
|
Quit---finish the merge.
|
|
|
|
@item C-]
|
|
Abort---exit merging and do not save the output.
|
|
|
|
@item f
|
|
Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
|
|
|
|
@item e
|
|
Go into Edit mode.
|
|
|
|
@item l
|
|
Recenter (like @kbd{C-l}) all three windows.
|
|
|
|
@item -
|
|
Specify part of a prefix numeric argument.
|
|
|
|
@item @var{digit}
|
|
Also specify part of a prefix numeric argument.
|
|
|
|
@item d a
|
|
Choose the A version as the default from here down in
|
|
the merge buffer.
|
|
|
|
@item d b
|
|
Choose the B version as the default from here down in
|
|
the merge buffer.
|
|
|
|
@item c a
|
|
Copy the A version of this difference into the kill ring.
|
|
|
|
@item c b
|
|
Copy the B version of this difference into the kill ring.
|
|
|
|
@item i a
|
|
Insert the A version of this difference at point.
|
|
|
|
@item i b
|
|
Insert the B version of this difference at point.
|
|
|
|
@item m
|
|
Put point and mark around the difference.
|
|
|
|
@item ^
|
|
Scroll all three windows down (like @kbd{M-v}).
|
|
|
|
@item v
|
|
Scroll all three windows up (like @kbd{C-v}).
|
|
|
|
@item <
|
|
Scroll all three windows left (like @kbd{C-x <}).
|
|
|
|
@item >
|
|
Scroll all three windows right (like @kbd{C-x >}).
|
|
|
|
@item |
|
|
Reset horizontal scroll on all three windows.
|
|
|
|
@item x 1
|
|
Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
|
|
to full size.)
|
|
|
|
@item x c
|
|
Combine the two versions of this difference (@pxref{Combining in
|
|
Emerge}).
|
|
|
|
@item x f
|
|
Show the names of the files/buffers Emerge is operating on, in a Help
|
|
window. (Use @kbd{C-u l} to restore windows.)
|
|
|
|
@item x j
|
|
Join this difference with the following one.
|
|
(@kbd{C-u x j} joins this difference with the previous one.)
|
|
|
|
@item x s
|
|
Split this difference into two differences. Before you use this
|
|
command, position point in each of the three buffers at the place where
|
|
you want to split the difference.
|
|
|
|
@item x t
|
|
Trim identical lines off the top and bottom of the difference.
|
|
Such lines occur when the A and B versions are
|
|
identical but differ from the ancestor version.
|
|
@end table
|
|
|
|
@node Exiting Emerge
|
|
@subsection Exiting Emerge
|
|
|
|
The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
|
|
the results into the output file if you specified one. It restores the
|
|
A and B buffers to their proper contents, or kills them if they were
|
|
created by Emerge and you haven't changed them. It also disables the
|
|
Emerge commands in the merge buffer, since executing them later could
|
|
damage the contents of the various buffers.
|
|
|
|
@kbd{C-]} aborts the merge. This means exiting without writing the
|
|
output file. If you didn't specify an output file, then there is no
|
|
real difference between aborting and finishing the merge.
|
|
|
|
If the Emerge command was called from another Lisp program, then its
|
|
return value is @code{t} for successful completion, or @code{nil} if you
|
|
abort.
|
|
|
|
@node Combining in Emerge
|
|
@subsection Combining the Two Versions
|
|
|
|
Sometimes you want to keep @emph{both} alternatives for a particular
|
|
difference. To do this, use @kbd{x c}, which edits the merge buffer
|
|
like this:
|
|
|
|
@example
|
|
@group
|
|
#ifdef NEW
|
|
@var{version from A buffer}
|
|
#else /* not NEW */
|
|
@var{version from B buffer}
|
|
#endif /* not NEW */
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
@vindex emerge-combine-versions-template
|
|
While this example shows C preprocessor conditionals delimiting the two
|
|
alternative versions, you can specify the strings to use by setting
|
|
the variable @code{emerge-combine-versions-template} to a string of your
|
|
choice. In the string, @samp{%a} says where to put version A, and
|
|
@samp{%b} says where to put version B. The default setting, which
|
|
produces the results shown above, looks like this:
|
|
|
|
@example
|
|
@group
|
|
"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
|
|
@end group
|
|
@end example
|
|
|
|
@node Fine Points of Emerge
|
|
@subsection Fine Points of Emerge
|
|
|
|
During the merge, you mustn't try to edit the A and B buffers yourself.
|
|
Emerge modifies them temporarily, but ultimately puts them back the way
|
|
they were.
|
|
|
|
You can have any number of merges going at once---just don't use any one
|
|
buffer as input to more than one merge at once, since the temporary
|
|
changes made in these buffers would get in each other's way.
|
|
|
|
Starting Emerge can take a long time because it needs to compare the
|
|
files fully. Emacs can't do anything else until @code{diff} finishes.
|
|
Perhaps in the future someone will change Emerge to do the comparison in
|
|
the background when the input files are large---then you could keep on
|
|
doing other things with Emacs until Emerge is ready to accept
|
|
commands.
|
|
|
|
@vindex emerge-startup-hook
|
|
After setting up the merge, Emerge runs the hook
|
|
@code{emerge-startup-hook} (@pxref{Hooks}).
|
|
|
|
@node C Modes
|
|
@section C and Related Modes
|
|
@cindex C mode
|
|
@cindex Java mode
|
|
@cindex Pike mode
|
|
@cindex IDL mode
|
|
@cindex CORBA IDL mode
|
|
@cindex Objective C mode
|
|
@cindex C++ mode
|
|
@cindex mode, Java
|
|
@cindex mode, C
|
|
@cindex mode, Objective C
|
|
@cindex mode, CORBA IDL
|
|
@cindex mode, Pike
|
|
|
|
This section describes special features available in C, C++,
|
|
Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and
|
|
related modes,'' those are the modes we mean.
|
|
|
|
Additional information is available in the separate manual for these
|
|
modes. @xref{Top, CC Mode, ccmode, , CC Mode}.
|
|
|
|
@menu
|
|
* Motion in C::
|
|
* Electric C::
|
|
* Hungry Delete::
|
|
* Other C Commands::
|
|
* Comments in C::
|
|
@end menu
|
|
|
|
@node Motion in C
|
|
@subsection C Mode Motion Commands
|
|
|
|
This section describes commands for moving point, in C mode and
|
|
related modes.
|
|
|
|
@table @code
|
|
@item C-c C-u
|
|
@kindex C-c C-u @r{(C mode)}
|
|
@findex c-up-conditional
|
|
Move point back to the containing preprocessor conditional, leaving the
|
|
mark behind. A prefix argument acts as a repeat count. With a negative
|
|
argument, move point forward to the end of the containing
|
|
preprocessor conditional. When going backwards, @code{#elif} is treated
|
|
like @code{#else} followed by @code{#if}. When going forwards,
|
|
@code{#elif} is ignored.@refill
|
|
|
|
@item C-c C-p
|
|
@kindex C-c C-p @r{(C mode)}
|
|
@findex c-backward-conditional
|
|
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.
|
|
|
|
@item C-c C-n
|
|
@kindex C-c C-n @r{(C mode)}
|
|
@findex c-forward-conditional
|
|
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.
|
|
|
|
@item M-a
|
|
@kindex ESC a
|
|
@findex c-beginning-of-statement
|
|
Move point to the beginning of the innermost C statement
|
|
(@code{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 @var{n}, move back @var{n} @minus{} 1 statements.
|
|
|
|
If point is within a string or comment, or next to a comment (only
|
|
whitespace between them), this command moves by sentences instead of
|
|
statements.
|
|
|
|
When called from a program, this function takes three optional
|
|
arguments: the numeric prefix argument, a buffer position limit
|
|
(don't move back before that place), and a flag that controls whether
|
|
to do sentence motion when inside of a comment.
|
|
|
|
@item M-e
|
|
@kindex ESC e
|
|
@findex c-end-of-statement
|
|
Move point to the end of the innermost C statement; like @kbd{M-a}
|
|
except that it moves in the other direction (@code{c-end-of-statement}).
|
|
|
|
@item M-x c-backward-into-nomenclature
|
|
@findex c-backward-into-nomenclature
|
|
Move point backward to beginning of a C++ nomenclature section or word.
|
|
With prefix argument @var{n}, move @var{n} times. If @var{n} is
|
|
negative, move forward. C++ nomenclature means a symbol name in the
|
|
style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
|
|
begins a section or word.
|
|
|
|
In the GNU project, we recommend using underscores to separate words
|
|
within an identifier in C or C++, rather than using case distinctions.
|
|
|
|
@item M-x c-forward-into-nomenclature
|
|
@findex c-forward-into-nomenclature
|
|
Move point forward to end of a C++ nomenclature section or word.
|
|
With prefix argument @var{n}, move @var{n} times.
|
|
@end table
|
|
|
|
@node Electric C
|
|
@subsection Electric C Characters
|
|
|
|
In C mode and related modes, certain printing characters are
|
|
``electric''---in addition to inserting themselves, they also reindent
|
|
the current line and may insert newlines. This feature is controlled by
|
|
the variable @code{c-auto-newline}. The ``electric'' characters are
|
|
@kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
|
|
@kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
|
|
|
|
Electric characters insert newlines only when the @dfn{auto-newline}
|
|
feature is enabled (indicated by @samp{/a} in the mode line after the
|
|
mode name). This feature is controlled by the variable
|
|
@code{c-auto-newline}. You can turn this feature on or off with the
|
|
command @kbd{C-c C-a}:
|
|
|
|
@table @kbd
|
|
@item C-c C-a
|
|
@kindex C-c C-a @r{(C mode)}
|
|
@findex c-toggle-auto-state
|
|
Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a
|
|
prefix argument, this command turns the auto-newline feature on if the
|
|
argument is positive, and off if it is negative.
|
|
@end table
|
|
|
|
The colon character is electric because that is appropriate for a
|
|
single colon. But when you want to insert a double colon in C++, the
|
|
electric behavior of colon is inconvenient. You can insert a double
|
|
colon with no reindentation or newlines by typing @kbd{C-c :}:
|
|
|
|
@table @kbd
|
|
@item C-c :
|
|
@kindex C-c : @r{(C mode)}
|
|
@findex c-scope-operator
|
|
Insert a double colon scope operator at point, without reindenting the
|
|
line or adding any newlines (@code{c-scope-operator}).
|
|
@end table
|
|
|
|
The electric @kbd{#} key reindents the line if it appears to be the
|
|
beginning of a preprocessor directive. This happens when the value of
|
|
@code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
|
|
this feature off by setting @code{c-electric-pound-behavior} to
|
|
@code{nil}.
|
|
|
|
The variable @code{c-hanging-braces-alist} controls the insertion of
|
|
newlines before and after inserted braces. It is an association list
|
|
with elements of the following form: @code{(@var{syntactic-symbol}
|
|
. @var{nl-list})}. Most of the syntactic symbols that appear in
|
|
@code{c-offsets-alist} are meaningful here as well.
|
|
|
|
The list @var{nl-list} may contain either of the symbols
|
|
@code{before} or @code{after}, or both; or it may be @code{nil}. When a
|
|
brace is inserted, the syntactic context it defines is looked up in
|
|
@code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
|
|
to determine where newlines are inserted: either before the brace,
|
|
after, or both. If not found, the default is to insert a newline both
|
|
before and after braces.
|
|
|
|
The variable @code{c-hanging-colons-alist} controls the insertion of
|
|
newlines before and after inserted colons. It is an association list
|
|
with elements of the following form: @code{(@var{syntactic-symbol}
|
|
. @var{nl-list})}. The list @var{nl-list} may contain either of the
|
|
symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
|
|
|
|
When a colon is inserted, the syntactic symbol it defines is looked
|
|
up in this list, and if found, the @var{nl-list} is used to determine
|
|
where newlines are inserted: either before the brace, after, or both.
|
|
If the syntactic symbol is not found in this list, no newlines are
|
|
inserted.
|
|
|
|
Electric characters can also delete newlines automatically when the
|
|
auto-newline feature is enabled. This feature makes auto-newline more
|
|
acceptable, by deleting the newlines in the most common cases where you
|
|
do not want them. Emacs can recognize several cases in which deleting a
|
|
newline might be desirable; by setting the variable
|
|
@code{c-cleanup-list}, you can specify @emph{which} of these cases that
|
|
should happen. The variable's value is a list of symbols, each
|
|
describing one case for possible deletion of a newline. Here are the
|
|
meaningful symbols, and their meanings:
|
|
|
|
@table @code
|
|
@item brace-catch-brace
|
|
Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
|
|
entire construct on a single line. The clean-up occurs when you type
|
|
the @samp{@{}, if there is nothing between the braces aside from
|
|
@code{catch} and @var{condition}.
|
|
|
|
@item brace-else-brace
|
|
Clean up @samp{@} else @{} constructs by placing the entire construct on
|
|
a single line. The clean-up occurs when you type the @samp{@{} after
|
|
the @code{else}, but only if there is nothing but white space between
|
|
the braces and the @code{else}.
|
|
|
|
@item brace-elseif-brace
|
|
Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
|
|
construct on a single line. The clean-up occurs when you type the
|
|
@samp{@{}, if there is nothing but white space between the @samp{@}} and
|
|
@samp{@{} aside from the keywords and the @code{if}-condition.
|
|
|
|
@item empty-defun-braces
|
|
Clean up empty defun braces by placing the braces on the same
|
|
line. Clean-up occurs when you type the closing brace.
|
|
|
|
@item defun-close-semi
|
|
Clean up the semicolon after a @code{struct} or similar type
|
|
declaration, by placing the semicolon on the same line as the closing
|
|
brace. Clean-up occurs when you type the semicolon.
|
|
|
|
@item list-close-comma
|
|
Clean up commas following braces in array and aggregate
|
|
initializers. Clean-up occurs when you type the comma.
|
|
|
|
@item scope-operator
|
|
Clean up double colons which may designate a C++ scope operator, by
|
|
placing the colons together. Clean-up occurs when you type the second
|
|
colon, but only when the two colons are separated by nothing but
|
|
whitespace.
|
|
@end table
|
|
|
|
@node Hungry Delete
|
|
@subsection Hungry Delete Feature in C
|
|
|
|
When the @dfn{hungry-delete} feature is enabled (indicated by
|
|
@samp{/h} or @samp{/ah} in the mode line after the mode name), a single
|
|
@key{DEL} command deletes all preceding whitespace, not just one space.
|
|
To turn this feature on or off, use @kbd{C-c C-d}:
|
|
|
|
@table @kbd
|
|
@item C-c C-d
|
|
@kindex C-c C-d @r{(C mode)}
|
|
@findex c-toggle-hungry-state
|
|
Toggle the hungry-delete feature (@code{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.
|
|
|
|
@item C-c C-t
|
|
@kindex C-c C-t @r{(C mode)}
|
|
@findex c-toggle-auto-hungry-state
|
|
Toggle the auto-newline and hungry-delete features, both at once
|
|
(@code{c-toggle-auto-hungry-state}).
|
|
@end table
|
|
|
|
@vindex c-hungry-delete-key
|
|
The variable @code{c-hungry-delete-key} controls whether the
|
|
hungry-delete feature is enabled.
|
|
|
|
@node Other C Commands
|
|
@subsection Other Commands for C Mode
|
|
|
|
@table @kbd
|
|
@item C-M-h
|
|
@findex c-mark-function
|
|
@kindex C-M-h @r{(C mode)}
|
|
Put mark at the end of a function definition, and put point at the
|
|
beginning (@code{c-mark-function}).
|
|
|
|
@item M-q
|
|
@kindex M-q @r{(C mode)}
|
|
@findex c-fill-paragraph
|
|
Fill a paragraph, handling C and C++ comments (@code{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.
|
|
|
|
@item C-c C-e
|
|
@cindex macro expansion in C
|
|
@cindex expansion of C macros
|
|
@findex c-macro-expand
|
|
@kindex C-c C-e @r{(C mode)}
|
|
Run the C preprocessor on the text in the region, and show the result,
|
|
which includes the expansion of all the macro calls
|
|
(@code{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.
|
|
|
|
@item C-c C-\
|
|
@findex c-backslash-region
|
|
@kindex C-c C-\ @r{(C mode)}
|
|
Insert or align @samp{\} characters at the ends of the lines of the
|
|
region (@code{c-backslash-region}). This is useful after writing or
|
|
editing a C macro definition.
|
|
|
|
If a line already ends in @samp{\}, this command adjusts the amount of
|
|
whitespace before it. Otherwise, it inserts a new @samp{\}. However,
|
|
the last line in the region is treated specially; no @samp{\} is
|
|
inserted on that line, and any @samp{\} there is deleted.
|
|
|
|
@item M-x cpp-highlight-buffer
|
|
@cindex preprocessor highlighting
|
|
@findex cpp-highlight-buffer
|
|
Highlight parts of the text according to its preprocessor conditionals.
|
|
This command displays another buffer named @samp{*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 @samp{[A]pply these settings} (or go to that buffer and type
|
|
@kbd{a}) to rehighlight the C mode buffer accordingly.
|
|
|
|
@item C-c C-s
|
|
@findex c-show-syntactic-information
|
|
@kindex C-c C-s @r{(C mode)}
|
|
Display the syntactic information about the current source line
|
|
(@code{c-show-syntactic-information}). This is the information that
|
|
directs how the line is indented.
|
|
|
|
@item M-x cwarn-mode
|
|
@itemx M-x global-cwarn-mode
|
|
@findex cwarn-mode
|
|
@findex global-cwarn-mode
|
|
@cindex CWarn mode
|
|
@cindex suspicious constructions in C, C++
|
|
CWarn minor mode highlights suspicious C and C++ constructions:
|
|
|
|
@itemize @bullet{}
|
|
@item
|
|
Assignments inside expressions, including variations like @samp{+=};
|
|
@item
|
|
Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
|
|
(except after a @samp{do @dots{} while} statement);
|
|
@item
|
|
C++ functions with reference parameters.
|
|
@end itemize
|
|
|
|
@noindent
|
|
You can activate the mode either by customizing @code{global-cwarn-mode}
|
|
or by adding @code{cwarn-mode} to @code{c-mode-common-hook}. It
|
|
requires Font Lock mode to be active.
|
|
|
|
@item M-x hide-ifdef-mode
|
|
@findex hide-ifdef-mode
|
|
@cindex Hide-ifdef mode
|
|
Hide-ifdef minor mode hides selected code within @samp{#if} and
|
|
@samp{#ifdef} preprocessor blocks. You can activate it by adding
|
|
@code{hide-ifdef-mode} to @code{c-mode-common-hook}. See the mode's
|
|
help for more information.
|
|
@end table
|
|
|
|
@node Comments in C
|
|
@subsection Comments in C Modes
|
|
|
|
C mode and related modes use a number of variables for controlling
|
|
comment format.
|
|
|
|
@table @code
|
|
@item c-comment-only-line-offset
|
|
@vindex c-comment-only-line-offset
|
|
Extra offset for line which contains only the start of a comment. It
|
|
can be either an integer or a cons cell of the form
|
|
@code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
|
|
@var{non-anchored-offset} is the amount of offset given to
|
|
non-column-zero anchored comment-only lines, and @var{anchored-offset}
|
|
is the amount of offset to give column-zero anchored comment-only lines.
|
|
Just an integer as value is equivalent to @code{(@var{val} . 0)}.
|
|
|
|
@item c-comment-start-regexp
|
|
@vindex c-comment-start-regexp
|
|
This buffer-local variable specifies how to recognize the start of a comment.
|
|
|
|
@item c-hanging-comment-ender-p
|
|
@vindex c-hanging-comment-ender-p
|
|
If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
|
|
comment terminator of a block comment on a line by itself. The default
|
|
value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
|
|
end of the last line of the comment text.
|
|
|
|
@item c-hanging-comment-starter-p
|
|
@vindex c-hanging-comment-starter-p
|
|
If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
|
|
starting delimiter of a block comment on a line by itself. The default
|
|
value is @code{t}, which puts the comment-start delimiter @samp{/*} at
|
|
the beginning of the first line of the comment text.
|
|
@end table
|
|
|
|
|
|
@node Fortran
|
|
@section Fortran Mode
|
|
@cindex Fortran mode
|
|
@cindex mode, Fortran
|
|
|
|
Fortran mode provides special motion commands for Fortran statements and
|
|
subprograms, and indentation commands that understand Fortran conventions
|
|
of nesting, line numbers and continuation statements. Fortran mode has
|
|
its own Auto Fill mode that breaks long lines into proper Fortran
|
|
continuation lines.
|
|
|
|
Special commands for comments are provided because Fortran comments
|
|
are unlike those of other languages. Built-in abbrevs optionally save
|
|
typing when you insert Fortran keywords.
|
|
|
|
@findex fortran-mode
|
|
Use @kbd{M-x fortran-mode} to switch to this major mode. This command
|
|
runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
|
|
|
|
@cindex Fortran77
|
|
@cindex Fortran90
|
|
@findex f90-mode
|
|
@findex fortran-mode
|
|
Note that Fortan mode described here (obtained with the
|
|
@code{fortran-mode} command) is for editing the old Fortran77
|
|
idiosyncratic `fixed format' source form. For editing the modern
|
|
Fortran90 `free format' source form (which is supported by the GNU
|
|
Fortran compiler) use @code{f90-mode}.
|
|
|
|
By default @code{fortran-mode} is invoked on files with extension
|
|
@samp{.f}, @samp{.F} or @samp{.for} and @code{f90-mode} is invoked for
|
|
the extension @samp{.f90}.
|
|
|
|
@menu
|
|
* Motion: Fortran Motion. Moving point by statements or subprograms.
|
|
* Indent: Fortran Indent. Indentation commands for Fortran.
|
|
* Comments: Fortran Comments. Inserting and aligning comments.
|
|
* Autofill: Fortran Autofill. Auto fill minor mode for Fortran.
|
|
* Columns: Fortran Columns. Measuring columns for valid Fortran.
|
|
* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
|
|
* Misc: Fortran Misc. Other Fortran mode features.
|
|
@end menu
|
|
|
|
@node Fortran Motion
|
|
@subsection Motion Commands
|
|
|
|
In addition to the normal commands for moving by and operating on
|
|
`defuns' (Fortran subprograms---functions
|
|
and subroutines) Fortran mode provides special commands to move by statements.
|
|
|
|
@kindex C-c C-p @r{(Fortran mode)}
|
|
@kindex C-c C-n @r{(Fortran mode)}
|
|
@findex fortran-previous-statement
|
|
@findex fortran-next-statement
|
|
|
|
@table @kbd
|
|
@item C-c C-n
|
|
Move to beginning of current or next statement
|
|
(@code{fortran-next-statement}).
|
|
@item C-c C-p
|
|
Move to beginning of current or previous statement
|
|
(@code{fortran-previous-statement}).
|
|
@end table
|
|
|
|
@node Fortran Indent
|
|
@subsection Fortran Indentation
|
|
|
|
Special commands and features are needed for indenting Fortran code in
|
|
order to make sure various syntactic entities (line numbers, comment line
|
|
indicators and continuation line flags) appear in the columns that are
|
|
required for standard Fortran.
|
|
|
|
@menu
|
|
* Commands: ForIndent Commands. Commands for indenting 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.
|
|
@end menu
|
|
|
|
@node ForIndent Commands
|
|
@subsubsection Fortran-Specific Indentation and Filling Commands
|
|
|
|
@table @kbd
|
|
@item C-M-j
|
|
Break the current line and set up a continuation line
|
|
(@code{fortran-split-line}).
|
|
@item M-^
|
|
Join this line to the previous line (@code{fortran-join-line}).
|
|
@item C-M-q
|
|
Indent all the lines of the subprogram point is in
|
|
(@code{fortran-indent-subprogram}).
|
|
@item M-q
|
|
Fill a comment block or statement.
|
|
@end table
|
|
|
|
@kindex C-M-q @r{(Fortran mode)}
|
|
@findex fortran-indent-subprogram
|
|
The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
|
|
to reindent all the lines of the Fortran subprogram (function or
|
|
subroutine) containing point.
|
|
|
|
@kindex C-M-j @r{(Fortran mode)}
|
|
@findex fortran-split-line
|
|
The key @kbd{C-M-j} runs @code{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.
|
|
|
|
@kindex M-^ @r{(Fortran mode)}
|
|
@kindex C-c C-d @r{(Fortran mode)}
|
|
@findex fortran-join-line
|
|
@kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
|
|
which joins a continuation line back to the previous line, roughly as
|
|
the inverse of @code{fortran-split-line}. The point must be on a
|
|
continuation line when this command is invoked.
|
|
|
|
@kindex M-q @r{(Fortran mode)}
|
|
Fortran mode defines the function for filling paragraphs such that
|
|
@kbd{M-q} fills the comment block or statement around point. Filling a
|
|
statement removes excess statement continuations.
|
|
|
|
@node ForIndent Cont
|
|
@subsubsection Continuation Lines
|
|
@cindex Fortran continuation lines
|
|
|
|
@vindex fortran-continuation-string
|
|
Most modern Fortran compilers allow two ways of writing continuation
|
|
lines. If the first non-space character on a line is in column 5, then
|
|
that line is a continuation of the previous line. We call this
|
|
@dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The
|
|
variable @code{fortran-continuation-string} specifies what character to
|
|
put on column 5. A line that starts with a tab character followed by
|
|
any digit except @samp{0} is also a continuation line. We call this
|
|
style of continuation @dfn{tab format}.
|
|
|
|
@vindex indent-tabs-mode @r{(Fortran mode)}
|
|
Fortran mode can make either style of continuation line, but you
|
|
must specify which one you prefer. The value of the variable
|
|
@code{indent-tabs-mode} controls the choice: @code{nil} for fixed
|
|
format, and non-@code{nil} for tab format. You can tell which style
|
|
is presently in effect by the presence or absence of the string
|
|
@samp{Tab} in the mode line.
|
|
|
|
If the text on a line starts with the conventional Fortran
|
|
continuation marker @samp{$}, 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 @key{TAB}, it converts the line
|
|
to the current continuation style. When you split a Fortran statement
|
|
with @kbd{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 format mode, the minimum column
|
|
number for the body of a statement is 6. Lines inside of Fortran
|
|
blocks that are indented to larger column numbers always use only the
|
|
space character for whitespace. In tab format mode, the minimum
|
|
column number for the statement body is 8, and the whitespace before
|
|
column 8 must always consist of one tab character.
|
|
|
|
@vindex fortran-tab-mode-default
|
|
@vindex fortran-analyze-depth
|
|
When you enter Fortran mode for an existing file, it tries to deduce the
|
|
proper continuation style automatically from the file contents. The first
|
|
line that begins with either a tab character or six spaces determines the
|
|
choice. The variable @code{fortran-analyze-depth} specifies how many lines
|
|
to consider (at the beginning of the file); if none of those lines
|
|
indicates a style, then the variable @code{fortran-tab-mode-default}
|
|
specifies the style. If it is @code{nil}, that specifies fixed format, and
|
|
non-@code{nil} specifies tab format.
|
|
|
|
@node ForIndent Num
|
|
@subsubsection Line Numbers
|
|
|
|
If a number is the first non-whitespace in the line, Fortran
|
|
indentation assumes it is a line number and moves it to columns 0
|
|
through 4. (Columns always count from 0 in GNU Emacs.)
|
|
|
|
@vindex fortran-line-number-indent
|
|
Line numbers of four digits or less are normally indented one space.
|
|
The variable @code{fortran-line-number-indent} controls this; it
|
|
specifies the maximum indentation a line number can have. Line numbers
|
|
are indented to right-justify them to end in column 4 unless that would
|
|
require more than this maximum indentation. The default value of the
|
|
variable is 1.
|
|
|
|
@vindex fortran-electric-line-number
|
|
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
|
|
@code{fortran-electric-line-number} to @code{nil}. Then inserting line
|
|
numbers is like inserting anything else.
|
|
|
|
@node ForIndent Conv
|
|
@subsubsection 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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Two nested @samp{do} loops never share a @samp{continue} statement.
|
|
|
|
@item
|
|
Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{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 @samp{else if} or @samp{end do}
|
|
are acceptable, but the second word should be on the same line as the
|
|
first and not on a continuation line.
|
|
@end itemize
|
|
|
|
@noindent
|
|
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.
|
|
|
|
@node ForIndent Vars
|
|
@subsubsection Variables for Fortran Indentation
|
|
|
|
@vindex fortran-do-indent
|
|
@vindex fortran-if-indent
|
|
@vindex fortran-structure-indent
|
|
@vindex fortran-continuation-indent
|
|
@vindex fortran-check-all-num@dots{}
|
|
@vindex fortran-minimum-statement-indent@dots{}
|
|
Several additional variables control how Fortran indentation works:
|
|
|
|
@table @code
|
|
@item fortran-do-indent
|
|
Extra indentation within each level of @samp{do} statement (default 3).
|
|
|
|
@item fortran-if-indent
|
|
Extra indentation within each level of @samp{if} statement (default 3).
|
|
This value is also used for extra indentation within each level of the
|
|
Fortran 90 @samp{where} statement.
|
|
|
|
@item fortran-structure-indent
|
|
Extra indentation within each level of @samp{structure}, @samp{union}, or
|
|
@samp{map} statements (default 3).
|
|
|
|
@item fortran-continuation-indent
|
|
Extra indentation for bodies of continuation lines (default 5).
|
|
|
|
@item fortran-check-all-num-for-matching-do
|
|
If this is @code{nil}, indentation assumes that each @samp{do} statement
|
|
ends on a @samp{continue} statement. Therefore, when computing
|
|
indentation for a statement other than @samp{continue}, it can save time
|
|
by not checking for a @samp{do} statement ending there. If this is
|
|
non-@code{nil}, indenting any numbered statement must check for a
|
|
@samp{do} that ends there. The default is @code{nil}.
|
|
|
|
@item fortran-blink-matching-if
|
|
If this is @code{t}, indenting an @samp{endif} statement moves the
|
|
cursor momentarily to the matching @samp{if} statement to show where it
|
|
is. The default is @code{nil}.
|
|
|
|
@item fortran-minimum-statement-indent-fixed
|
|
Minimum indentation for fortran statements when using fixed format
|
|
continuation line style. Statement bodies are never indented less than
|
|
this much. The default is 6.
|
|
|
|
@item fortran-minimum-statement-indent-tab
|
|
Minimum indentation for fortran statements for tab format continuation line
|
|
style. Statement bodies are never indented less than this much. The
|
|
default is 8.
|
|
@end table
|
|
|
|
@node Fortran Comments
|
|
@subsection Fortran Comments
|
|
|
|
The usual Emacs comment commands assume that a comment can follow a line
|
|
of code. In Fortran, the standard comment syntax requires an entire line
|
|
to be just a comment. Therefore, Fortran mode replaces the standard Emacs
|
|
comment commands and defines some new variables.
|
|
|
|
Fortran mode can also handle the Fortran90 comment syntax where comments
|
|
start with @samp{!} and can follow other text. Because only some Fortran77
|
|
compilers accept this syntax, Fortran mode will not insert such comments
|
|
unless you have said in advance to do so. To do this, set the variable
|
|
@code{comment-start} to @samp{"!"} (@pxref{Variables}).
|
|
|
|
@table @kbd
|
|
@item M-;
|
|
Align comment or insert new comment (@code{fortran-comment-indent}).
|
|
|
|
@item C-x ;
|
|
Applies to nonstandard @samp{!} comments only.
|
|
|
|
@item C-c ;
|
|
Turn all lines of the region into comments, or (with argument) turn them back
|
|
into real code (@code{fortran-comment-region}).
|
|
@end table
|
|
|
|
@kbd{M-;} in Fortran mode is redefined as the command
|
|
@code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
|
|
recognizes any kind of existing comment and aligns its text appropriately;
|
|
if there is no existing comment, a comment is inserted and aligned. But
|
|
inserting and aligning comments are not the same in Fortran mode as in
|
|
other modes.
|
|
|
|
When a new comment must be inserted, if the current line is blank, a
|
|
full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
|
|
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 @samp{!} 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
|
|
@code{fortran-comment-indent-style} to one of these values:
|
|
|
|
@vindex fortran-comment-indent-style
|
|
@vindex fortran-comment-line-extra-indent
|
|
@table @code
|
|
@item fixed
|
|
Align the text at a fixed column, which is the sum of
|
|
@code{fortran-comment-line-extra-indent} and the minimum statement
|
|
indentation. This is the default.
|
|
|
|
The minimum statement indentation is
|
|
@code{fortran-minimum-statement-indent-fixed} for fixed format
|
|
continuation line style and @code{fortran-minimum-statement-indent-tab}
|
|
for tab format style.
|
|
|
|
@item relative
|
|
Align the text as if it were a line of code, but with an additional
|
|
@code{fortran-comment-line-extra-indent} columns of indentation.
|
|
|
|
@item nil
|
|
Don't move text in full-line comments automatically at all.
|
|
@end table
|
|
|
|
@vindex fortran-comment-indent-char
|
|
In addition, you can specify the character to be used to indent within
|
|
full-line comments by setting the variable
|
|
@code{fortran-comment-indent-char} to the single-character string you want
|
|
to use.
|
|
|
|
@vindex comment-line-start
|
|
@vindex comment-line-start-skip
|
|
Fortran mode introduces two variables @code{comment-line-start} and
|
|
@code{comment-line-start-skip}, which play for full-line comments the same
|
|
roles played by @code{comment-start} and @code{comment-start-skip} for
|
|
ordinary text-following comments. Normally these are set properly by
|
|
Fortran mode, so you do not need to change them.
|
|
|
|
The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
|
|
you use @samp{!} comments, this command can be used with them. Otherwise
|
|
it is useless in Fortran mode.
|
|
|
|
@kindex C-c ; @r{(Fortran mode)}
|
|
@findex fortran-comment-region
|
|
@vindex fortran-comment-region
|
|
The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
|
|
lines of the region into comments by inserting the string @samp{C$$$} at
|
|
the front of each one. With a numeric argument, it turns the region
|
|
back into live code by deleting @samp{C$$$} from the front of each line
|
|
in it. The string used for these comments can be controlled by setting
|
|
the variable @code{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.
|
|
|
|
@node Fortran Autofill
|
|
@subsection Fortran Auto Fill Mode
|
|
|
|
Fortran Auto Fill mode is a minor mode which automatically splits
|
|
Fortran statements as you insert them when they become too wide.
|
|
Splitting a statement involves making continuation lines using
|
|
@code{fortran-continuation-string} (@pxref{ForIndent Cont}). This
|
|
splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
|
|
also in the Fortran indentation commands.
|
|
|
|
@findex fortran-auto-fill-mode
|
|
@kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
|
|
was off, or off if it was on. This command works the same as @kbd{M-x
|
|
auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
|
|
positive numeric argument turns Fortran Auto Fill mode on, and a
|
|
negative argument turns it off. You can see when Fortran Auto Fill mode
|
|
is in effect by the presence of the word @samp{Fill} in the mode line,
|
|
inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
|
|
on or off for each buffer individually. @xref{Minor Modes}.
|
|
|
|
@vindex fortran-break-before-delimiters
|
|
Fortran Auto Fill mode breaks lines at spaces or delimiters when the
|
|
lines get longer than the desired width (the value of @code{fill-column}).
|
|
The delimiters that Fortran Auto Fill mode may break at are @samp{,},
|
|
@samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
|
|
The line break comes after the delimiter if the variable
|
|
@code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by
|
|
default), the break comes before the delimiter.
|
|
|
|
By default, Fortran Auto Fill mode is not enabled. If you want this
|
|
feature turned on permanently, add a hook function to
|
|
@code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
|
|
@xref{Hooks}.
|
|
|
|
@node Fortran Columns
|
|
@subsection Checking Columns in Fortran
|
|
|
|
@table @kbd
|
|
@item C-c C-r
|
|
Display a ``column ruler'' momentarily above the current line
|
|
(@code{fortran-column-ruler}).
|
|
@item C-c C-w
|
|
Split the current window horizontally temporarily so that it is 72
|
|
columns wide. This may help you avoid making lines longer than the
|
|
72-character limit that some Fortran compilers impose
|
|
(@code{fortran-window-create-momentarily}).
|
|
@end table
|
|
|
|
@kindex C-c C-r @r{(Fortran mode)}
|
|
@findex fortran-column-ruler
|
|
@vindex fortran-column-ruler
|
|
The command @kbd{C-c C-r} (@code{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 @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
|
|
@code{nil}, then the value of the variable
|
|
@code{fortran-column-ruler-fixed} is used as the column ruler.
|
|
Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
|
|
By changing these variables, you can change the column ruler display.
|
|
|
|
@kindex C-u C-c C-w @r{(Fortran mode)}
|
|
@findex fortran-window-create
|
|
For even more help, use @kbd{M-x fortran-window-create}), a
|
|
command which splits the current window horizontally, making a window 72
|
|
columns wide. By editing in this window you can immediately see when you
|
|
make a line too wide to be correct Fortran.
|
|
|
|
@kindex C-c C-w @r{(Fortran mode)}
|
|
@findex fortran-window-create-momentarily
|
|
Also, @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) can be
|
|
used temporarily to split the current window horizontally, making a
|
|
window 72 columns wide to check column widths rather than to edit in
|
|
this mode. The normal width is restored when you type a space.
|
|
|
|
@node Fortran Abbrev
|
|
@subsection 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. @xref{Abbrevs}.
|
|
|
|
The built-in abbrevs are unusual in one way: they all start with a
|
|
semicolon. You cannot normally use semicolon in an abbrev, but Fortran
|
|
mode makes this possible by changing the syntax of semicolon to ``word
|
|
constituent.''
|
|
|
|
For example, one built-in Fortran abbrev is @samp{;c} for
|
|
@samp{continue}. If you insert @samp{;c} and then insert a punctuation
|
|
character such as a space or a newline, the @samp{;c} expands automatically
|
|
to @samp{continue}, provided Abbrev mode is enabled.@refill
|
|
|
|
Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
|
|
Fortran abbrevs and what they stand for.
|
|
|
|
@node Fortran Misc
|
|
@subsection Other Fortran Mode Commands
|
|
|
|
The command @kbd{fortran-strip-sqeuence-nos} can be used to remove text
|
|
past Fortran column 72, which is typically old `sequence numbers'.
|
|
|
|
@node Asm Mode
|
|
@section Asm Mode
|
|
|
|
@cindex Asm mode
|
|
@cindex Assembler mode
|
|
Asm mode is a major mode for editing files of assembler code. It
|
|
defines these commands:
|
|
|
|
@table @kbd
|
|
@item @key{TAB}
|
|
@code{tab-to-tab-stop}.
|
|
@item C-j
|
|
Insert a newline and then indent using @code{tab-to-tab-stop}.
|
|
@item :
|
|
Insert a colon and then remove the indentation from before the label
|
|
preceding colon. Then do @code{tab-to-tab-stop}.
|
|
@item ;
|
|
Insert or align a comment.
|
|
@end table
|
|
|
|
The variable @code{asm-comment-char} specifies which character
|
|
starts comments in assembler syntax.
|