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 provides many features to facilitate editing programs. These
15 Move over or kill balanced expressions (@pxref{Lists}).
17 Move over or mark top-level expressions, such as @dfn{defuns} in
18 Lisp, or function definitions 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}).
27 Highlight program syntax (@pxref{Font Lock}).
29 Compile and debug programs (@pxref{Building}).
33 * Misc for Programs:: Other Emacs features useful for editing programs.
34 * Program Modes:: Major modes for editing programs.
35 * Lists:: Expressions with balanced parentheses.
36 * List Commands:: The commands for working with list and sexps.
37 * Defuns:: Each program is made up of separate functions.
38 There are editing commands to operate on them.
39 * Program Indent:: Adjusting indentation to show the nesting.
40 * Matching:: Insertion of a close-delimiter flashes matching open.
41 * Comments:: Inserting, killing, and aligning comments.
42 * Balanced Editing:: Inserting two matching parentheses at once, etc.
43 * Symbol Completion:: Completion on symbol names of your program or language.
44 * Which Function:: Which Function mode shows which function you are in.
45 * Hideshow:: Displaying blocks selectively.
46 * Glasses:: Making identifiersLikeThis more readable.
47 * Documentation:: Getting documentation of functions you plan to call.
48 * Change Log:: Maintaining a change history for your program.
49 * Authors:: Maintaining an @file{AUTHORS} file.
50 * Tags:: Go direct to any function in your program in one
51 command. Tags remembers which file it is in.
52 * Imenu:: Making buffer indexes as menus.
53 * Emerge:: A convenient way of merging two versions of a program.
54 * C Modes:: Special commands of C, C++, Objective-C,
56 * Fortran:: Fortran mode and its special features.
57 * Asm Mode:: Asm mode and its special features.
60 @node Misc for Programs
61 @section Other Features Useful for Editing Programs
63 A number of Emacs commands that aren't designed specifically for
64 editing programs are useful for it nonetheless.
66 The Emacs commands that operate on words, sentences and paragraphs
67 are useful for editing code. Most symbols names contain words
68 (@pxref{Words}); sentences can be found in strings and comments
69 (@pxref{Sentences}). Paragraphs in the strict sense may be found in
70 program code (in long comments), but the paragraph commands are useful
71 in other places too, because programming language major modes define
72 paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
73 Judicious use of blank lines to make the program clearer will also
74 provide useful chunks of text for the paragraph commands to work on.
76 The selective display feature is useful for looking at the overall
77 structure of a function (@pxref{Selective Display}). This feature
78 hides the lines that are indented more than a specified amount.
79 Programming modes often support Outline minor mode (@pxref{Outline
80 Mode}). The Foldout package provides folding-editor features
83 The ``automatic typing'' features may be useful for writing programs.
84 @xref{Top,,Autotyping, autotype, Autotyping}.
87 @section Major Modes for Programming Languages
88 @cindex modes for programming languages
90 Emacs has specialized major modes for various programming languages.
91 @xref{Major Modes}. A programming language major mode typically
92 specifies the syntax of expressions, the customary rules for
93 indentation, how to do syntax highlighting for the language, and how
94 to find the beginning of a function definition. They often provide
95 facilities for compiling and debugging programs as well.
97 Ideally, Emacs should provide a major mode for each programming
98 language that you might want to edit; if it doesn't have a mode for
99 your favorite language, you can contribute one. But often the mode
100 for one language can serve for other syntactically similar languages.
101 The major mode for language @var{l} is called @code{@var{l}-mode},
102 and you can enable it by typing @kbd{M-x @var{l}-mode @key{RET}}.
103 @xref{Choosing Modes}.
108 @cindex Makefile mode
113 @cindex Metafont mode
119 @cindex Shell-script mode
121 @cindex PostScript mode
122 The existing programming language major modes include Lisp, Scheme (a
123 variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
124 Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
125 format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
126 companion for font creation), Modula2, Objective-C, Octave, Pascal,
127 Perl, Pike, PostScript, Prolog, Simula, and Tcl, and VHDL. There is
128 also a major mode for makefiles, called Makefile mode. An alternative
129 mode for Perl is called CPerl mode. Modes are available for the
130 scripting languages of the common Unix shells, VMS DCL, and
131 MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
132 editing various sorts of configuration files.
134 @kindex DEL @r{(programming modes)}
135 @findex c-electric-backspace
136 In most programming languages, indentation is likely to vary from
137 line to line. So the major modes for those languages rebind @key{DEL}
138 to treat a tab as if it were the equivalent number of spaces. This
139 makes it possible to reduce indentation one column at a time without
140 worrying whether it is made up of spaces or tabs. Use @kbd{C-b C-d}
141 to delete a tab character before point, in these modes.
143 Programming language modes define paragraphs to be separated only by
144 blank lines, so that the paragraph commands remain useful. Auto Fill mode,
145 if enabled in a programming language major mode, indents the new lines
148 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
149 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
150 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
151 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
155 @vindex lisp-mode-hook
156 @vindex emacs-lisp-mode-hook
157 @vindex lisp-interaction-mode-hook
158 @vindex scheme-mode-hook
159 Turning on a major mode runs a normal hook called the @dfn{mode hook},
160 which is the value of a Lisp variable. Each major mode has a mode hook,
161 and the hook's name is always made from the mode command's name by
162 adding @samp{-hook}. For example, turning on C mode runs the hook
163 @code{c-mode-hook}, while turning on Lisp mode runs the hook
164 @code{lisp-mode-hook}. @xref{Hooks}.
167 @section Lists and Sexps
170 By convention, Emacs keys for dealing with balanced expressions are
171 Control-Meta characters. They act like the corresponding Control and
172 Meta equivalents, except that they operate on balanced expressions
173 instead of on characters or words. For instance, the command
174 @kbd{C-M-b} moves backward over a balanced expression, just as
175 @kbd{C-b} moves back over a character and @kbd{M-b} moves back over a
176 word. These commands are intended for expressions in programming
177 languages, but can be useful for editing any text that has
183 These commands fall into two classes. Some deal only with @dfn{lists}
184 (parenthetical groupings). They see nothing except parentheses, brackets,
185 braces (whichever ones must balance in the language you are working with),
186 and escape characters that might be used to quote those.
188 The other commands deal with expressions or @dfn{sexps}. The word ``sexp''
189 is derived from @dfn{s-expression}, the ancient term for an expression in
190 Lisp. But in Emacs, the notion of ``sexp'' is not limited to Lisp. It
191 refers to an expression in whatever language your program is written in.
192 Each programming language has its own major mode, which customizes the
193 syntax tables so that expressions in that language count as sexps.
195 Sexps typically include symbols, numbers, and string constants, as well
196 as anything contained in parentheses, brackets or braces.
198 In languages that use prefix and infix operators, such as C, it is not
199 possible for all expressions to be sexps. For example, C mode does not
200 recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression;
201 it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
202 @samp{+} as punctuation between them. This is a fundamental ambiguity:
203 both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
204 move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
205 single sexp in C mode.
207 Some languages have obscure forms of expression syntax that nobody
208 has bothered to make Emacs understand properly.
211 @section List And Sexp Commands
213 @c doublewidecommands
216 Move forward over a sexp (@code{forward-sexp}).
218 Move backward over a sexp (@code{backward-sexp}).
220 Kill sexp forward (@code{kill-sexp}).
222 Kill sexp backward (@code{backward-kill-sexp}).
224 Move up and backward in list structure (@code{backward-up-list}).
226 Move down and forward in list structure (@code{down-list}).
228 Move forward over a list (@code{forward-list}).
230 Move backward over a list (@code{backward-list}).
232 Transpose expressions (@code{transpose-sexps}).
234 Put mark after following expression (@code{mark-sexp}).
237 @cindex parentheses, moving across
238 @cindex matching parenthesis and braces, moving to
239 @cindex braces, moving across
243 @findex backward-sexp
244 To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
245 the first significant character after point is an opening delimiter
246 (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
247 moves past the matching closing delimiter. If the character begins a
248 symbol, string, or number, @kbd{C-M-f} moves over that.
250 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
251 sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
252 directions reversed. If there are any prefix characters (single-quote,
253 backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
254 over them as well. The sexp commands move across comments as if they
255 were whitespace in most modes.
257 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
258 specified number of times; with a negative argument, it moves in the
261 @cindex deleting parenthesized expressions
265 @findex backward-kill-sexp
266 Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp})
267 or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills
268 the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}}
269 kills the characters that @kbd{C-M-b} would move over.
274 @findex backward-list
275 The @dfn{list commands} move over lists, as the sexp commands do, but skip
276 blithely over any number of other kinds of sexps (symbols, strings, etc.).
277 They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
278 (@code{backward-list}). The main reason they are useful is that they
279 usually ignore comments (since the comments usually do not contain any
284 @findex backward-up-list
286 @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
287 that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u}
288 (@code{backward-up-list}).
289 @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
290 positive argument serves as a repeat count; a negative argument reverses
291 direction of motion and also requests repetition, so it moves forward and
292 up one or more levels.@refill
294 To move @emph{down} in list structure, use @kbd{C-M-d}
295 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
296 delimiter, this is nearly the same as searching for a @samp{(}. An
297 argument specifies the number of levels of parentheses to go down.
299 @cindex transposition of parenthesized expressions
301 @findex transpose-sexps
302 A somewhat random-sounding command which is nevertheless handy is
303 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp
304 across the next one. An argument serves as a repeat count, and a
305 negative argument drags backwards (thus canceling out the effect of
306 @kbd{C-M-t} with a positive argument). An argument of zero, rather than
307 doing nothing, transposes the sexps ending after point and the mark.
311 To set the region around the next sexp in the buffer, use @kbd{C-M-@@}
312 (@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f}
313 would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In
314 particular, a negative argument is useful for putting the mark at the
315 beginning of the previous sexp.
317 The list and sexp commands' understanding of syntax is completely
318 controlled by the syntax table. Any character can, for example, be
319 declared to be an opening delimiter and act like an open parenthesis.
326 In Emacs, a parenthetical grouping at the top level in the buffer is
327 called a @dfn{defun}. The name derives from the fact that most top-level
328 lists in a Lisp file are instances of the special form @code{defun}, but
329 any top-level parenthetical grouping counts as a defun in Emacs parlance
330 regardless of what its contents are, and regardless of the programming
331 language in use. For example, in C, the body of a function definition is a
335 @cindex move to beginning or end of function
336 @cindex function, move to beginning or end
340 @findex beginning-of-defun
343 @c doublewidecommands
346 Move to beginning of current or preceding defun
347 (@code{beginning-of-defun}).
349 Move to end of current or following defun (@code{end-of-defun}).
351 Put region around whole current or following defun (@code{mark-defun}).
354 @kindex C-M-h @r{(C mode)}
355 @findex c-mark-function
356 If you wish to operate on the current defun, use @kbd{C-M-h}
357 (@code{mark-defun}) which puts point at the beginning and mark at the end
358 of the current or next defun. For example, this is the easiest way to get
359 ready to move the defun to a different place in the text. In C mode,
360 @kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the
361 same as @code{mark-defun}; the difference is that it backs up over the
362 argument declarations, function name and returned data type so that the
363 entire C function is inside the region. @xref{Marking Objects}.
365 @cindex open-parenthesis in leftmost column
366 @cindex ( in leftmost column
367 Emacs assumes that any open-parenthesis found in the leftmost column
368 is the start of a defun. Therefore, @strong{never put an
369 open-parenthesis at the left margin in a Lisp file unless it is the
370 start of a top-level list. Never put an open-brace or other opening
371 delimiter at the beginning of a line of C code unless it starts the body
372 of a function.} The most likely problem case is when you want an
373 opening delimiter at the start of a line inside a string. To avoid
374 trouble, put an escape character (@samp{\}, in C and Emacs Lisp,
375 @samp{/} in some other Lisp dialects) before the opening delimiter. It
376 will not affect the contents of the string.
378 In the remotest past, the original Emacs found defuns by moving upward a
379 level of parentheses until there were no more levels to go up. This always
380 required scanning all the way back to the beginning of the buffer, even for
381 a small function. To speed up the operation, Emacs was changed to assume
382 that any @samp{(} (or other character assigned the syntactic class of
383 opening-delimiter) at the left margin is the start of a defun. This
384 heuristic is nearly always right and avoids the costly scan; however,
385 it mandates the convention described above.
388 @section Indentation for Programs
389 @cindex indentation for programs
391 The best way to keep a program properly indented is to use Emacs to
392 reindent it as you change it. Emacs has commands to indent properly
393 either a single line, a specified number of lines, or all of the lines
394 inside a single parenthetical grouping.
397 * Basic Indent:: Indenting a single line.
398 * Multi-line Indent:: Commands to reindent many lines at once.
399 * Lisp Indent:: Specifying how each Lisp function should be indented.
400 * C Indent:: Extra features for indenting C and related modes.
401 * Custom C Indent:: Controlling indentation style for C and related modes.
404 Emacs also provides a Lisp pretty-printer in the library @code{pp}.
405 This program reformats a Lisp object with indentation chosen to look nice.
408 @subsection Basic Program Indentation Commands
410 Programming language major modes define the @key{TAB} key to indent
411 according to the usual conventions of the language you are editing.
412 @kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
413 thus, it too indents in a mode-specific fashion.
418 Adjust indentation of current line.
420 Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
423 @kindex TAB @r{(programming modes)}
424 @findex c-indent-command
425 @findex indent-line-function
426 The basic indentation command is @key{TAB}, which gives the current line
427 the correct indentation as determined from the previous lines. The
428 function that @key{TAB} runs depends on the major mode; it is
429 @code{indent-for-tab-command}
430 in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
431 understand the syntax and conventions of different languages, but they all do
432 conceptually the same job: @key{TAB} in any programming-language major mode
433 inserts or deletes whitespace at the beginning of the current line,
434 independent of where point is in the line. If point was inside the
435 whitespace at the beginning of the line, @key{TAB} puts it at the end of
436 that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
437 the characters around it.
439 Use @kbd{C-q @key{TAB}} to insert a tab at point.
442 @findex newline-and-indent
443 When entering lines of new code, use @kbd{C-j}
444 (@code{newline-and-indent}), which is equivalent to a @key{RET}
445 followed by a @key{TAB}. @kbd{C-j} at the end of a line creates a
446 blank line and then gives it the appropriate indentation.
448 @key{TAB} indents the second and following lines of the body of a
449 parenthetical grouping each under the preceding one; therefore, if you
450 alter one line's indentation to be nonstandard, the lines below will
451 tend to follow it. This behavior is convenient in cases where you have
452 overridden the standard result of @key{TAB} because you find it
453 unaesthetic for a particular line.
455 Remember that an open-parenthesis, open-brace or other opening delimiter
456 at the left margin is assumed by Emacs (including the indentation routines)
457 to be the start of a function. Therefore, you must never have an opening
458 delimiter in column zero that is not the beginning of a function, not even
459 inside a string. This restriction is vital for making the indentation
460 commands fast; you must simply accept it. @xref{Defuns}, for more
463 Normally, lines are indented with tabs and spaces. If you want Emacs
464 to use spaces only, see @ref{Just Spaces}.
466 @node Multi-line Indent
467 @subsection Indenting Several Lines
469 When you wish to reindent several lines of code which have been altered
470 or moved to a different level in the list structure, you have several
475 Reindent all the lines within one list (@code{indent-sexp}).
477 Shift an entire list rigidly sideways so that its first line
478 is properly indented.
480 Reindent all lines in the region (@code{indent-region}).
485 You can reindent the contents of a single list by positioning point
486 before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
487 Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable
488 commands in other modes). The indentation of the line the sexp starts on
489 is not changed; therefore, only the relative indentation within the list,
490 and not its position, is changed. To correct the position as well, type a
491 @key{TAB} before the @kbd{C-M-q}.
494 If the relative indentation within a list is correct but the
495 indentation of its first line is not, go to that line and type @kbd{C-u
496 @key{TAB}}. @key{TAB} with a numeric argument reindents the current
497 line as usual, then reindents by the same amount all the lines in the
498 grouping starting on the current line. In other words, it reindents the
499 whole grouping rigidly as a unit. It is clever, though, and does not
500 alter lines that start inside strings, or C preprocessor lines when in C
503 Another way to specify the range to be reindented is with the region.
504 The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to
505 every line whose first character is between point and mark.
508 @subsection Customizing Lisp Indentation
509 @cindex customizing Lisp indentation
511 The indentation pattern for a Lisp expression can depend on the function
512 called by the expression. For each Lisp function, you can choose among
513 several predefined patterns of indentation, or define an arbitrary one with
516 The standard pattern of indentation is as follows: the second line of the
517 expression is indented under the first argument, if that is on the same
518 line as the beginning of the expression; otherwise, the second line is
519 indented underneath the function name. Each following line is indented
520 under the previous line whose nesting depth is the same.
522 @vindex lisp-indent-offset
523 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
524 the usual indentation pattern for the second line of an expression, so that
525 such lines are always indented @code{lisp-indent-offset} more columns than
528 @vindex lisp-body-indent
529 The standard pattern is overridden for certain functions. Functions
530 whose names start with @code{def} always indent the second line by
531 @code{lisp-body-indent} extra columns beyond the open-parenthesis
532 starting the expression.
534 The standard pattern can be overridden in various ways for individual
535 functions, according to the @code{lisp-indent-function} property of the
536 function name. There are four possibilities for this property:
540 This is the same as no property; the standard indentation pattern is used.
542 The pattern used for function names that start with @code{def} is used for
544 @item a number, @var{number}
545 The first @var{number} arguments of the function are
546 @dfn{distinguished} arguments; the rest are considered the @dfn{body}
547 of the expression. A line in the expression is indented according to
548 whether the first argument on it is distinguished or not. If the
549 argument is part of the body, the line is indented @code{lisp-body-indent}
550 more columns than the open-parenthesis starting the containing
551 expression. If the argument is distinguished and is either the first
552 or second argument, it is indented @emph{twice} that many extra columns.
553 If the argument is distinguished and not the first or second argument,
554 the standard pattern is followed for that line.
555 @item a symbol, @var{symbol}
556 @var{symbol} should be a function name; that function is called to
557 calculate the indentation of a line within this expression. The
558 function receives two arguments:
561 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
562 indentation and nesting computation) when it parses up to the
563 beginning of this line.
565 The position at which the line being indented begins.
568 It should return either a number, which is the number of columns of
569 indentation for that line, or a list whose car is such a number. The
570 difference between returning a number and returning a list is that a
571 number says that all following lines at the same nesting level should
572 be indented just like this one; a list says that following lines might
573 call for different indentations. This makes a difference when the
574 indentation is being computed by @kbd{C-M-q}; if the value is a
575 number, @kbd{C-M-q} need not recalculate indentation for the following
576 lines until the end of the list.
580 @subsection Commands for C Indentation
582 Here are the commands for indentation in C mode and related modes:
586 @kindex C-c C-q @r{(C mode)}
587 @findex c-indent-defun
588 Reindent the current top-level function definition or aggregate type
589 declaration (@code{c-indent-defun}).
592 @kindex C-M-q @r{(C mode)}
594 Reindent each line in the balanced expression that follows point
595 (@code{c-indent-exp}). A prefix argument inhibits error checking and
596 warning messages about invalid syntax.
599 @findex c-indent-command
600 Reindent the current line, and/or in some cases insert a tab character
601 (@code{c-indent-command}).
603 If @code{c-tab-always-indent} is @code{t}, this command always reindents
604 the current line and does nothing else. This is the default.
606 If that variable is @code{nil}, this command reindents the current line
607 only if point is at the left margin or in the line's indentation;
608 otherwise, it inserts a tab (or the equivalent number of spaces,
609 if @code{indent-tabs-mode} is @code{nil}).
611 Any other value (not @code{nil} or @code{t}) means always reindent the
612 line, and also insert a tab if within a comment, a string, or a
613 preprocessor directive.
616 Reindent the current line according to its syntax; also rigidly reindent
617 any other lines of the expression that starts on the current line.
618 @xref{Multi-line Indent}.
621 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
622 first selects the whole buffer as the region, then reindents that
625 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
626 to the front of the block and then reindents it all.
628 @node Custom C Indent
629 @subsection Customizing C Indentation
631 C mode and related modes use a simple yet flexible mechanism for
632 customizing indentation. The mechanism works in two steps: first it
633 classifies the line syntactically according to its contents and context;
634 second, it associates each kind of syntactic construct with an
635 indentation offset which you can customize.
638 * Syntactic Analysis::
639 * Indentation Calculation::
640 * Changing Indent Style::
641 * Syntactic Symbols::
642 * Variables for C Indent::
646 @node Syntactic Analysis
647 @subsubsection Step 1---Syntactic Analysis
648 @cindex syntactic analysis
650 In the first step, the C indentation mechanism looks at the line
651 before the one you are currently indenting and determines the syntactic
652 components of the construct on that line. It builds a list of these
653 syntactic components, each of which contains a @dfn{syntactic symbol}
654 and sometimes also a buffer position. Some syntactic symbols describe
655 grammatical elements, for example @code{statement} and
656 @code{substatement}; others describe locations amidst grammatical
657 elements, for example @code{class-open} and @code{knr-argdecl}.
659 Conceptually, a line of C code is always indented relative to the
660 indentation of some line higher up in the buffer. This is represented
661 by the buffer positions in the syntactic component list.
663 Here is an example. Suppose we have the following code in a C++ mode
664 buffer (the line numbers don't actually appear in the buffer):
667 1: void swap (int& a, int& b)
675 If you type @kbd{C-c C-s} (which runs the command
676 @code{c-show-syntactic-information}) on line 4, it shows the result of
677 the indentation mechanism for that line:
680 syntactic analysis: ((statement . 32))
683 This indicates that the line is a statement and it is indented
684 relative to buffer position 32, which happens to be the @samp{i} in
685 @code{int} on line 3. If you move the cursor to line 3 and type
686 @kbd{C-c C-s}, it displays this:
689 syntactic analysis: ((defun-block-intro . 28))
692 This indicates that the @code{int} line is the first statement in a
693 block, and is indented relative to buffer position 28, which is the
694 brace just after the function header.
697 Here is another example:
700 1: int add (int val, int incr, int doit)
704 5: return (val + incr);
711 Typing @kbd{C-c C-s} on line 4 displays this:
714 syntactic analysis: ((substatement-open . 43))
717 This says that the brace @emph{opens} a substatement block. By the
718 way, a @dfn{substatement} indicates the line after an @code{if},
719 @code{else}, @code{while}, @code{do}, @code{switch}, @code{for},
720 @code{try}, @code{catch}, @code{finally}, or @code{synchronized}
723 @cindex syntactic component
724 @cindex syntactic symbol
725 @vindex c-syntactic-context
726 Within the C indentation commands, after a line has been analyzed
727 syntactically for indentation, the variable @code{c-syntactic-context}
728 contains a list that describes the results. Each element in this list
729 is a @dfn{syntactic component}: a cons cell containing a syntactic
730 symbol and (optionally) its corresponding buffer position. There may be
731 several elements in a component list; typically only one element has a
734 @node Indentation Calculation
735 @subsubsection Step 2---Indentation Calculation
736 @cindex Indentation Calculation
738 The C indentation mechanism calculates the indentation for the current
739 line using the list of syntactic components, @code{c-syntactic-context},
740 derived from syntactic analysis. Each component is a cons cell that
741 contains a syntactic symbol and may also contain a buffer position.
743 Each component contributes to the final total indentation of the line
744 in two ways. First, the syntactic symbol identifies an element of
745 @code{c-offsets-alist}, which is an association list mapping syntactic
746 symbols into indentation offsets. Each syntactic symbol's offset adds
747 to the total indentation. Second, if the component includes a buffer
748 position, the column number of that position adds to the indentation.
749 All these offsets and column numbers, added together, give the total
752 The following examples demonstrate the workings of the C indentation
756 1: void swap (int& a, int& b)
764 Suppose that point is on line 3 and you type @key{TAB} to reindent the
765 line. As explained above (@pxref{Syntactic Analysis}), the syntactic
766 component list for that line is:
769 ((defun-block-intro . 28))
772 In this case, the indentation calculation first looks up
773 @code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose
774 that it finds the integer 2; it adds this to the running total
775 (initialized to zero), yielding a updated total indentation of 2 spaces.
777 The next step is to find the column number of buffer position 28.
778 Since the brace at buffer position 28 is in column zero, this adds 0 to
779 the running total. Since this line has only one syntactic component,
780 the total indentation for the line is 2 spaces.
783 1: int add (int val, int incr, int doit)
787 5: return(val + incr);
793 If you type @key{TAB} on line 4, the same process is performed, but
794 with different data. The syntactic component list for this line is:
797 ((substatement-open . 43))
800 Here, the indentation calculation's first job is to look up the
801 symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume
802 that the offset for this symbol is 2. At this point the running total
803 is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43,
804 which is the @samp{i} in @code{if} on line 3. This character is in
805 column 2 on that line. Adding this yields a total indentation of 4
808 @vindex c-strict-syntax-p
809 If a syntactic symbol in the analysis of a line does not appear in
810 @code{c-offsets-alist}, it is ignored.
812 @node Changing Indent Style
813 @subsubsection Changing Indentation Style
815 There are two ways to customize the indentation style for the C-like
816 modes. First, you can select one of several predefined styles, each of
817 which specifies offsets for all the syntactic symbols. For more
818 flexibility, you can customize the handling of individual syntactic
819 symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic
823 @item M-x c-set-style @key{RET} @var{style} @key{RET}
824 Select predefined indentation style @var{style}. Type @kbd{?} when
825 entering @var{style} to see a list of supported styles; to find out what
826 a style looks like, select it and reindent some C code.
828 @item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET}
829 Set the indentation offset for syntactic symbol @var{symbol}
830 (@code{c-set-offset}). The second argument @var{offset} specifies the
831 new indentation offset.
834 The @code{c-offsets-alist} variable controls the amount of
835 indentation to give to each syntactic symbol. Its value is an
836 association list, and each element of the list has the form
837 @code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets
838 for various syntactic symbols, you can customize indentation in fine
839 detail. To change this alist, use @code{c-set-offset} (see below).
841 Each offset value in @code{c-offsets-alist} can be an integer, a
842 function or variable name, a list, or one of the following symbols: @code{+},
843 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative
844 multiples of the variable @code{c-basic-offset}. Thus, if you want to
845 change the levels of indentation to be 3 spaces instead of 2 spaces, set
846 @code{c-basic-offset} to 3.
848 Using a function as the offset value provides the ultimate flexibility
849 in customizing indentation. The function is called with a single
850 argument containing the @code{cons} of the syntactic symbol and
851 the buffer position, if any. The function should return an integer
854 If the offset value is a list, its elements are processed according
855 to the rules above until a non-@code{nil} value is found. That value is
856 then added to the total indentation in the normal manner. The primary
857 use for this is to combine the results of several functions.
859 @kindex C-c C-o @r{(C mode)}
861 The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to
862 set offsets, both interactively or in your @file{~/.emacs} file. First
863 specify the syntactic symbol, then the offset you want. @xref{Syntactic
864 Symbols}, for a list of valid syntactic symbols and their meanings.
866 @node Syntactic Symbols
867 @subsubsection Syntactic Symbols
869 Here is a table of valid syntactic symbols for indentation in C and
870 related modes, with their syntactic meanings. Normally, most of these
871 symbols are assigned offsets in @code{c-offsets-alist}.
875 Inside a multi-line string.
878 Inside a multi-line C style block comment.
881 On a brace that opens a function definition.
884 On a brace that closes a function definition.
886 @item defun-block-intro
887 In the first line in a top-level defun.
890 On a brace that opens a class definition.
893 On a brace that closes a class definition.
896 On a brace that opens an in-class inline method.
899 On a brace that closes an in-class inline method.
901 @item extern-lang-open
902 On a brace that opens an external language block.
904 @item extern-lang-close
905 On a brace that closes an external language block.
908 The region between a function definition's argument list and the defun
909 opening brace (excluding K&R function definitions). In C, you cannot
910 put anything but whitespace and comments between them; in C++ and Java,
911 @code{throws} declarations and other things can appear in this context.
913 @item knr-argdecl-intro
914 On the first line of a K&R C argument declaration.
917 In one of the subsequent lines in a K&R C argument declaration.
920 On the first line in a topmost construct definition.
922 @item topmost-intro-cont
923 On the topmost definition continuation lines.
925 @item member-init-intro
926 On the first line in a member initialization list.
928 @item member-init-cont
929 On one of the subsequent member initialization list lines.
932 On the first line of a multiple inheritance list.
935 On one of the subsequent multiple inheritance lines.
938 On a statement block open brace.
941 On a statement block close brace.
943 @item brace-list-open
944 On the opening brace of an @code{enum} or @code{static} array list.
946 @item brace-list-close
947 On the closing brace of an @code{enum} or @code{static} array list.
949 @item brace-list-intro
950 On the first line in an @code{enum} or @code{static} array list.
952 @item brace-list-entry
953 On one of the subsequent lines in an @code{enum} or @code{static} array
956 @item brace-entry-open
957 On one of the subsequent lines in an @code{enum} or @code{static} array
958 list, when the line begins with an open brace.
961 On an ordinary statement.
964 On a continuation line of a statement.
966 @item statement-block-intro
967 On the first line in a new statement block.
969 @item statement-case-intro
970 On the first line in a @code{case} ``block.''
972 @item statement-case-open
973 On the first line in a @code{case} block starting with brace.
975 @item inexpr-statement
976 On a statement block inside an expression. This is used for a GNU
977 extension to the C language, and for Pike special functions that take a
978 statement block as an argument.
981 On a class definition inside an expression. This is used for anonymous
982 classes and anonymous array initializers in Java.
985 On the first line after an @code{if}, @code{while}, @code{for},
986 @code{do}, or @code{else}.
988 @item substatement-open
989 On the brace that opens a substatement block.
992 On a @code{case} or @code{default} label.
995 On a C++ @code{private}, @code{protected}, or @code{public} access label.
998 On any ordinary label.
1000 @item do-while-closure
1001 On the @code{while} that ends a @code{do}-@code{while} construct.
1004 On the @code{else} of an @code{if}-@code{else} construct.
1007 On the @code{catch} and @code{finally} lines in
1008 @code{try}@dots{}@code{catch} constructs in C++ and Java.
1011 On a line containing only a comment introduction.
1014 On the first line in an argument list.
1017 On one of the subsequent argument list lines when no arguments follow on
1018 the same line as the arglist opening parenthesis.
1020 @item arglist-cont-nonempty
1021 On one of the subsequent argument list lines when at least one argument
1022 follows on the same line as the arglist opening parenthesis.
1025 On the closing parenthesis of an argument list.
1028 On one of the lines continuing a stream operator construct.
1031 On a construct that is nested inside a class definition. The
1032 indentation is relative to the open brace of the class definition.
1035 On a construct that is nested inside an external language block.
1037 @item inexpr-statement
1038 On the first line of statement block inside an expression. This is used
1039 for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}.
1040 It is also used for the special functions that takes a statement block
1041 as an argument in Pike.
1044 On the first line of a class definition inside an expression. This is
1045 used for anonymous classes and anonymous array initializers in Java.
1048 On the start of a cpp macro.
1051 On a C++ @code{friend} declaration.
1053 @item objc-method-intro
1054 On the first line of an Objective-C method definition.
1056 @item objc-method-args-cont
1057 On one of the lines continuing an Objective-C method definition.
1059 @item objc-method-call-cont
1060 On one of the lines continuing an Objective-C method call.
1063 Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only
1066 @item lambda-intro-cont
1067 On a line continuing the header of a lambda function, between the
1068 @code{lambda} keyword and the function body. Only used in Pike.
1071 @node Variables for C Indent
1072 @subsubsection Variables for C Indentation
1074 This section describes additional variables which control the
1075 indentation behavior of C mode and related mode.
1078 @item c-offsets-alist
1079 @vindex c-offsets-alist
1080 Association list of syntactic symbols and their indentation offsets.
1081 You should not set this directly, only with @code{c-set-offset}.
1082 @xref{Changing Indent Style}, for details.
1085 @vindex c-style-alist
1086 Variable for defining indentation styles; see below.
1088 @item c-basic-offset
1089 @vindex c-basic-offset
1090 Amount of basic offset used by @code{+} and @code{-} symbols in
1091 @code{c-offsets-alist}.@refill
1093 @item c-special-indent-hook
1094 @vindex c-special-indent-hook
1095 Hook for user-defined special indentation adjustments. This hook is
1096 called after a line is indented by C mode and related modes.
1099 The variable @code{c-style-alist} specifies the predefined indentation
1100 styles. Each element has form @code{(@var{name}
1101 @var{variable-setting}@dots{})}, where @var{name} is the name of the
1102 style. Each @var{variable-setting} has the form @code{(@var{variable}
1103 . @var{value})}; @var{variable} is one of the customization variables
1104 used by C mode, and @var{value} is the value for that variable when
1105 using the selected style.
1107 When @var{variable} is @code{c-offsets-alist}, that is a special case:
1108 @var{value} is appended to the front of the value of @code{c-offsets-alist}
1109 instead of replacing that value outright. Therefore, it is not necessary
1110 for @var{value} to specify each and every syntactic symbol---only those
1111 for which the style differs from the default.
1113 The indentation of lines containing only comments is also affected by
1114 the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}).
1116 @node C Indent Styles
1117 @subsubsection C Indentation Styles
1118 @cindex c indentation styles
1120 A @dfn{C style} is a collection of indentation style customizations.
1121 Emacs comes with several predefined indentation styles for C and related
1122 modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup},
1123 @code{linux}, @code{python}, @code{java}, @code{whitesmith},
1124 @code{ellemtel}, @code{cc-mode}, and @code{user}.
1127 @vindex c-default-style
1128 To choose the style you want, use the command @kbd{M-x c-set-style}.
1129 Specify a style name as an argument (case is not significant in C style
1130 names). The chosen style only affects newly visited buffers, not those
1131 you are already editing. You can also set the variable
1132 @code{c-default-style} to specify the style for various major modes.
1133 Its value should be an alist, in which each element specifies one major
1134 mode and which indentation style to use for it. For example,
1137 (setq c-default-style
1138 '((java-mode . "java") (other . "gnu")))
1142 specifies an explicit choice for Java mode, and the default @samp{gnu}
1143 style for the other C-like modes.
1145 The style @code{gnu} defines the formatting recommend by the GNU
1146 Project; it is the default, so as to encourage the indentation we
1147 recommend. However, if you make changes in variables such as
1148 @code{c-basic-offset} and @code{c-offsets-alist} in your
1149 @file{~/.emacs} file, your changes override the what @code{gnu} style
1153 To define a new C indentation style, call the function
1157 (c-add-style @var{name} @var{values} @var{use-now})
1161 Here @var{name} is the name of the new style (a string), and
1162 @var{values} is an alist whose elements have the form
1163 @code{(@var{variable} . @var{value})}. The variables you specify should
1164 be among those documented in @ref{Variables for C Indent}.
1166 If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new
1167 style after defining it.
1170 @section Automatic Display Of Matching Parentheses
1171 @cindex matching parentheses
1172 @cindex parentheses, displaying matches
1174 The Emacs parenthesis-matching feature is designed to show
1175 automatically how parentheses match in the text. Whenever you type a
1176 self-inserting character that is a closing delimiter, the cursor moves
1177 momentarily to the location of the matching opening delimiter, provided
1178 that is on the screen. If it is not on the screen, some text near it is
1179 displayed in the echo area. Either way, you can tell what grouping is
1182 In Lisp, automatic matching applies only to parentheses. In C, it
1183 applies to braces and brackets too. Emacs knows which characters to regard
1184 as matching delimiters based on the syntax table, which is set by the major
1185 mode. @xref{Syntax}.
1187 If the opening delimiter and closing delimiter are mismatched---such as
1188 in @samp{[x)}---a warning message is displayed in the echo area. The
1189 correct matches are specified in the syntax table.
1191 @vindex blink-matching-paren
1192 @vindex blink-matching-paren-distance
1193 @vindex blink-matching-delay
1194 Three variables control parenthesis match display.
1195 @code{blink-matching-paren} turns the feature on or off; @code{nil}
1196 turns it off, but the default is @code{t} to turn match display on.
1197 @code{blink-matching-delay} says how many seconds to wait; the default
1198 is 1, but on some systems it is useful to specify a fraction of a
1199 second. @code{blink-matching-paren-distance} specifies how many
1200 characters back to search to find the matching opening delimiter. If
1201 the match is not found in that far, scanning stops, and nothing is
1202 displayed. This is to prevent scanning for the matching delimiter from
1203 wasting lots of time when there is no match. The default is 25600.
1205 @cindex Show Paren mode
1206 @cindex highlighting matching parentheses
1207 @findex show-paren-mode
1208 Show Paren mode provides a more powerful kind of automatic
1209 parenthesis matching. Whenever point is after a close parenthesis,
1210 the close parenthesis and its matching open parenthesis are both
1211 highlighted; otherwise, if point is before an open parenthesis, the
1212 matching close parenthesis is highlighted. (There is no need to
1213 highlight the open parenthesis after point because the cursor appears
1214 on top of that character.) Use the command @kbd{M-x show-paren-mode}
1215 to enable or disable this mode.
1217 By default, @code{show-paren-mode} uses colors to highlight the
1218 parentheses. However, if your display doesn't support colors, you can
1219 customize the faces @code{show-paren-match-face} and
1220 @code{show-paren-mismatch-face} to use other attributes, such as bold or
1221 underline. @xref{Face Customization}.
1224 @section Manipulating Comments
1227 Because comments are such an important part of programming, Emacs
1228 provides special commands for editing and inserting comments.
1231 * Comment Commands::
1232 * Multi-Line Comments::
1233 * Options for Comments::
1236 @node Comment Commands
1237 @subsection Comment Commands
1238 @cindex indentation for comments
1240 The comment commands in this table insert, kill and align comments.
1241 They are described in this section and following sections.
1245 Insert or realign comment on current line; alternatively, comment or
1246 uncomment the region (@code{comment-dwim}).
1248 Kill comment on current line (@code{comment-kill}).
1250 Set comment column (@code{comment-set-column}).
1252 Like @key{RET} followed by inserting and aligning a comment
1253 (@code{comment-indent-new-line}).
1254 @item M-x comment-region
1255 Add or remove comment delimiters on all the lines in the region.
1259 @findex comment-dwim
1260 The command to create or align a comment is @kbd{M-;}
1261 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
1262 I Mean''; it indicates that this command can be used for many
1263 different jobs relating to comments, depending on the situation where
1266 If there is no comment already on the line, @kbd{M-;} inserts a new
1267 comment, aligned at a specific column called the @dfn{comment column}.
1268 The new comment begins with the string Emacs thinks comments should
1269 start with (the value of @code{comment-start}; see below). Point is
1270 after that string, so you can insert the text of the comment right
1271 away. If the major mode has specified a string to terminate comments,
1272 @kbd{M-;} inserts that too, to keep the syntax valid.
1274 If the text of the line extends past the comment column, then the
1275 comment start string is indented to a suitable boundary (usually, at
1276 least one space is inserted).
1278 You can also use @kbd{M-;} to align an existing comment. If a line
1279 already contains the comment-start string, @kbd{M-;} reindents it to
1280 the conventional alignment and moves point after it. (Exception:
1281 comments starting in column 0 are not moved.) Even when an existing
1282 comment is properly aligned, @kbd{M-;} is still useful for moving
1283 directly to the start of the text inside the comment.
1285 @findex comment-kill
1287 @kbd{C-u M-;} kills any comment on the current line, along with the
1288 whitespace before it. To reinsert the comment on another line, move
1289 to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
1292 Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
1293 (@code{comment-dwim}) with a prefix argument. That command is
1294 programmed so that when it receives a prefix argument it calls
1295 @code{comment-kill}. However, @code{comment-kill} is a valid command
1296 in its own right, and you can bind it directly to a key if you wish.
1298 @kbd{M-;} does two other jobs when used with an active region in
1299 Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
1300 removes comment delimiters on each line of the region. (If every line
1301 is a comment, it removes comment delimiters from each; otherwise, it
1302 adds comment delimiters to each.) If you are not using Transient Mark
1303 mode, then you should use the commands @code{comment-region} and
1304 @code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}).
1305 A prefix argument used in these circumstances specifies how many
1306 comment delimiters to add or how many to delete.
1308 Some major modes have special rules for indenting certain kinds of
1309 comments in certain contexts. For example, in Lisp code, comments which
1310 start with two semicolons are indented as if they were lines of code,
1311 instead of at the comment column. Comments which start with three
1312 semicolons are supposed to start at the left margin. Emacs understands
1313 these conventions by indenting a double-semicolon comment using @key{TAB},
1314 and by not changing the indentation of a triple-semicolon comment at all.
1317 ;; This function is just an example
1318 ;;; Here either two or three semicolons are appropriate.
1320 ;;; And now, the first part of the function:
1321 ;; The following line adds one.
1322 (1+ x)) ; This line adds one.
1325 In C code, a comment preceded on its line by nothing but whitespace
1326 is indented like a line of code.
1328 @node Multi-Line Comments
1329 @subsection Multiple Lines of Comments
1332 @cindex blank lines in programs
1333 @findex comment-indent-new-line
1334 If you are typing a comment and wish to continue it on another line,
1335 you can use the command @kbd{C-M-j} (@code{comment-indent-new-line}).
1336 This terminates the comment you are typing, creates a new blank line
1337 afterward, and begins a new comment indented under the old one. When
1338 Auto Fill mode is on, going past the fill column while typing a comment
1339 causes the comment to be continued in just this fashion. If point is
1340 not at the end of the line when @kbd{C-M-j} is typed, the text on
1341 the rest of the line becomes part of the new comment line.
1343 @findex comment-region
1344 To turn existing lines into comment lines, use the @kbd{M-x
1345 comment-region} command. It adds comment delimiters to the lines that start
1346 in the region, thus commenting them out. With a negative argument, it
1347 does the opposite---it deletes comment delimiters from the lines in the
1350 With a positive argument, @code{comment-region} duplicates the last
1351 character of the comment start sequence it adds; the argument specifies
1352 how many copies of the character to insert. Thus, in Lisp mode,
1353 @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
1354 the comment delimiter is a way of calling attention to the comment. It
1355 can also affect how the comment is indented. In Lisp, for proper
1356 indentation, you should use an argument of two or three, if between defuns;
1357 if within a defun, it must be three.
1359 @node Options for Comments
1360 @subsection Options Controlling Comments
1362 @vindex comment-column
1364 @findex comment-set-column
1365 The comment column is stored in the variable @code{comment-column}. You
1366 can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
1367 (@code{comment-set-column}) sets the comment column to the column point is
1368 at. @kbd{C-u C-x ;} sets the comment column to match the last comment
1369 before point in the buffer, and then does a @kbd{M-;} to align the
1370 current line's comment under the previous one.
1372 The variable @code{comment-column} is per-buffer: setting the variable
1373 in the normal fashion affects only the current buffer, but there is a
1374 default value which you can change with @code{setq-default}.
1375 @xref{Locals}. Many major modes initialize this variable for the
1378 @vindex comment-start-skip
1379 The comment commands recognize comments based on the regular
1380 expression that is the value of the variable @code{comment-start-skip}.
1381 Make sure this regexp does not match the null string. It may match more
1382 than the comment starting delimiter in the strictest sense of the word;
1383 for example, in C mode the value of the variable is
1384 @c This stops M-q from breaking the line inside that @code.
1385 @code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spaces
1386 after the @samp{/*} itself, and accepts C++ style comments also.
1387 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
1388 the string, which is needed to deny the first star its special meaning
1389 in regexp syntax. @xref{Regexps}.)
1391 @vindex comment-start
1393 When a comment command makes a new comment, it inserts the value of
1394 @code{comment-start} to begin it. The value of @code{comment-end} is
1395 inserted after point, so that it will follow the text that you will insert
1396 into the comment. In C mode, @code{comment-start} has the value
1397 @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
1399 @vindex comment-padding
1400 The variable @code{comment-padding} specifies how many spaces
1401 @code{comment-region} should insert on each line between the
1402 comment delimiter and the line's original text. The default is 1,
1403 to insert one space.
1405 @vindex comment-multi-line
1406 The variable @code{comment-multi-line} controls how @kbd{C-M-j}
1407 (@code{indent-new-comment-line}) behaves when used inside a comment. If
1408 @code{comment-multi-line} is @code{nil}, as it normally is, then the
1409 comment on the starting line is terminated and a new comment is started
1410 on the new following line. If @code{comment-multi-line} is not
1411 @code{nil}, then the new following line is set up as part of the same
1412 comment that was found on the starting line. This is done by not
1413 inserting a terminator on the old line, and not inserting a starter on
1414 the new line. In languages where multi-line comments work, the choice
1415 of value for this variable is a matter of taste.
1417 @vindex comment-indent-function
1418 The variable @code{comment-indent-function} should contain a function
1419 that will be called to compute the indentation for a newly inserted
1420 comment or for aligning an existing comment. It is set differently by
1421 various major modes. The function is called with no arguments, but with
1422 point at the beginning of the comment, or at the end of a line if a new
1423 comment is to be inserted. It should return the column in which the
1424 comment ought to start. For example, in Lisp mode, the indent hook
1425 function bases its decision on how many semicolons begin an existing
1426 comment, and on the code in the preceding lines.
1428 @node Balanced Editing
1429 @section Editing Without Unbalanced Parentheses
1433 Put parentheses around next sexp(s) (@code{insert-parentheses}).
1435 Move past next close parenthesis and reindent
1436 (@code{move-past-close-and-reindent}).
1441 @findex insert-parentheses
1442 @findex move-past-close-and-reindent
1443 The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
1444 (@code{move-past-close-and-reindent}) are designed to facilitate a style
1445 of editing which keeps parentheses balanced at all times. @kbd{M-(}
1446 inserts a pair of parentheses, either together as in @samp{()}, or, if
1447 given an argument, around the next several sexps. It leaves point after
1448 the open parenthesis. The command @kbd{M-)} moves past the close
1449 parenthesis, deleting any indentation preceding it, and indenting with
1452 For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
1453 F O O}, which has the same effect except for leaving the cursor before
1454 the close parenthesis.
1456 @vindex parens-require-spaces
1457 @kbd{M-(} may insert a space before the open parenthesis, depending on
1458 the syntax class of the preceding character. Set
1459 @code{parens-require-spaces} to @code{nil} value if you wish to inhibit
1462 @findex check-parens
1463 @cindex unbalanced parentheses and quotes
1464 You can use @kbd{M-x check-parens} to find any unbalanced
1465 parentheses and unbalanced string quotes in a buffer.
1467 @node Symbol Completion
1468 @section Completion for Symbol Names
1469 @cindex completion (symbol names)
1471 Usually completion happens in the minibuffer. But one kind of completion
1472 is available in all buffers: completion for symbol names.
1475 The character @kbd{M-@key{TAB}} runs a command to complete the partial
1476 symbol before point against the set of meaningful symbol names. Any
1477 additional characters determined by the partial name are inserted at
1480 If the partial name in the buffer has more than one possible completion
1481 and they have no additional characters in common, a list of all possible
1482 completions is displayed in another window.
1484 @cindex tags-based completion
1485 @cindex Info index completion
1486 @findex complete-symbol
1487 In most programming language major modes, @kbd{M-@key{TAB}} runs the
1488 command @code{complete-symbol}, which provides two kinds of completion.
1489 Normally it does completion based on a tags table (@pxref{Tags}); with a
1490 numeric argument (regardless of the value), it does completion based on
1491 the names listed in the Info file indexes for your language. Thus, to
1492 complete the name of a symbol defined in your own program, use
1493 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard
1494 library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
1495 completion works only if there is an Info file for the standard library
1496 functions of your language, and only if it is installed at your site.
1498 @cindex Lisp symbol completion
1499 @cindex completion (Lisp symbols)
1500 @findex lisp-complete-symbol
1501 In Emacs-Lisp mode, the name space for completion normally consists of
1502 nontrivial symbols present in Emacs---those that have function
1503 definitions, values or properties. However, if there is an
1504 open-parenthesis immediately before the beginning of the partial symbol,
1505 only symbols with function definitions are considered as completions.
1506 The command which implements this is @code{lisp-complete-symbol}.
1508 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1509 based on the spell-checker's dictionary. @xref{Spelling}.
1511 @node Which Function
1512 @section Which Function Mode
1514 Which Function mode is a minor mode that displays the current function
1515 name in the mode line, as you move around in a buffer.
1517 @findex which-function-mode
1518 @vindex which-func-modes
1519 To enable (or disable) Which Function mode, use the command @kbd{M-x
1520 which-function-mode}. This command is global; it applies to all
1521 buffers, both existing ones and those yet to be created. However, this
1522 only affects certain major modes, those listed in the value of
1523 @code{which-func-modes}. (If the value is @code{t}, then Which Function
1524 mode applies to all major modes that know how to support it---which are
1525 the major modes that support Imenu.)
1528 @section Hideshow minor mode
1530 @findex hs-minor-mode
1531 Hideshow minor mode provides selective display of portions of a
1532 file, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} to
1533 enable or disable this mode, or add @code{hs-minor-mode} to the mode
1534 hook for certain major modes in order to enable it automatically for
1537 Just what constitutes a block depends on the major mode. In C mode
1538 or C++ mode, they are delimited by braces, while in Lisp mode and
1539 similar modes they are delimited by parentheses. Multi-line comments
1540 also count as blocks.
1543 @findex hs-hide-block
1545 @findex hs-show-block
1546 @findex hs-show-region
1547 @findex hs-hide-level
1548 @findex hs-minor-mode
1551 @kindex C-c @@ C-M-h
1552 @kindex C-c @@ C-M-s
1558 Hide the current block (@code{hs-hide-block}).
1560 Show the current block (@code{hs-show-block}).
1562 Either hide or show the current block (@code{hs-toggle-hiding})
1564 Either hide or show the block you click on (@code{hs-mouse-toggle-hiding})
1566 Hide all top-level blocks (@code{hs-hide-all}).
1568 Show everything in the buffer (@code{hs-show-all}).
1570 Hide all blocks @var{n} levels below this block
1571 (@code{hs-hide-level}).
1574 @vindex hs-hide-comments-when-hiding-all
1575 @vindex hs-isearch-open
1576 @vindex hs-special-modes-alist
1577 These user options exist for customizing Hideshow mode.
1580 @item hs-hide-comments-when-hiding-all
1581 Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
1582 @item hs-isearch-open
1583 Specifies what kind of hidden blocks to open in Isearch mode.
1584 @item hs-special-modes-alist
1586 Initializes Hideshow variables for different modes.
1590 @section Glasses minor mode
1591 @cindex Glasses mode
1592 @cindex identifiers, making long ones readable
1593 @cindex StudlyCaps, making them readable
1594 @findex glasses-mode
1596 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
1597 readable by altering the display. It can do this in two different
1598 ways: by displaying underscores between an lower-case letter and the
1599 following capital letter, or by emboldening the capital letters. It
1600 does not alter the buffer text, only the way they display, so you can
1601 use it even on read-only buffers. You can use the command @kbd{M-x
1602 glasses-mode} to enable or disable the mode; you can also add
1603 @code{glasses-mode} to the mode hook of appropriate programming
1604 language major modes.
1607 @section Documentation Commands
1609 As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
1610 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
1611 be used to print documentation of functions and variables that you want to
1612 call. These commands use the minibuffer to read the name of a function or
1613 variable to document, and display the documentation in a window.
1615 For extra convenience, these commands provide default arguments based on
1616 the code in the neighborhood of point. @kbd{C-h f} sets the default to the
1617 function called in the innermost list containing point. @kbd{C-h v} uses
1618 the symbol name around or adjacent to point as its default.
1622 For Emacs Lisp code, you can also use Eldoc mode. This minor mode
1623 constantly displays in the echo area the argument list for the function
1624 being called at point. (In other words, it finds the function call that
1625 point is contained in, and displays the argument list of that function.)
1626 Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
1627 the command @kbd{M-x eldoc-mode} to enable or disable this feature.
1629 @findex info-lookup-symbol
1630 @findex info-lookup-file
1632 For C, Lisp, and other languages, you can use @kbd{C-h C-i}
1633 (@code{info-lookup-symbol}) to view the Info documentation for a symbol.
1634 You specify the symbol with the minibuffer; by default, it uses the
1635 symbol that appears in the buffer at point. The major mode determines
1636 where to look for documentation for the symbol---which Info files and
1637 which indices. You can also use @kbd{M-x info-lookup-file} to look for
1638 documentation for a file name. Currently this supports the following
1639 modes: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
1640 Makefile, Octave, Perl, Scheme and Texinfo, provided you have installed
1641 the relevant Info files, which are typically available with the appropriate GNU
1644 @findex manual-entry
1645 @cindex manual pages
1646 You can read the ``man page'' for an operating system command, library
1647 function, or system call, with the @kbd{M-x manual-entry} command. It
1648 runs the @code{man} program to format the man page, and runs it
1649 asynchronously if your system permits, so that you can keep on editing
1650 while the page is being formatted. (MS-DOS and MS-Windows 3 do not
1651 permit asynchronous subprocesses, so on these systems you cannot edit
1652 while Emacs waits for @code{man} to exit.) The result goes in a buffer
1653 named @samp{*Man @var{topic}*}. These buffers use a special major mode,
1654 Man mode, that facilitates scrolling and examining other manual pages.
1655 For details, type @kbd{C-h m} while in a man page buffer.
1657 @cindex sections of manual pages
1658 Man pages are classified into @dfn{sections}; sometimes there are
1659 man pages with the same name in different sections. To read a man
1660 page from a specific section, type @samp{@var{topic}(@var{section})} or
1661 @samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
1662 for the topic. For example, to read the man page for the C library
1663 function @code{chmod} (as opposed to a command by the same name), type
1664 @kbd{M-x manual-entry @key{RET} chmod(2v) @key{RET}} (assuming
1665 @code{chmod} is in section @samp{2v}).
1667 If you do not specify a section, the results depend on how the
1668 @code{man} command works on your system. Some of them display only
1669 the first man page they find. Others display all man pages that have
1670 the specified name, so you can page between them with the @kbd{M-n}
1671 and @kbd{M-p} keys. The mode line shows how many manual pages are
1672 available in the Man buffer.
1674 @vindex Man-fontify-manpage-flag
1675 For a long man page, setting the faces properly can take substantial
1676 time. By default, Emacs uses faces in man pages if Emacs can display
1677 different fonts or colors. You can turn off use of faces in man pages
1678 by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
1680 @findex Man-fontify-manpage
1681 If you insert the text of a man page into an Emacs buffer in some
1682 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
1683 perform the same conversions that @kbd{M-x manual-entry} does.
1686 @cindex manual pages, on MS-DOS/MS-Windows
1687 An alternative way of reading manual pages is the @kbd{M-x woman}
1688 command@footnote{The name of the command, @code{woman}, is an acronym
1689 for ``w/o (without) man,'' since it doesn't use the @code{man}
1690 program.}. Unlike @kbd{M-x man}, it does not run any external
1691 programs to format and display the man pages; instead it does the job
1692 in Emacs Lisp, so it works on systems such as MS-Windows, where the
1693 @code{man} program and other the programs it needs are not readily
1694 available. @kbd{M-x woman} prompts for a name of a manual page, and
1695 provides completion based on the list of manual pages that are
1696 installed on your machine; the list of available manual pages is
1697 computed automatically the first time you invoke @code{woman}. The
1698 word at point in the current buffer is used to suggest the default
1699 name of the manual page.
1701 With a numeric argument, @kbd{M-x woman} recomputes the list of the
1702 manual pages used for completion. This is useful if you add or delete
1705 If you type a name of a manual page and @kbd{M-x woman} finds that
1706 several manual pages by the same name exist in different sections, it
1707 pops up a window with possible candidates asking you to choose one of
1710 @vindex woman-manpath
1711 By default, @kbd{M-x woman} looks up the manual pages in directories
1712 listed by the @code{MANPATH} environment variable. (If @code{MANPATH}
1713 is not set, @code{woman} uses a suitable default value, which can be
1714 customized.) More precisely, @code{woman} looks for subdirectories that
1715 match the shell wildcard @file{man*} in each one of these directories,
1716 and tries to find the manual pages in those subdirectories. When first
1717 invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list
1718 of directory names and stores that list in the @code{woman-manpath}
1719 variable. By changing the value of this variable, you can customize the
1720 list of directories where @code{woman} looks for manual pages.
1723 In addition, you can augment the list of directories searched by
1724 @code{woman} by setting the value of the @code{woman-path} variable.
1725 This variable should hold a list of specific directories which
1726 @code{woman} should search, in addition to those in
1727 @code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
1728 @code{woman-path} are searched for the manual pages, not for @file{man*}
1731 @findex woman-find-file
1732 Occasionally, you might need to display manual pages that are not in
1733 any of the directories listed by @code{woman-manpath} and
1734 @code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
1735 name of a manual page file, with completion, and then formats and
1736 displays that file like @kbd{M-x woman} does.
1738 @vindex woman-dired-keys
1739 First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W}
1740 key to run the @code{woman-find-file} command on the current line's
1741 file. You can disable this by setting the variable
1742 @code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the
1743 Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current
1744 line's archive member.
1746 For more information about setting up and using @kbd{M-x woman}, see
1747 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
1750 Eventually the GNU project hopes to replace most man pages with
1751 better-organized manuals that you can browse with Info. @xref{Misc
1752 Help}. Since this process is only partially completed, it is still
1753 useful to read manual pages.
1756 @section Change Logs
1760 @findex add-change-log-entry-other-window
1761 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1762 file for the file you are editing
1763 (@code{add-change-log-entry-other-window}). If that file is actually
1764 a backup file, it makes an entry appropriate for the file's
1765 parent---that is useful for making log entries for functions that
1766 have been deleted in the current version.
1768 A change log file contains a chronological record of when and why you
1769 have changed a program, consisting of a sequence of entries describing
1770 individual changes. Normally it is kept in a file called
1771 @file{ChangeLog} in the same directory as the file you are editing, or
1772 one of its parent directories. A single @file{ChangeLog} file can
1773 record changes for all the files in its directory and all its
1776 A change log entry starts with a header line that contains your name,
1777 your email address (taken from the variable @code{user-mail-address}),
1778 and the current date and time. Aside from these header lines, every
1779 line in the change log starts with a space or a tab. The bulk of the
1780 entry consists of @dfn{items}, each of which starts with a line starting
1781 with whitespace and a star. Here are two entries, both dated in May
1782 1993, each with two items:
1788 1993-05-25 Richard Stallman <rms@@gnu.org>
1790 * man.el: Rename symbols `man-*' to `Man-*'.
1791 (manual-entry): Make prompt string clearer.
1793 * simple.el (blink-matching-paren-distance):
1794 Change default to 12,000.
1796 1993-05-24 Richard Stallman <rms@@gnu.org>
1798 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1799 (vc-cancel-version): Doc fix.
1802 One entry can describe several changes; each change should have its
1803 own item. Normally there should be a blank line between items. When
1804 items are related (parts of the same change, in different places), group
1805 them by leaving no blank line between them. The second entry above
1806 contains two items grouped in this way.
1808 @kbd{C-x 4 a} visits the change log file and creates a new entry
1809 unless the most recent entry is for today's date and your name. It
1810 also creates a new item for the current file. For many languages, it
1811 can even guess the name of the function or other object that was
1814 @vindex add-log-keep-changes-together
1815 When the option @code{add-log-keep-changes-together} is
1816 non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
1817 rather than starting a new entry.
1819 @vindex change-log-version-info-enabled
1820 @vindex change-log-version-number-regexp-list
1821 @cindex file version in change log entries
1822 If the value of the variable @code{change-log-version-info-enabled}
1823 is non-@code{nil}, @kbd{C-x 4 a} ads the file's version number to the
1824 change log entry. It finds the version number by searching the first
1825 ten percent of the file, using regular expressions from the variable
1826 @code{change-log-version-number-regexp-list}.
1828 @cindex Change Log mode
1829 @findex change-log-mode
1830 The change log file is visited in Change Log mode. In this major
1831 mode, each bunch of grouped items counts as one paragraph, and each
1832 entry is considered a page. This facilitates editing the entries.
1833 @kbd{C-j} and auto-fill indent each new line like the previous line;
1834 this is convenient for entering the contents of an entry.
1836 @findex change-log-merge
1837 You can use the command @kbd{M-x change-log-merge} to merge other
1838 log files into a buffer in Change Log Mode, preserving the date
1839 ordering of entries.
1841 @findex change-log-redate
1842 @cindex converting change log date style
1843 Versions of Emacs before 20.1 used a different format for the time of
1844 the change log entry:
1847 Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
1851 The @kbd{M-x change-log-redate} command converts all the old-style
1852 date entries in the change log file visited in the current buffer to
1853 the new format, to make the file uniform in style. This is handy when
1854 entries are contributed by many different people, some of whom use old
1857 Version control systems are another way to keep track of changes in your
1858 program and keep a change log. @xref{Log Buffer}.
1861 @section @file{AUTHORS} files
1862 @cindex @file{AUTHORS} file
1864 Programs which have many contributors usually include a file named
1865 @file{AUTHORS} in their distribution, which lists the individual
1866 contributions. Emacs has a special command for maintaining the
1867 @file{AUTHORS} file that is part of the Emacs distribution.
1870 The @kbd{M-x authors} command prompts for the name of the root of the
1871 Emacs source directory. It then scans @file{ChageLog} files and Lisp
1872 source files under that directory for information about authors of
1873 individual packages and people who made changes in source files, and
1874 puts the information it gleans into a buffer named @samp{*Authors*}.
1875 You can then edit the contents of that buffer and merge it with the
1876 exisiting @file{AUTHORS} file.
1878 Do not assume that this command finds all the contributors; don't
1879 assume that a person not listed in the output was not a contributor.
1880 If you merged in someone's contribution and did not put his name
1881 in the change log, he won't show up in @kbd{M-x authors} either.
1884 @section Tags Tables
1887 A @dfn{tags table} is a description of how a multi-file program is
1888 broken up into files. It lists the names of the component files and the
1889 names and positions of the functions (or other named subunits) in each
1890 file. Grouping the related files makes it possible to search or replace
1891 through all the files with one command. Recording the function names
1892 and positions makes possible the @kbd{M-.} command which finds the
1893 definition of a function by looking up which of the files it is in.
1895 Tags tables are stored in files called @dfn{tags table files}. The
1896 conventional name for a tags table file is @file{TAGS}.
1898 Each entry in the tags table records the name of one tag, the name of the
1899 file that the tag is defined in (implicitly), and the position in that file
1900 of the tag's definition.
1902 Just what names from the described files are recorded in the tags table
1903 depends on the programming language of the described file. They
1904 normally include all file names, functions and subroutines, and may
1905 also include global variables, data types, and anything else
1906 convenient. Each name recorded is called a @dfn{tag}.
1908 @cindex C++ class browser, tags
1910 @cindex class browser, C++
1912 See also the Ebrowse facility, which is tailored for C++.
1913 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
1916 * Tag Syntax:: Tag syntax for various types of code and text files.
1917 * Create Tags Table:: Creating a tags table with @code{etags}.
1918 * Etags Regexps:: Create arbitrary tags using regular expressions.
1919 * Select Tags Table:: How to visit a tags table.
1920 * Find Tag:: Commands to find the definition of a specific tag.
1921 * Tags Search:: Using a tags table for searching and replacing.
1922 * List Tags:: Listing and finding tags defined in a file.
1926 @subsection Source File Tag Syntax
1928 Here is how tag syntax is defined for the most popular languages:
1932 In C code, any C function or typedef is a tag, and so are definitions of
1933 @code{struct}, @code{union} and @code{enum}.
1934 @code{#define} macro definitions and @code{enum} constants are also
1935 tags, unless you specify @samp{--no-defines} when making the tags table.
1936 Similarly, global variables are tags, unless you specify
1937 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
1938 can make the tags table file much smaller.
1940 You can tag function declarations and external variables in addition
1941 to function definitions by giving the @samp{--declarations} option to
1945 In C++ code, in addition to all the tag constructs of C code, member
1946 functions are also recognized, and optionally member variables if you
1947 use the @samp{--members} option. Tags for variables and functions in
1948 classes are named @samp{@var{class}::@var{variable}} and
1949 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1950 tag names like @samp{operator+}.
1953 In Java code, tags include all the constructs recognized in C++, plus
1954 the @code{interface}, @code{extends} and @code{implements} constructs.
1955 Tags for variables and functions in classes are named
1956 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1959 In La@TeX{} text, the argument of any of the commands @code{\chapter},
1960 @code{\section}, @code{\subsection}, @code{\subsubsection},
1961 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
1962 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
1965 Other commands can make tags as well, if you specify them in the
1966 environment variable @env{TEXTAGS} before invoking @code{etags}. The
1967 value of this environment variable should be a colon-separated list of
1968 command names. For example,
1971 TEXTAGS="def:newcommand:newenvironment"
1976 specifies (using Bourne shell syntax) that the commands @samp{\def},
1977 @samp{\newcommand} and @samp{\newenvironment} also define tags.
1980 In Lisp code, any function defined with @code{defun}, any variable
1981 defined with @code{defvar} or @code{defconst}, and in general the first
1982 argument of any expression that starts with @samp{(def} in column zero, is
1986 In Scheme code, tags include anything defined with @code{def} or with a
1987 construct whose name starts with @samp{def}. They also include variables
1988 set with @code{set!} at top level in the file.
1991 Several other languages are also supported:
1996 In Ada code, functions, procedures, packages, tasks, and types are
1997 tags. Use the @samp{--packages-only} option to create tags for
2000 In Ada, the same name can be used for different kinds of entity
2001 (e.g.@:, for a procedure and for a function). Also, for things like
2002 packages, procedures and functions, there is the spec (i.e.@: the
2003 interface) and the body (i.e.@: the implementation). To make it
2004 easier to pick the definition you want, Ada tag name have suffixes
2005 indicating the type of entity:
2022 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
2023 directly to the body of the package @code{bidule}, while @kbd{M-x
2024 find-tag @key{RET} bidule @key{RET}} will just search for any tag
2028 In assembler code, labels appearing at the beginning of a line,
2029 followed by a colon, are tags.
2032 In Bison or Yacc input files, each rule defines as a tag the nonterminal
2033 it constructs. The portions of the file that contain C code are parsed
2037 In Cobol code, tags are paragraph names; that is, any word starting in
2038 column 8 and followed by a period.
2041 In Erlang code, the tags are the functions, records, and macros defined
2045 In Fortran code, functions, subroutines and blockdata are tags.
2048 In makefiles, targets are tags.
2051 In Objective C code, tags include Objective C definitions for classes,
2052 class categories, methods, and protocols.
2055 In Pascal code, the tags are the functions and procedures defined in
2059 In Perl code, the tags are the procedures defined by the @code{sub},
2060 @code{my} and @code{local} keywords. Use @samp{--globals} if you want
2061 to tag global variables.
2064 In PostScript code, the tags are the functions.
2067 In Prolog code, a tag name appears at the left margin.
2070 In Python code, @code{def} or @code{class} at the beginning of a line
2074 You can also generate tags based on regexp matching (@pxref{Etags
2075 Regexps}) to handle other formats and languages.
2077 @node Create Tags Table
2078 @subsection Creating Tags Tables
2079 @cindex @code{etags} program
2081 The @code{etags} program is used to create a tags table file. It knows
2082 the syntax of several languages, as described in
2084 the previous section.
2089 Here is how to run @code{etags}:
2092 etags @var{inputfiles}@dots{}
2096 The @code{etags} program reads the specified files, and writes a tags
2097 table named @file{TAGS} in the current working directory.
2099 If the specified files don't exist, @code{etags} looks for
2100 compressed versions of them and uncompresses them to read them. Under
2101 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
2102 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
2105 @code{etags} recognizes the language used in an input file based on
2106 its file name and contents. You can specify the language with the
2107 @samp{--language=@var{name}} option, described below.
2109 If the tags table data become outdated due to changes in the files
2110 described in the table, the way to update the tags table is the same
2111 way it was made in the first place. But it is not necessary to do
2114 If the tags table fails to record a tag, or records it for the wrong
2115 file, then Emacs cannot possibly find its definition. However, if the
2116 position recorded in the tags table becomes a little bit wrong (due to
2117 some editing in the file that the tag definition is in), the only
2118 consequence is a slight delay in finding the tag. Even if the stored
2119 position is very wrong, Emacs will still find the tag, but it must
2120 search the entire file for it.
2122 So you should update a tags table when you define new tags that you want
2123 to have listed, or when you move tag definitions from one file to another,
2124 or when changes become substantial. Normally there is no need to update
2125 the tags table after each edit, or even every day.
2127 One tags table can virtually include another. Specify the included
2128 tags file name with the @samp{--include=@var{file}} option when
2129 creating the file that is to include it. The latter file then acts as
2130 if it covered all the source files specified in the included file, as
2131 well as the files it directly contains.
2133 If you specify the source files with relative file names when you run
2134 @code{etags}, the tags file will contain file names relative to the
2135 directory where the tags file was initially written. This way, you can
2136 move an entire directory tree containing both the tags file and the
2137 source files, and the tags file will still refer correctly to the source
2140 If you specify absolute file names as arguments to @code{etags}, then
2141 the tags file will contain absolute file names. This way, the tags file
2142 will still refer to the same files even if you move it, as long as the
2143 source files remain in the same place. Absolute file names start with
2144 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
2146 When you want to make a tags table from a great number of files, you
2147 may have problems listing them on the command line, because some systems
2148 have a limit on its length. The simplest way to circumvent this limit
2149 is to tell @code{etags} to read the file names from its standard input,
2150 by typing a dash in place of the file names, like this:
2153 find . -name "*.[chCH]" -print | etags -
2156 Use the option @samp{--language=@var{name}} to specify the language
2157 explicitly. You can intermix these options with file names; each one
2158 applies to the file names that follow it. Specify
2159 @samp{--language=auto} to tell @code{etags} to resume guessing the
2160 language from the file names and file contents. Specify
2161 @samp{--language=none} to turn off language-specific processing
2162 entirely; then @code{etags} recognizes tags by regexp matching alone
2163 (@pxref{Etags Regexps}).
2165 @samp{etags --help} prints the list of the languages @code{etags}
2166 knows, and the file name rules for guessing the language. It also prints
2167 a list of all the available @code{etags} options, together with a short
2171 @subsection Etags Regexps
2173 The @samp{--regex} option provides a general way of recognizing tags
2174 based on regexp matching. You can freely intermix it with file names.
2175 Each @samp{--regex} option adds to the preceding ones, and applies only
2176 to the following files. The syntax is:
2179 --regex=/@var{tagregexp}[/@var{nameregexp}]/
2183 where @var{tagregexp} is used to match the lines to tag. It is always
2184 anchored, that is, it behaves as if preceded by @samp{^}. If you want
2185 to account for indentation, just match any initial number of blanks by
2186 beginning your regular expression with @samp{[ \t]*}. In the regular
2187 expressions, @samp{\} quotes the next character, and @samp{\t} stands
2188 for the tab character. Note that @code{etags} does not handle the other
2189 C escape sequences for special characters.
2191 @cindex interval operator (in regexps)
2192 The syntax of regular expressions in @code{etags} is the same as in
2193 Emacs, augmented with the @dfn{interval operator}, which works as in
2194 @code{grep} and @code{ed}. The syntax of an interval operator is
2195 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
2196 expression at least @var{m} times and up to @var{n} times.
2198 You should not match more characters with @var{tagregexp} than that
2199 needed to recognize what you want to tag. If the match is such that
2200 more characters than needed are unavoidably matched by @var{tagregexp}
2201 (as will usually be the case), you should add a @var{nameregexp}, to
2202 pick out just the tag. This will enable Emacs to find tags more
2203 accurately and to do completion on tag names more reliably. You can
2204 find some examples below.
2206 The option @samp{--ignore-case-regex} (or @samp{-c}) works like
2207 @samp{--regex}, except that matching ignores case. This is
2208 appropriate for certain programming languages.
2210 The @samp{-R} option deletes all the regexps defined with
2211 @samp{--regex} options. It applies to the file names following it, as
2212 you can see from the following example:
2215 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
2216 bar.ber -R --lang=lisp los.er
2220 Here @code{etags} chooses the parsing language for @file{voo.doo} and
2221 @file{bar.ber} according to their contents. @code{etags} also uses
2222 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
2223 @var{reg1} and @var{reg2} to recognize additional tags in
2224 @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
2225 matching, to recognize tags in @file{los.er}.
2227 You can specify a regular expression for a particular language, by
2228 writing @samp{@{lang@}} in front of it. Then @code{etags} will use
2229 the regular expression only for files of that language. (@samp{etags
2230 --help} prints the list of languages recognised by @code{etags}.) The
2231 following example tags the @code{DEFVAR} macros in the Emacs source
2232 files, for the C language only:
2235 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
2239 This feature is particularly useful when you store a list of regular
2240 expressions in a file. The following option syntax instructs
2241 @code{etags} to read two files of regular expressions. The regular
2242 expressions contained in the second file are matched without regard to
2246 --regex=@@first-file --ignore-case-regex=@@second-file
2250 A regex file contains one regular expressions per line. Empty lines,
2251 and lines beginning with space or tab are ignored. When the first
2252 character in a line is @samp{@@}, @code{etags} assumes that the rest
2253 of the line is the name of a file of regular expressions; thus, one
2254 such file can include another file. All the other lines are taken to
2255 be regular expressions. If the first non-whitespace text on the line
2256 is @samp{--}, that line is a comment.
2258 For example, one can create a file called @samp{emacs.tags} with the
2262 -- This is for GNU Emacs C source files
2263 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2267 and then use it like this:
2270 etags --regex=@@emacs.tags *.[ch] */*.[ch]
2273 Here are some more examples. The regexps are quoted to protect them
2274 from shell interpretation.
2282 etags --language=none \
2283 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2284 --regex='/###key \(.*\)/\1/' \
2285 --regex='/[ \t]*global[ \t].*/' \
2290 Note that tags are not generated for scripts, so that you have to add
2291 a line by yourself of the form @samp{###key @var{scriptname}} if you
2298 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2305 etags --language=none \
2306 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2307 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2308 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2312 @node Select Tags Table
2313 @subsection Selecting a Tags Table
2315 @vindex tags-file-name
2316 @findex visit-tags-table
2317 Emacs has at any time one @dfn{selected} tags table, and all the commands
2318 for working with tags tables use the selected one. To select a tags table,
2319 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
2320 argument. The name @file{TAGS} in the default directory is used as the
2323 All this command does is store the file name in the variable
2324 @code{tags-file-name}. Emacs does not actually read in the tags table
2325 contents until you try to use them. Setting this variable yourself is just
2326 as good as using @code{visit-tags-table}. The variable's initial value is
2327 @code{nil}; that value tells all the commands for working with tags tables
2328 that they must ask for a tags table file name to use.
2330 Using @code{visit-tags-table} when a tags table is already loaded
2331 gives you a choice: you can add the new tags table to the current list
2332 of tags tables, or start a new list. The tags commands use all the tags
2333 tables in the current list. If you start a new list, the new tags table
2334 is used @emph{instead} of others. If you add the new table to the
2335 current list, it is used @emph{as well as} the others. When the tags
2336 commands scan the list of tags tables, they don't always start at the
2337 beginning of the list; they start with the first tags table (if any)
2338 that describes the current file, proceed from there to the end of the
2339 list, and then scan from the beginning of the list until they have
2340 covered all the tables in the list.
2342 @vindex tags-table-list
2343 You can specify a precise list of tags tables by setting the variable
2344 @code{tags-table-list} to a list of strings, like this:
2346 @c keep this on two lines for formatting in smallbook
2349 (setq tags-table-list
2350 '("~/emacs" "/usr/local/lib/emacs/src"))
2355 This tells the tags commands to look at the @file{TAGS} files in your
2356 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2357 directory. The order depends on which file you are in and which tags
2358 table mentions that file, as explained above.
2360 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2363 @subsection Finding a Tag
2365 The most important thing that a tags table enables you to do is to find
2366 the definition of a specific tag.
2369 @item M-.@: @var{tag} @key{RET}
2370 Find first definition of @var{tag} (@code{find-tag}).
2372 Find next alternate definition of last tag specified.
2374 Go back to previous tag found.
2375 @item C-M-. @var{pattern} @key{RET}
2376 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2378 Find the next tag whose name matches the last pattern used.
2379 @item C-x 4 .@: @var{tag} @key{RET}
2380 Find first definition of @var{tag}, but display it in another window
2381 (@code{find-tag-other-window}).
2382 @item C-x 5 .@: @var{tag} @key{RET}
2383 Find first definition of @var{tag}, and create a new frame to select the
2384 buffer (@code{find-tag-other-frame}).
2386 Pop back to where you previously invoked @kbd{M-.} and friends.
2391 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
2392 a specified tag. It searches through the tags table for that tag, as a
2393 string, and then uses the tags table info to determine the file that the
2394 definition is in and the approximate character position in the file of
2395 the definition. Then @code{find-tag} visits that file, moves point to
2396 the approximate character position, and searches ever-increasing
2397 distances away to find the tag definition.
2399 If an empty argument is given (just type @key{RET}), the sexp in the
2400 buffer before or around point is used as the @var{tag} argument.
2401 @xref{Lists}, for info on sexps.
2403 You don't need to give @kbd{M-.} the full name of the tag; a part
2404 will do. This is because @kbd{M-.} finds tags in the table which
2405 contain @var{tag} as a substring. However, it prefers an exact match
2406 to a substring match. To find other tags that match the same
2407 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
2408 M-.}; this does not read a tag name, but continues searching the tags
2409 table's text for another tag containing the same substring last used.
2410 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
2411 alternative to @kbd{C-u M-.}.
2414 @findex find-tag-other-window
2416 @findex find-tag-other-frame
2417 Like most commands that can switch buffers, @code{find-tag} has a
2418 variant that displays the new buffer in another window, and one that
2419 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
2420 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
2421 which invokes @code{find-tag-other-frame}.
2423 To move back to places you've found tags recently, use @kbd{C-u -
2424 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
2425 command can take you to another buffer. @kbd{C-x 4 .} with a negative
2426 argument finds the previous tag location in another window.
2429 @findex pop-tag-mark
2430 @vindex find-tag-marker-ring-length
2431 As well as going back to places you've found tags recently, you can go
2432 back to places @emph{from where} you found them. Use @kbd{M-*}, which
2433 invokes the command @code{pop-tag-mark}, for this. Typically you would
2434 find and study the definition of something with @kbd{M-.} and then
2435 return to where you were with @kbd{M-*}.
2437 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2438 a depth determined by the variable @code{find-tag-marker-ring-length}.
2440 @findex find-tag-regexp
2442 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2443 match a specified regular expression. It is just like @kbd{M-.} except
2444 that it does regexp matching instead of substring matching.
2447 @subsection Searching and Replacing with Tags Tables
2448 @cindex search and replace in multiple files
2449 @cindex multiple-file search and replace
2451 The commands in this section visit and search all the files listed in the
2452 selected tags table, one by one. For these commands, the tags table serves
2453 only to specify a sequence of files to search.
2456 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2457 Search for @var{regexp} through the files in the selected tags
2459 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2460 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2462 Restart one of the commands above, from the current location of point
2463 (@code{tags-loop-continue}).
2467 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2468 searches for matches in all the files in the selected tags table, one
2469 file at a time. It displays the name of the file being searched so you
2470 can follow its progress. As soon as it finds an occurrence,
2471 @code{tags-search} returns.
2474 @findex tags-loop-continue
2475 Having found one match, you probably want to find all the rest. To find
2476 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2477 @code{tags-search}. This searches the rest of the current buffer, followed
2478 by the remaining files of the tags table.@refill
2480 @findex tags-query-replace
2481 @kbd{M-x tags-query-replace} performs a single
2482 @code{query-replace-regexp} through all the files in the tags table. It
2483 reads a regexp to search for and a string to replace with, just like
2484 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2485 tags-search}, but repeatedly, processing matches according to your
2486 input. @xref{Replace}, for more information on query replace.
2488 @vindex tags-case-fold-search
2489 @cindex case-sensitivity and tags search
2490 You can control the case-sensitivity of tags search commands by
2491 customizing the value of the variable @code{tags-case-fold-search}. The
2492 default is to use the same setting as the value of
2493 @code{case-fold-search} (@pxref{Search Case}).
2495 It is possible to get through all the files in the tags table with a
2496 single invocation of @kbd{M-x tags-query-replace}. But often it is
2497 useful to exit temporarily, which you can do with any input event that
2498 has no special query replace meaning. You can resume the query replace
2499 subsequently by typing @kbd{M-,}; this command resumes the last tags
2500 search or replace command that you did.
2502 The commands in this section carry out much broader searches than the
2503 @code{find-tag} family. The @code{find-tag} commands search only for
2504 definitions of tags that match your substring or regexp. The commands
2505 @code{tags-search} and @code{tags-query-replace} find every occurrence
2506 of the regexp, as ordinary search commands and replace commands do in
2509 These commands create buffers only temporarily for the files that they
2510 have to search (those which are not already visited in Emacs buffers).
2511 Buffers in which no match is found are quickly killed; the others
2514 It may have struck you that @code{tags-search} is a lot like
2515 @code{grep}. You can also run @code{grep} itself as an inferior of
2516 Emacs and have Emacs show you the matching lines one by one. This works
2517 much like running a compilation; finding the source locations of the
2518 @code{grep} matches works like finding the compilation errors.
2522 @subsection Tags Table Inquiries
2525 @item M-x list-tags @key{RET} @var{file} @key{RET}
2526 Display a list of the tags defined in the program file @var{file}.
2527 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2528 Display a list of all tags matching @var{regexp}.
2532 @kbd{M-x list-tags} reads the name of one of the files described by
2533 the selected tags table, and displays a list of all the tags defined in
2534 that file. The ``file name'' argument is really just a string to
2535 compare against the file names recorded in the tags table; it is read as
2536 a string rather than as a file name. Therefore, completion and
2537 defaulting are not available, and you must enter the file name the same
2538 way it appears in the tags table. Do not include a directory as part of
2539 the file name unless the file name recorded in the tags table includes a
2542 @findex tags-apropos
2543 @vindex tags-apropos-verbose
2544 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2545 (@pxref{Apropos}). It finds all the tags in the selected tags table
2546 whose entries match @var{regexp}, and displays them. If the variable
2547 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2548 of the tags files together with the tag names.
2550 @vindex tags-tag-face
2551 @vindex tags-apropos-additional-actions
2552 You can customize the appearance of the output with the face
2553 @code{tags-tag-face}. You can display additional output with @kbd{M-x
2554 tags-apropos} by customizing the variable
2555 @code{tags-apropos-additional-actions}---see its documentation for
2558 You can also use the collection of tag names to complete a symbol
2559 name in the buffer. @xref{Symbol Completion}.
2563 @cindex indexes of buffer contents
2564 @cindex buffer content indexes
2567 The Imenu facility is another way to find definitions or sections
2568 in a file. It is similar in spirit to Tags, but operates on a single
2569 buffer only, and works entirely within Emacs with no need for a separate
2573 @findex imenu-add-menu-bar-index
2574 If you type @kbd{M-x imenu}, it reads the name of a section or
2575 definition in the current buffer, then goes to that section or
2576 definition. You can use completion to specify the name, and a
2577 complete list of possible names is always displayed.
2579 Alternatively you can bind the command @code{imenu} to a mouse
2580 click. Then it displays mouse menus for you to select the section or
2581 definition you want. You can also add the buffer's index to the menu
2582 bar by calling @code{imenu-add-menu-bar-index}. If you want to have
2583 this menu bar item available for all buffers in a certain major mode,
2584 you can do this by adding @code{imenu-add-menu-bar-index} to its mode
2585 hook. But then you will have to wait for the buffer to be searched
2586 for sections and definitions, each time you visit a file which uses
2589 @vindex imenu-auto-rescan
2590 When you change the contents of a buffer, if you add or delete
2591 definitions or sections, you can update the buffer's index to
2592 correspond to the new contents by invoking the @samp{*Rescan*} item in
2593 the menu. Rescanning happens automatically if
2594 @code{imenu-auto-rescan} is non-@code{nil}. There is no need to
2595 rescan because of small changes in the text.
2597 @vindex imenu-sort-function
2598 You can customize the way the menus are sorted via the variable
2599 @code{imenu-sort-function}. By default names are ordered as they
2600 occur in the buffer; alphabetic sorting is provided as an alternative.
2602 Imenu provides the information to guide Which Function mode
2603 (@pxref{Which Function}). The Speedbar can also use it
2606 @node Emerge, C Modes, Imenu, Programs
2607 @section Merging Files with Emerge
2609 @cindex merging files
2611 It's not unusual for programmers to get their signals crossed and modify
2612 the same program in two different directions. To recover from this
2613 confusion, you need to merge the two versions. Emerge makes this
2614 easier. See also @ref{Comparing Files}, for commands to compare
2615 in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
2618 * Overview of Emerge:: How to start Emerge. Basic concepts.
2619 * Submodes of Emerge:: Fast mode vs. Edit mode.
2620 Skip Prefers mode and Auto Advance mode.
2621 * State of Difference:: You do the merge by specifying state A or B
2622 for each difference.
2623 * Merge Commands:: Commands for selecting a difference,
2624 changing states of differences, etc.
2625 * Exiting Emerge:: What to do when you've finished the merge.
2626 * Combining in Emerge:: How to keep both alternatives for a difference.
2627 * Fine Points of Emerge:: Misc.
2630 @node Overview of Emerge
2631 @subsection Overview of Emerge
2633 To start Emerge, run one of these four commands:
2636 @item M-x emerge-files
2637 @findex emerge-files
2638 Merge two specified files.
2640 @item M-x emerge-files-with-ancestor
2641 @findex emerge-files-with-ancestor
2642 Merge two specified files, with reference to a common ancestor.
2644 @item M-x emerge-buffers
2645 @findex emerge-buffers
2648 @item M-x emerge-buffers-with-ancestor
2649 @findex emerge-buffers-with-ancestor
2650 Merge two buffers with reference to a common ancestor in a third
2654 @cindex merge buffer (Emerge)
2655 @cindex A and B buffers (Emerge)
2656 The Emerge commands compare two files or buffers, and display the
2657 comparison in three buffers: one for each input text (the @dfn{A buffer}
2658 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
2659 takes place. The merge buffer shows the full merged text, not just the
2660 differences. Wherever the two input texts differ, you can choose which
2661 one of them to include in the merge buffer.
2663 The Emerge commands that take input from existing buffers use only the
2664 accessible portions of those buffers, if they are narrowed
2665 (@pxref{Narrowing}).
2667 If a common ancestor version is available, from which the two texts to
2668 be merged were both derived, Emerge can use it to guess which
2669 alternative is right. Wherever one current version agrees with the
2670 ancestor, Emerge presumes that the other current version is a deliberate
2671 change which should be kept in the merged version. Use the
2672 @samp{with-ancestor} commands if you want to specify a common ancestor
2673 text. These commands read three file or buffer names---variant A,
2674 variant B, and the common ancestor.
2676 After the comparison is done and the buffers are prepared, the
2677 interactive merging starts. You control the merging by typing special
2678 @dfn{merge commands} in the merge buffer. The merge buffer shows you a
2679 full merged text, not just differences. For each run of differences
2680 between the input texts, you can choose which one of them to keep, or
2681 edit them both together.
2683 The merge buffer uses a special major mode, Emerge mode, with commands
2684 for making these choices. But you can also edit the buffer with
2685 ordinary Emacs commands.
2687 At any given time, the attention of Emerge is focused on one
2688 particular difference, called the @dfn{selected} difference. This
2689 difference is marked off in the three buffers like this:
2692 vvvvvvvvvvvvvvvvvvvv
2693 @var{text that differs}
2694 ^^^^^^^^^^^^^^^^^^^^
2698 Emerge numbers all the differences sequentially and the mode
2699 line always shows the number of the selected difference.
2701 Normally, the merge buffer starts out with the A version of the text.
2702 But when the A version of a difference agrees with the common ancestor,
2703 then the B version is initially preferred for that difference.
2705 Emerge leaves the merged text in the merge buffer when you exit. At
2706 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
2707 numeric argument to @code{emerge-files} or
2708 @code{emerge-files-with-ancestor}, it reads the name of the output file
2709 using the minibuffer. (This is the last file name those commands read.)
2710 Then exiting from Emerge saves the merged text in the output file.
2712 Normally, Emerge commands save the output buffer in its file when you
2713 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
2714 save the output buffer, but you can save it yourself if you wish.
2716 @node Submodes of Emerge
2717 @subsection Submodes of Emerge
2719 You can choose between two modes for giving merge commands: Fast mode
2720 and Edit mode. In Fast mode, basic merge commands are single
2721 characters, but ordinary Emacs commands are disabled. This is
2722 convenient if you use only merge commands. In Edit mode, all merge
2723 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
2724 commands are also available. This allows editing the merge buffer, but
2725 slows down Emerge operations.
2727 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
2728 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
2731 Emerge has two additional submodes that affect how particular merge
2732 commands work: Auto Advance mode and Skip Prefers mode.
2734 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
2735 advance to the next difference. This lets you go through the merge
2736 faster as long as you simply choose one of the alternatives from the
2737 input. The mode line indicates Auto Advance mode with @samp{A}.
2739 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
2740 skip over differences in states prefer-A and prefer-B (@pxref{State of
2741 Difference}). Thus you see only differences for which neither version
2742 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
2745 @findex emerge-auto-advance-mode
2746 @findex emerge-skip-prefers-mode
2747 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
2748 clear Auto Advance mode. Use @kbd{s s}
2749 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
2750 These commands turn on the mode with a positive argument, turns it off
2751 with a negative or zero argument, and toggle the mode with no argument.
2753 @node State of Difference
2754 @subsection State of a Difference
2756 In the merge buffer, a difference is marked with lines of @samp{v} and
2757 @samp{^} characters. Each difference has one of these seven states:
2761 The difference is showing the A version. The @kbd{a} command always
2762 produces this state; the mode line indicates it with @samp{A}.
2765 The difference is showing the B version. The @kbd{b} command always
2766 produces this state; the mode line indicates it with @samp{B}.
2770 The difference is showing the A or the B state by default, because you
2771 haven't made a choice. All differences start in the default-A state
2772 (and thus the merge buffer is a copy of the A buffer), except those for
2773 which one alternative is ``preferred'' (see below).
2775 When you select a difference, its state changes from default-A or
2776 default-B to plain A or B. Thus, the selected difference never has
2777 state default-A or default-B, and these states are never displayed in
2780 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
2781 b} chooses default-B. This chosen default applies to all differences
2782 which you haven't ever selected and for which no alternative is preferred.
2783 If you are moving through the merge sequentially, the differences you
2784 haven't selected are those following the selected one. Thus, while
2785 moving sequentially, you can effectively make the A version the default
2786 for some sections of the merge buffer and the B version the default for
2787 others by using @kbd{d a} and @kbd{d b} between sections.
2791 The difference is showing the A or B state because it is
2792 @dfn{preferred}. This means that you haven't made an explicit choice,
2793 but one alternative seems likely to be right because the other
2794 alternative agrees with the common ancestor. Thus, where the A buffer
2795 agrees with the common ancestor, the B version is preferred, because
2796 chances are it is the one that was actually changed.
2798 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
2801 The difference is showing a combination of the A and B states, as a
2802 result of the @kbd{x c} or @kbd{x C} commands.
2804 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
2805 don't do anything to it unless you give them a numeric argument.
2807 The mode line displays this state as @samp{comb}.
2810 @node Merge Commands
2811 @subsection Merge Commands
2813 Here are the Merge commands for Fast mode; in Edit mode, precede them
2818 Select the previous difference.
2821 Select the next difference.
2824 Choose the A version of this difference.
2827 Choose the B version of this difference.
2830 Select difference number @var{n}.
2833 Select the difference containing point. You can use this command in the
2834 merge buffer or in the A or B buffer.
2837 Quit---finish the merge.
2840 Abort---exit merging and do not save the output.
2843 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
2849 Recenter (like @kbd{C-l}) all three windows.
2852 Specify part of a prefix numeric argument.
2855 Also specify part of a prefix numeric argument.
2858 Choose the A version as the default from here down in
2862 Choose the B version as the default from here down in
2866 Copy the A version of this difference into the kill ring.
2869 Copy the B version of this difference into the kill ring.
2872 Insert the A version of this difference at point.
2875 Insert the B version of this difference at point.
2878 Put point and mark around the difference.
2881 Scroll all three windows down (like @kbd{M-v}).
2884 Scroll all three windows up (like @kbd{C-v}).
2887 Scroll all three windows left (like @kbd{C-x <}).
2890 Scroll all three windows right (like @kbd{C-x >}).
2893 Reset horizontal scroll on all three windows.
2896 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
2900 Combine the two versions of this difference (@pxref{Combining in
2904 Show the names of the files/buffers Emerge is operating on, in a Help
2905 window. (Use @kbd{C-u l} to restore windows.)
2908 Join this difference with the following one.
2909 (@kbd{C-u x j} joins this difference with the previous one.)
2912 Split this difference into two differences. Before you use this
2913 command, position point in each of the three buffers at the place where
2914 you want to split the difference.
2917 Trim identical lines off the top and bottom of the difference.
2918 Such lines occur when the A and B versions are
2919 identical but differ from the ancestor version.
2922 @node Exiting Emerge
2923 @subsection Exiting Emerge
2925 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
2926 the results into the output file if you specified one. It restores the
2927 A and B buffers to their proper contents, or kills them if they were
2928 created by Emerge and you haven't changed them. It also disables the
2929 Emerge commands in the merge buffer, since executing them later could
2930 damage the contents of the various buffers.
2932 @kbd{C-]} aborts the merge. This means exiting without writing the
2933 output file. If you didn't specify an output file, then there is no
2934 real difference between aborting and finishing the merge.
2936 If the Emerge command was called from another Lisp program, then its
2937 return value is @code{t} for successful completion, or @code{nil} if you
2940 @node Combining in Emerge
2941 @subsection Combining the Two Versions
2943 Sometimes you want to keep @emph{both} alternatives for a particular
2944 difference. To do this, use @kbd{x c}, which edits the merge buffer
2950 @var{version from A buffer}
2952 @var{version from B buffer}
2953 #endif /* not NEW */
2958 @vindex emerge-combine-versions-template
2959 While this example shows C preprocessor conditionals delimiting the two
2960 alternative versions, you can specify the strings to use by setting
2961 the variable @code{emerge-combine-versions-template} to a string of your
2962 choice. In the string, @samp{%a} says where to put version A, and
2963 @samp{%b} says where to put version B. The default setting, which
2964 produces the results shown above, looks like this:
2968 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
2972 @node Fine Points of Emerge
2973 @subsection Fine Points of Emerge
2975 During the merge, you mustn't try to edit the A and B buffers yourself.
2976 Emerge modifies them temporarily, but ultimately puts them back the way
2979 You can have any number of merges going at once---just don't use any one
2980 buffer as input to more than one merge at once, since the temporary
2981 changes made in these buffers would get in each other's way.
2983 Starting Emerge can take a long time because it needs to compare the
2984 files fully. Emacs can't do anything else until @code{diff} finishes.
2985 Perhaps in the future someone will change Emerge to do the comparison in
2986 the background when the input files are large---then you could keep on
2987 doing other things with Emacs until Emerge is ready to accept
2990 @vindex emerge-startup-hook
2991 After setting up the merge, Emerge runs the hook
2992 @code{emerge-startup-hook} (@pxref{Hooks}).
2995 @section C and Related Modes
3000 @cindex CORBA IDL mode
3001 @cindex Objective C mode
3005 @cindex mode, Objective C
3006 @cindex mode, CORBA IDL
3009 This section gives a brief description of the special features
3010 available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes.
3011 (These are called ``C mode and related modes.'') @xref{Top, CC Mode,
3012 ccmode, , CC Mode}, for a more extensive description of these modes
3013 and their special features.
3019 * Other C Commands::
3024 @subsection C Mode Motion Commands
3026 This section describes commands for moving point, in C mode and
3031 @kindex C-c C-u @r{(C mode)}
3032 @findex c-up-conditional
3033 Move point back to the containing preprocessor conditional, leaving the
3034 mark behind. A prefix argument acts as a repeat count. With a negative
3035 argument, move point forward to the end of the containing
3036 preprocessor conditional. When going backwards, @code{#elif} is treated
3037 like @code{#else} followed by @code{#if}. When going forwards,
3038 @code{#elif} is ignored.@refill
3041 @kindex C-c C-p @r{(C mode)}
3042 @findex c-backward-conditional
3043 Move point back over a preprocessor conditional, leaving the mark
3044 behind. A prefix argument acts as a repeat count. With a negative
3045 argument, move forward.
3048 @kindex C-c C-n @r{(C mode)}
3049 @findex c-forward-conditional
3050 Move point forward across a preprocessor conditional, leaving the mark
3051 behind. A prefix argument acts as a repeat count. With a negative
3052 argument, move backward.
3056 @findex c-beginning-of-statement
3057 Move point to the beginning of the innermost C statement
3058 (@code{c-beginning-of-statement}). If point is already at the beginning
3059 of a statement, move to the beginning of the preceding statement. With
3060 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
3062 If point is within a string or comment, or next to a comment (only
3063 whitespace between them), this command moves by sentences instead of
3066 When called from a program, this function takes three optional
3067 arguments: the numeric prefix argument, a buffer position limit
3068 (don't move back before that place), and a flag that controls whether
3069 to do sentence motion when inside of a comment.
3073 @findex c-end-of-statement
3074 Move point to the end of the innermost C statement; like @kbd{M-a}
3075 except that it moves in the other direction (@code{c-end-of-statement}).
3077 @item M-x c-backward-into-nomenclature
3078 @findex c-backward-into-nomenclature
3079 Move point backward to beginning of a C++ nomenclature section or word.
3080 With prefix argument @var{n}, move @var{n} times. If @var{n} is
3081 negative, move forward. C++ nomenclature means a symbol name in the
3082 style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
3083 begins a section or word.
3085 In the GNU project, we recommend using underscores to separate words
3086 within an identifier in C or C++, rather than using case distinctions.
3088 @item M-x c-forward-into-nomenclature
3089 @findex c-forward-into-nomenclature
3090 Move point forward to end of a C++ nomenclature section or word.
3091 With prefix argument @var{n}, move @var{n} times.
3095 @subsection Electric C Characters
3097 In C mode and related modes, certain printing characters are
3098 ``electric''---in addition to inserting themselves, they also reindent
3099 the current line and may insert newlines. This feature is controlled by
3100 the variable @code{c-auto-newline}. The ``electric'' characters are
3101 @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
3102 @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
3104 Electric characters insert newlines only when the @dfn{auto-newline}
3105 feature is enabled (indicated by @samp{/a} in the mode line after the
3106 mode name). This feature is controlled by the variable
3107 @code{c-auto-newline}. You can turn this feature on or off with the
3108 command @kbd{C-c C-a}:
3112 @kindex C-c C-a @r{(C mode)}
3113 @findex c-toggle-auto-state
3114 Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a
3115 prefix argument, this command turns the auto-newline feature on if the
3116 argument is positive, and off if it is negative.
3119 The colon character is electric because that is appropriate for a
3120 single colon. But when you want to insert a double colon in C++, the
3121 electric behavior of colon is inconvenient. You can insert a double
3122 colon with no reindentation or newlines by typing @kbd{C-c :}:
3126 @kindex C-c : @r{(C mode)}
3127 @findex c-scope-operator
3128 Insert a double colon scope operator at point, without reindenting the
3129 line or adding any newlines (@code{c-scope-operator}).
3132 The electric @kbd{#} key reindents the line if it appears to be the
3133 beginning of a preprocessor directive. This happens when the value of
3134 @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
3135 this feature off by setting @code{c-electric-pound-behavior} to
3138 The variable @code{c-hanging-braces-alist} controls the insertion of
3139 newlines before and after inserted braces. It is an association list
3140 with elements of the following form: @code{(@var{syntactic-symbol}
3141 . @var{nl-list})}. Most of the syntactic symbols that appear in
3142 @code{c-offsets-alist} are meaningful here as well.
3144 The list @var{nl-list} may contain either of the symbols
3145 @code{before} or @code{after}, or both; or it may be @code{nil}. When a
3146 brace is inserted, the syntactic context it defines is looked up in
3147 @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
3148 to determine where newlines are inserted: either before the brace,
3149 after, or both. If not found, the default is to insert a newline both
3150 before and after braces.
3152 The variable @code{c-hanging-colons-alist} controls the insertion of
3153 newlines before and after inserted colons. It is an association list
3154 with elements of the following form: @code{(@var{syntactic-symbol}
3155 . @var{nl-list})}. The list @var{nl-list} may contain either of the
3156 symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
3158 When a colon is inserted, the syntactic symbol it defines is looked
3159 up in this list, and if found, the @var{nl-list} is used to determine
3160 where newlines are inserted: either before the brace, after, or both.
3161 If the syntactic symbol is not found in this list, no newlines are
3164 Electric characters can also delete newlines automatically when the
3165 auto-newline feature is enabled. This feature makes auto-newline more
3166 acceptable, by deleting the newlines in the most common cases where you
3167 do not want them. Emacs can recognize several cases in which deleting a
3168 newline might be desirable; by setting the variable
3169 @code{c-cleanup-list}, you can specify @emph{which} of these cases that
3170 should happen. The variable's value is a list of symbols, each
3171 describing one case for possible deletion of a newline. Here are the
3172 meaningful symbols, and their meanings:
3175 @item brace-catch-brace
3176 Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
3177 entire construct on a single line. The clean-up occurs when you type
3178 the @samp{@{}, if there is nothing between the braces aside from
3179 @code{catch} and @var{condition}.
3181 @item brace-else-brace
3182 Clean up @samp{@} else @{} constructs by placing the entire construct on
3183 a single line. The clean-up occurs when you type the @samp{@{} after
3184 the @code{else}, but only if there is nothing but white space between
3185 the braces and the @code{else}.
3187 @item brace-elseif-brace
3188 Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
3189 construct on a single line. The clean-up occurs when you type the
3190 @samp{@{}, if there is nothing but white space between the @samp{@}} and
3191 @samp{@{} aside from the keywords and the @code{if}-condition.
3193 @item empty-defun-braces
3194 Clean up empty defun braces by placing the braces on the same
3195 line. Clean-up occurs when you type the closing brace.
3197 @item defun-close-semi
3198 Clean up the semicolon after a @code{struct} or similar type
3199 declaration, by placing the semicolon on the same line as the closing
3200 brace. Clean-up occurs when you type the semicolon.
3202 @item list-close-comma
3203 Clean up commas following braces in array and aggregate
3204 initializers. Clean-up occurs when you type the comma.
3206 @item scope-operator
3207 Clean up double colons which may designate a C++ scope operator, by
3208 placing the colons together. Clean-up occurs when you type the second
3209 colon, but only when the two colons are separated by nothing but
3214 @subsection Hungry Delete Feature in C
3216 When the @dfn{hungry-delete} feature is enabled (indicated by
3217 @samp{/h} or @samp{/ah} in the mode line after the mode name), a single
3218 @key{DEL} command deletes all preceding whitespace, not just one space.
3219 To turn this feature on or off, use @kbd{C-c C-d}:
3223 @kindex C-c C-d @r{(C mode)}
3224 @findex c-toggle-hungry-state
3225 Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a
3226 prefix argument, this command turns the hungry-delete feature on if the
3227 argument is positive, and off if it is negative.
3230 @kindex C-c C-t @r{(C mode)}
3231 @findex c-toggle-auto-hungry-state
3232 Toggle the auto-newline and hungry-delete features, both at once
3233 (@code{c-toggle-auto-hungry-state}).
3236 @vindex c-hungry-delete-key
3237 The variable @code{c-hungry-delete-key} controls whether the
3238 hungry-delete feature is enabled.
3240 @node Other C Commands
3241 @subsection Other Commands for C Mode
3245 Put mark at the end of a function definition, and put point at the
3246 beginning (@code{c-mark-function}).
3249 @kindex M-q @r{(C mode)}
3250 @findex c-fill-paragraph
3251 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
3252 If any part of the current line is a comment or within a comment, this
3253 command fills the comment or the paragraph of it that point is in,
3254 preserving the comment indentation and comment delimiters.
3257 @cindex macro expansion in C
3258 @cindex expansion of C macros
3259 @findex c-macro-expand
3260 @kindex C-c C-e @r{(C mode)}
3261 Run the C preprocessor on the text in the region, and show the result,
3262 which includes the expansion of all the macro calls
3263 (@code{c-macro-expand}). The buffer text before the region is also
3264 included in preprocessing, for the sake of macros defined there, but the
3265 output from this part isn't shown.
3267 When you are debugging C code that uses macros, sometimes it is hard to
3268 figure out precisely how the macros expand. With this command, you
3269 don't have to figure it out; you can see the expansions.
3272 @findex c-backslash-region
3273 @kindex C-c C-\ @r{(C mode)}
3274 Insert or align @samp{\} characters at the ends of the lines of the
3275 region (@code{c-backslash-region}). This is useful after writing or
3276 editing a C macro definition.
3278 If a line already ends in @samp{\}, this command adjusts the amount of
3279 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
3280 the last line in the region is treated specially; no @samp{\} is
3281 inserted on that line, and any @samp{\} there is deleted.
3283 @item M-x cpp-highlight-buffer
3284 @cindex preprocessor highlighting
3285 @findex cpp-highlight-buffer
3286 Highlight parts of the text according to its preprocessor conditionals.
3287 This command displays another buffer named @samp{*CPP Edit*}, which
3288 serves as a graphic menu for selecting how to display particular kinds
3289 of conditionals and their contents. After changing various settings,
3290 click on @samp{[A]pply these settings} (or go to that buffer and type
3291 @kbd{a}) to rehighlight the C mode buffer accordingly.
3294 @findex c-show-syntactic-information
3295 @kindex C-c C-s @r{(C mode)}
3296 Display the syntactic information about the current source line
3297 (@code{c-show-syntactic-information}). This is the information that
3298 directs how the line is indented.
3300 @item M-x cwarn-mode
3301 @itemx M-x global-cwarn-mode
3303 @findex global-cwarn-mode
3305 @cindex suspicious constructions in C, C++
3306 CWarn minor mode highlights certain suspicious C and C++ constructions:
3310 Assignments inside expressions.
3312 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
3313 (except after a @samp{do @dots{} while} statement);
3315 C++ functions with reference parameters.
3319 You can enable the mode for one buffer with the command @kbd{M-x
3320 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
3321 global-cwarn-mode} or by customizing the variable
3322 @code{global-cwarn-mode}. You must also enable Font Lock mode to make
3325 @item M-x hide-ifdef-mode
3326 @findex hide-ifdef-mode
3327 @cindex Hide-ifdef mode
3328 Hide-ifdef minor mode hides selected code within @samp{#if} and
3329 @samp{#ifdef} preprocessor blocks. See the documentation string of
3330 @code{hide-ifdef-mode} for more information.
3332 @item M-x ff-find-related-file
3333 @cindex related files
3334 @findex ff-find-related-file
3335 @vindex ff-related-file-alist
3336 Find a file ``related'' in a special way to the file visited by the
3337 current buffer. Typically this will be the header file corresponding
3338 to a C/C++ source file, or vice versa. The variable
3339 @code{ff-related-file-alist} specifies how to compute related file
3344 @subsection Comments in C Modes
3346 C mode and related modes use a number of variables for controlling
3350 @item c-comment-only-line-offset
3351 @vindex c-comment-only-line-offset
3352 Extra offset for line which contains only the start of a comment. It
3353 can be either an integer or a cons cell of the form
3354 @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
3355 @var{non-anchored-offset} is the amount of offset given to
3356 non-column-zero anchored comment-only lines, and @var{anchored-offset}
3357 is the amount of offset to give column-zero anchored comment-only lines.
3358 Just an integer as value is equivalent to @code{(@var{val} . 0)}.
3360 @item c-comment-start-regexp
3361 @vindex c-comment-start-regexp
3362 This buffer-local variable specifies how to recognize the start of a comment.
3364 @item c-hanging-comment-ender-p
3365 @vindex c-hanging-comment-ender-p
3366 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
3367 comment terminator of a block comment on a line by itself. The default
3368 value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
3369 end of the last line of the comment text.
3371 @item c-hanging-comment-starter-p
3372 @vindex c-hanging-comment-starter-p
3373 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
3374 starting delimiter of a block comment on a line by itself. The default
3375 value is @code{t}, which puts the comment-start delimiter @samp{/*} at
3376 the beginning of the first line of the comment text.
3380 @section Fortran Mode
3381 @cindex Fortran mode
3382 @cindex mode, Fortran
3384 Fortran mode provides special motion commands for Fortran statements and
3385 subprograms, and indentation commands that understand Fortran conventions
3386 of nesting, line numbers and continuation statements. Fortran mode has
3387 its own Auto Fill mode that breaks long lines into proper Fortran
3390 Special commands for comments are provided because Fortran comments
3391 are unlike those of other languages. Built-in abbrevs optionally save
3392 typing when you insert Fortran keywords.
3394 Use @kbd{M-x fortran-mode} to switch to this major mode. This command
3395 runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
3397 @cindex Fortran77 and Fortran90
3399 @findex fortran-mode
3400 Fortan mode is meant for editing Fortran77 ``fixed format'' source
3401 code. For editing the modern Fortran90 ``free format'' source code,
3402 use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for
3403 files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode
3404 for the extension @samp{.f90}. GNU Fortran supports both kinds of
3408 * Motion: Fortran Motion. Moving point by statements or subprograms.
3409 * Indent: Fortran Indent. Indentation commands for Fortran.
3410 * Comments: Fortran Comments. Inserting and aligning comments.
3411 * Autofill: Fortran Autofill. Auto fill minor mode for Fortran.
3412 * Columns: Fortran Columns. Measuring columns for valid Fortran.
3413 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
3416 @node Fortran Motion
3417 @subsection Motion Commands
3419 In addition to the normal commands for moving by and operating on
3420 ``defuns'' (Fortran subprograms---functions and subroutines), Fortran
3421 mode provides special commands to move by statements.
3424 @kindex C-c C-n @r{(Fortran mode)}
3425 @findex fortran-next-statement
3427 Move to beginning of current or next statement
3428 (@code{fortran-next-statement}).
3430 @kindex C-c C-p @r{(Fortran mode)}
3431 @findex fortran-previous-statement
3433 Move to beginning of current or previous statement
3434 (@code{fortran-previous-statement}).
3437 @node Fortran Indent
3438 @subsection Fortran Indentation
3440 Special commands and features are needed for indenting Fortran code in
3441 order to make sure various syntactic entities (line numbers, comment line
3442 indicators and continuation line flags) appear in the columns that are
3443 required for standard Fortran.
3446 * Commands: ForIndent Commands. Commands for indenting and filling Fortran.
3447 * Contline: ForIndent Cont. How continuation lines indent.
3448 * Numbers: ForIndent Num. How line numbers auto-indent.
3449 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
3450 * Vars: ForIndent Vars. Variables controlling Fortran indent style.
3453 @node ForIndent Commands
3454 @subsubsection Fortran Indentation and Filling Commands
3458 Break the current line and set up a continuation line
3459 (@code{fortran-split-line}).
3461 Join this line to the previous line (@code{fortran-join-line}).
3463 Indent all the lines of the subprogram point is in
3464 (@code{fortran-indent-subprogram}).
3466 Fill a comment block or statement.
3469 @kindex C-M-q @r{(Fortran mode)}
3470 @findex fortran-indent-subprogram
3471 The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
3472 to reindent all the lines of the Fortran subprogram (function or
3473 subroutine) containing point.
3475 @kindex C-M-j @r{(Fortran mode)}
3476 @findex fortran-split-line
3477 The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
3478 a line in the appropriate fashion for Fortran. In a non-comment line,
3479 the second half becomes a continuation line and is indented
3480 accordingly. In a comment line, both halves become separate comment
3483 @kindex M-^ @r{(Fortran mode)}
3484 @kindex C-c C-d @r{(Fortran mode)}
3485 @findex fortran-join-line
3486 @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
3487 which joins a continuation line back to the previous line, roughly as
3488 the inverse of @code{fortran-split-line}. The point must be on a
3489 continuation line when this command is invoked.
3491 @kindex M-q @r{(Fortran mode)}
3492 @kbd{M-q} in Fortran mode fills the comment block or statement that
3493 point is in. This removes any excess statement continuations.
3495 @node ForIndent Cont
3496 @subsubsection Continuation Lines
3497 @cindex Fortran continuation lines
3499 @vindex fortran-continuation-string
3500 Most modern Fortran compilers allow two ways of writing continuation
3501 lines. If the first non-space character on a line is in column 5, then
3502 that line is a continuation of the previous line. We call this
3503 @dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The
3504 variable @code{fortran-continuation-string} specifies what character to
3505 put on column 5. A line that starts with a tab character followed by
3506 any digit except @samp{0} is also a continuation line. We call this
3507 style of continuation @dfn{tab format}.
3509 @vindex indent-tabs-mode @r{(Fortran mode)}
3510 Fortran mode can make either style of continuation line, but you
3511 must specify which one you prefer. The value of the variable
3512 @code{indent-tabs-mode} controls the choice: @code{nil} for fixed
3513 format, and non-@code{nil} for tab format. You can tell which style
3514 is presently in effect by the presence or absence of the string
3515 @samp{Tab} in the mode line.
3517 If the text on a line starts with the conventional Fortran
3518 continuation marker @samp{$}, or if it begins with any non-whitespace
3519 character in column 5, Fortran mode treats it as a continuation line.
3520 When you indent a continuation line with @key{TAB}, it converts the line
3521 to the current continuation style. When you split a Fortran statement
3522 with @kbd{C-M-j}, the continuation marker on the newline is created
3523 according to the continuation style.
3525 The setting of continuation style affects several other aspects of
3526 editing in Fortran mode. In fixed format mode, the minimum column
3527 number for the body of a statement is 6. Lines inside of Fortran
3528 blocks that are indented to larger column numbers always use only the
3529 space character for whitespace. In tab format mode, the minimum
3530 column number for the statement body is 8, and the whitespace before
3531 column 8 must always consist of one tab character.
3533 @vindex fortran-tab-mode-default
3534 @vindex fortran-analyze-depth
3535 When you enter Fortran mode for an existing file, it tries to deduce the
3536 proper continuation style automatically from the file contents. The first
3537 line that begins with either a tab character or six spaces determines the
3538 choice. The variable @code{fortran-analyze-depth} specifies how many lines
3539 to consider (at the beginning of the file); if none of those lines
3540 indicates a style, then the variable @code{fortran-tab-mode-default}
3541 specifies the style. If it is @code{nil}, that specifies fixed format, and
3542 non-@code{nil} specifies tab format.
3545 @subsubsection Line Numbers
3547 If a number is the first non-whitespace in the line, Fortran
3548 indentation assumes it is a line number and moves it to columns 0
3549 through 4. (Columns always count from 0 in GNU Emacs.)
3551 @vindex fortran-line-number-indent
3552 Line numbers of four digits or less are normally indented one space.
3553 The variable @code{fortran-line-number-indent} controls this; it
3554 specifies the maximum indentation a line number can have. Line numbers
3555 are indented to right-justify them to end in column 4 unless that would
3556 require more than this maximum indentation. The default value of the
3559 @vindex fortran-electric-line-number
3560 Simply inserting a line number is enough to indent it according to
3561 these rules. As each digit is inserted, the indentation is recomputed.
3562 To turn off this feature, set the variable
3563 @code{fortran-electric-line-number} to @code{nil}. Then inserting line
3564 numbers is like inserting anything else.
3566 @node ForIndent Conv
3567 @subsubsection Syntactic Conventions
3569 Fortran mode assumes that you follow certain conventions that simplify
3570 the task of understanding a Fortran program well enough to indent it
3575 Two nested @samp{do} loops never share a @samp{continue} statement.
3578 Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
3579 and others are written without embedded whitespace or line breaks.
3581 Fortran compilers generally ignore whitespace outside of string
3582 constants, but Fortran mode does not recognize these keywords if they
3583 are not contiguous. Constructs such as @samp{else if} or @samp{end do}
3584 are acceptable, but the second word should be on the same line as the
3585 first and not on a continuation line.
3589 If you fail to follow these conventions, the indentation commands may
3590 indent some lines unaesthetically. However, a correct Fortran program
3591 retains its meaning when reindented even if the conventions are not
3594 @node ForIndent Vars
3595 @subsubsection Variables for Fortran Indentation
3597 @vindex fortran-do-indent
3598 @vindex fortran-if-indent
3599 @vindex fortran-structure-indent
3600 @vindex fortran-continuation-indent
3601 @vindex fortran-check-all-num@dots{}
3602 @vindex fortran-minimum-statement-indent@dots{}
3603 Several additional variables control how Fortran indentation works:
3606 @item fortran-do-indent
3607 Extra indentation within each level of @samp{do} statement (default 3).
3609 @item fortran-if-indent
3610 Extra indentation within each level of @samp{if} statement (default 3).
3611 This value is also used for extra indentation within each level of the
3612 Fortran 90 @samp{where} statement.
3614 @item fortran-structure-indent
3615 Extra indentation within each level of @samp{structure}, @samp{union}, or
3616 @samp{map} statements (default 3).
3618 @item fortran-continuation-indent
3619 Extra indentation for bodies of continuation lines (default 5).
3621 @item fortran-check-all-num-for-matching-do
3622 If this is @code{nil}, indentation assumes that each @samp{do} statement
3623 ends on a @samp{continue} statement. Therefore, when computing
3624 indentation for a statement other than @samp{continue}, it can save time
3625 by not checking for a @samp{do} statement ending there. If this is
3626 non-@code{nil}, indenting any numbered statement must check for a
3627 @samp{do} that ends there. The default is @code{nil}.
3629 @item fortran-blink-matching-if
3630 If this is @code{t}, indenting an @samp{endif} statement moves the
3631 cursor momentarily to the matching @samp{if} statement to show where it
3632 is. The default is @code{nil}.
3634 @item fortran-minimum-statement-indent-fixed
3635 Minimum indentation for fortran statements when using fixed format
3636 continuation line style. Statement bodies are never indented less than
3637 this much. The default is 6.
3639 @item fortran-minimum-statement-indent-tab
3640 Minimum indentation for fortran statements for tab format continuation line
3641 style. Statement bodies are never indented less than this much. The
3645 @node Fortran Comments
3646 @subsection Fortran Comments
3648 The usual Emacs comment commands assume that a comment can follow a line
3649 of code. In Fortran, the standard comment syntax requires an entire line
3650 to be just a comment. Therefore, Fortran mode replaces the standard Emacs
3651 comment commands and defines some new variables.
3653 Fortran mode can also handle the Fortran90 comment syntax where comments
3654 start with @samp{!} and can follow other text. Because only some Fortran77
3655 compilers accept this syntax, Fortran mode will not insert such comments
3656 unless you have said in advance to do so. To do this, set the variable
3657 @code{comment-start} to @samp{"!"} (@pxref{Variables}).
3661 Align comment or insert new comment (@code{fortran-comment-indent}).
3664 Applies to nonstandard @samp{!} comments only.
3667 Turn all lines of the region into comments, or (with argument) turn them back
3668 into real code (@code{fortran-comment-region}).
3671 @kbd{M-;} in Fortran mode is redefined as the command
3672 @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
3673 recognizes any kind of existing comment and aligns its text appropriately;
3674 if there is no existing comment, a comment is inserted and aligned. But
3675 inserting and aligning comments are not the same in Fortran mode as in
3678 When a new comment must be inserted, if the current line is blank, a
3679 full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
3680 comment is inserted if you have said you want to use them. Otherwise a
3681 full-line comment is inserted on a new line before the current line.
3683 Nonstandard @samp{!} comments are aligned like comments in other
3684 languages, but full-line comments are different. In a standard full-line
3685 comment, the comment delimiter itself must always appear in column zero.
3686 What can be aligned is the text within the comment. You can choose from
3687 three styles of alignment by setting the variable
3688 @code{fortran-comment-indent-style} to one of these values:
3690 @vindex fortran-comment-indent-style
3691 @vindex fortran-comment-line-extra-indent
3694 Align the text at a fixed column, which is the sum of
3695 @code{fortran-comment-line-extra-indent} and the minimum statement
3696 indentation. This is the default.
3698 The minimum statement indentation is
3699 @code{fortran-minimum-statement-indent-fixed} for fixed format
3700 continuation line style and @code{fortran-minimum-statement-indent-tab}
3701 for tab format style.
3704 Align the text as if it were a line of code, but with an additional
3705 @code{fortran-comment-line-extra-indent} columns of indentation.
3708 Don't move text in full-line comments automatically at all.
3711 @vindex fortran-comment-indent-char
3712 In addition, you can specify the character to be used to indent within
3713 full-line comments by setting the variable
3714 @code{fortran-comment-indent-char} to the single-character string you want
3717 @vindex comment-line-start
3718 @vindex comment-line-start-skip
3719 Fortran mode introduces two variables @code{comment-line-start} and
3720 @code{comment-line-start-skip}, which play for full-line comments the same
3721 roles played by @code{comment-start} and @code{comment-start-skip} for
3722 ordinary text-following comments. Normally these are set properly by
3723 Fortran mode, so you do not need to change them.
3725 The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
3726 you use @samp{!} comments, this command can be used with them. Otherwise
3727 it is useless in Fortran mode.
3729 @kindex C-c ; @r{(Fortran mode)}
3730 @findex fortran-comment-region
3731 @vindex fortran-comment-region
3732 The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
3733 lines of the region into comments by inserting the string @samp{C$$$} at
3734 the front of each one. With a numeric argument, it turns the region
3735 back into live code by deleting @samp{C$$$} from the front of each line
3736 in it. The string used for these comments can be controlled by setting
3737 the variable @code{fortran-comment-region}. Note that here we have an
3738 example of a command and a variable with the same name; these two uses
3739 of the name never conflict because in Lisp and in Emacs it is always
3740 clear from the context which one is meant.
3742 @node Fortran Autofill
3743 @subsection Fortran Auto Fill Mode
3745 Fortran Auto Fill mode is a minor mode which automatically splits
3746 Fortran statements as you insert them when they become too wide.
3747 Splitting a statement involves making continuation lines using
3748 @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This
3749 splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
3750 also in the Fortran indentation commands.
3752 @findex fortran-auto-fill-mode
3753 @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
3754 was off, or off if it was on. This command works the same as @kbd{M-x
3755 auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
3756 positive numeric argument turns Fortran Auto Fill mode on, and a
3757 negative argument turns it off. You can see when Fortran Auto Fill mode
3758 is in effect by the presence of the word @samp{Fill} in the mode line,
3759 inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
3760 on or off for each buffer individually. @xref{Minor Modes}.
3762 @vindex fortran-break-before-delimiters
3763 Fortran Auto Fill mode breaks lines at spaces or delimiters when the
3764 lines get longer than the desired width (the value of @code{fill-column}).
3765 The delimiters that Fortran Auto Fill mode may break at are @samp{,},
3766 @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
3767 The line break comes after the delimiter if the variable
3768 @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by
3769 default), the break comes before the delimiter.
3771 By default, Fortran Auto Fill mode is not enabled. If you want this
3772 feature turned on permanently, add a hook function to
3773 @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
3776 @node Fortran Columns
3777 @subsection Checking Columns in Fortran
3781 Display a ``column ruler'' momentarily above the current line
3782 (@code{fortran-column-ruler}).
3784 Split the current window horizontally temporarily so that it is 72
3785 columns wide (@code{fortran-window-create-momentarily}). This may
3786 help you avoid making lines longer than the 72-character limit that
3787 some Fortran compilers impose.
3789 Split the current window horizontally so that it is 72 columns wide
3790 (@code{fortran-window-create}). You can then continue editing.
3791 @item M-x fortran-strip-sequence-nos
3792 Delete all text in column 72 and beyond.
3795 @kindex C-c C-r @r{(Fortran mode)}
3796 @findex fortran-column-ruler
3797 The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
3798 ruler momentarily above the current line. The comment ruler is two lines
3799 of text that show you the locations of columns with special significance in
3800 Fortran programs. Square brackets show the limits of the columns for line
3801 numbers, and curly brackets show the limits of the columns for the
3802 statement body. Column numbers appear above them.
3804 Note that the column numbers count from zero, as always in GNU Emacs.
3805 As a result, the numbers may be one less than those you are familiar
3806 with; but the positions they indicate in the line are standard for
3809 @vindex fortran-column-ruler-fixed
3810 @vindex fortran-column-ruler-tabs
3811 The text used to display the column ruler depends on the value of
3812 the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
3813 @code{nil}, then the value of the variable
3814 @code{fortran-column-ruler-fixed} is used as the column ruler.
3815 Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
3816 By changing these variables, you can change the column ruler display.
3818 @kindex C-c C-w @r{(Fortran mode)}
3819 @findex fortran-window-create-momentarily
3820 @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
3821 splits the current window horizontally, making a window 72 columns
3822 wide, so you can see which lines that is too long. Type a space to
3823 restore the normal width.
3825 @kindex C-u C-c C-w @r{(Fortran mode)}
3826 @findex fortran-window-create
3827 You can also split the window horizontally and continue editing with
3828 the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x
3829 fortran-window-create}). By editing in this window you can
3830 immediately see when you make a line too wide to be correct Fortran.
3832 @findex fortran-strip-sequence-nos
3833 The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in
3834 column 72 and beyond, on all lines in the current buffer. This is the
3835 easiest way to get rid of old sequence numbers.
3837 @node Fortran Abbrev
3838 @subsection Fortran Keyword Abbrevs
3840 Fortran mode provides many built-in abbrevs for common keywords and
3841 declarations. These are the same sort of abbrev that you can define
3842 yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}.
3844 The built-in abbrevs are unusual in one way: they all start with a
3845 semicolon. You cannot normally use semicolon in an abbrev, but Fortran
3846 mode makes this possible by changing the syntax of semicolon to ``word
3849 For example, one built-in Fortran abbrev is @samp{;c} for
3850 @samp{continue}. If you insert @samp{;c} and then insert a punctuation
3851 character such as a space or a newline, the @samp{;c} expands automatically
3852 to @samp{continue}, provided Abbrev mode is enabled.@refill
3854 Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
3855 Fortran abbrevs and what they stand for.
3861 @cindex assembler mode
3862 Asm mode is a major mode for editing files of assembler code. It
3863 defines these commands:
3867 @code{tab-to-tab-stop}.
3869 Insert a newline and then indent using @code{tab-to-tab-stop}.
3871 Insert a colon and then remove the indentation from before the label
3872 preceding colon. Then do @code{tab-to-tab-stop}.
3874 Insert or align a comment.
3877 The variable @code{asm-comment-char} specifies which character
3878 starts comments in assembler syntax.