1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,99,2000 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Programs, Building, Text, Top
5 @chapter Editing Programs
8 @cindex program editing
10 Emacs has many commands designed to understand the syntax of programming
11 languages such as Lisp and C. These commands can
15 Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
17 Move over or mark top-level expressions---@dfn{defuns}, in Lisp;
18 functions, in C (@pxref{Defuns}).
20 Show how parentheses balance (@pxref{Matching}).
22 Insert, kill or align comments (@pxref{Comments}).
24 Follow the usual indentation conventions of the language
25 (@pxref{Program Indent}).
28 The commands for words, sentences and paragraphs are very useful in
29 editing code even though their canonical application is for editing
30 human language text. Most symbols contain words (@pxref{Words});
31 sentences can be found in strings and comments (@pxref{Sentences}).
32 Paragraphs per se don't exist in code, but the paragraph commands are
33 useful anyway, because programming language major modes define
34 paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
35 Judicious use of blank lines to make the program clearer will also
36 provide useful chunks of text for the paragraph commands to work
39 @cindex selective display
42 @findex outline-minor-mode
44 The selective display feature is useful for looking at the overall
45 structure of a function (@pxref{Selective Display}). This feature
46 causes only the lines that are indented less than a specified amount to
47 appear on the screen. Programming modes often support Outline minor
48 mode (@pxref{Outline Mode}). The Foldout package provides
49 folding-editor features (@pxref{Foldout}).
51 The `automatic typing' features may be useful when writing programs.
52 @xref{,Autotyping,, autotype, Autotyping}.
55 * Program Modes:: Major modes for editing programs.
56 * Lists:: Expressions with balanced parentheses.
57 * List Commands:: The commands for working with list and sexps.
58 * Defuns:: Each program is made up of separate functions.
59 There are editing commands to operate on them.
60 * Program Indent:: Adjusting indentation to show the nesting.
61 * Matching:: Insertion of a close-delimiter flashes matching open.
62 * Comments:: Inserting, killing, and aligning comments.
63 * Balanced Editing:: Inserting two matching parentheses at once, etc.
64 * Symbol Completion:: Completion on symbol names of your program or language.
65 * Which Function:: Which Function mode shows which function you are in.
66 * Hideshow:: Displaying blocks selectively.
67 * Glasses:: Making identifiersLikeThis more readable.
68 * Documentation:: Getting documentation of functions you plan to call.
69 * Change Log:: Maintaining a change history for your program.
70 * Authors:: Maintaining an @file{AUTHORS} file.
71 * Tags:: Go direct to any function in your program in one
72 command. Tags remembers which file it is in.
73 * Imenu:: Making buffer indexes as menus.
74 * Emerge:: A convenient way of merging two versions of a program.
75 * C Modes:: Special commands of C, C++, Objective-C,
77 * Fortran:: Fortran mode and its special features.
78 * Asm Mode:: Asm mode and its special features.
82 @section Major Modes for Programming Languages
84 @cindex modes for programming languages
99 @cindex Shell-script mode
101 @cindex PostScript mode
102 Emacs also has major modes for the programming languages Lisp, Scheme
103 (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
104 Awk, C, C++, Delphi (Object Pascal), Fortran (free and fixed format),
106 Java, Metafont (@TeX{}'s companion for font creation), Modula2,
107 Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula,
108 VHDL, CORBA IDL, and Tcl.
109 There is also a major mode for makefiles, called Makefile
110 mode. An alternative mode for Perl is called CPerl mode. Modes
111 are available for scripts for the common Unix shells, VMS DCL and
112 MS-DOS/MS-Windows `BAT' files. In a similar fashion to programming
113 languages, modes are provided for editing various sorts of configuration
116 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
117 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
118 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
119 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
121 Ideally, a major mode should be implemented for each programming
122 language that you might want to edit with Emacs; but often the mode for
123 one language can serve for other syntactically similar languages. The
124 language modes that exist are those that someone decided to take the
127 There are several forms of Lisp mode, which differ in the way they
128 interface to Lisp execution. @xref{Executing Lisp}.
130 Each of the programming language major modes defines the @key{TAB} key
131 to run an indentation function that knows the indentation conventions of
132 that language and updates the current line's indentation accordingly.
133 For example, in C mode @key{TAB} is bound to @code{c-indent-line}.
134 @kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
135 thus, it too indents in a mode-specific fashion.
137 @kindex DEL @r{(programming modes)}
138 @findex backward-delete-char-untabify
139 In most programming languages, indentation is likely to vary from line to
140 line. So the major modes for those languages rebind @key{DEL} to treat a
141 tab as if it were the equivalent number of spaces (using the command
142 @code{backward-delete-char-untabify}). This makes it possible to rub out
143 indentation one column at a time without worrying whether it is made up of
144 spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point,
147 Programming language modes define paragraphs to be separated only by
148 blank lines, so that the paragraph commands remain useful. Auto Fill mode,
149 if enabled in a programming language major mode, indents the new lines
154 @vindex lisp-mode-hook
155 @vindex emacs-lisp-mode-hook
156 @vindex lisp-interaction-mode-hook
157 @vindex scheme-mode-hook
158 Turning on a major mode runs a normal hook called the @dfn{mode hook},
159 which is the value of a Lisp variable. Each major mode has a mode hook,
160 and the hook's name is always made from the mode command's name by
161 adding @samp{-hook}. For example, turning on C mode runs the hook
162 @code{c-mode-hook}, while turning on Lisp mode runs the hook
163 @code{lisp-mode-hook}. @xref{Hooks}.
166 @section Lists and Sexps
169 By convention, Emacs keys for dealing with balanced expressions are
170 usually Control-Meta characters. They tend to be analogous in
171 function to their Control and Meta equivalents. These commands are
172 usually thought of as pertaining to expressions in programming
173 languages, but can be useful with any language in which some sort of
174 parentheses exist (including human languages).
179 @cindex parentheses, moving across
180 @cindex matching parenthesis, moving to
181 These commands fall into two classes. Some deal only with @dfn{lists}
182 (parenthetical groupings). They see nothing except parentheses, brackets,
183 braces (whichever ones must balance in the language you are working with),
184 and escape characters that might be used to quote those.
186 The other commands deal with expressions or @dfn{sexps}. The word `sexp'
187 is derived from @dfn{s-expression}, the ancient term for an expression in
188 Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
189 refers to an expression in whatever language your program is written in.
190 Each programming language has its own major mode, which customizes the
191 syntax tables so that expressions in that language count as sexps.
193 Sexps typically include symbols, numbers, and string constants, as well
194 as anything contained in parentheses, brackets or braces.
196 In languages that use prefix and infix operators, such as C, it is not
197 possible for all expressions to be sexps. For example, C mode does not
198 recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression;
199 it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
200 @samp{+} as punctuation between them. This is a fundamental ambiguity:
201 both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
202 move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
203 single sexp in C mode.
205 Some languages have obscure forms of expression syntax that nobody
206 has bothered to make Emacs understand properly.
209 @section List And Sexp Commands
211 @c doublewidecommands
214 Move forward over a sexp (@code{forward-sexp}).
216 Move backward over a sexp (@code{backward-sexp}).
218 Kill sexp forward (@code{kill-sexp}).
220 Kill sexp backward (@code{backward-kill-sexp}).
222 Move up and backward in list structure (@code{backward-up-list}).
224 Move down and forward in list structure (@code{down-list}).
226 Move forward over a list (@code{forward-list}).
228 Move backward over a list (@code{backward-list}).
230 Transpose expressions (@code{transpose-sexps}).
232 Put mark after following expression (@code{mark-sexp}).
238 @findex backward-sexp
239 To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
240 the first significant character after point is an opening delimiter
241 (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
242 moves past the matching closing delimiter. If the character begins a
243 symbol, string, or number, @kbd{C-M-f} moves over that.
245 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
246 sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
247 directions reversed. If there are any prefix characters (single-quote,
248 backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
249 over them as well. The sexp commands move across comments as if they
250 were whitespace in most modes.
252 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
253 specified number of times; with a negative argument, it moves in the
259 @findex backward-kill-sexp
260 Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp})
261 or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills
262 the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}}
263 kills the characters that @kbd{C-M-b} would move over.
268 @findex backward-list
269 The @dfn{list commands} move over lists, as the sexp commands do, but skip
270 blithely over any number of other kinds of sexps (symbols, strings, etc.).
271 They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
272 (@code{backward-list}). The main reason they are useful is that they
273 usually ignore comments (since the comments usually do not contain any
278 @findex backward-up-list
280 @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
281 that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u}
282 (@code{backward-up-list}).
283 @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
284 positive argument serves as a repeat count; a negative argument reverses
285 direction of motion and also requests repetition, so it moves forward and
286 up one or more levels.@refill
288 To move @emph{down} in list structure, use @kbd{C-M-d}
289 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
290 delimiter, this is nearly the same as searching for a @samp{(}. An
291 argument specifies the number of levels of parentheses to go down.
293 @cindex transposition
295 @findex transpose-sexps
296 A somewhat random-sounding command which is nevertheless handy is
297 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp
298 across the next one. An argument serves as a repeat count, and a
299 negative argument drags backwards (thus canceling out the effect of
300 @kbd{C-M-t} with a positive argument). An argument of zero, rather than
301 doing nothing, transposes the sexps ending after point and the mark.
305 To set the region around the next sexp in the buffer, use @kbd{C-M-@@}
306 (@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f}
307 would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In
308 particular, a negative argument is useful for putting the mark at the
309 beginning of the previous sexp.
311 The list and sexp commands' understanding of syntax is completely
312 controlled by the syntax table. Any character can, for example, be
313 declared to be an opening delimiter and act like an open parenthesis.
320 In Emacs, a parenthetical grouping at the top level in the buffer is
321 called a @dfn{defun}. The name derives from the fact that most top-level
322 lists in a Lisp file are instances of the special form @code{defun}, but
323 any top-level parenthetical grouping counts as a defun in Emacs parlance
324 regardless of what its contents are, and regardless of the programming
325 language in use. For example, in C, the body of a function definition is a
328 @c doublewidecommands
331 Move to beginning of current or preceding defun
332 (@code{beginning-of-defun}).
334 Move to end of current or following defun (@code{end-of-defun}).
336 Put region around whole current or following defun (@code{mark-defun}).
342 @findex beginning-of-defun
345 The commands to move to the beginning and end of the current defun are
346 @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
348 @findex c-mark-function
349 If you wish to operate on the current defun, use @kbd{C-M-h}
350 (@code{mark-defun}) which puts point at the beginning and mark at the end
351 of the current or next defun. For example, this is the easiest way to get
352 ready to move the defun to a different place in the text. In C mode,
353 @kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the
354 same as @code{mark-defun}; the difference is that it backs up over the
355 argument declarations, function name and returned data type so that the
356 entire C function is inside the region. @xref{Marking Objects}.
358 @cindex open-parenthesis in leftmost column
359 @cindex ( in leftmost column
360 Emacs assumes that any open-parenthesis found in the leftmost column
361 is the start of a defun. Therefore, @strong{never put an
362 open-parenthesis at the left margin in a Lisp file unless it is the
363 start of a top-level list. Never put an open-brace or other opening
364 delimiter at the beginning of a line of C code unless it starts the body
365 of a function.} The most likely problem case is when you want an
366 opening delimiter at the start of a line inside a string. To avoid
367 trouble, put an escape character (@samp{\}, in C and Emacs Lisp,
368 @samp{/} in some other Lisp dialects) before the opening delimiter. It
369 will not affect the contents of the string.
371 In the remotest past, the original Emacs found defuns by moving upward a
372 level of parentheses until there were no more levels to go up. This always
373 required scanning all the way back to the beginning of the buffer, even for
374 a small function. To speed up the operation, Emacs was changed to assume
375 that any @samp{(} (or other character assigned the syntactic class of
376 opening-delimiter) at the left margin is the start of a defun. This
377 heuristic is nearly always right and avoids the costly scan; however,
378 it mandates the convention described above.
381 @section Indentation for Programs
382 @cindex indentation for programs
384 The best way to keep a program properly indented is to use Emacs to
385 reindent it as you change it. Emacs has commands to indent properly
386 either a single line, a specified number of lines, or all of the lines
387 inside a single parenthetical grouping.
390 * Basic Indent:: Indenting a single line.
391 * Multi-line Indent:: Commands to reindent many lines at once.
392 * Lisp Indent:: Specifying how each Lisp function should be indented.
393 * C Indent:: Extra features for indenting C and related modes.
394 * Custom C Indent:: Controlling indentation style for C and related modes.
397 Emacs also provides a Lisp pretty-printer in the library @code{pp}.
398 This program reformats a Lisp object with indentation chosen to look nice.
401 @subsection Basic Program Indentation Commands
406 Adjust indentation of current line.
408 Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
411 @kindex TAB @r{(programming modes)}
412 @findex c-indent-line
413 @findex lisp-indent-line
414 The basic indentation command is @key{TAB}, which gives the current line
415 the correct indentation as determined from the previous lines. The
416 function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
417 in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
418 understand different syntaxes for different languages, but they all do
419 about the same thing. @key{TAB} in any programming-language major mode
420 inserts or deletes whitespace at the beginning of the current line,
421 independent of where point is in the line. If point is inside the
422 whitespace at the beginning of the line, @key{TAB} leaves it at the end of
423 that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
424 the characters around it.
426 Use @kbd{C-q @key{TAB}} to insert a tab at point.
429 @findex newline-and-indent
430 When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}),
431 which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates
432 a blank line and then gives it the appropriate indentation.
434 @key{TAB} indents the second and following lines of the body of a
435 parenthetical grouping each under the preceding one; therefore, if you
436 alter one line's indentation to be nonstandard, the lines below will
437 tend to follow it. This behavior is convenient in cases where you have
438 overridden the standard result of @key{TAB} because you find it
439 unaesthetic for a particular line.
441 Remember that an open-parenthesis, open-brace or other opening delimiter
442 at the left margin is assumed by Emacs (including the indentation routines)
443 to be the start of a function. Therefore, you must never have an opening
444 delimiter in column zero that is not the beginning of a function, not even
445 inside a string. This restriction is vital for making the indentation
446 commands fast; you must simply accept it. @xref{Defuns}, for more
449 @node Multi-line Indent
450 @subsection Indenting Several Lines
452 When you wish to reindent several lines of code which have been altered
453 or moved to a different level in the list structure, you have several
458 Reindent all the lines within one list (@code{indent-sexp}).
460 Shift an entire list rigidly sideways so that its first line
461 is properly indented.
463 Reindent all lines in the region (@code{indent-region}).
468 You can reindent the contents of a single list by positioning point
469 before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
470 Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable
471 commands in other modes). The indentation of the line the sexp starts on
472 is not changed; therefore, only the relative indentation within the list,
473 and not its position, is changed. To correct the position as well, type a
474 @key{TAB} before the @kbd{C-M-q}.
477 If the relative indentation within a list is correct but the
478 indentation of its first line is not, go to that line and type @kbd{C-u
479 @key{TAB}}. @key{TAB} with a numeric argument reindents the current
480 line as usual, then reindents by the same amount all the lines in the
481 grouping starting on the current line. In other words, it reindents the
482 whole grouping rigidly as a unit. It is clever, though, and does not
483 alter lines that start inside strings, or C preprocessor lines when in C
486 Another way to specify the range to be reindented is with the region.
487 The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to
488 every line whose first character is between point and mark.
491 @subsection Customizing Lisp Indentation
492 @cindex customizing Lisp indentation
494 The indentation pattern for a Lisp expression can depend on the function
495 called by the expression. For each Lisp function, you can choose among
496 several predefined patterns of indentation, or define an arbitrary one with
499 The standard pattern of indentation is as follows: the second line of the
500 expression is indented under the first argument, if that is on the same
501 line as the beginning of the expression; otherwise, the second line is
502 indented underneath the function name. Each following line is indented
503 under the previous line whose nesting depth is the same.
505 @vindex lisp-indent-offset
506 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
507 the usual indentation pattern for the second line of an expression, so that
508 such lines are always indented @code{lisp-indent-offset} more columns than
511 @vindex lisp-body-indent
512 The standard pattern is overridden for certain functions. Functions
513 whose names start with @code{def} always indent the second line by
514 @code{lisp-body-indent} extra columns beyond the open-parenthesis
515 starting the expression.
517 The standard pattern can be overridden in various ways for individual
518 functions, according to the @code{lisp-indent-function} property of the
519 function name. There are four possibilities for this property:
523 This is the same as no property; the standard indentation pattern is used.
525 The pattern used for function names that start with @code{def} is used for
527 @item a number, @var{number}
528 The first @var{number} arguments of the function are
529 @dfn{distinguished} arguments; the rest are considered the @dfn{body}
530 of the expression. A line in the expression is indented according to
531 whether the first argument on it is distinguished or not. If the
532 argument is part of the body, the line is indented @code{lisp-body-indent}
533 more columns than the open-parenthesis starting the containing
534 expression. If the argument is distinguished and is either the first
535 or second argument, it is indented @emph{twice} that many extra columns.
536 If the argument is distinguished and not the first or second argument,
537 the standard pattern is followed for that line.
538 @item a symbol, @var{symbol}
539 @var{symbol} should be a function name; that function is called to
540 calculate the indentation of a line within this expression. The
541 function receives two arguments:
544 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
545 indentation and nesting computation) when it parses up to the
546 beginning of this line.
548 The position at which the line being indented begins.
551 It should return either a number, which is the number of columns of
552 indentation for that line, or a list whose car is such a number. The
553 difference between returning a number and returning a list is that a
554 number says that all following lines at the same nesting level should
555 be indented just like this one; a list says that following lines might
556 call for different indentations. This makes a difference when the
557 indentation is being computed by @kbd{C-M-q}; if the value is a
558 number, @kbd{C-M-q} need not recalculate indentation for the following
559 lines until the end of the list.
563 @subsection Commands for C Indentation
565 Here are the commands for indentation in C mode and related modes:
569 @kindex C-c C-q @r{(C mode)}
570 @findex c-indent-defun
571 Reindent the current top-level function definition or aggregate type
572 declaration (@code{c-indent-defun}).
575 @kindex C-M-q @r{(C mode)}
577 Reindent each line in the balanced expression that follows point
578 (@code{c-indent-exp}). A prefix argument inhibits error checking and
579 warning messages about invalid syntax.
582 @findex c-indent-command
583 Reindent the current line, and/or in some cases insert a tab character
584 (@code{c-indent-command}).
586 If @code{c-tab-always-indent} is @code{t}, this command always reindents
587 the current line and does nothing else. This is the default.
589 If that variable is @code{nil}, this command reindents the current line
590 only if point is at the left margin or in the line's indentation;
591 otherwise, it inserts a tab (or the equivalent number of spaces,
592 if @code{indent-tabs-mode} is @code{nil}).
594 Any other value (not @code{nil} or @code{t}) means always reindent the
595 line, and also insert a tab if within a comment, a string, or a
596 preprocessor directive.
599 Reindent the current line according to its syntax; also rigidly reindent
600 any other lines of the expression that starts on the current line.
601 @xref{Multi-line Indent}.
604 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
605 first selects the whole buffer as the region, then reindents that
608 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
609 to the front of the block and then reindents it all.
611 @node Custom C Indent
612 @subsection Customizing C Indentation
614 C mode and related modes use a simple yet flexible mechanism for
615 customizing indentation. The mechanism works in two steps: first it
616 classifies the line syntactically according to its contents and context;
617 second, it associates each kind of syntactic construct with an
618 indentation offset which you can customize.
621 * Syntactic Analysis::
622 * Indentation Calculation::
623 * Changing Indent Style::
624 * Syntactic Symbols::
625 * Variables for C Indent::
629 @node Syntactic Analysis
630 @subsubsection Step 1---Syntactic Analysis
631 @cindex syntactic analysis
633 In the first step, the C indentation mechanism looks at the line
634 before the one you are currently indenting and determines the syntactic
635 components of the construct on that line. It builds a list of these
636 syntactic components, each of which contains a @dfn{syntactic symbol}
637 and sometimes also a buffer position. Some syntactic symbols describe
638 grammatical elements, for example @code{statement} and
639 @code{substatement}; others describe locations amidst grammatical
640 elements, for example @code{class-open} and @code{knr-argdecl}.
642 Conceptually, a line of C code is always indented relative to the
643 indentation of some line higher up in the buffer. This is represented
644 by the buffer positions in the syntactic component list.
646 Here is an example. Suppose we have the following code in a C++ mode
647 buffer (the line numbers don't actually appear in the buffer):
650 1: void swap (int& a, int& b)
658 If you type @kbd{C-c C-s} (which runs the command
659 @code{c-show-syntactic-information}) on line 4, it shows the result of
660 the indentation mechanism for that line:
666 This indicates that the line is a statement and it is indented
667 relative to buffer position 32, which happens to be the @samp{i} in
668 @code{int} on line 3. If you move the cursor to line 3 and type
669 @kbd{C-c C-s}, it displays this:
672 ((defun-block-intro . 28))
675 This indicates that the @code{int} line is the first statement in a
676 block, and is indented relative to buffer position 28, which is the
677 brace just after the function header.
680 Here is another example:
683 1: int add (int val, int incr, int doit)
687 5: return (val + incr);
694 Typing @kbd{C-c C-s} on line 4 displays this:
697 ((substatement-open . 43))
700 This says that the brace @emph{opens} a substatement block. By the
701 way, a @dfn{substatement} indicates the line after an @code{if},
702 @code{else}, @code{while}, @code{do}, @code{switch}, @code{for},
703 @code{try}, @code{catch}, @code{finally}, or @code{synchronized}
706 @cindex syntactic component
707 @cindex syntactic symbol
708 @vindex c-syntactic-context
709 Within the C indentation commands, after a line has been analyzed
710 syntactically for indentation, the variable @code{c-syntactic-context}
711 contains a list that describes the results. Each element in this list
712 is a @dfn{syntactic component}: a cons cell containing a syntactic
713 symbol and (optionally) its corresponding buffer position. There may be
714 several elements in a component list; typically only one element has a
717 @node Indentation Calculation
718 @subsubsection Step 2---Indentation Calculation
719 @cindex Indentation Calculation
721 The C indentation mechanism calculates the indentation for the current
722 line using the list of syntactic components, @code{c-syntactic-context},
723 derived from syntactic analysis. Each component is a cons cell that
724 contains a syntactic symbol and may also contain a buffer position.
726 Each component contributes to the final total indentation of the line
727 in two ways. First, the syntactic symbol identifies an element of
728 @code{c-offsets-alist}, which is an association list mapping syntactic
729 symbols into indentation offsets. Each syntactic symbol's offset adds
730 to the total indentation. Second, if the component includes a buffer
731 position, the column number of that position adds to the indentation.
732 All these offsets and column numbers, added together, give the total
735 The following examples demonstrate the workings of the C indentation
739 1: void swap (int& a, int& b)
747 Suppose that point is on line 3 and you type @key{TAB} to reindent the
748 line. As explained above (@pxref{Syntactic Analysis}), the syntactic
749 component list for that line is:
752 ((defun-block-intro . 28))
755 In this case, the indentation calculation first looks up
756 @code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose
757 that it finds the integer 2; it adds this to the running total
758 (initialized to zero), yielding a updated total indentation of 2 spaces.
760 The next step is to find the column number of buffer position 28.
761 Since the brace at buffer position 28 is in column zero, this adds 0 to
762 the running total. Since this line has only one syntactic component,
763 the total indentation for the line is 2 spaces.
766 1: int add (int val, int incr, int doit)
770 5: return(val + incr);
776 If you type @key{TAB} on line 4, the same process is performed, but
777 with different data. The syntactic component list for this line is:
780 ((substatement-open . 43))
783 Here, the indentation calculation's first job is to look up the
784 symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume
785 that the offset for this symbol is 2. At this point the running total
786 is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43,
787 which is the @samp{i} in @code{if} on line 3. This character is in
788 column 2 on that line. Adding this yields a total indentation of 4
791 @vindex c-strict-syntax-p
792 If a syntactic symbol in the analysis of a line does not appear in
793 @code{c-offsets-alist}, it is ignored; if in addition the variable
794 @code{c-strict-syntax-p} is non-@code{nil}, it is an error.
796 @node Changing Indent Style
797 @subsubsection Changing Indentation Style
799 There are two ways to customize the indentation style for the C-like
800 modes. First, you can select one of several predefined styles, each of
801 which specifies offsets for all the syntactic symbols. For more
802 flexibility, you can customize the handling of individual syntactic
803 symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic
807 @item M-x c-set-style @key{RET} @var{style} @key{RET}
808 Select predefined indentation style @var{style}. Type @kbd{?} when
809 entering @var{style} to see a list of supported styles; to find out what
810 a style looks like, select it and reindent some C code.
812 @item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET}
813 Set the indentation offset for syntactic symbol @var{symbol}
814 (@code{c-set-offset}). The second argument @var{offset} specifies the
815 new indentation offset.
818 The @code{c-offsets-alist} variable controls the amount of
819 indentation to give to each syntactic symbol. Its value is an
820 association list, and each element of the list has the form
821 @code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets
822 for various syntactic symbols, you can customize indentation in fine
823 detail. To change this alist, use @code{c-set-offset} (see below).
825 Each offset value in @code{c-offsets-alist} can be an integer, a
826 function or variable name, a list, or one of the following symbols: @code{+},
827 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative
828 multiples of the variable @code{c-basic-offset}. Thus, if you want to
829 change the levels of indentation to be 3 spaces instead of 2 spaces, set
830 @code{c-basic-offset} to 3.
832 Using a function as the offset value provides the ultimate flexibility
833 in customizing indentation. The function is called with a single
834 argument containing the @code{cons} of the syntactic symbol and
835 the buffer position, if any. The function should return an integer
838 If the offset value is a list, its elements are processed according
839 to the rules above until a non-@code{nil} value is found. That value is
840 then added to the total indentation in the normal manner. The primary
841 use for this is to combine the results of several functions.
843 @kindex C-c C-o @r{(C mode)}
845 The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to
846 set offsets, both interactively or in your @file{~/.emacs} file. First
847 specify the syntactic symbol, then the offset you want. @xref{Syntactic
848 Symbols}, for a list of valid syntactic symbols and their meanings.
850 @node Syntactic Symbols
851 @subsubsection Syntactic Symbols
853 Here is a table of valid syntactic symbols for indentation in C and
854 related modes, with their syntactic meanings. Normally, most of these
855 symbols are assigned offsets in @code{c-offsets-alist}.
859 Inside a multi-line string.
862 Inside a multi-line C style block comment.
865 On a brace that opens a function definition.
868 On a brace that closes a function definition.
870 @item defun-block-intro
871 In the first line in a top-level defun.
874 On a brace that opens a class definition.
877 On a brace that closes a class definition.
880 On a brace that opens an in-class inline method.
883 On a brace that closes an in-class inline method.
885 @item extern-lang-open
886 On a brace that opens an external language block.
888 @item extern-lang-close
889 On a brace that closes an external language block.
892 The region between a function definition's argument list and the defun
893 opening brace (excluding K&R function definitions). In C, you cannot
894 put anything but whitespace and comments between them; in C++ and Java,
895 @code{throws} declarations and other things can appear in this context.
897 @item knr-argdecl-intro
898 On the first line of a K&R C argument declaration.
901 In one of the subsequent lines in a K&R C argument declaration.
904 On the first line in a topmost construct definition.
906 @item topmost-intro-cont
907 On the topmost definition continuation lines.
909 @item member-init-intro
910 On the first line in a member initialization list.
912 @item member-init-cont
913 On one of the subsequent member initialization list lines.
916 On the first line of a multiple inheritance list.
919 On one of the subsequent multiple inheritance lines.
922 On a statement block open brace.
925 On a statement block close brace.
927 @item brace-list-open
928 On the opening brace of an @code{enum} or @code{static} array list.
930 @item brace-list-close
931 On the closing brace of an @code{enum} or @code{static} array list.
933 @item brace-list-intro
934 On the first line in an @code{enum} or @code{static} array list.
936 @item brace-list-entry
937 On one of the subsequent lines in an @code{enum} or @code{static} array
940 @item brace-entry-open
941 On one of the subsequent lines in an @code{enum} or @code{static} array
942 list, when the line begins with an open brace.
945 On an ordinary statement.
948 On a continuation line of a statement.
950 @item statement-block-intro
951 On the first line in a new statement block.
953 @item statement-case-intro
954 On the first line in a @code{case} ``block.''
956 @item statement-case-open
957 On the first line in a @code{case} block starting with brace.
959 @item inexpr-statement
960 On a statement block inside an expression. This is used for a GNU
961 extension to the C language, and for Pike special functions that take a
962 statement block as an argument.
965 On a class definition inside an expression. This is used for anonymous
966 classes and anonymous array initializers in Java.
969 On the first line after an @code{if}, @code{while}, @code{for},
970 @code{do}, or @code{else}.
972 @item substatement-open
973 On the brace that opens a substatement block.
976 On a @code{case} or @code{default} label.
979 On a C++ @code{private}, @code{protected}, or @code{public} access label.
982 On any ordinary label.
984 @item do-while-closure
985 On the @code{while} that ends a @code{do}-@code{while} construct.
988 On the @code{else} of an @code{if}-@code{else} construct.
991 On the @code{catch} and @code{finally} lines in
992 @code{try}@dots{}@code{catch} constructs in C++ and Java.
995 On a line containing only a comment introduction.
998 On the first line in an argument list.
1001 On one of the subsequent argument list lines when no arguments follow on
1002 the same line as the arglist opening parenthesis.
1004 @item arglist-cont-nonempty
1005 On one of the subsequent argument list lines when at least one argument
1006 follows on the same line as the arglist opening parenthesis.
1009 On the closing parenthesis of an argument list.
1012 On one of the lines continuing a stream operator construct.
1015 On a construct that is nested inside a class definition. The
1016 indentation is relative to the open brace of the class definition.
1019 On a construct that is nested inside an external language block.
1021 @item inexpr-statement
1022 On the first line of statement block inside an expression. This is used
1023 for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}.
1024 It is also used for the special functions that takes a statement block
1025 as an argument in Pike.
1028 On the first line of a class definition inside an expression. This is
1029 used for anonymous classes and anonymous array initializers in Java.
1032 On the start of a cpp macro.
1035 On a C++ @code{friend} declaration.
1037 @item objc-method-intro
1038 On the first line of an Objective-C method definition.
1040 @item objc-method-args-cont
1041 On one of the lines continuing an Objective-C method definition.
1043 @item objc-method-call-cont
1044 On one of the lines continuing an Objective-C method call.
1047 Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only
1050 @item lambda-intro-cont
1051 On a line continuing the header of a lambda function, between the
1052 @code{lambda} keyword and the function body. Only used in Pike.
1055 @node Variables for C Indent
1056 @subsubsection Variables for C Indentation
1058 This section describes additional variables which control the
1059 indentation behavior of C mode and related mode.
1062 @item c-offsets-alist
1063 @vindex c-offsets-alist
1064 Association list of syntactic symbols and their indentation offsets.
1065 You should not set this directly, only with @code{c-set-offset}.
1066 @xref{Changing Indent Style}, for details.
1069 @vindex c-style-alist
1070 Variable for defining indentation styles; see below.
1072 @item c-basic-offset
1073 @vindex c-basic-offset
1074 Amount of basic offset used by @code{+} and @code{-} symbols in
1075 @code{c-offsets-alist}.@refill
1077 @item c-special-indent-hook
1078 @vindex c-special-indent-hook
1079 Hook for user-defined special indentation adjustments. This hook is
1080 called after a line is indented by C mode and related modes.
1083 The variable @code{c-style-alist} specifies the predefined indentation
1084 styles. Each element has form @code{(@var{name}
1085 @var{variable-setting}@dots{})}, where @var{name} is the name of the
1086 style. Each @var{variable-setting} has the form @code{(@var{variable}
1087 . @var{value})}; @var{variable} is one of the customization variables
1088 used by C mode, and @var{value} is the value for that variable when
1089 using the selected style.
1091 When @var{variable} is @code{c-offsets-alist}, that is a special case:
1092 @var{value} is appended to the front of the value of @code{c-offsets-alist}
1093 instead of replacing that value outright. Therefore, it is not necessary
1094 for @var{value} to specify each and every syntactic symbol---only those
1095 for which the style differs from the default.
1097 The indentation of lines containing only comments is also affected by
1098 the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}).
1100 @node C Indent Styles
1101 @subsubsection C Indentation Styles
1102 @cindex c indentation styles
1104 A @dfn{C style} is a collection of indentation style customizations.
1105 Emacs comes with several predefined indentation styles for C and related
1106 modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup},
1107 @code{linux}, @code{python}, @code{java}, @code{whitesmith},
1108 @code{ellemtel}, @code{cc-mode}, and @code{user}.
1111 @vindex c-default-style
1112 To choose the style you want, use the command @kbd{M-x c-set-style}.
1113 Specify a style name as an argument (case is not significant in C style
1114 names). The chosen style only affects newly visited buffers, not those
1115 you are already editing. You can also set the variable
1116 @code{c-default-style} to specify the style for various major modes.
1117 Its value should be an alist, in which each element specifies one major
1118 mode and which indentation style to use for it. For example,
1121 (setq c-default-style
1122 '((java-mode . "java") (other . "gnu")))
1126 specifies an explicit choice for Java mode, and the default @samp{gnu}
1127 style for the other C-like modes.
1129 The style @code{gnu} defines the formatting recommend by the GNU
1130 Project; it is the default, so as to encourage the indentation we
1131 recommend. If you make changes in variables such as
1132 @code{c-basic-offset} and @code{c-offsets-alist} in your @file{~/.emacs}
1133 file, they will however take precedence.
1136 To define a new C indentation style, call the function
1140 (c-add-style @var{name} @var{values} @var{use-now})
1144 Here @var{name} is the name of the new style (a string), and
1145 @var{values} is an alist whose elements have the form
1146 @code{(@var{variable} . @var{value})}. The variables you specify should
1147 be among those documented in @ref{Variables for C Indent}.
1149 If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new
1150 style after defining it.
1153 @section Automatic Display Of Matching Parentheses
1154 @cindex matching parentheses
1155 @cindex parentheses, displaying matches
1157 The Emacs parenthesis-matching feature is designed to show
1158 automatically how parentheses match in the text. Whenever you type a
1159 self-inserting character that is a closing delimiter, the cursor moves
1160 momentarily to the location of the matching opening delimiter, provided
1161 that is on the screen. If it is not on the screen, some text near it is
1162 displayed in the echo area. Either way, you can tell what grouping is
1165 In Lisp, automatic matching applies only to parentheses. In C, it
1166 applies to braces and brackets too. Emacs knows which characters to regard
1167 as matching delimiters based on the syntax table, which is set by the major
1168 mode. @xref{Syntax}.
1170 If the opening delimiter and closing delimiter are mismatched---such as
1171 in @samp{[x)}---a warning message is displayed in the echo area. The
1172 correct matches are specified in the syntax table.
1174 @vindex blink-matching-paren
1175 @vindex blink-matching-paren-distance
1176 @vindex blink-matching-delay
1177 Three variables control parenthesis match display.
1178 @code{blink-matching-paren} turns the feature on or off; @code{nil}
1179 turns it off, but the default is @code{t} to turn match display on.
1180 @code{blink-matching-delay} says how many seconds to wait; the default
1181 is 1, but on some systems it is useful to specify a fraction of a
1182 second. @code{blink-matching-paren-distance} specifies how many
1183 characters back to search to find the matching opening delimiter. If
1184 the match is not found in that far, scanning stops, and nothing is
1185 displayed. This is to prevent scanning for the matching delimiter from
1186 wasting lots of time when there is no match. The default is 12,000.
1188 @cindex Show Paren mode
1189 @findex show-paren-mode
1190 When using X Windows, you can request a more powerful alternative kind
1191 of automatic parenthesis matching by enabling Show Paren mode. This
1192 mode turns off the usual kind of matching parenthesis display and
1193 instead uses highlighting to show what matches. Whenever point is after
1194 a close parenthesis, the close parenthesis and its matching open
1195 parenthesis are both highlighted; otherwise, if point is before an open
1196 parenthesis, the matching close parenthesis is highlighted. (There is
1197 no need to highlight the open parenthesis after point because the cursor
1198 appears on top of that character.) Use the command @kbd{M-x
1199 show-paren-mode} to enable or disable this mode.
1202 @section Manipulating Comments
1205 Because comments are such an important part of programming, Emacs
1206 provides special commands for editing and inserting comments.
1209 * Comment Commands::
1210 * Multi-Line Comments::
1211 * Options for Comments::
1214 @node Comment Commands
1215 @subsection Comment Commands
1218 @cindex indentation for comments
1219 @findex indent-for-comment
1220 @findex comment-dwim
1222 The comment commands insert, kill and align comments.
1227 Call the comment command that is appropriate for the context
1228 (@code{comment-dwim}).
1229 @item M-x indent-for-comment
1230 Insert or align comment.
1232 Set comment column (@code{set-comment-column}).
1234 Kill comment on current line (@code{comment-kill}).
1236 Like @key{RET} followed by inserting and aligning a comment
1237 (@code{indent-new-comment-line}).
1238 @item M-x comment-region
1239 Add or remove comment delimiters on all the lines in the region.
1242 The command that creates a comment is @kbd{M-x indent-for-comment}.
1243 If there is no comment already on the line, a new comment is created,
1244 aligned at a specific column called the @dfn{comment column}. The comment
1245 is created by inserting the string Emacs thinks comments should start with
1246 (the value of @code{comment-start}; see below). Point is left after that
1247 string. If the text of the line extends past the comment column, then the
1248 indentation is done to a suitable boundary (usually, at least one space is
1249 inserted). If the major mode has specified a string to terminate comments,
1250 that is inserted after point, to keep the syntax valid.
1252 @kbd{M-x indent-for-comment} can also be used to align an existing
1253 comment. If a line already contains the string that starts comments,
1254 then @kbd{M-x indent-for-comment} just moves point after it and
1255 reindents it to the conventional place. Exception: comments starting in
1256 column 0 are not moved.
1258 @kbd{M-;} (@code{comment-dwim}) conveniently combines
1259 @code{indent-for-comment} with @code{comment-region} and
1260 @code{uncomment-region}, described below in @ref{Multi-Line Comments},
1261 as appropriate for the current context. If the region is active and the
1262 Transient Mark mode is on (@pxref{Transient Mark}), @kbd{M-;} invokes
1263 @code{comment-region}, unless the region consists only of comments, in
1264 which case it invokes @code{uncomment-region}. Otherwise, if the
1265 current line is empty, @kbd{M-;} inserts a comment and indents it. If
1266 the current line is not empty, @kbd{M-;} invokes @code{comment-kill} if
1267 a numeric argument was given, else it reindents the comment on the
1268 current line. (The @dfn{dwim} in @code{comment-dwim} is an acronym for
1269 ``Do What I Mean''.)
1271 Some major modes have special rules for indenting certain kinds of
1272 comments in certain contexts. For example, in Lisp code, comments which
1273 start with two semicolons are indented as if they were lines of code,
1274 instead of at the comment column. Comments which start with three
1275 semicolons are supposed to start at the left margin. Emacs understands
1276 these conventions by indenting a double-semicolon comment using @key{TAB},
1277 and by not changing the indentation of a triple-semicolon comment at all.
1280 ;; This function is just an example
1281 ;;; Here either two or three semicolons are appropriate.
1283 ;;; And now, the first part of the function:
1284 ;; The following line adds one.
1285 (1+ x)) ; This line adds one.
1288 In C code, a comment preceded on its line by nothing but whitespace
1289 is indented like a line of code.
1291 Even when an existing comment is properly aligned, @kbd{M-;} is still
1292 useful for moving directly to the start of the comment.
1295 @findex kill-comment
1296 @findex comment-kill
1297 @kbd{C-u - C-x ;} (@code{comment-kill}) kills the comment on the current line,
1298 if there is one. The indentation before the start of the comment is killed
1299 as well. If there does not appear to be a comment in the line, nothing is
1300 done. To reinsert the comment on another line, move to the end of that
1301 line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
1302 @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
1303 with a negative argument. That command is programmed so that when it
1304 receives a negative argument it calls @code{comment-kill}. However,
1305 @code{comment-kill} is a valid command which you could bind directly to a
1306 key if you wanted to. (For compatibility with previous versions,
1307 @code{kill-comment} is provided as an alias to @code{comment-kill}.)
1309 @node Multi-Line Comments
1310 @subsection Multiple Lines of Comments
1313 @cindex blank lines in programs
1314 @findex indent-new-comment-line
1315 If you are typing a comment and wish to continue it on another line,
1316 you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}).
1317 This terminates the comment you are typing, creates a new blank line
1318 afterward, and begins a new comment indented under the old one. When
1319 Auto Fill mode is on, going past the fill column while typing a comment
1320 causes the comment to be continued in just this fashion. If point is
1321 not at the end of the line when @kbd{C-M-j} is typed, the text on
1322 the rest of the line becomes part of the new comment line.
1324 @findex comment-region
1325 To turn existing lines into comment lines, use the @kbd{M-x
1326 comment-region} command. It adds comment delimiters to the lines that start
1327 in the region, thus commenting them out. With a negative argument, it
1328 does the opposite---it deletes comment delimiters from the lines in the
1331 With a positive argument, @code{comment-region} duplicates the last
1332 character of the comment start sequence it adds; the argument specifies
1333 how many copies of the character to insert. Thus, in Lisp mode,
1334 @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
1335 the comment delimiter is a way of calling attention to the comment. It
1336 can also affect how the comment is indented. In Lisp, for proper
1337 indentation, you should use an argument of two, if between defuns, and
1338 three, if within a defun.
1340 @vindex comment-padding
1341 The variable @code{comment-padding} specifies how many spaces
1342 @code{comment-region} should insert on each line between the
1343 comment delimiter and the line's original text. The default is 1.
1345 @node Options for Comments
1346 @subsection Options Controlling Comments
1348 @vindex comment-column
1350 @findex set-comment-column
1351 The comment column is stored in the variable @code{comment-column}. You
1352 can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
1353 (@code{set-comment-column}) sets the comment column to the column point is
1354 at. @kbd{C-u C-x ;} sets the comment column to match the last comment
1355 before point in the buffer, and then does a @kbd{M-;} to align the
1356 current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
1357 runs the function @code{comment-kill} as described above.
1359 The variable @code{comment-column} is per-buffer: setting the variable
1360 in the normal fashion affects only the current buffer, but there is a
1361 default value which you can change with @code{setq-default}.
1362 @xref{Locals}. Many major modes initialize this variable for the
1365 @vindex comment-start-skip
1366 The comment commands recognize comments based on the regular
1367 expression that is the value of the variable @code{comment-start-skip}.
1368 Make sure this regexp does not match the null string. It may match more
1369 than the comment starting delimiter in the strictest sense of the word;
1370 for example, in C mode the value of the variable is @code{@t{"/\\*+
1371 *"}}, which matches extra stars and spaces after the @samp{/*} itself.
1372 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
1373 the string, which is needed to deny the first star its special meaning
1374 in regexp syntax. @xref{Regexps}.)
1376 @vindex comment-start
1378 When a comment command makes a new comment, it inserts the value of
1379 @code{comment-start} to begin it. The value of @code{comment-end} is
1380 inserted after point, so that it will follow the text that you will insert
1381 into the comment. In C mode, @code{comment-start} has the value
1382 @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
1384 @vindex comment-multi-line
1385 The variable @code{comment-multi-line} controls how @kbd{C-M-j}
1386 (@code{indent-new-comment-line}) behaves when used inside a comment. If
1387 @code{comment-multi-line} is @code{nil}, as it normally is, then the
1388 comment on the starting line is terminated and a new comment is started
1389 on the new following line. If @code{comment-multi-line} is not
1390 @code{nil}, then the new following line is set up as part of the same
1391 comment that was found on the starting line. This is done by not
1392 inserting a terminator on the old line, and not inserting a starter on
1393 the new line. In languages where multi-line comments work, the choice
1394 of value for this variable is a matter of taste.
1396 @vindex comment-indent-function
1397 The variable @code{comment-indent-function} should contain a function
1398 that will be called to compute the indentation for a newly inserted
1399 comment or for aligning an existing comment. It is set differently by
1400 various major modes. The function is called with no arguments, but with
1401 point at the beginning of the comment, or at the end of a line if a new
1402 comment is to be inserted. It should return the column in which the
1403 comment ought to start. For example, in Lisp mode, the indent hook
1404 function bases its decision on how many semicolons begin an existing
1405 comment, and on the code in the preceding lines.
1407 @node Balanced Editing
1408 @section Editing Without Unbalanced Parentheses
1412 Put parentheses around next sexp(s) (@code{insert-parentheses}).
1414 Move past next close parenthesis and reindent
1415 (@code{move-past-close-and-reindent}).
1420 @findex insert-parentheses
1421 @findex move-past-close-and-reindent
1422 The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
1423 (@code{move-past-close-and-reindent}) are designed to facilitate a style
1424 of editing which keeps parentheses balanced at all times. @kbd{M-(}
1425 inserts a pair of parentheses, either together as in @samp{()}, or, if
1426 given an argument, around the next several sexps. It leaves point after
1427 the open parenthesis. The command @kbd{M-)} moves past the close
1428 parenthesis, deleting any indentation preceding it, and indenting with
1431 For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
1432 F O O}, which has the same effect except for leaving the cursor before
1433 the close parenthesis.
1435 @vindex parens-require-spaces
1436 @kbd{M-(} may insert a space before the open parenthesis, depending on
1437 the syntax class of the preceding character. Set
1438 @code{parens-require-spaces} to @code{nil} value if you wish to inhibit
1441 @findex check-parens
1442 You can use @kbd{M-x check-parens} to find any unbalanced parentheses in
1445 @node Symbol Completion
1446 @section Completion for Symbol Names
1447 @cindex completion (symbol names)
1449 Usually completion happens in the minibuffer. But one kind of completion
1450 is available in all buffers: completion for symbol names.
1453 The character @kbd{M-@key{TAB}} runs a command to complete the partial
1454 symbol before point against the set of meaningful symbol names. Any
1455 additional characters determined by the partial name are inserted at
1458 If the partial name in the buffer has more than one possible completion
1459 and they have no additional characters in common, a list of all possible
1460 completions is displayed in another window.
1462 @cindex completion using tags
1463 @cindex tags completion
1464 @cindex Info index completion
1465 @findex complete-symbol
1466 In most programming language major modes, @kbd{M-@key{TAB}} runs the
1467 command @code{complete-symbol}, which provides two kinds of completion.
1468 Normally it does completion based on a tags table (@pxref{Tags}); with a
1469 numeric argument (regardless of the value), it does completion based on
1470 the names listed in the Info file indexes for your language. Thus, to
1471 complete the name of a symbol defined in your own program, use
1472 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard
1473 library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
1474 completion works only if there is an Info file for the standard library
1475 functions of your language, and only if it is installed at your site.
1477 @cindex Lisp symbol completion
1478 @cindex completion in Lisp
1479 @findex lisp-complete-symbol
1480 In Emacs-Lisp mode, the name space for completion normally consists of
1481 nontrivial symbols present in Emacs---those that have function
1482 definitions, values or properties. However, if there is an
1483 open-parenthesis immediately before the beginning of the partial symbol,
1484 only symbols with function definitions are considered as completions.
1485 The command which implements this is @code{lisp-complete-symbol}.
1487 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1488 based on the spell-checker's dictionary. @xref{Spelling}.
1490 @node Which Function
1491 @section Which Function Mode
1493 Which Function mode is a minor mode that displays the current function
1494 name in the mode line, as you move around in a buffer.
1496 @findex which-function-mode
1497 @vindex which-func-modes
1498 To enable (or disable) Which Function mode, use the command @kbd{M-x
1499 which-function-mode}. This command is global; it applies to all
1500 buffers, both existing ones and those yet to be created. However, this
1501 only affects certain major modes, those listed in the value of
1502 @code{which-func-modes}. (If the value is @code{t}, then Which Function
1503 mode applies to all major modes that know how to support it---which are
1504 the major modes that support Imenu.)
1507 @section Hideshow minor mode
1509 @findex hs-minor-mode
1510 Hideshow minor mode provides selective display of blocks. Use @kbd{M-x
1511 hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the
1512 hook for major modes with which you want to use it and which support it.
1514 Blocks are defined dependent on the mode. In C mode or C++ mode, they
1515 are delimited by braces, while in Lisp-ish modes they are delimited by
1516 parens. Multi-line comments can also be hidden.
1519 @findex hs-hide-block
1521 @findex hs-show-block
1522 @findex hs-show-region
1523 @findex hs-hide-level
1524 @findex hs-minor-mode
1532 The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}),
1533 @kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x
1534 hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R}
1535 (@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level})
1536 with obvious functions and @kbd{S-mouse-2} toggles hiding of a block
1539 @vindex hs-hide-comments-when-hiding-all
1540 @vindex hs-show-hidden-short-form
1541 @vindex hs-isearch-open
1542 @vindex hs-special-modes-alist
1543 Hideshow is customized by the variables
1545 @item hs-hide-comments-when-hiding-all
1546 Specifies whether @kbd{hs-hide-all} should hide comments too.
1547 @item hs-show-hidden-short-form
1548 Specifies whether or not the last line in a form is omitted (saving
1550 @item hs-isearch-open
1551 Specifies what kind of hidden blocks to open in Isearch mode.
1552 @item hs-special-modes-alist
1553 Initializes Hideshow variables for different modes.
1557 @section Glasses minor mode
1558 @cindex Glasses mode
1559 @cindex identifiers, unreadable
1561 @findex glasses-mode
1563 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} readable
1564 by displaying underscores between all the pairs of lower and upper
1565 English letters or by emboldening the capitals. The text is not
1566 altered, only the display, so that you can use this mode on code written
1567 with such a convention for separating words in identifiers without
1568 modifying the code. It can be customized under the group
1569 @samp{glasses}. You can use it by adding @code{glasses-mode} to the
1570 mode hook of appropriate programming modes.
1574 @section Documentation Commands
1576 As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
1577 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
1578 be used to print documentation of functions and variables that you want to
1579 call. These commands use the minibuffer to read the name of a function or
1580 variable to document, and display the documentation in a window.
1582 For extra convenience, these commands provide default arguments based on
1583 the code in the neighborhood of point. @kbd{C-h f} sets the default to the
1584 function called in the innermost list containing point. @kbd{C-h v} uses
1585 the symbol name around or adjacent to point as its default.
1589 For Emacs Lisp code, you can also use Eldoc mode. This minor mode
1590 constantly displays in the echo area the argument list for the function
1591 being called at point. (In other words, it finds the function call that
1592 point is contained in, and displays the argument list of that function.)
1593 Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
1594 the command @kbd{M-x eldoc-mode} to enable or disable this feature.
1596 @findex info-lookup-symbol
1597 @findex info-lookup-file
1599 For C, Lisp, and other languages, you can use @kbd{C-h C-i}
1600 (@code{info-lookup-symbol}) to view the Info documentation for a symbol.
1601 You specify the symbol with the minibuffer; by default, it uses the
1602 symbol that appears in the buffer at point. The major mode determines
1603 where to look for documentation for the symbol---which Info files and
1604 which indices. You can also use @kbd{M-x info-lookup-file} to look for
1605 documentation for a file name. Currently the modes supported by
1606 Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
1607 Makefile, Octave, Perl, Scheme and Texinfo. The relevant Info files
1608 mostly must be obtained separately, typically from the appropriate GNU
1611 @findex manual-entry
1612 @cindex manual pages
1613 You can read the ``man page'' for an operating system command, library
1614 function, or system call, with the @kbd{M-x manual-entry} command. It
1615 runs the @code{man} program to format the man page, and runs it
1616 asynchronously if your system permits, so that you can keep on editing
1617 while the page is being formatted. (MS-DOS and MS-Windows 3 do not
1618 permit asynchronous subprocesses, so on these systems you cannot edit
1619 while Emacs waits for @code{man} to exit.) The result goes in a buffer
1620 named @samp{*Man @var{topic}*}. These buffers use a special major mode,
1621 Man mode, that facilitates scrolling and examining other manual pages.
1622 For details, type @kbd{C-h m} while in a man page buffer.
1624 @cindex sections of manual pages
1625 Man pages are subdivided into @dfn{sections}, and some man pages have
1626 identical names, but belong to different sections. To read a man page
1627 from a certain section, type @kbd{@var{topic}(@var{section})} or
1628 @kbd{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts for
1629 the topic. For example, to read the man page for the C library function
1630 @code{chmod} (as opposed to a command by the same name), type @kbd{M-x
1631 manual-entry @key{RET} chmod(2v) @key{RET}} (assuming @code{chmod} is in
1634 If you do not specify a section, the results depend on how the
1635 @code{man} command works on your system. Some of them display only the
1636 first man page they find, others display all the man pages, and you can
1637 page between them with the @kbd{M-n} and @kbd{M-p} keys. The mode line
1638 shows how many manual pages are available in the Man buffer.
1640 @vindex Man-fontify-manpage-flag
1641 For a long man page, setting the faces properly can take substantial
1642 time. By default, Emacs uses faces in man pages if Emacs can display
1643 different fonts or colors. You can turn off use of faces in man pages
1644 by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
1646 @findex Man-fontify-manpage
1647 If you insert the text of a man page into an Emacs buffer in some
1648 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
1649 perform the same conversions that @kbd{M-x manual-entry} does.
1652 @cindex manual pages, on MS-DOS/MS-Windows
1653 An alternative way of reading manual pages is the @kbd{M-x woman}
1654 command@footnote{The name of the command, @code{woman}, is an acronym
1655 for ``w/o (without) man'', since it doesn't use the @code{man}
1656 program.}. Unlike @kbd{M-x man}, it does not run any external programs
1657 to format and display the man pages, instead it does that entirely in
1658 Emacs Lisp. Thus, it is useful on systems such as MS-Windows, where the
1659 @code{man} program and the programs it runs are not readily available.
1660 When invoked, @kbd{M-x woman} prompts for a name of a manual page and
1661 provides completion based on the list of manual pages that are installed
1662 on your machine; the list of available manual pages is computed
1663 automatically the first time you invoke @code{woman}. The word at point
1664 in the current buffer is used to suggest the default name of the manual
1667 With a numeric argument, @kbd{M-x woman} recomputes the list of the
1668 manual pages used for completion. This is useful if you add or delete
1671 If you type a name of a manual page and @kbd{M-x woman} finds that
1672 several manual pages by the same name exist in different sections, it
1673 pops up a window with possible candidates asking you to choose one of
1676 @vindex woman-manpath
1677 By default, @kbd{M-x woman} looks up the manual pages in directories
1678 listed by the @code{MANPATH} environment variable. (If @code{MANPATH}
1679 is not set, @code{woman} uses a suitable default value, which can be
1680 customized.) More precisely, @code{woman} looks for subdirectories that
1681 match the shell wildcard @file{man*} in each one of these directories,
1682 and tries to find the manual pages in those subdirectories. When first
1683 invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list
1684 of directory names and stores that list in the @code{woman-manpath}
1685 variable. By changing the value of this variable, you can customize the
1686 list of directories where @code{woman} looks for manual pages.
1689 In addition, you can augment the list of directories searched by
1690 @code{woman} by setting the value of the @code{woman-path} variable.
1691 This variable should hold a list of specific directories which
1692 @code{woman} should search, in addition to those in
1693 @code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
1694 @code{woman-path} are searched for the manual pages, not for @file{man*}
1697 @findex woman-find-file
1698 Occasionally, you might need to display manual pages that are not in
1699 any of the directories listed by @code{woman-manpath} and
1700 @code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
1701 name of a manual page file, with completion, and then formats and
1702 displays that file like @kbd{M-x woman} does.
1704 @vindex woman-dired-keys
1705 First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W}
1706 key to run the @code{woman-find-file} command on the current line's
1707 file. You can disable this by setting the variable
1708 @code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the
1709 Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current
1710 line's archive member.
1712 For more information about setting up and using @kbd{M-x woman}, see
1713 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
1716 Eventually the GNU project hopes to replace most man pages with
1717 better-organized manuals that you can browse with Info. @xref{Misc
1718 Help}. Since this process is only partially completed, it is still
1719 useful to read manual pages.
1722 @section Change Logs
1726 @findex add-change-log-entry-other-window
1727 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1728 file for the file you are editing
1729 (@code{add-change-log-entry-other-window}). If that file is actually a
1730 backup file, it makes an entry appropriate for the file's parent. This
1731 is useful for making log entries by comparing a version with deleted
1734 A change log file contains a chronological record of when and why you
1735 have changed a program, consisting of a sequence of entries describing
1736 individual changes. Normally it is kept in a file called
1737 @file{ChangeLog} in the same directory as the file you are editing, or
1738 one of its parent directories. A single @file{ChangeLog} file can
1739 record changes for all the files in its directory and all its
1742 A change log entry starts with a header line that contains your name,
1743 your email address (taken from the variable @code{user-mail-address}),
1744 and the current date and time. Aside from these header lines, every
1745 line in the change log starts with a space or a tab. The bulk of the
1746 entry consists of @dfn{items}, each of which starts with a line starting
1747 with whitespace and a star. Here are two entries, both dated in May
1748 1993, each with two items:
1754 1993-05-25 Richard Stallman <rms@@gnu.org>
1756 * man.el: Rename symbols `man-*' to `Man-*'.
1757 (manual-entry): Make prompt string clearer.
1759 * simple.el (blink-matching-paren-distance):
1760 Change default to 12,000.
1762 1993-05-24 Richard Stallman <rms@@gnu.org>
1764 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1765 (vc-cancel-version): Doc fix.
1768 One entry can describe several changes; each change should have its
1769 own item. Normally there should be a blank line between items. When
1770 items are related (parts of the same change, in different places), group
1771 them by leaving no blank line between them. The second entry above
1772 contains two items grouped in this way.
1774 @vindex add-log-keep-changes-together
1775 @kbd{C-x 4 a} visits the change log file and creates a new entry
1776 unless the most recent entry is for today's date and your name. It also
1777 creates a new item for the current file. For many languages, it can
1778 even guess the name of the function or other object that was changed.
1779 When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4
1780 a} adds to any existing entry for the file rather than starting a new
1783 @cindex Change Log mode
1784 @findex change-log-mode
1785 The change log file is visited in Change Log mode. In this major
1786 mode, each bunch of grouped items counts as one paragraph, and each
1787 entry is considered a page. This facilitates editing the entries.
1788 @kbd{C-j} and auto-fill indent each new line like the previous line;
1789 this is convenient for entering the contents of an entry.
1791 @findex change-log-merge
1792 The command @kbd{M-x change-log-merge} can be used to merge other log
1793 files into a buffer in Change Log Mode, preserving the date ordering
1794 of entries with either the current or old-style date formats.
1796 @findex change-log-redate
1797 @cindex converting change log date style
1798 Versions of Emacs before 20.1 used a different format for the time of
1799 the change log entry:
1802 Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
1806 The @kbd{M-x change-log-redate} command converts all the old-style date
1807 entries in the change log file visited in the current buffer to the new
1808 format, so that all entries are kept in unified format. This is handy
1809 when the entries are contributed by many different people some of whom
1810 still use old versions of Emacs.
1812 Version control systems are another way to keep track of changes in your
1813 program and keep a change log. @xref{Log Buffer}.
1816 @section @file{AUTHORS} files
1817 @cindex @file{AUTHORS} file
1819 Programs which have many contributors usually include a file named
1820 @file{AUTHORS} in their distribution, which lists the individual
1821 contributions. Emacs has a special command for maintaining the
1822 @file{AUTHORS} file that is part of the Emacs distribution.
1825 The @kbd{M-x authors} command prompts for the name of the root of the
1826 Emacs source directory. It then scans @file{ChageLog} files and Lisp
1827 source files under that directory for information about authors of
1828 individual packages and people who made changes in source files, and
1829 puts the information it gleans into a buffer named @samp{*Authors*}.
1830 You can then edit the contents of that buffer and merge it with the
1831 exisiting @file{AUTHORS} file.
1834 @section Tags Tables
1837 A @dfn{tags table} is a description of how a multi-file program is
1838 broken up into files. It lists the names of the component files and the
1839 names and positions of the functions (or other named subunits) in each
1840 file. Grouping the related files makes it possible to search or replace
1841 through all the files with one command. Recording the function names
1842 and positions makes possible the @kbd{M-.} command which finds the
1843 definition of a function by looking up which of the files it is in.
1845 Tags tables are stored in files called @dfn{tags table files}. The
1846 conventional name for a tags table file is @file{TAGS}.
1848 Each entry in the tags table records the name of one tag, the name of the
1849 file that the tag is defined in (implicitly), and the position in that file
1850 of the tag's definition.
1852 Just what names from the described files are recorded in the tags table
1853 depends on the programming language of the described file. They
1854 normally include all functions and subroutines, and may also include
1855 global variables, data types, and anything else convenient. Each name
1856 recorded is called a @dfn{tag}.
1858 @cindex C++ class browser, tags
1860 @cindex class browser, C++
1862 The Ebrowse is a separate facility tailored for C++, with tags and a
1863 class browser. @xref{,,, ebrowse, Ebrowse User's Manual}.
1866 * Tag Syntax:: Tag syntax for various types of code and text files.
1867 * Create Tags Table:: Creating a tags table with @code{etags}.
1868 * Etags Regexps:: Create arbitrary tags using regular expressions.
1869 * Select Tags Table:: How to visit a tags table.
1870 * Find Tag:: Commands to find the definition of a specific tag.
1871 * Tags Search:: Using a tags table for searching and replacing.
1872 * List Tags:: Listing and finding tags defined in a file.
1876 @subsection Source File Tag Syntax
1878 Here is how tag syntax is defined for the most popular languages:
1882 In C code, any C function or typedef is a tag, and so are definitions of
1883 @code{struct}, @code{union} and @code{enum}. You can tag function
1884 declarations and external variables in addition to function definitions
1885 by giving the @samp{--declarations} option to @code{etags}.
1886 @code{#define} macro definitions and @code{enum} constants are also
1887 tags, unless you specify @samp{--no-defines} when making the tags table.
1888 Similarly, global variables are tags, unless you specify
1889 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
1890 can make the tags table file much smaller.
1893 In C++ code, in addition to all the tag constructs of C code, member
1894 functions are also recognized, and optionally member variables if you
1895 use the @samp{--members} option. Tags for variables and functions in
1896 classes are named @samp{@var{class}::@var{variable}} and
1897 @samp{@var{class}::@var{function}}. @code{operator} functions tags are
1898 named, for example @samp{operator+}.
1901 In Java code, tags include all the constructs recognized in C++, plus
1902 the @code{interface}, @code{extends} and @code{implements} constructs.
1903 Tags for variables and functions in classes are named
1904 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1907 In La@TeX{} text, the argument of any of the commands @code{\chapter},
1908 @code{\section}, @code{\subsection}, @code{\subsubsection},
1909 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
1910 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
1913 Other commands can make tags as well, if you specify them in the
1914 environment variable @env{TEXTAGS} before invoking @code{etags}. The
1915 value of this environment variable should be a colon-separated list of
1916 command names. For example,
1919 TEXTAGS="def:newcommand:newenvironment"
1924 specifies (using Bourne shell syntax) that the commands @samp{\def},
1925 @samp{\newcommand} and @samp{\newenvironment} also define tags.
1928 In Lisp code, any function defined with @code{defun}, any variable
1929 defined with @code{defvar} or @code{defconst}, and in general the first
1930 argument of any expression that starts with @samp{(def} in column zero, is
1934 In Scheme code, tags include anything defined with @code{def} or with a
1935 construct whose name starts with @samp{def}. They also include variables
1936 set with @code{set!} at top level in the file.
1939 Several other languages are also supported:
1944 In Ada code, functions, procedures, packages, tasks, and types are
1945 tags. Use the @samp{--packages-only} option to create tags for packages
1949 In assembler code, labels appearing at the beginning of a line,
1950 followed by a colon, are tags.
1953 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1954 it constructs. The portions of the file that contain C code are parsed
1958 In Cobol code, tags are paragraph names; that is, any word starting in
1959 column 8 and followed by a period.
1962 In Erlang code, the tags are the functions, records, and macros defined
1966 In Fortran code, functions, subroutines and blockdata are tags.
1969 In Objective C code, tags include Objective C definitions for classes,
1970 class categories, methods, and protocols.
1973 In Pascal code, the tags are the functions and procedures defined in
1977 In Perl code, the tags are the procedures defined by the @code{sub},
1978 @code{my} and @code{local} keywords. Use @samp{--globals} if you want
1979 to tag global variables.
1982 In PostScript code, the tags are the functions.
1985 In Prolog code, a tag name appears at the left margin.
1988 In Python code, @code{def} or @code{class} at the beginning of a line
1992 You can also generate tags based on regexp matching (@pxref{Etags
1993 Regexps}) to handle other formats and languages.
1995 @node Create Tags Table
1996 @subsection Creating Tags Tables
1997 @cindex @code{etags} program
1999 The @code{etags} program is used to create a tags table file. It knows
2000 the syntax of several languages, as described in
2002 the previous section.
2007 Here is how to run @code{etags}:
2010 etags @var{inputfiles}@dots{}
2014 The @code{etags} program reads the specified files, and writes a tags
2015 table named @file{TAGS} in the current working directory. You can
2016 intermix compressed and plain text source file names. @code{etags}
2017 knows about the most common compression formats, and does the right
2018 thing. So you can compress all your source files and have @code{etags}
2019 look for compressed versions of its file name arguments, if it does not
2020 find uncompressed versions. Under MS-DOS, @code{etags} also looks for
2021 file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
2022 command line and @samp{mycode.c} does not exist.
2024 @code{etags} recognizes the language used in an input file based on
2025 its file name and contents. You can specify the language with the
2026 @samp{--language=@var{name}} option, described below.
2028 If the tags table data become outdated due to changes in the files
2029 described in the table, the way to update the tags table is the same way it
2030 was made in the first place. It is not necessary to do this often.
2032 If the tags table fails to record a tag, or records it for the wrong
2033 file, then Emacs cannot possibly find its definition. However, if the
2034 position recorded in the tags table becomes a little bit wrong (due to
2035 some editing in the file that the tag definition is in), the only
2036 consequence is a slight delay in finding the tag. Even if the stored
2037 position is very wrong, Emacs will still find the tag, but it must
2038 search the entire file for it.
2040 So you should update a tags table when you define new tags that you want
2041 to have listed, or when you move tag definitions from one file to another,
2042 or when changes become substantial. Normally there is no need to update
2043 the tags table after each edit, or even every day.
2045 One tags table can effectively include another. Specify the included
2046 tags file name with the @samp{--include=@var{file}} option when creating
2047 the file that is to include it. The latter file then acts as if it
2048 contained all the files specified in the included file, as well as the
2049 files it directly contains.
2051 If you specify the source files with relative file names when you run
2052 @code{etags}, the tags file will contain file names relative to the
2053 directory where the tags file was initially written. This way, you can
2054 move an entire directory tree containing both the tags file and the
2055 source files, and the tags file will still refer correctly to the source
2058 If you specify absolute file names as arguments to @code{etags}, then
2059 the tags file will contain absolute file names. This way, the tags file
2060 will still refer to the same files even if you move it, as long as the
2061 source files remain in the same place. Absolute file names start with
2062 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
2064 When you want to make a tags table from a great number of files, you
2065 may have problems listing them on the command line, because some systems
2066 have a limit on its length. The simplest way to circumvent this limit
2067 is to tell @code{etags} to read the file names from its standard input,
2068 by typing a dash in place of the file names, like this:
2071 find . -name "*.[chCH]" -print | etags -
2074 Use the option @samp{--language=@var{name}} to specify the language
2075 explicitly. You can intermix these options with file names; each one
2076 applies to the file names that follow it. Specify
2077 @samp{--language=auto} to tell @code{etags} to resume guessing the
2078 language from the file names and file contents. Specify
2079 @samp{--language=none} to turn off language-specific processing
2080 entirely; then @code{etags} recognizes tags by regexp matching alone
2081 (@pxref{Etags Regexps}).
2083 @samp{etags --help} prints the list of the languages @code{etags}
2084 knows, and the file name rules for guessing the language. It also prints
2085 a list of all the available @code{etags} options, together with a short
2089 @subsection Etags Regexps
2091 The @samp{--regex} option provides a general way of recognizing tags
2092 based on regexp matching. You can freely intermix it with file names.
2093 Each @samp{--regex} option adds to the preceding ones, and applies only
2094 to the following files. The syntax is:
2097 --regex=/@var{tagregexp}[/@var{nameregexp}]/
2101 where @var{tagregexp} is used to match the lines to tag. It is always
2102 anchored, that is, it behaves as if preceded by @samp{^}. If you want
2103 to account for indentation, just match any initial number of blanks by
2104 beginning your regular expression with @samp{[ \t]*}. In the regular
2105 expressions, @samp{\} quotes the next character, and @samp{\t} stands
2106 for the tab character. Note that @code{etags} does not handle the other
2107 C escape sequences for special characters.
2109 @cindex interval operator (in regexps)
2110 The syntax of regular expressions in @code{etags} is the same as in
2111 Emacs, augmented with the @dfn{interval operator}, which works as in
2112 @code{grep} and @code{ed}. The syntax of an interval operator is
2113 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
2114 expression at least @var{m} times and up to @var{n} times.
2116 You should not match more characters with @var{tagregexp} than that
2117 needed to recognize what you want to tag. If the match is such that
2118 more characters than needed are unavoidably matched by @var{tagregexp}
2119 (as will usually be the case), you should add a @var{nameregexp}, to
2120 pick out just the tag. This will enable Emacs to find tags more
2121 accurately and to do completion on tag names more reliably. You can
2122 find some examples below.
2124 The option @samp{--ignore-case-regex} (or @samp{-c}) is like
2125 @samp{--regex}, except that the regular expression provided will be
2126 matched without regard to case, which is appropriate for various
2127 programming languages.
2129 The @samp{-R} option deletes all the regexps defined with
2130 @samp{--regex} options. It applies to the file names following it, as
2131 you can see from the following example:
2134 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
2135 bar.ber -R --lang=lisp los.er
2139 Here @code{etags} chooses the parsing language for @file{voo.doo} and
2140 @file{bar.ber} according to their contents. @code{etags} also uses
2141 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
2142 @var{reg1} and @var{reg2} to recognize additional tags in
2143 @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
2144 matching, to recognize tags in @file{los.er}.
2146 A regular expression can be bound to a given language, by prepending
2147 it with @samp{@{lang@}}. When you do this, @code{etags} will use the
2148 regular expression only for files of that language. @samp{etags --help}
2149 prints the list of languages recognised by @code{etags}. The following
2150 example tags the @code{DEFVAR} macros in the Emacs source files.
2151 @code{etags} applies this regular expression to C files only:
2154 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
2158 This feature is particularly useful when storing a list of regular
2159 expressions in a file. The following option syntax instructs
2160 @code{etags} to read two files of regular expressions. The regular
2161 expressions contained in the second file are matched without regard to
2165 --regex=@@first-file --ignore-case-regex=@@second-file
2169 A regex file contains one regular expressions per line. Empty lines,
2170 and lines beginning with space or tab are ignored. When the first
2171 character in a line is @samp{@@}, @code{etags} assumes that the rest of
2172 the line is the name of a file of regular expressions. This means that
2173 such files can be nested. All the other lines are taken to be regular
2174 expressions. For example, one can create a file called
2175 @samp{emacs.tags} with the following contents (the first line in the
2179 -- This is for GNU Emacs source files
2180 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2184 and then use it like this:
2187 etags --regex=@@emacs.tags *.[ch] */*.[ch]
2190 Here are some more examples. The regexps are quoted to protect them
2191 from shell interpretation.
2199 etags --language=none \
2200 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2201 --regex='/###key \(.*\)/\1/' \
2202 --regex='/[ \t]*global[ \t].*/' \
2207 Note that tags are not generated for scripts so that you have to add a
2208 line by yourself of the form `###key <script-name>' if you want to jump
2215 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2223 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2224 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2225 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2229 @node Select Tags Table
2230 @subsection Selecting a Tags Table
2232 @vindex tags-file-name
2233 @findex visit-tags-table
2234 Emacs has at any time one @dfn{selected} tags table, and all the commands
2235 for working with tags tables use the selected one. To select a tags table,
2236 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
2237 argument. The name @file{TAGS} in the default directory is used as the
2240 All this command does is store the file name in the variable
2241 @code{tags-file-name}. Emacs does not actually read in the tags table
2242 contents until you try to use them. Setting this variable yourself is just
2243 as good as using @code{visit-tags-table}. The variable's initial value is
2244 @code{nil}; that value tells all the commands for working with tags tables
2245 that they must ask for a tags table file name to use.
2247 Using @code{visit-tags-table} when a tags table is already loaded
2248 gives you a choice: you can add the new tags table to the current list
2249 of tags tables, or start a new list. The tags commands use all the tags
2250 tables in the current list. If you start a new list, the new tags table
2251 is used @emph{instead} of others. If you add the new table to the
2252 current list, it is used @emph{as well as} the others. When the tags
2253 commands scan the list of tags tables, they don't always start at the
2254 beginning of the list; they start with the first tags table (if any)
2255 that describes the current file, proceed from there to the end of the
2256 list, and then scan from the beginning of the list until they have
2257 covered all the tables in the list.
2259 @vindex tags-table-list
2260 You can specify a precise list of tags tables by setting the variable
2261 @code{tags-table-list} to a list of strings, like this:
2263 @c keep this on two lines for formatting in smallbook
2266 (setq tags-table-list
2267 '("~/emacs" "/usr/local/lib/emacs/src"))
2272 This tells the tags commands to look at the @file{TAGS} files in your
2273 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2274 directory. The order depends on which file you are in and which tags
2275 table mentions that file, as explained above.
2277 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2280 @subsection Finding a Tag
2282 The most important thing that a tags table enables you to do is to find
2283 the definition of a specific tag.
2286 @item M-.@: @var{tag} @key{RET}
2287 Find first definition of @var{tag} (@code{find-tag}).
2289 Find next alternate definition of last tag specified.
2291 Go back to previous tag found.
2292 @item C-M-. @var{pattern} @key{RET}
2293 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2295 Find the next tag whose name matches the last pattern used.
2296 @item C-x 4 .@: @var{tag} @key{RET}
2297 Find first definition of @var{tag}, but display it in another window
2298 (@code{find-tag-other-window}).
2299 @item C-x 5 .@: @var{tag} @key{RET}
2300 Find first definition of @var{tag}, and create a new frame to select the
2301 buffer (@code{find-tag-other-frame}).
2303 Pop back to where you previously invoked @kbd{M-.} and friends.
2308 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
2309 a specified tag. It searches through the tags table for that tag, as a
2310 string, and then uses the tags table info to determine the file that the
2311 definition is in and the approximate character position in the file of
2312 the definition. Then @code{find-tag} visits that file, moves point to
2313 the approximate character position, and searches ever-increasing
2314 distances away to find the tag definition.
2316 If an empty argument is given (just type @key{RET}), the sexp in the
2317 buffer before or around point is used as the @var{tag} argument.
2318 @xref{Lists}, for info on sexps.
2320 You don't need to give @kbd{M-.} the full name of the tag; a part
2321 will do. This is because @kbd{M-.} finds tags in the table which
2322 contain @var{tag} as a substring. However, it prefers an exact match
2323 to a substring match. To find other tags that match the same
2324 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
2325 M-.}; this does not read a tag name, but continues searching the tags
2326 table's text for another tag containing the same substring last used.
2327 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
2328 alternative to @kbd{C-u M-.}.
2331 @findex find-tag-other-window
2333 @findex find-tag-other-frame
2334 Like most commands that can switch buffers, @code{find-tag} has a
2335 variant that displays the new buffer in another window, and one that
2336 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
2337 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
2338 which invokes @code{find-tag-other-frame}.
2340 To move back to places you've found tags recently, use @kbd{C-u -
2341 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
2342 command can take you to another buffer. @kbd{C-x 4 .} with a negative
2343 argument finds the previous tag location in another window.
2346 @findex pop-tag-mark
2347 @vindex find-tag-marker-ring-length
2348 As well as going back to places you've found tags recently, you can go
2349 back to places @emph{from where} you found them. Use @kbd{M-*}, which
2350 invokes the command @code{pop-tag-mark}, for this. Typically you would
2351 find and study the definition of something with @kbd{M-.} and then
2352 return to where you were with @kbd{M-*}.
2354 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2355 a depth determined by the variable @code{find-tag-marker-ring-length}.
2357 @findex find-tag-regexp
2359 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2360 match a specified regular expression. It is just like @kbd{M-.} except
2361 that it does regexp matching instead of substring matching.
2364 @subsection Searching and Replacing with Tags Tables
2366 The commands in this section visit and search all the files listed in the
2367 selected tags table, one by one. For these commands, the tags table serves
2368 only to specify a sequence of files to search.
2371 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2372 Search for @var{regexp} through the files in the selected tags
2374 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2375 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2377 Restart one of the commands above, from the current location of point
2378 (@code{tags-loop-continue}).
2382 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2383 searches for matches in all the files in the selected tags table, one
2384 file at a time. It displays the name of the file being searched so you
2385 can follow its progress. As soon as it finds an occurrence,
2386 @code{tags-search} returns.
2389 @findex tags-loop-continue
2390 Having found one match, you probably want to find all the rest. To find
2391 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2392 @code{tags-search}. This searches the rest of the current buffer, followed
2393 by the remaining files of the tags table.@refill
2395 @findex tags-query-replace
2396 @kbd{M-x tags-query-replace} performs a single
2397 @code{query-replace-regexp} through all the files in the tags table. It
2398 reads a regexp to search for and a string to replace with, just like
2399 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2400 tags-search}, but repeatedly, processing matches according to your
2401 input. @xref{Replace}, for more information on query replace.
2403 It is possible to get through all the files in the tags table with a
2404 single invocation of @kbd{M-x tags-query-replace}. But often it is
2405 useful to exit temporarily, which you can do with any input event that
2406 has no special query replace meaning. You can resume the query replace
2407 subsequently by typing @kbd{M-,}; this command resumes the last tags
2408 search or replace command that you did.
2410 The commands in this section carry out much broader searches than the
2411 @code{find-tag} family. The @code{find-tag} commands search only for
2412 definitions of tags that match your substring or regexp. The commands
2413 @code{tags-search} and @code{tags-query-replace} find every occurrence
2414 of the regexp, as ordinary search commands and replace commands do in
2417 These commands create buffers only temporarily for the files that they
2418 have to search (those which are not already visited in Emacs buffers).
2419 Buffers in which no match is found are quickly killed; the others
2422 It may have struck you that @code{tags-search} is a lot like
2423 @code{grep}. You can also run @code{grep} itself as an inferior of
2424 Emacs and have Emacs show you the matching lines one by one. This works
2425 much like running a compilation; finding the source locations of the
2426 @code{grep} matches works like finding the compilation errors.
2430 @subsection Tags Table Inquiries
2433 @item M-x list-tags @key{RET} @var{file} @key{RET}
2434 Display a list of the tags defined in the program file @var{file}.
2435 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2436 Display a list of all tags matching @var{regexp}.
2440 @kbd{M-x list-tags} reads the name of one of the files described by
2441 the selected tags table, and displays a list of all the tags defined in
2442 that file. The ``file name'' argument is really just a string to
2443 compare against the file names recorded in the tags table; it is read as
2444 a string rather than as a file name. Therefore, completion and
2445 defaulting are not available, and you must enter the file name the same
2446 way it appears in the tags table. Do not include a directory as part of
2447 the file name unless the file name recorded in the tags table includes a
2450 @findex tags-apropos
2451 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2452 (@pxref{Apropos}). It reads a regexp, then finds all the tags in the
2453 selected tags table whose entries match that regexp, and displays the
2455 @vindex tags-apropos-additional-actions
2456 You can display additional output with @kbd{M-x tags-apropos} by customizing
2457 the variable @code{tags-apropos-additional-actions}. See its
2458 documentation for details.
2460 You can also perform completion in the buffer on the name space of tag
2461 names in the current tags tables. @xref{Symbol Completion}.
2465 @cindex indexes of buffer contents
2466 @cindex buffer content indexes
2469 The Imenu facility provides mode-specific indexes of the contents of
2470 single buffers and provides selection from a menu. Selecting a menu
2471 item takes you to the indexed point in the buffer, in a similar way to
2472 the Tags facility. Indexing is typically by names of program routines
2473 and variables but in Texinfo mode, for instance, node names are indexed.
2474 Most major modes for which it is appropriate have Imenu support.
2477 @findex imenu-add-menu-bar-index
2478 @kbd{M-x imenu} builds the index if necessary and presents you with an
2479 electric buffer menu from which to select an entry (with completion).
2480 If you bind @code{imenu} to a mouse event (@pxref{Mouse Buttons}) and
2481 invoke it that way, the index will appear as a popup menu; there is no
2482 such binding by default. You can add an index menubar on the menubar
2483 with @kbd{imenu-add-menu-bar-index}.
2485 Some major modes provide facilities for invoking Imenu; otherwise you
2486 could add @code{imenu-add-menu-bar-index} to a major mode's hook to
2487 generate an index for each buffer created in that mode. (If you do
2488 that, it takes sime time to generate the index when finding a file,
2489 depending on the file's size and the complexity of the indexing function
2492 @vindex imenu-auto-rescan
2493 The index should be regenerated (via the @samp{*Rescan*} menu item) when
2494 indexable items are added to or deleted from the buffer. Rescanning is
2495 done when a menu selction is requested if the option
2496 @code{imenu-auto-rescan} is set. By default buffer positions are in
2497 terms of markers, so that changing non-indexable text doesn't require
2500 @vindex imenu-sort-function
2501 The way the menus are sorted can be customized via the option
2502 @code{imenu-sort-function}. By default names are ordered as they occur
2503 in the buffer; alphabetic sorting is provided as an alternative.
2505 Imenu provides the information used by Which Function mode (@pxref{Which
2506 Function}). It may also be used by Speedbar (@pxref{Speedbar}).
2508 @node Emerge, C Modes, Imenu, Programs
2509 @section Merging Files with Emerge
2511 @cindex merging files
2513 It's not unusual for programmers to get their signals crossed and modify
2514 the same program in two different directions. To recover from this
2515 confusion, you need to merge the two versions. Emerge makes this
2516 easier. See also @ref{Comparing Files}, for commands to compare
2517 in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
2520 * Overview of Emerge:: How to start Emerge. Basic concepts.
2521 * Submodes of Emerge:: Fast mode vs. Edit mode.
2522 Skip Prefers mode and Auto Advance mode.
2523 * State of Difference:: You do the merge by specifying state A or B
2524 for each difference.
2525 * Merge Commands:: Commands for selecting a difference,
2526 changing states of differences, etc.
2527 * Exiting Emerge:: What to do when you've finished the merge.
2528 * Combining in Emerge:: How to keep both alternatives for a difference.
2529 * Fine Points of Emerge:: Misc.
2532 @node Overview of Emerge
2533 @subsection Overview of Emerge
2535 To start Emerge, run one of these four commands:
2538 @item M-x emerge-files
2539 @findex emerge-files
2540 Merge two specified files.
2542 @item M-x emerge-files-with-ancestor
2543 @findex emerge-files-with-ancestor
2544 Merge two specified files, with reference to a common ancestor.
2546 @item M-x emerge-buffers
2547 @findex emerge-buffers
2550 @item M-x emerge-buffers-with-ancestor
2551 @findex emerge-buffers-with-ancestor
2552 Merge two buffers with reference to a common ancestor in a third
2556 @cindex merge buffer (Emerge)
2557 @cindex A and B buffers (Emerge)
2558 The Emerge commands compare two files or buffers, and display the
2559 comparison in three buffers: one for each input text (the @dfn{A buffer}
2560 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
2561 takes place. The merge buffer shows the full merged text, not just the
2562 differences. Wherever the two input texts differ, you can choose which
2563 one of them to include in the merge buffer.
2565 The Emerge commands that take input from existing buffers use only the
2566 accessible portions of those buffers, if they are narrowed
2567 (@pxref{Narrowing}).
2569 If a common ancestor version is available, from which the two texts to
2570 be merged were both derived, Emerge can use it to guess which
2571 alternative is right. Wherever one current version agrees with the
2572 ancestor, Emerge presumes that the other current version is a deliberate
2573 change which should be kept in the merged version. Use the
2574 @samp{with-ancestor} commands if you want to specify a common ancestor
2575 text. These commands read three file or buffer names---variant A,
2576 variant B, and the common ancestor.
2578 After the comparison is done and the buffers are prepared, the
2579 interactive merging starts. You control the merging by typing special
2580 @dfn{merge commands} in the merge buffer. The merge buffer shows you a
2581 full merged text, not just differences. For each run of differences
2582 between the input texts, you can choose which one of them to keep, or
2583 edit them both together.
2585 The merge buffer uses a special major mode, Emerge mode, with commands
2586 for making these choices. But you can also edit the buffer with
2587 ordinary Emacs commands.
2589 At any given time, the attention of Emerge is focused on one
2590 particular difference, called the @dfn{selected} difference. This
2591 difference is marked off in the three buffers like this:
2594 vvvvvvvvvvvvvvvvvvvv
2595 @var{text that differs}
2596 ^^^^^^^^^^^^^^^^^^^^
2600 Emerge numbers all the differences sequentially and the mode
2601 line always shows the number of the selected difference.
2603 Normally, the merge buffer starts out with the A version of the text.
2604 But when the A version of a difference agrees with the common ancestor,
2605 then the B version is initially preferred for that difference.
2607 Emerge leaves the merged text in the merge buffer when you exit. At
2608 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
2609 numeric argument to @code{emerge-files} or
2610 @code{emerge-files-with-ancestor}, it reads the name of the output file
2611 using the minibuffer. (This is the last file name those commands read.)
2612 Then exiting from Emerge saves the merged text in the output file.
2614 Normally, Emerge commands save the output buffer in its file when you
2615 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
2616 save the output buffer, but you can save it yourself if you wish.
2618 @node Submodes of Emerge
2619 @subsection Submodes of Emerge
2621 You can choose between two modes for giving merge commands: Fast mode
2622 and Edit mode. In Fast mode, basic merge commands are single
2623 characters, but ordinary Emacs commands are disabled. This is
2624 convenient if you use only merge commands. In Edit mode, all merge
2625 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
2626 commands are also available. This allows editing the merge buffer, but
2627 slows down Emerge operations.
2629 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
2630 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
2633 Emerge has two additional submodes that affect how particular merge
2634 commands work: Auto Advance mode and Skip Prefers mode.
2636 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
2637 advance to the next difference. This lets you go through the merge
2638 faster as long as you simply choose one of the alternatives from the
2639 input. The mode line indicates Auto Advance mode with @samp{A}.
2641 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
2642 skip over differences in states prefer-A and prefer-B (@pxref{State of
2643 Difference}). Thus you see only differences for which neither version
2644 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
2647 @findex emerge-auto-advance-mode
2648 @findex emerge-skip-prefers-mode
2649 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
2650 clear Auto Advance mode. Use @kbd{s s}
2651 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
2652 These commands turn on the mode with a positive argument, turns it off
2653 with a negative or zero argument, and toggle the mode with no argument.
2655 @node State of Difference
2656 @subsection State of a Difference
2658 In the merge buffer, a difference is marked with lines of @samp{v} and
2659 @samp{^} characters. Each difference has one of these seven states:
2663 The difference is showing the A version. The @kbd{a} command always
2664 produces this state; the mode line indicates it with @samp{A}.
2667 The difference is showing the B version. The @kbd{b} command always
2668 produces this state; the mode line indicates it with @samp{B}.
2672 The difference is showing the A or the B state by default, because you
2673 haven't made a choice. All differences start in the default-A state
2674 (and thus the merge buffer is a copy of the A buffer), except those for
2675 which one alternative is ``preferred'' (see below).
2677 When you select a difference, its state changes from default-A or
2678 default-B to plain A or B. Thus, the selected difference never has
2679 state default-A or default-B, and these states are never displayed in
2682 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
2683 b} chooses default-B. This chosen default applies to all differences
2684 which you haven't ever selected and for which no alternative is preferred.
2685 If you are moving through the merge sequentially, the differences you
2686 haven't selected are those following the selected one. Thus, while
2687 moving sequentially, you can effectively make the A version the default
2688 for some sections of the merge buffer and the B version the default for
2689 others by using @kbd{d a} and @kbd{d b} between sections.
2693 The difference is showing the A or B state because it is
2694 @dfn{preferred}. This means that you haven't made an explicit choice,
2695 but one alternative seems likely to be right because the other
2696 alternative agrees with the common ancestor. Thus, where the A buffer
2697 agrees with the common ancestor, the B version is preferred, because
2698 chances are it is the one that was actually changed.
2700 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
2703 The difference is showing a combination of the A and B states, as a
2704 result of the @kbd{x c} or @kbd{x C} commands.
2706 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
2707 don't do anything to it unless you give them a numeric argument.
2709 The mode line displays this state as @samp{comb}.
2712 @node Merge Commands
2713 @subsection Merge Commands
2715 Here are the Merge commands for Fast mode; in Edit mode, precede them
2720 Select the previous difference.
2723 Select the next difference.
2726 Choose the A version of this difference.
2729 Choose the B version of this difference.
2732 Select difference number @var{n}.
2735 Select the difference containing point. You can use this command in the
2736 merge buffer or in the A or B buffer.
2739 Quit---finish the merge.
2742 Abort---exit merging and do not save the output.
2745 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
2751 Recenter (like @kbd{C-l}) all three windows.
2754 Specify part of a prefix numeric argument.
2757 Also specify part of a prefix numeric argument.
2760 Choose the A version as the default from here down in
2764 Choose the B version as the default from here down in
2768 Copy the A version of this difference into the kill ring.
2771 Copy the B version of this difference into the kill ring.
2774 Insert the A version of this difference at point.
2777 Insert the B version of this difference at point.
2780 Put point and mark around the difference.
2783 Scroll all three windows down (like @kbd{M-v}).
2786 Scroll all three windows up (like @kbd{C-v}).
2789 Scroll all three windows left (like @kbd{C-x <}).
2792 Scroll all three windows right (like @kbd{C-x >}).
2795 Reset horizontal scroll on all three windows.
2798 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
2802 Combine the two versions of this difference (@pxref{Combining in
2806 Show the names of the files/buffers Emerge is operating on, in a Help
2807 window. (Use @kbd{C-u l} to restore windows.)
2810 Join this difference with the following one.
2811 (@kbd{C-u x j} joins this difference with the previous one.)
2814 Split this difference into two differences. Before you use this
2815 command, position point in each of the three buffers at the place where
2816 you want to split the difference.
2819 Trim identical lines off the top and bottom of the difference.
2820 Such lines occur when the A and B versions are
2821 identical but differ from the ancestor version.
2824 @node Exiting Emerge
2825 @subsection Exiting Emerge
2827 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
2828 the results into the output file if you specified one. It restores the
2829 A and B buffers to their proper contents, or kills them if they were
2830 created by Emerge and you haven't changed them. It also disables the
2831 Emerge commands in the merge buffer, since executing them later could
2832 damage the contents of the various buffers.
2834 @kbd{C-]} aborts the merge. This means exiting without writing the
2835 output file. If you didn't specify an output file, then there is no
2836 real difference between aborting and finishing the merge.
2838 If the Emerge command was called from another Lisp program, then its
2839 return value is @code{t} for successful completion, or @code{nil} if you
2842 @node Combining in Emerge
2843 @subsection Combining the Two Versions
2845 Sometimes you want to keep @emph{both} alternatives for a particular
2846 difference. To do this, use @kbd{x c}, which edits the merge buffer
2852 @var{version from A buffer}
2854 @var{version from B buffer}
2855 #endif /* not NEW */
2860 @vindex emerge-combine-versions-template
2861 While this example shows C preprocessor conditionals delimiting the two
2862 alternative versions, you can specify the strings to use by setting
2863 the variable @code{emerge-combine-versions-template} to a string of your
2864 choice. In the string, @samp{%a} says where to put version A, and
2865 @samp{%b} says where to put version B. The default setting, which
2866 produces the results shown above, looks like this:
2870 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
2874 @node Fine Points of Emerge
2875 @subsection Fine Points of Emerge
2877 During the merge, you mustn't try to edit the A and B buffers yourself.
2878 Emerge modifies them temporarily, but ultimately puts them back the way
2881 You can have any number of merges going at once---just don't use any one
2882 buffer as input to more than one merge at once, since the temporary
2883 changes made in these buffers would get in each other's way.
2885 Starting Emerge can take a long time because it needs to compare the
2886 files fully. Emacs can't do anything else until @code{diff} finishes.
2887 Perhaps in the future someone will change Emerge to do the comparison in
2888 the background when the input files are large---then you could keep on
2889 doing other things with Emacs until Emerge is ready to accept
2892 @vindex emerge-startup-hook
2893 After setting up the merge, Emerge runs the hook
2894 @code{emerge-startup-hook} (@pxref{Hooks}).
2897 @section C and Related Modes
2902 @cindex CORBA IDL mode
2903 @cindex Objective C mode
2907 @cindex mode, Objective C
2908 @cindex mode, CORBA IDL
2911 This section describes special features available in C, C++,
2912 Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and
2913 related modes,'' those are the modes we mean.
2915 Additional information is available in the separate manual for these
2916 modes. @xref{Top, CC Mode, ccmode, , CC Mode}.
2922 * Other C Commands::
2927 @subsection C Mode Motion Commands
2929 This section describes commands for moving point, in C mode and
2934 @kindex C-c C-u @r{(C mode)}
2935 @findex c-up-conditional
2936 Move point back to the containing preprocessor conditional, leaving the
2937 mark behind. A prefix argument acts as a repeat count. With a negative
2938 argument, move point forward to the end of the containing
2939 preprocessor conditional. When going backwards, @code{#elif} is treated
2940 like @code{#else} followed by @code{#if}. When going forwards,
2941 @code{#elif} is ignored.@refill
2944 @kindex C-c C-p @r{(C mode)}
2945 @findex c-backward-conditional
2946 Move point back over a preprocessor conditional, leaving the mark
2947 behind. A prefix argument acts as a repeat count. With a negative
2948 argument, move forward.
2951 @kindex C-c C-n @r{(C mode)}
2952 @findex c-forward-conditional
2953 Move point forward across a preprocessor conditional, leaving the mark
2954 behind. A prefix argument acts as a repeat count. With a negative
2955 argument, move backward.
2959 @findex c-beginning-of-statement
2960 Move point to the beginning of the innermost C statement
2961 (@code{c-beginning-of-statement}). If point is already at the beginning
2962 of a statement, move to the beginning of the preceding statement. With
2963 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
2965 If point is within a string or comment, or next to a comment (only
2966 whitespace between them), this command moves by sentences instead of
2969 When called from a program, this function takes three optional
2970 arguments: the numeric prefix argument, a buffer position limit
2971 (don't move back before that place), and a flag that controls whether
2972 to do sentence motion when inside of a comment.
2976 @findex c-end-of-statement
2977 Move point to the end of the innermost C statement; like @kbd{M-a}
2978 except that it moves in the other direction (@code{c-end-of-statement}).
2980 @item M-x c-backward-into-nomenclature
2981 @findex c-backward-into-nomenclature
2982 Move point backward to beginning of a C++ nomenclature section or word.
2983 With prefix argument @var{n}, move @var{n} times. If @var{n} is
2984 negative, move forward. C++ nomenclature means a symbol name in the
2985 style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
2986 begins a section or word.
2988 In the GNU project, we recommend using underscores to separate words
2989 within an identifier in C or C++, rather than using case distinctions.
2991 @item M-x c-forward-into-nomenclature
2992 @findex c-forward-into-nomenclature
2993 Move point forward to end of a C++ nomenclature section or word.
2994 With prefix argument @var{n}, move @var{n} times.
2998 @subsection Electric C Characters
3000 In C mode and related modes, certain printing characters are
3001 ``electric''---in addition to inserting themselves, they also reindent
3002 the current line and may insert newlines. This feature is controlled by
3003 the variable @code{c-auto-newline}. The ``electric'' characters are
3004 @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
3005 @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
3007 Electric characters insert newlines only when the @dfn{auto-newline}
3008 feature is enabled (indicated by @samp{/a} in the mode line after the
3009 mode name). This feature is controlled by the variable
3010 @code{c-auto-newline}. You can turn this feature on or off with the
3011 command @kbd{C-c C-a}:
3015 @kindex C-c C-a @r{(C mode)}
3016 @findex c-toggle-auto-state
3017 Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a
3018 prefix argument, this command turns the auto-newline feature on if the
3019 argument is positive, and off if it is negative.
3022 The colon character is electric because that is appropriate for a
3023 single colon. But when you want to insert a double colon in C++, the
3024 electric behavior of colon is inconvenient. You can insert a double
3025 colon with no reindentation or newlines by typing @kbd{C-c :}:
3029 @kindex C-c : @r{(C mode)}
3030 @findex c-scope-operator
3031 Insert a double colon scope operator at point, without reindenting the
3032 line or adding any newlines (@code{c-scope-operator}).
3035 The electric @kbd{#} key reindents the line if it appears to be the
3036 beginning of a preprocessor directive. This happens when the value of
3037 @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
3038 this feature off by setting @code{c-electric-pound-behavior} to
3041 The variable @code{c-hanging-braces-alist} controls the insertion of
3042 newlines before and after inserted braces. It is an association list
3043 with elements of the following form: @code{(@var{syntactic-symbol}
3044 . @var{nl-list})}. Most of the syntactic symbols that appear in
3045 @code{c-offsets-alist} are meaningful here as well.
3047 The list @var{nl-list} may contain either of the symbols
3048 @code{before} or @code{after}, or both; or it may be @code{nil}. When a
3049 brace is inserted, the syntactic context it defines is looked up in
3050 @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
3051 to determine where newlines are inserted: either before the brace,
3052 after, or both. If not found, the default is to insert a newline both
3053 before and after braces.
3055 The variable @code{c-hanging-colons-alist} controls the insertion of
3056 newlines before and after inserted colons. It is an association list
3057 with elements of the following form: @code{(@var{syntactic-symbol}
3058 . @var{nl-list})}. The list @var{nl-list} may contain either of the
3059 symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
3061 When a colon is inserted, the syntactic symbol it defines is looked
3062 up in this list, and if found, the @var{nl-list} is used to determine
3063 where newlines are inserted: either before the brace, after, or both.
3064 If the syntactic symbol is not found in this list, no newlines are
3067 Electric characters can also delete newlines automatically when the
3068 auto-newline feature is enabled. This feature makes auto-newline more
3069 acceptable, by deleting the newlines in the most common cases where you
3070 do not want them. Emacs can recognize several cases in which deleting a
3071 newline might be desirable; by setting the variable
3072 @code{c-cleanup-list}, you can specify @emph{which} of these cases that
3073 should happen. The variable's value is a list of symbols, each
3074 describing one case for possible deletion of a newline. Here are the
3075 meaningful symbols, and their meanings:
3078 @item brace-catch-brace
3079 Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
3080 entire construct on a single line. The clean-up occurs when you type
3081 the @samp{@{}, if there is nothing between the braces aside from
3082 @code{catch} and @var{condition}.
3084 @item brace-else-brace
3085 Clean up @samp{@} else @{} constructs by placing the entire construct on
3086 a single line. The clean-up occurs when you type the @samp{@{} after
3087 the @code{else}, but only if there is nothing but white space between
3088 the braces and the @code{else}.
3090 @item brace-elseif-brace
3091 Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
3092 construct on a single line. The clean-up occurs when you type the
3093 @samp{@{}, if there is nothing but white space between the @samp{@}} and
3094 @samp{@{} aside from the keywords and the @code{if}-condition.
3096 @item empty-defun-braces
3097 Clean up empty defun braces by placing the braces on the same
3098 line. Clean-up occurs when you type the closing brace.
3100 @item defun-close-semi
3101 Clean up the semicolon after a @code{struct} or similar type
3102 declaration, by placing the semicolon on the same line as the closing
3103 brace. Clean-up occurs when you type the semicolon.
3105 @item list-close-comma
3106 Clean up commas following braces in array and aggregate
3107 initializers. Clean-up occurs when you type the comma.
3109 @item scope-operator
3110 Clean up double colons which may designate a C++ scope operator, by
3111 placing the colons together. Clean-up occurs when you type the second
3112 colon, but only when the two colons are separated by nothing but
3117 @subsection Hungry Delete Feature in C
3119 When the @dfn{hungry-delete} feature is enabled (indicated by
3120 @samp{/h} or @samp{/ah} in the mode line after the mode name), a single
3121 @key{DEL} command deletes all preceding whitespace, not just one space.
3122 To turn this feature on or off, use @kbd{C-c C-d}:
3126 @kindex C-c C-d @r{(C mode)}
3127 @findex c-toggle-hungry-state
3128 Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a
3129 prefix argument, this command turns the hungry-delete feature on if the
3130 argument is positive, and off if it is negative.
3133 @kindex C-c C-t @r{(C mode)}
3134 @findex c-toggle-auto-hungry-state
3135 Toggle the auto-newline and hungry-delete features, both at once
3136 (@code{c-toggle-auto-hungry-state}).
3139 @vindex c-hungry-delete-key
3140 The variable @code{c-hungry-delete-key} controls whether the
3141 hungry-delete feature is enabled.
3143 @node Other C Commands
3144 @subsection Other Commands for C Mode
3148 @findex c-mark-function
3149 @kindex C-M-h @r{(C mode)}
3150 Put mark at the end of a function definition, and put point at the
3151 beginning (@code{c-mark-function}).
3154 @kindex M-q @r{(C mode)}
3155 @findex c-fill-paragraph
3156 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
3157 If any part of the current line is a comment or within a comment, this
3158 command fills the comment or the paragraph of it that point is in,
3159 preserving the comment indentation and comment delimiters.
3162 @cindex macro expansion in C
3163 @cindex expansion of C macros
3164 @findex c-macro-expand
3165 @kindex C-c C-e @r{(C mode)}
3166 Run the C preprocessor on the text in the region, and show the result,
3167 which includes the expansion of all the macro calls
3168 (@code{c-macro-expand}). The buffer text before the region is also
3169 included in preprocessing, for the sake of macros defined there, but the
3170 output from this part isn't shown.
3172 When you are debugging C code that uses macros, sometimes it is hard to
3173 figure out precisely how the macros expand. With this command, you
3174 don't have to figure it out; you can see the expansions.
3177 @findex c-backslash-region
3178 @kindex C-c C-\ @r{(C mode)}
3179 Insert or align @samp{\} characters at the ends of the lines of the
3180 region (@code{c-backslash-region}). This is useful after writing or
3181 editing a C macro definition.
3183 If a line already ends in @samp{\}, this command adjusts the amount of
3184 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
3185 the last line in the region is treated specially; no @samp{\} is
3186 inserted on that line, and any @samp{\} there is deleted.
3188 @item M-x cpp-highlight-buffer
3189 @cindex preprocessor highlighting
3190 @findex cpp-highlight-buffer
3191 Highlight parts of the text according to its preprocessor conditionals.
3192 This command displays another buffer named @samp{*CPP Edit*}, which
3193 serves as a graphic menu for selecting how to display particular kinds
3194 of conditionals and their contents. After changing various settings,
3195 click on @samp{[A]pply these settings} (or go to that buffer and type
3196 @kbd{a}) to rehighlight the C mode buffer accordingly.
3199 @findex c-show-syntactic-information
3200 @kindex C-c C-s @r{(C mode)}
3201 Display the syntactic information about the current source line
3202 (@code{c-show-syntactic-information}). This is the information that
3203 directs how the line is indented.
3205 @item M-x cwarn-mode
3206 @itemx M-x global-cwarn-mode
3208 @findex global-cwarn-mode
3210 @cindex suspicious constructions in C, C++
3211 CWarn minor mode highlights suspicious C and C++ constructions:
3215 Assignments inside expressions, including variations like @samp{+=};
3217 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
3218 (except after a @samp{do @dots{} while} statement);
3220 C++ functions with reference parameters.
3224 You can activate the mode either by customizing @code{global-cwarn-mode}
3225 or by adding @code{cwarn-mode} to @code{c-mode-common-hook}. It
3226 requires Font Lock mode to be active.
3228 @item M-x hide-ifdef-mode
3229 @findex hide-ifdef-mode
3230 @cindex Hide-ifdef mode
3231 Hide-ifdef minor mode hides selected code within @samp{#if} and
3232 @samp{#ifdef} preprocessor blocks. You can activate it by adding
3233 @code{hide-ifdef-mode} to @code{c-mode-common-hook}. See the mode's
3234 help for more information.
3238 @subsection Comments in C Modes
3240 C mode and related modes use a number of variables for controlling
3244 @item c-comment-only-line-offset
3245 @vindex c-comment-only-line-offset
3246 Extra offset for line which contains only the start of a comment. It
3247 can be either an integer or a cons cell of the form
3248 @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
3249 @var{non-anchored-offset} is the amount of offset given to
3250 non-column-zero anchored comment-only lines, and @var{anchored-offset}
3251 is the amount of offset to give column-zero anchored comment-only lines.
3252 Just an integer as value is equivalent to @code{(@var{val} . 0)}.
3254 @item c-comment-start-regexp
3255 @vindex c-comment-start-regexp
3256 This buffer-local variable specifies how to recognize the start of a comment.
3258 @item c-hanging-comment-ender-p
3259 @vindex c-hanging-comment-ender-p
3260 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
3261 comment terminator of a block comment on a line by itself. The default
3262 value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
3263 end of the last line of the comment text.
3265 @item c-hanging-comment-starter-p
3266 @vindex c-hanging-comment-starter-p
3267 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
3268 starting delimiter of a block comment on a line by itself. The default
3269 value is @code{t}, which puts the comment-start delimiter @samp{/*} at
3270 the beginning of the first line of the comment text.
3275 @section Fortran Mode
3276 @cindex Fortran mode
3277 @cindex mode, Fortran
3279 Fortran mode provides special motion commands for Fortran statements and
3280 subprograms, and indentation commands that understand Fortran conventions
3281 of nesting, line numbers and continuation statements. Fortran mode has
3282 its own Auto Fill mode that breaks long lines into proper Fortran
3285 Special commands for comments are provided because Fortran comments
3286 are unlike those of other languages. Built-in abbrevs optionally save
3287 typing when you insert Fortran keywords.
3289 @findex fortran-mode
3290 Use @kbd{M-x fortran-mode} to switch to this major mode. This command
3291 runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
3296 @findex fortran-mode
3297 Note that Fortan mode described here (obtained with the
3298 @code{fortran-mode} command) is for editing the old Fortran77
3299 idiosyncratic `fixed format' source form. For editing the modern
3300 Fortran90 `free format' source form (which is supported by the GNU
3301 Fortran compiler) use @code{f90-mode}.
3303 By default @code{fortran-mode} is invoked on files with extension
3304 @samp{.f}, @samp{.F} or @samp{.for} and @code{f90-mode} is invoked for
3305 the extension @samp{.f90}.
3308 * Motion: Fortran Motion. Moving point by statements or subprograms.
3309 * Indent: Fortran Indent. Indentation commands for Fortran.
3310 * Comments: Fortran Comments. Inserting and aligning comments.
3311 * Autofill: Fortran Autofill. Auto fill minor mode for Fortran.
3312 * Columns: Fortran Columns. Measuring columns for valid Fortran.
3313 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
3314 * Misc: Fortran Misc. Other Fortran mode features.
3317 @node Fortran Motion
3318 @subsection Motion Commands
3320 In addition to the normal commands for moving by and operating on
3321 `defuns' (Fortran subprograms---functions
3322 and subroutines) Fortran mode provides special commands to move by statements.
3324 @kindex C-c C-p @r{(Fortran mode)}
3325 @kindex C-c C-n @r{(Fortran mode)}
3326 @findex fortran-previous-statement
3327 @findex fortran-next-statement
3331 Move to beginning of current or next statement
3332 (@code{fortran-next-statement}).
3334 Move to beginning of current or previous statement
3335 (@code{fortran-previous-statement}).
3338 @node Fortran Indent
3339 @subsection Fortran Indentation
3341 Special commands and features are needed for indenting Fortran code in
3342 order to make sure various syntactic entities (line numbers, comment line
3343 indicators and continuation line flags) appear in the columns that are
3344 required for standard Fortran.
3347 * Commands: ForIndent Commands. Commands for indenting and filling Fortran.
3348 * Contline: ForIndent Cont. How continuation lines indent.
3349 * Numbers: ForIndent Num. How line numbers auto-indent.
3350 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
3351 * Vars: ForIndent Vars. Variables controlling Fortran indent style.
3354 @node ForIndent Commands
3355 @subsubsection Fortran-Specific Indentation and Filling Commands
3359 Break the current line and set up a continuation line
3360 (@code{fortran-split-line}).
3362 Join this line to the previous line (@code{fortran-join-line}).
3364 Indent all the lines of the subprogram point is in
3365 (@code{fortran-indent-subprogram}).
3367 Fill a comment block or statement.
3370 @kindex C-M-q @r{(Fortran mode)}
3371 @findex fortran-indent-subprogram
3372 The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
3373 to reindent all the lines of the Fortran subprogram (function or
3374 subroutine) containing point.
3376 @kindex C-M-j @r{(Fortran mode)}
3377 @findex fortran-split-line
3378 The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
3379 a line in the appropriate fashion for Fortran. In a non-comment line,
3380 the second half becomes a continuation line and is indented
3381 accordingly. In a comment line, both halves become separate comment
3384 @kindex M-^ @r{(Fortran mode)}
3385 @kindex C-c C-d @r{(Fortran mode)}
3386 @findex fortran-join-line
3387 @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
3388 which joins a continuation line back to the previous line, roughly as
3389 the inverse of @code{fortran-split-line}. The point must be on a
3390 continuation line when this command is invoked.
3392 @kindex M-q @r{(Fortran mode)}
3393 Fortran mode defines the function for filling paragraphs such that
3394 @kbd{M-q} fills the comment block or statement around point. Filling a
3395 statement removes excess statement continuations.
3397 @node ForIndent Cont
3398 @subsubsection Continuation Lines
3399 @cindex Fortran continuation lines
3401 @vindex fortran-continuation-string
3402 Most modern Fortran compilers allow two ways of writing continuation
3403 lines. If the first non-space character on a line is in column 5, then
3404 that line is a continuation of the previous line. We call this
3405 @dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The
3406 variable @code{fortran-continuation-string} specifies what character to
3407 put on column 5. A line that starts with a tab character followed by
3408 any digit except @samp{0} is also a continuation line. We call this
3409 style of continuation @dfn{tab format}.
3411 @vindex indent-tabs-mode @r{(Fortran mode)}
3412 Fortran mode can make either style of continuation line, but you
3413 must specify which one you prefer. The value of the variable
3414 @code{indent-tabs-mode} controls the choice: @code{nil} for fixed
3415 format, and non-@code{nil} for tab format. You can tell which style
3416 is presently in effect by the presence or absence of the string
3417 @samp{Tab} in the mode line.
3419 If the text on a line starts with the conventional Fortran
3420 continuation marker @samp{$}, or if it begins with any non-whitespace
3421 character in column 5, Fortran mode treats it as a continuation line.
3422 When you indent a continuation line with @key{TAB}, it converts the line
3423 to the current continuation style. When you split a Fortran statement
3424 with @kbd{C-M-j}, the continuation marker on the newline is created
3425 according to the continuation style.
3427 The setting of continuation style affects several other aspects of
3428 editing in Fortran mode. In fixed format mode, the minimum column
3429 number for the body of a statement is 6. Lines inside of Fortran
3430 blocks that are indented to larger column numbers always use only the
3431 space character for whitespace. In tab format mode, the minimum
3432 column number for the statement body is 8, and the whitespace before
3433 column 8 must always consist of one tab character.
3435 @vindex fortran-tab-mode-default
3436 @vindex fortran-analyze-depth
3437 When you enter Fortran mode for an existing file, it tries to deduce the
3438 proper continuation style automatically from the file contents. The first
3439 line that begins with either a tab character or six spaces determines the
3440 choice. The variable @code{fortran-analyze-depth} specifies how many lines
3441 to consider (at the beginning of the file); if none of those lines
3442 indicates a style, then the variable @code{fortran-tab-mode-default}
3443 specifies the style. If it is @code{nil}, that specifies fixed format, and
3444 non-@code{nil} specifies tab format.
3447 @subsubsection Line Numbers
3449 If a number is the first non-whitespace in the line, Fortran
3450 indentation assumes it is a line number and moves it to columns 0
3451 through 4. (Columns always count from 0 in GNU Emacs.)
3453 @vindex fortran-line-number-indent
3454 Line numbers of four digits or less are normally indented one space.
3455 The variable @code{fortran-line-number-indent} controls this; it
3456 specifies the maximum indentation a line number can have. Line numbers
3457 are indented to right-justify them to end in column 4 unless that would
3458 require more than this maximum indentation. The default value of the
3461 @vindex fortran-electric-line-number
3462 Simply inserting a line number is enough to indent it according to
3463 these rules. As each digit is inserted, the indentation is recomputed.
3464 To turn off this feature, set the variable
3465 @code{fortran-electric-line-number} to @code{nil}. Then inserting line
3466 numbers is like inserting anything else.
3468 @node ForIndent Conv
3469 @subsubsection Syntactic Conventions
3471 Fortran mode assumes that you follow certain conventions that simplify
3472 the task of understanding a Fortran program well enough to indent it
3477 Two nested @samp{do} loops never share a @samp{continue} statement.
3480 Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
3481 and others are written without embedded whitespace or line breaks.
3483 Fortran compilers generally ignore whitespace outside of string
3484 constants, but Fortran mode does not recognize these keywords if they
3485 are not contiguous. Constructs such as @samp{else if} or @samp{end do}
3486 are acceptable, but the second word should be on the same line as the
3487 first and not on a continuation line.
3491 If you fail to follow these conventions, the indentation commands may
3492 indent some lines unaesthetically. However, a correct Fortran program
3493 retains its meaning when reindented even if the conventions are not
3496 @node ForIndent Vars
3497 @subsubsection Variables for Fortran Indentation
3499 @vindex fortran-do-indent
3500 @vindex fortran-if-indent
3501 @vindex fortran-structure-indent
3502 @vindex fortran-continuation-indent
3503 @vindex fortran-check-all-num@dots{}
3504 @vindex fortran-minimum-statement-indent@dots{}
3505 Several additional variables control how Fortran indentation works:
3508 @item fortran-do-indent
3509 Extra indentation within each level of @samp{do} statement (default 3).
3511 @item fortran-if-indent
3512 Extra indentation within each level of @samp{if} statement (default 3).
3513 This value is also used for extra indentation within each level of the
3514 Fortran 90 @samp{where} statement.
3516 @item fortran-structure-indent
3517 Extra indentation within each level of @samp{structure}, @samp{union}, or
3518 @samp{map} statements (default 3).
3520 @item fortran-continuation-indent
3521 Extra indentation for bodies of continuation lines (default 5).
3523 @item fortran-check-all-num-for-matching-do
3524 If this is @code{nil}, indentation assumes that each @samp{do} statement
3525 ends on a @samp{continue} statement. Therefore, when computing
3526 indentation for a statement other than @samp{continue}, it can save time
3527 by not checking for a @samp{do} statement ending there. If this is
3528 non-@code{nil}, indenting any numbered statement must check for a
3529 @samp{do} that ends there. The default is @code{nil}.
3531 @item fortran-blink-matching-if
3532 If this is @code{t}, indenting an @samp{endif} statement moves the
3533 cursor momentarily to the matching @samp{if} statement to show where it
3534 is. The default is @code{nil}.
3536 @item fortran-minimum-statement-indent-fixed
3537 Minimum indentation for fortran statements when using fixed format
3538 continuation line style. Statement bodies are never indented less than
3539 this much. The default is 6.
3541 @item fortran-minimum-statement-indent-tab
3542 Minimum indentation for fortran statements for tab format continuation line
3543 style. Statement bodies are never indented less than this much. The
3547 @node Fortran Comments
3548 @subsection Fortran Comments
3550 The usual Emacs comment commands assume that a comment can follow a line
3551 of code. In Fortran, the standard comment syntax requires an entire line
3552 to be just a comment. Therefore, Fortran mode replaces the standard Emacs
3553 comment commands and defines some new variables.
3555 Fortran mode can also handle the Fortran90 comment syntax where comments
3556 start with @samp{!} and can follow other text. Because only some Fortran77
3557 compilers accept this syntax, Fortran mode will not insert such comments
3558 unless you have said in advance to do so. To do this, set the variable
3559 @code{comment-start} to @samp{"!"} (@pxref{Variables}).
3563 Align comment or insert new comment (@code{fortran-comment-indent}).
3566 Applies to nonstandard @samp{!} comments only.
3569 Turn all lines of the region into comments, or (with argument) turn them back
3570 into real code (@code{fortran-comment-region}).
3573 @kbd{M-;} in Fortran mode is redefined as the command
3574 @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
3575 recognizes any kind of existing comment and aligns its text appropriately;
3576 if there is no existing comment, a comment is inserted and aligned. But
3577 inserting and aligning comments are not the same in Fortran mode as in
3580 When a new comment must be inserted, if the current line is blank, a
3581 full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
3582 comment is inserted if you have said you want to use them. Otherwise a
3583 full-line comment is inserted on a new line before the current line.
3585 Nonstandard @samp{!} comments are aligned like comments in other
3586 languages, but full-line comments are different. In a standard full-line
3587 comment, the comment delimiter itself must always appear in column zero.
3588 What can be aligned is the text within the comment. You can choose from
3589 three styles of alignment by setting the variable
3590 @code{fortran-comment-indent-style} to one of these values:
3592 @vindex fortran-comment-indent-style
3593 @vindex fortran-comment-line-extra-indent
3596 Align the text at a fixed column, which is the sum of
3597 @code{fortran-comment-line-extra-indent} and the minimum statement
3598 indentation. This is the default.
3600 The minimum statement indentation is
3601 @code{fortran-minimum-statement-indent-fixed} for fixed format
3602 continuation line style and @code{fortran-minimum-statement-indent-tab}
3603 for tab format style.
3606 Align the text as if it were a line of code, but with an additional
3607 @code{fortran-comment-line-extra-indent} columns of indentation.
3610 Don't move text in full-line comments automatically at all.
3613 @vindex fortran-comment-indent-char
3614 In addition, you can specify the character to be used to indent within
3615 full-line comments by setting the variable
3616 @code{fortran-comment-indent-char} to the single-character string you want
3619 @vindex comment-line-start
3620 @vindex comment-line-start-skip
3621 Fortran mode introduces two variables @code{comment-line-start} and
3622 @code{comment-line-start-skip}, which play for full-line comments the same
3623 roles played by @code{comment-start} and @code{comment-start-skip} for
3624 ordinary text-following comments. Normally these are set properly by
3625 Fortran mode, so you do not need to change them.
3627 The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
3628 you use @samp{!} comments, this command can be used with them. Otherwise
3629 it is useless in Fortran mode.
3631 @kindex C-c ; @r{(Fortran mode)}
3632 @findex fortran-comment-region
3633 @vindex fortran-comment-region
3634 The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
3635 lines of the region into comments by inserting the string @samp{C$$$} at
3636 the front of each one. With a numeric argument, it turns the region
3637 back into live code by deleting @samp{C$$$} from the front of each line
3638 in it. The string used for these comments can be controlled by setting
3639 the variable @code{fortran-comment-region}. Note that here we have an
3640 example of a command and a variable with the same name; these two uses
3641 of the name never conflict because in Lisp and in Emacs it is always
3642 clear from the context which one is meant.
3644 @node Fortran Autofill
3645 @subsection Fortran Auto Fill Mode
3647 Fortran Auto Fill mode is a minor mode which automatically splits
3648 Fortran statements as you insert them when they become too wide.
3649 Splitting a statement involves making continuation lines using
3650 @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This
3651 splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
3652 also in the Fortran indentation commands.
3654 @findex fortran-auto-fill-mode
3655 @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
3656 was off, or off if it was on. This command works the same as @kbd{M-x
3657 auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
3658 positive numeric argument turns Fortran Auto Fill mode on, and a
3659 negative argument turns it off. You can see when Fortran Auto Fill mode
3660 is in effect by the presence of the word @samp{Fill} in the mode line,
3661 inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
3662 on or off for each buffer individually. @xref{Minor Modes}.
3664 @vindex fortran-break-before-delimiters
3665 Fortran Auto Fill mode breaks lines at spaces or delimiters when the
3666 lines get longer than the desired width (the value of @code{fill-column}).
3667 The delimiters that Fortran Auto Fill mode may break at are @samp{,},
3668 @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
3669 The line break comes after the delimiter if the variable
3670 @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by
3671 default), the break comes before the delimiter.
3673 By default, Fortran Auto Fill mode is not enabled. If you want this
3674 feature turned on permanently, add a hook function to
3675 @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
3678 @node Fortran Columns
3679 @subsection Checking Columns in Fortran
3683 Display a ``column ruler'' momentarily above the current line
3684 (@code{fortran-column-ruler}).
3686 Split the current window horizontally temporarily so that it is 72
3687 columns wide. This may help you avoid making lines longer than the
3688 72-character limit that some Fortran compilers impose
3689 (@code{fortran-window-create-momentarily}).
3692 @kindex C-c C-r @r{(Fortran mode)}
3693 @findex fortran-column-ruler
3694 @vindex fortran-column-ruler
3695 The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
3696 ruler momentarily above the current line. The comment ruler is two lines
3697 of text that show you the locations of columns with special significance in
3698 Fortran programs. Square brackets show the limits of the columns for line
3699 numbers, and curly brackets show the limits of the columns for the
3700 statement body. Column numbers appear above them.
3702 Note that the column numbers count from zero, as always in GNU Emacs.
3703 As a result, the numbers may be one less than those you are familiar
3704 with; but the positions they indicate in the line are standard for
3707 The text used to display the column ruler depends on the value of
3708 the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
3709 @code{nil}, then the value of the variable
3710 @code{fortran-column-ruler-fixed} is used as the column ruler.
3711 Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
3712 By changing these variables, you can change the column ruler display.
3714 @kindex C-u C-c C-w @r{(Fortran mode)}
3715 @findex fortran-window-create
3716 For even more help, use @kbd{M-x fortran-window-create}), a
3717 command which splits the current window horizontally, making a window 72
3718 columns wide. By editing in this window you can immediately see when you
3719 make a line too wide to be correct Fortran.
3721 @kindex C-c C-w @r{(Fortran mode)}
3722 @findex fortran-window-create-momentarily
3723 Also, @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) can be
3724 used temporarily to split the current window horizontally, making a
3725 window 72 columns wide to check column widths rather than to edit in
3726 this mode. The normal width is restored when you type a space.
3728 @node Fortran Abbrev
3729 @subsection Fortran Keyword Abbrevs
3731 Fortran mode provides many built-in abbrevs for common keywords and
3732 declarations. These are the same sort of abbrev that you can define
3733 yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}.
3735 The built-in abbrevs are unusual in one way: they all start with a
3736 semicolon. You cannot normally use semicolon in an abbrev, but Fortran
3737 mode makes this possible by changing the syntax of semicolon to ``word
3740 For example, one built-in Fortran abbrev is @samp{;c} for
3741 @samp{continue}. If you insert @samp{;c} and then insert a punctuation
3742 character such as a space or a newline, the @samp{;c} expands automatically
3743 to @samp{continue}, provided Abbrev mode is enabled.@refill
3745 Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
3746 Fortran abbrevs and what they stand for.
3749 @subsection Other Fortran Mode Commands
3751 The command @kbd{fortran-strip-sqeuence-nos} can be used to remove text
3752 past Fortran column 72, which is typically old `sequence numbers'.
3758 @cindex Assembler mode
3759 Asm mode is a major mode for editing files of assembler code. It
3760 defines these commands:
3764 @code{tab-to-tab-stop}.
3766 Insert a newline and then indent using @code{tab-to-tab-stop}.
3768 Insert a colon and then remove the indentation from before the label
3769 preceding colon. Then do @code{tab-to-tab-stop}.
3771 Insert or align a comment.
3774 The variable @code{asm-comment-char} specifies which character
3775 starts comments in assembler syntax.