*** empty log message ***
[emacs.git] / man / programs.texi
blobffd08d17f5c3e687678d5caaf33a4e54658388b4
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
6 @cindex Lisp editing
7 @cindex C editing
8 @cindex program editing
10   Emacs has many commands designed to understand the syntax of programming
11 languages such as Lisp and C.  These commands can
13 @itemize @bullet
14 @item
15 Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
16 @item
17 Move over or mark top-level expressions---@dfn{defuns}, in Lisp;
18 functions, in C (@pxref{Defuns}).
19 @item
20 Show how parentheses balance (@pxref{Matching}).
21 @item
22 Insert, kill or align comments (@pxref{Comments}).
23 @item
24 Follow the usual indentation conventions of the language
25 (@pxref{Program Indent}).
26 @end itemize
28   The commands for words, sentences and paragraphs are very useful in
29 editing code even though their canonical application is for editing
30 human language text.  Most symbols contain words (@pxref{Words});
31 sentences can be found in strings and comments (@pxref{Sentences}).
32 Paragraphs per se don't exist in code, but the paragraph commands are
33 useful anyway, because programming language major modes define
34 paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
35 Judicious use of blank lines to make the program clearer will also
36 provide useful chunks of text for the paragraph commands to work
37 on.
39 @cindex selective display
40 @cindex outline
41 @cindex folding
42 @findex outline-minor-mode
43 @cindex outlines
44   The selective display feature is useful for looking at the overall
45 structure of a function (@pxref{Selective Display}).  This feature
46 causes only the lines that are indented less than a specified amount to
47 appear on the screen.  Programming modes often support Outline minor
48 mode (@pxref{Outline Mode}).  The Foldout package provides
49 folding-editor features (@pxref{Foldout}).
51   The `automatic typing' features may be useful when writing programs.
52 @xref{,Autotyping,, autotype, Autotyping}.
54 @menu
55 * Program Modes::       Major modes for editing programs.
56 * Lists::               Expressions with balanced parentheses.
57 * List Commands::       The commands for working with list and sexps.
58 * Defuns::              Each program is made up of separate functions.
59                           There are editing commands to operate on them.
60 * Program Indent::      Adjusting indentation to show the nesting.
61 * Matching::            Insertion of a close-delimiter flashes matching open.
62 * Comments::            Inserting, killing, and aligning comments.
63 * Balanced Editing::    Inserting two matching parentheses at once, etc.
64 * Symbol Completion::   Completion on symbol names of your program or language.
65 * Which Function::      Which Function mode shows which function you are in.
66 * Hideshow::            Displaying blocks selectively.
67 * Glasses::             Making identifiersLikeThis more readable.
68 * Documentation::       Getting documentation of functions you plan to call.
69 * Change Log::          Maintaining a change history for your program.
70 * Authors::             Maintaining an @file{AUTHORS} file.
71 * Tags::                Go direct to any function in your program in one
72                           command.  Tags remembers which file it is in.
73 * Imenu::               Making buffer indexes as menus.
74 * Emerge::              A convenient way of merging two versions of a program.
75 * C Modes::             Special commands of C, C++, Objective-C,
76                           Java, and Pike modes.
77 * Fortran::             Fortran mode and its special features.
78 * Asm Mode::            Asm mode and its special features.
79 @end menu
81 @node Program Modes
82 @section Major Modes for Programming Languages
84 @cindex modes for programming languages
85 @cindex Perl mode
86 @cindex Icon mode
87 @cindex Awk mode
88 @cindex Makefile mode
89 @cindex Tcl mode
90 @cindex CPerl mode
91 @cindex DSSSL mode
92 @cindex Octave mode
93 @cindex Metafont mode
94 @cindex Modula2 mode
95 @cindex Prolog mode
96 @cindex Simula mode
97 @cindex VHDL mode
98 @cindex M4 mode
99 @cindex Shell-script mode
100 @cindex Delphi mode
101 @cindex PostScript mode
102   Emacs also has major modes for the programming languages Lisp, Scheme
103 (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
104 Awk, C, C++, Delphi (Object Pascal), Fortran (free and fixed format),
105 Icon, IDLWAVE,
106 Java, Metafont (@TeX{}'s companion for font creation), Modula2,
107 Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula,
108 VHDL, CORBA IDL, and Tcl.
109 There is also a major mode for makefiles, called Makefile
110 mode.  An alternative mode for Perl is called CPerl mode.  Modes
111 are available for scripts for the common Unix shells, VMS DCL and
112 MS-DOS/MS-Windows `BAT' files.  In a similar fashion to programming
113 languages, modes are provided for editing various sorts of configuration
114 files.
116 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
117 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
118 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
119 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
121   Ideally, a major mode should be implemented for each programming
122 language that you might want to edit with Emacs; but often the mode for
123 one language can serve for other syntactically similar languages.  The
124 language modes that exist are those that someone decided to take the
125 trouble to write.
127   There are several forms of Lisp mode, which differ in the way they
128 interface to Lisp execution.  @xref{Executing Lisp}.
130   Each of the programming language major modes defines the @key{TAB} key
131 to run an indentation function that knows the indentation conventions of
132 that language and updates the current line's indentation accordingly.
133 For example, in C mode @key{TAB} is bound to @code{c-indent-line}.
134 @kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
135 thus, it too indents in a mode-specific fashion.
137 @kindex DEL @r{(programming modes)}
138 @findex backward-delete-char-untabify
139   In most programming languages, indentation is likely to vary from line to
140 line.  So the major modes for those languages rebind @key{DEL} to treat a
141 tab as if it were the equivalent number of spaces (using the command
142 @code{backward-delete-char-untabify}).  This makes it possible to rub out
143 indentation one column at a time without worrying whether it is made up of
144 spaces or tabs.  Use @kbd{C-b C-d} to delete a tab character before point,
145 in these modes.
147   Programming language modes define paragraphs to be separated only by
148 blank lines, so that the paragraph commands remain useful.  Auto Fill mode,
149 if enabled in a programming language major mode, indents the new lines
150 which it creates.
152 @cindex mode hook
153 @vindex c-mode-hook
154 @vindex lisp-mode-hook
155 @vindex emacs-lisp-mode-hook
156 @vindex lisp-interaction-mode-hook
157 @vindex scheme-mode-hook
158   Turning on a major mode runs a normal hook called the @dfn{mode hook},
159 which is the value of a Lisp variable.  Each major mode has a mode hook,
160 and the hook's name is always made from the mode command's name by
161 adding @samp{-hook}.  For example, turning on C mode runs the hook
162 @code{c-mode-hook}, while turning on Lisp mode runs the hook
163 @code{lisp-mode-hook}.  @xref{Hooks}.
165 @node Lists
166 @section Lists and Sexps
168 @cindex Control-Meta
169   By convention, Emacs keys for dealing with balanced expressions are
170 usually Control-Meta characters.  They tend to be analogous in
171 function to their Control and Meta equivalents.  These commands are
172 usually thought of as pertaining to expressions in programming
173 languages, but can be useful with any language in which some sort of
174 parentheses exist (including human languages).
176 @cindex list
177 @cindex sexp
178 @cindex expression
179 @cindex parentheses, moving across
180 @cindex matching parenthesis, moving to
181   These commands fall into two classes.  Some deal only with @dfn{lists}
182 (parenthetical groupings).  They see nothing except parentheses, brackets,
183 braces (whichever ones must balance in the language you are working with),
184 and escape characters that might be used to quote those.
186   The other commands deal with expressions or @dfn{sexps}.  The word `sexp'
187 is derived from @dfn{s-expression}, the ancient term for an expression in
188 Lisp.  But in Emacs, the notion of `sexp' is not limited to Lisp.  It
189 refers to an expression in whatever language your program is written in.
190 Each programming language has its own major mode, which customizes the
191 syntax tables so that expressions in that language count as sexps.
193   Sexps typically include symbols, numbers, and string constants, as well
194 as anything contained in parentheses, brackets or braces.
196   In languages that use prefix and infix operators, such as C, it is not
197 possible for all expressions to be sexps.  For example, C mode does not
198 recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression;
199 it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
200 @samp{+} as punctuation between them.  This is a fundamental ambiguity:
201 both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
202 move over if point is at the @samp{f}.  Note that @samp{(foo + bar)} is a
203 single sexp in C mode.
205   Some languages have obscure forms of expression syntax that nobody
206 has bothered to make Emacs understand properly.
208 @node List Commands
209 @section List And Sexp Commands
211 @c doublewidecommands
212 @table @kbd
213 @item C-M-f
214 Move forward over a sexp (@code{forward-sexp}).
215 @item C-M-b
216 Move backward over a sexp (@code{backward-sexp}).
217 @item C-M-k
218 Kill sexp forward (@code{kill-sexp}).
219 @item C-M-@key{DEL}
220 Kill sexp backward (@code{backward-kill-sexp}).
221 @item C-M-u
222 Move up and backward in list structure (@code{backward-up-list}).
223 @item C-M-d
224 Move down and forward in list structure (@code{down-list}).
225 @item C-M-n
226 Move forward over a list (@code{forward-list}).
227 @item C-M-p
228 Move backward over a list (@code{backward-list}).
229 @item C-M-t
230 Transpose expressions (@code{transpose-sexps}).
231 @item C-M-@@
232 Put mark after following expression (@code{mark-sexp}).
233 @end table
235 @kindex C-M-f
236 @kindex C-M-b
237 @findex forward-sexp
238 @findex backward-sexp
239   To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}).  If
240 the first significant character after point is an opening delimiter
241 (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
242 moves past the matching closing delimiter.  If the character begins a
243 symbol, string, or number, @kbd{C-M-f} moves over that.
245   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
246 sexp.  The detailed rules are like those above for @kbd{C-M-f}, but with
247 directions reversed.  If there are any prefix characters (single-quote,
248 backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
249 over them as well.  The sexp commands move across comments as if they
250 were whitespace in most modes.
252   @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
253 specified number of times; with a negative argument, it moves in the
254 opposite direction.
256 @kindex C-M-k
257 @findex kill-sexp
258 @kindex C-M-DEL
259 @findex backward-kill-sexp
260   Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp})
261 or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}).  @kbd{C-M-k} kills
262 the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}}
263 kills the characters that @kbd{C-M-b} would move over.
265 @kindex C-M-n
266 @kindex C-M-p
267 @findex forward-list
268 @findex backward-list
269   The @dfn{list commands} move over lists, as the sexp commands do, but skip
270 blithely over any number of other kinds of sexps (symbols, strings, etc.).
271 They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
272 (@code{backward-list}).  The main reason they are useful is that they
273 usually ignore comments (since the comments usually do not contain any
274 lists).@refill
276 @kindex C-M-u
277 @kindex C-M-d
278 @findex backward-up-list
279 @findex down-list
280   @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
281 that's possible.  To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u}
282 (@code{backward-up-list}).
283 @kbd{C-M-u} moves backward up past one unmatched opening delimiter.  A
284 positive argument serves as a repeat count; a negative argument reverses
285 direction of motion and also requests repetition, so it moves forward and
286 up one or more levels.@refill
288   To move @emph{down} in list structure, use @kbd{C-M-d}
289 (@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
290 delimiter, this is nearly the same as searching for a @samp{(}.  An
291 argument specifies the number of levels of parentheses to go down.
293 @cindex transposition
294 @kindex C-M-t
295 @findex transpose-sexps
296   A somewhat random-sounding command which is nevertheless handy is
297 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp
298 across the next one.  An argument serves as a repeat count, and a
299 negative argument drags backwards (thus canceling out the effect of
300 @kbd{C-M-t} with a positive argument).  An argument of zero, rather than
301 doing nothing, transposes the sexps ending after point and the mark.
303 @kindex C-M-@@
304 @findex mark-sexp
305   To set the region around the next sexp in the buffer, use @kbd{C-M-@@}
306 (@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f}
307 would move to.  @kbd{C-M-@@} takes arguments like @kbd{C-M-f}.  In
308 particular, a negative argument is useful for putting the mark at the
309 beginning of the previous sexp.
311   The list and sexp commands' understanding of syntax is completely
312 controlled by the syntax table.  Any character can, for example, be
313 declared to be an opening delimiter and act like an open parenthesis.
314 @xref{Syntax}.
316 @node Defuns
317 @section Defuns
318 @cindex defuns
320   In Emacs, a parenthetical grouping at the top level in the buffer is
321 called a @dfn{defun}.  The name derives from the fact that most top-level
322 lists in a Lisp file are instances of the special form @code{defun}, but
323 any top-level parenthetical grouping counts as a defun in Emacs parlance
324 regardless of what its contents are, and regardless of the programming
325 language in use.  For example, in C, the body of a function definition is a
326 defun.
328 @c doublewidecommands
329 @table @kbd
330 @item C-M-a
331 Move to beginning of current or preceding defun
332 (@code{beginning-of-defun}).
333 @item C-M-e
334 Move to end of current or following defun (@code{end-of-defun}).
335 @item C-M-h
336 Put region around whole current or following defun (@code{mark-defun}).
337 @end table
339 @kindex C-M-a
340 @kindex C-M-e
341 @kindex C-M-h
342 @findex beginning-of-defun
343 @findex end-of-defun
344 @findex mark-defun
345   The commands to move to the beginning and end of the current defun are
346 @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
348 @findex c-mark-function
349   If you wish to operate on the current defun, use @kbd{C-M-h}
350 (@code{mark-defun}) which puts point at the beginning and mark at the end
351 of the current or next defun.  For example, this is the easiest way to get
352 ready to move the defun to a different place in the text.  In C mode,
353 @kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the
354 same as @code{mark-defun}; the difference is that it backs up over the
355 argument declarations, function name and returned data type so that the
356 entire C function is inside the region.  @xref{Marking Objects}.
358 @cindex open-parenthesis in leftmost column
359 @cindex ( in leftmost column
360   Emacs assumes that any open-parenthesis found in the leftmost column
361 is the start of a defun.  Therefore, @strong{never put an
362 open-parenthesis at the left margin in a Lisp file unless it is the
363 start of a top-level list.  Never put an open-brace or other opening
364 delimiter at the beginning of a line of C code unless it starts the body
365 of a function.}  The most likely problem case is when you want an
366 opening delimiter at the start of a line inside a string.  To avoid
367 trouble, put an escape character (@samp{\}, in C and Emacs Lisp,
368 @samp{/} in some other Lisp dialects) before the opening delimiter.  It
369 will not affect the contents of the string.
371   In the remotest past, the original Emacs found defuns by moving upward a
372 level of parentheses until there were no more levels to go up.  This always
373 required scanning all the way back to the beginning of the buffer, even for
374 a small function.  To speed up the operation, Emacs was changed to assume
375 that any @samp{(} (or other character assigned the syntactic class of
376 opening-delimiter) at the left margin is the start of a defun.  This
377 heuristic is nearly always right and avoids the costly scan; however,
378 it mandates the convention described above.
380 @node Program Indent
381 @section Indentation for Programs
382 @cindex indentation for programs
384   The best way to keep a program properly indented is to use Emacs to
385 reindent it as you change it.  Emacs has commands to indent properly
386 either a single line, a specified number of lines, or all of the lines
387 inside a single parenthetical grouping.
389 @menu
390 * Basic Indent::        Indenting a single line.
391 * Multi-line Indent::   Commands to reindent many lines at once.
392 * Lisp Indent::         Specifying how each Lisp function should be indented.
393 * C Indent::            Extra features for indenting C and related modes.
394 * Custom C Indent::     Controlling indentation style for C and related modes.
395 @end menu
397   Emacs also provides a Lisp pretty-printer in the library @code{pp}.
398 This program reformats a Lisp object with indentation chosen to look nice.
400 @node Basic Indent
401 @subsection Basic Program Indentation Commands
403 @c WideCommands
404 @table @kbd
405 @item @key{TAB}
406 Adjust indentation of current line.
407 @item C-j
408 Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
409 @end table
411 @kindex TAB @r{(programming modes)}
412 @findex c-indent-line
413 @findex lisp-indent-line
414   The basic indentation command is @key{TAB}, which gives the current line
415 the correct indentation as determined from the previous lines.  The
416 function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
417 in Lisp mode, @code{c-indent-line} in C mode, etc.  These functions
418 understand different syntaxes for different languages, but they all do
419 about the same thing.  @key{TAB} in any programming-language major mode
420 inserts or deletes whitespace at the beginning of the current line,
421 independent of where point is in the line.  If point is inside the
422 whitespace at the beginning of the line, @key{TAB} leaves it at the end of
423 that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
424 the characters around it.
426   Use @kbd{C-q @key{TAB}} to insert a tab at point.
428 @kindex C-j
429 @findex newline-and-indent
430   When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}),
431 which is equivalent to a @key{RET} followed by a @key{TAB}.  @kbd{C-j} creates
432 a blank line and then gives it the appropriate indentation.
434   @key{TAB} indents the second and following lines of the body of a
435 parenthetical grouping each under the preceding one; therefore, if you
436 alter one line's indentation to be nonstandard, the lines below will
437 tend to follow it.  This behavior is convenient in cases where you have
438 overridden the standard result of @key{TAB} because you find it
439 unaesthetic for a particular line.
441   Remember that an open-parenthesis, open-brace or other opening delimiter
442 at the left margin is assumed by Emacs (including the indentation routines)
443 to be the start of a function.  Therefore, you must never have an opening
444 delimiter in column zero that is not the beginning of a function, not even
445 inside a string.  This restriction is vital for making the indentation
446 commands fast; you must simply accept it.  @xref{Defuns}, for more
447 information on this.
449 @node Multi-line Indent
450 @subsection Indenting Several Lines
452   When you wish to reindent several lines of code which have been altered
453 or moved to a different level in the list structure, you have several
454 commands available.
456 @table @kbd
457 @item C-M-q
458 Reindent all the lines within one list (@code{indent-sexp}).
459 @item C-u @key{TAB}
460 Shift an entire list rigidly sideways so that its first line
461 is properly indented.
462 @item C-M-\
463 Reindent all lines in the region (@code{indent-region}).
464 @end table
466 @kindex C-M-q
467 @findex indent-sexp
468   You can reindent the contents of a single list by positioning point
469 before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
470 Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable
471 commands in other modes).  The indentation of the line the sexp starts on
472 is not changed; therefore, only the relative indentation within the list,
473 and not its position, is changed.  To correct the position as well, type a
474 @key{TAB} before the @kbd{C-M-q}.
476 @kindex C-u TAB
477   If the relative indentation within a list is correct but the
478 indentation of its first line is not, go to that line and type @kbd{C-u
479 @key{TAB}}.  @key{TAB} with a numeric argument reindents the current
480 line as usual, then reindents by the same amount all the lines in the
481 grouping starting on the current line.  In other words, it reindents the
482 whole grouping rigidly as a unit.  It is clever, though, and does not
483 alter lines that start inside strings, or C preprocessor lines when in C
484 mode.
486   Another way to specify the range to be reindented is with the region.
487 The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to
488 every line whose first character is between point and mark.
490 @node Lisp Indent
491 @subsection Customizing Lisp Indentation
492 @cindex customizing Lisp indentation
494   The indentation pattern for a Lisp expression can depend on the function
495 called by the expression.  For each Lisp function, you can choose among
496 several predefined patterns of indentation, or define an arbitrary one with
497 a Lisp program.
499   The standard pattern of indentation is as follows: the second line of the
500 expression is indented under the first argument, if that is on the same
501 line as the beginning of the expression; otherwise, the second line is
502 indented underneath the function name.  Each following line is indented
503 under the previous line whose nesting depth is the same.
505 @vindex lisp-indent-offset
506   If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
507 the usual indentation pattern for the second line of an expression, so that
508 such lines are always indented @code{lisp-indent-offset} more columns than
509 the containing list.
511 @vindex lisp-body-indent
512   The standard pattern is overridden for certain functions.  Functions
513 whose names start with @code{def} always indent the second line by
514 @code{lisp-body-indent} extra columns beyond the open-parenthesis
515 starting the expression.
517   The standard pattern can be overridden in various ways for individual
518 functions, according to the @code{lisp-indent-function} property of the
519 function name.  There are four possibilities for this property:
521 @table @asis
522 @item @code{nil}
523 This is the same as no property; the standard indentation pattern is used.
524 @item @code{defun}
525 The pattern used for function names that start with @code{def} is used for
526 this function also.
527 @item a number, @var{number}
528 The first @var{number} arguments of the function are
529 @dfn{distinguished} arguments; the rest are considered the @dfn{body}
530 of the expression.  A line in the expression is indented according to
531 whether the first argument on it is distinguished or not.  If the
532 argument is part of the body, the line is indented @code{lisp-body-indent}
533 more columns than the open-parenthesis starting the containing
534 expression.  If the argument is distinguished and is either the first
535 or second argument, it is indented @emph{twice} that many extra columns.
536 If the argument is distinguished and not the first or second argument,
537 the standard pattern is followed for that line.
538 @item a symbol, @var{symbol}
539 @var{symbol} should be a function name; that function is called to
540 calculate the indentation of a line within this expression.  The
541 function receives two arguments:
542 @table @asis
543 @item @var{state}
544 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
545 indentation and nesting computation) when it parses up to the
546 beginning of this line.
547 @item @var{pos}
548 The position at which the line being indented begins.
549 @end table
550 @noindent
551 It should return either a number, which is the number of columns of
552 indentation for that line, or a list whose car is such a number.  The
553 difference between returning a number and returning a list is that a
554 number says that all following lines at the same nesting level should
555 be indented just like this one; a list says that following lines might
556 call for different indentations.  This makes a difference when the
557 indentation is being computed by @kbd{C-M-q}; if the value is a
558 number, @kbd{C-M-q} need not recalculate indentation for the following
559 lines until the end of the list.
560 @end table
562 @node C Indent
563 @subsection Commands for C Indentation
565   Here are the commands for indentation in C mode and related modes:
567 @table @code
568 @item C-c C-q
569 @kindex C-c C-q @r{(C mode)}
570 @findex c-indent-defun
571 Reindent the current top-level function definition or aggregate type
572 declaration (@code{c-indent-defun}).
574 @item C-M-q
575 @kindex C-M-q @r{(C mode)}
576 @findex c-indent-exp
577 Reindent each line in the balanced expression that follows point
578 (@code{c-indent-exp}).  A prefix argument inhibits error checking and
579 warning messages about invalid syntax.
581 @item @key{TAB}
582 @findex c-indent-command
583 Reindent the current line, and/or in some cases insert a tab character
584 (@code{c-indent-command}).
586 If @code{c-tab-always-indent} is @code{t}, this command always reindents
587 the current line and does nothing else.  This is the default.
589 If that variable is @code{nil}, this command reindents the current line
590 only if point is at the left margin or in the line's indentation;
591 otherwise, it inserts a tab (or the equivalent number of spaces,
592 if @code{indent-tabs-mode} is @code{nil}).
594 Any other value (not @code{nil} or @code{t}) means always reindent the
595 line, and also insert a tab if within a comment, a string, or a
596 preprocessor directive.
598 @item C-u @key{TAB}
599 Reindent the current line according to its syntax; also rigidly reindent
600 any other lines of the expression that starts on the current line.
601 @xref{Multi-line Indent}.
602 @end table
604   To reindent the whole current buffer, type @kbd{C-x h C-M-\}.  This
605 first selects the whole buffer as the region, then reindents that
606 region.
608   To reindent the current block, use @kbd{C-M-u C-M-q}.  This moves
609 to the front of the block and then reindents it all.
611 @node Custom C Indent
612 @subsection Customizing C Indentation
614   C mode and related modes use a simple yet flexible mechanism for
615 customizing indentation.  The mechanism works in two steps: first it
616 classifies the line syntactically according to its contents and context;
617 second, it associates each kind of syntactic construct with an
618 indentation offset which you can customize.
620 @menu
621 * Syntactic Analysis::
622 * Indentation Calculation::
623 * Changing Indent Style::
624 * Syntactic Symbols::
625 * Variables for C Indent::
626 * C Indent Styles::
627 @end menu
629 @node Syntactic Analysis
630 @subsubsection Step 1---Syntactic Analysis
631 @cindex syntactic analysis
633   In the first step, the C indentation mechanism looks at the line
634 before the one you are currently indenting and determines the syntactic
635 components of the construct on that line.  It builds a list of these
636 syntactic components, each of which contains a @dfn{syntactic symbol}
637 and sometimes also a buffer position.  Some syntactic symbols describe
638 grammatical elements, for example @code{statement} and
639 @code{substatement}; others describe locations amidst grammatical
640 elements, for example @code{class-open} and @code{knr-argdecl}.
642   Conceptually, a line of C code is always indented relative to the
643 indentation of some line higher up in the buffer.  This is represented
644 by the buffer positions in the syntactic component list.
646   Here is an example.  Suppose we have the following code in a C++ mode
647 buffer (the line numbers don't actually appear in the buffer):
649 @example
650 1: void swap (int& a, int& b)
651 2: @{
652 3:   int tmp = a;
653 4:   a = b;
654 5:   b = tmp;
655 6: @}
656 @end example
658   If you type @kbd{C-c C-s} (which runs the command
659 @code{c-show-syntactic-information}) on line 4, it shows the result of
660 the indentation mechanism for that line:
662 @example
663 ((statement . 32))
664 @end example
666   This indicates that the line is a statement and it is indented
667 relative to buffer position 32, which happens to be the @samp{i} in
668 @code{int} on line 3.  If you move the cursor to line 3 and type
669 @kbd{C-c C-s}, it displays this:
671 @example
672 ((defun-block-intro . 28))
673 @end example
675   This indicates that the @code{int} line is the first statement in a
676 block, and is indented relative to buffer position 28, which is the
677 brace just after the function header.
679 @noindent
680 Here is another example:
682 @example
683 1: int add (int val, int incr, int doit)
684 2: @{
685 3:   if (doit)
686 4:     @{
687 5:       return (val + incr);
688 6:     @}
689 7:   return (val);
690 8: @}
691 @end example
693 @noindent
694 Typing @kbd{C-c C-s} on line 4 displays this:
696 @example
697 ((substatement-open . 43))
698 @end example
700   This says that the brace @emph{opens} a substatement block.  By the
701 way, a @dfn{substatement} indicates the line after an @code{if},
702 @code{else}, @code{while}, @code{do}, @code{switch}, @code{for},
703 @code{try}, @code{catch}, @code{finally}, or @code{synchronized}
704 statement.
706 @cindex syntactic component
707 @cindex syntactic symbol
708 @vindex c-syntactic-context
709   Within the C indentation commands, after a line has been analyzed
710 syntactically for indentation, the variable @code{c-syntactic-context}
711 contains a list that describes the results.  Each element in this list
712 is a @dfn{syntactic component}: a cons cell containing a syntactic
713 symbol and (optionally) its corresponding buffer position.  There may be
714 several elements in a component list; typically only one element has a
715 buffer position.
717 @node Indentation Calculation
718 @subsubsection  Step 2---Indentation Calculation
719 @cindex Indentation Calculation
721   The C indentation mechanism calculates the indentation for the current
722 line using the list of syntactic components, @code{c-syntactic-context},
723 derived from syntactic analysis.  Each component is a cons cell that
724 contains a syntactic symbol and may also contain a buffer position.
726   Each component contributes to the final total indentation of the line
727 in two ways.  First, the syntactic symbol identifies an element of
728 @code{c-offsets-alist}, which is an association list mapping syntactic
729 symbols into indentation offsets.  Each syntactic symbol's offset adds
730 to the total indentation.  Second, if the component includes a buffer
731 position, the column number of that position adds to the indentation.
732 All these offsets and column numbers, added together, give the total
733 indentation.
735   The following examples demonstrate the workings of the C indentation
736 mechanism:
738 @example
739 1: void swap (int& a, int& b)
740 2: @{
741 3:   int tmp = a;
742 4:   a = b;
743 5:   b = tmp;
744 6: @}
745 @end example
747   Suppose that point is on line 3 and you type @key{TAB} to reindent the
748 line.  As explained above (@pxref{Syntactic Analysis}), the syntactic
749 component list for that line is:
751 @example
752 ((defun-block-intro . 28))
753 @end example
755   In this case, the indentation calculation first looks up
756 @code{defun-block-intro} in the @code{c-offsets-alist} alist.  Suppose
757 that it finds the integer 2; it adds this to the running total
758 (initialized to zero), yielding a updated total indentation of 2 spaces.
760   The next step is to find the column number of buffer position 28.
761 Since the brace at buffer position 28 is in column zero, this adds 0 to
762 the running total.  Since this line has only one syntactic component,
763 the total indentation for the line is 2 spaces.
765 @example
766 1: int add (int val, int incr, int doit)
767 2: @{
768 3:   if (doit)
769 4:     @{
770 5:       return(val + incr);
771 6:     @}
772 7:   return(val);
773 8: @}
774 @end example
776   If you type @key{TAB} on line 4, the same process is performed, but
777 with different data.  The syntactic component list for this line is:
779 @example
780 ((substatement-open . 43))
781 @end example
783    Here, the indentation calculation's first job is to look up the
784 symbol @code{substatement-open} in @code{c-offsets-alist}.  Let's assume
785 that the offset for this symbol is 2.  At this point the running total
786 is 2 (0 + 2 = 2).  Then it adds the column number of buffer position 43,
787 which is the @samp{i} in @code{if} on line 3.  This character is in
788 column 2 on that line.  Adding this yields a total indentation of 4
789 spaces.
791 @vindex c-strict-syntax-p
792    If a syntactic symbol in the analysis of a line does not appear in
793 @code{c-offsets-alist}, it is ignored; if in addition the variable
794 @code{c-strict-syntax-p} is non-@code{nil}, it is an error.
796 @node Changing Indent Style
797 @subsubsection Changing Indentation Style
799    There are two ways to customize the indentation style for the C-like
800 modes.  First, you can select one of several predefined styles, each of
801 which specifies offsets for all the syntactic symbols.  For more
802 flexibility, you can customize the handling of individual syntactic
803 symbols.  @xref{Syntactic Symbols}, for a list of all defined syntactic
804 symbols.
806 @table @kbd
807 @item M-x c-set-style @key{RET} @var{style} @key{RET}
808 Select predefined indentation style @var{style}.  Type @kbd{?} when
809 entering @var{style} to see a list of supported styles; to find out what
810 a style looks like, select it and reindent some C code.
812 @item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET}
813 Set the indentation offset for syntactic symbol @var{symbol}
814 (@code{c-set-offset}).  The second argument @var{offset} specifies the
815 new indentation offset.
816 @end table
818    The @code{c-offsets-alist} variable controls the amount of
819 indentation to give to each syntactic symbol.  Its value is an
820 association list, and each element of the list has the form
821 @code{(@var{syntactic-symbol} . @var{offset})}.  By changing the offsets
822 for various syntactic symbols, you can customize indentation in fine
823 detail.  To change this alist, use @code{c-set-offset} (see below).
825    Each offset value in @code{c-offsets-alist} can be an integer, a
826 function or variable name, a list, or one of the following symbols: @code{+},
827 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative
828 multiples of the variable @code{c-basic-offset}.  Thus, if you want to
829 change the levels of indentation to be 3 spaces instead of 2 spaces, set
830 @code{c-basic-offset} to 3.
832    Using a function as the offset value provides the ultimate flexibility
833 in customizing indentation.  The function is called with a single
834 argument containing the @code{cons} of the syntactic symbol and
835 the buffer position, if any.  The function should return an integer
836 offset.
838    If the offset value is a list, its elements are processed according
839 to the rules above until a non-@code{nil} value is found.  That value is
840 then added to the total indentation in the normal manner.  The primary
841 use for this is to combine the results of several functions.
843 @kindex C-c C-o @r{(C mode)}
844 @findex c-set-offset
845    The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to
846 set offsets, both interactively or in your @file{~/.emacs} file.  First
847 specify the syntactic symbol, then the offset you want.  @xref{Syntactic
848 Symbols}, for a list of valid syntactic symbols and their meanings.
850 @node Syntactic Symbols
851 @subsubsection Syntactic Symbols
853    Here is a table of valid syntactic symbols for indentation in C and
854 related modes, with their syntactic meanings.  Normally, most of these
855 symbols are assigned offsets in @code{c-offsets-alist}.
857 @table @code
858 @item string
859 Inside a multi-line string.
861 @item c
862 Inside a multi-line C style block comment.
864 @item defun-open
865 On a brace that opens a function definition.
867 @item defun-close
868 On a brace that closes a function definition.
870 @item defun-block-intro
871 In the first line in a top-level defun.
873 @item class-open
874 On a brace that opens a class definition.
876 @item class-close
877 On a brace that closes a class definition.
879 @item inline-open
880 On a brace that opens an in-class inline method.
882 @item inline-close
883 On a brace that closes an in-class inline method.
885 @item extern-lang-open
886 On a brace that opens an external language block.
888 @item extern-lang-close
889 On a brace that closes an external language block.
891 @item func-decl-cont
892 The region between a function definition's argument list and the defun
893 opening brace (excluding K&R function definitions).  In C, you cannot
894 put anything but whitespace and comments between them; in C++ and Java,
895 @code{throws} declarations and other things can appear in this context.
897 @item knr-argdecl-intro
898 On the first line of a K&R C argument declaration.
900 @item knr-argdecl
901 In one of the subsequent lines in a K&R C argument declaration.
903 @item topmost-intro
904 On the first line in a topmost construct definition.
906 @item topmost-intro-cont
907 On the topmost definition continuation lines.
909 @item member-init-intro
910 On the first line in a member initialization list.
912 @item member-init-cont
913 On one of the subsequent member initialization list lines.
915 @item inher-intro
916 On the first line of a multiple inheritance list.
918 @item inher-cont
919 On one of the subsequent multiple inheritance lines.
921 @item block-open
922 On a statement block open brace.
924 @item block-close
925 On a statement block close brace.
927 @item brace-list-open
928 On the opening brace of an @code{enum} or @code{static} array list.
930 @item brace-list-close
931 On the closing brace of an @code{enum} or @code{static} array list.
933 @item brace-list-intro
934 On the first line in an @code{enum} or @code{static} array list.
936 @item brace-list-entry
937 On one of the subsequent lines in an @code{enum} or @code{static} array
938 list.
940 @item brace-entry-open
941 On one of the subsequent lines in an @code{enum} or @code{static} array
942 list, when the line begins with an open brace.
944 @item statement
945 On an ordinary statement.
947 @item statement-cont
948 On a continuation line of a statement.
950 @item statement-block-intro
951 On the first line in a new statement block.
953 @item statement-case-intro
954 On the first line in a @code{case} ``block.''
956 @item statement-case-open
957 On the first line in a @code{case} block starting with brace.
959 @item inexpr-statement
960 On a statement block inside an expression.  This is used for a GNU
961 extension to the C language, and for Pike special functions that take a
962 statement block as an argument.
964 @item inexpr-class
965 On a class definition inside an expression.  This is used for anonymous
966 classes and anonymous array initializers in Java.
968 @item substatement
969 On the first line after an @code{if}, @code{while}, @code{for},
970 @code{do}, or @code{else}.
972 @item substatement-open
973 On the brace that opens a substatement block.
975 @item case-label
976 On a @code{case} or @code{default} label.
978 @item access-label
979 On a C++ @code{private}, @code{protected}, or @code{public} access label.
981 @item label
982 On any ordinary label.
984 @item do-while-closure
985 On the @code{while} that ends a @code{do}-@code{while} construct.
987 @item else-clause
988 On the @code{else} of an @code{if}-@code{else} construct.
990 @item catch-clause
991 On the @code{catch} and @code{finally} lines in
992 @code{try}@dots{}@code{catch} constructs in C++ and Java.
994 @item comment-intro
995 On a line containing only a comment introduction.
997 @item arglist-intro
998 On the first line in an argument list.
1000 @item arglist-cont
1001 On one of the subsequent argument list lines when no arguments follow on
1002 the same line as the arglist opening parenthesis.
1004 @item arglist-cont-nonempty
1005 On one of the subsequent argument list lines when at least one argument
1006 follows on the same line as the arglist opening parenthesis.
1008 @item arglist-close
1009 On the closing parenthesis of an argument list.
1011 @item stream-op
1012 On one of the lines continuing a stream operator construct.
1014 @item inclass
1015 On a construct that is nested inside a class definition.  The
1016 indentation is relative to the open brace of the class definition.
1018 @item inextern-lang
1019 On a construct that is nested inside an external language block.
1021 @item inexpr-statement
1022 On the first line of statement block inside an expression.  This is used
1023 for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}.
1024 It is also used for the special functions that takes a statement block
1025 as an argument in Pike.
1027 @item inexpr-class
1028 On the first line of a class definition inside an expression.  This is
1029 used for anonymous classes and anonymous array initializers in Java.
1031 @item cpp-macro
1032 On the start of a cpp macro.
1034 @item friend
1035 On a C++ @code{friend} declaration.
1037 @item objc-method-intro
1038 On the first line of an Objective-C method definition.
1040 @item objc-method-args-cont
1041 On one of the lines continuing an Objective-C method definition.
1043 @item objc-method-call-cont
1044 On one of the lines continuing an Objective-C method call.
1046 @item inlambda
1047 Like @code{inclass}, but used inside lambda (i.e. anonymous) functions.  Only
1048 used in Pike.
1050 @item lambda-intro-cont
1051 On a line continuing the header of a lambda function, between the
1052 @code{lambda} keyword and the function body.  Only used in Pike.
1053 @end table
1055 @node Variables for C Indent
1056 @subsubsection Variables for C Indentation
1058   This section describes additional variables which control the
1059 indentation behavior of C mode and related mode.
1061 @table @code
1062 @item c-offsets-alist
1063 @vindex c-offsets-alist
1064 Association list of syntactic symbols and their indentation offsets.
1065 You should not set this directly, only with @code{c-set-offset}.
1066 @xref{Changing Indent Style}, for details.
1068 @item c-style-alist
1069 @vindex c-style-alist
1070 Variable for defining indentation styles; see below.
1072 @item c-basic-offset
1073 @vindex c-basic-offset
1074 Amount of basic offset used by @code{+} and @code{-} symbols in
1075 @code{c-offsets-alist}.@refill
1077 @item c-special-indent-hook
1078 @vindex c-special-indent-hook
1079 Hook for user-defined special indentation adjustments.  This hook is
1080 called after a line is indented by C mode and related modes.
1081 @end table
1083   The variable @code{c-style-alist} specifies the predefined indentation
1084 styles.  Each element has form @code{(@var{name}
1085 @var{variable-setting}@dots{})}, where @var{name} is the name of the
1086 style.  Each @var{variable-setting} has the form @code{(@var{variable}
1087 . @var{value})}; @var{variable} is one of the customization variables
1088 used by C mode, and @var{value} is the value for that variable when
1089 using the selected style.
1091   When @var{variable} is @code{c-offsets-alist}, that is a special case:
1092 @var{value} is appended to the front of the value of @code{c-offsets-alist}
1093 instead of replacing that value outright.  Therefore, it is not necessary
1094 for @var{value} to specify each and every syntactic symbol---only those
1095 for which the style differs from the default.
1097   The indentation of lines containing only comments is also affected by
1098 the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}).
1100 @node C Indent Styles
1101 @subsubsection C Indentation Styles
1102 @cindex c indentation styles
1104   A @dfn{C style} is a collection of indentation style customizations.
1105 Emacs comes with several predefined indentation styles for C and related
1106 modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup},
1107 @code{linux}, @code{python}, @code{java}, @code{whitesmith},
1108 @code{ellemtel}, @code{cc-mode}, and @code{user}.
1110 @findex c-set-style
1111 @vindex c-default-style
1112   To choose the style you want, use the command @kbd{M-x c-set-style}.
1113 Specify a style name as an argument (case is not significant in C style
1114 names).  The chosen style only affects newly visited buffers, not those
1115 you are already editing.  You can also set the variable
1116 @code{c-default-style} to specify the style for various major modes.
1117 Its value should be an alist, in which each element specifies one major
1118 mode and which indentation style to use for it.  For example,
1120 @example
1121 (setq c-default-style
1122       '((java-mode . "java") (other . "gnu")))
1123 @end example
1125 @noindent
1126 specifies an explicit choice for Java mode, and the default @samp{gnu}
1127 style for the other C-like modes.
1129   The style @code{gnu} defines the formatting recommend by the GNU
1130 Project; it is the default, so as to encourage the indentation we
1131 recommend. If you make changes in variables such as
1132 @code{c-basic-offset} and @code{c-offsets-alist} in your @file{~/.emacs}
1133 file, they will however take precedence.
1135 @findex c-add-style
1136   To define a new C indentation style, call the function
1137 @code{c-add-style}:
1139 @example
1140 (c-add-style @var{name} @var{values} @var{use-now})
1141 @end example
1143 @noindent
1144 Here @var{name} is the name of the new style (a string), and
1145 @var{values} is an alist whose elements have the form
1146 @code{(@var{variable} . @var{value})}.  The variables you specify should
1147 be among those documented in @ref{Variables for C Indent}.
1149   If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new
1150 style after defining it.
1152 @node Matching
1153 @section Automatic Display Of Matching Parentheses
1154 @cindex matching parentheses
1155 @cindex parentheses, displaying matches
1157   The Emacs parenthesis-matching feature is designed to show
1158 automatically how parentheses match in the text.  Whenever you type a
1159 self-inserting character that is a closing delimiter, the cursor moves
1160 momentarily to the location of the matching opening delimiter, provided
1161 that is on the screen.  If it is not on the screen, some text near it is
1162 displayed in the echo area.  Either way, you can tell what grouping is
1163 being closed off.
1165   In Lisp, automatic matching applies only to parentheses.  In C, it
1166 applies to braces and brackets too.  Emacs knows which characters to regard
1167 as matching delimiters based on the syntax table, which is set by the major
1168 mode.  @xref{Syntax}.
1170   If the opening delimiter and closing delimiter are mismatched---such as
1171 in @samp{[x)}---a warning message is displayed in the echo area.  The
1172 correct matches are specified in the syntax table.
1174 @vindex blink-matching-paren
1175 @vindex blink-matching-paren-distance
1176 @vindex blink-matching-delay
1177   Three variables control parenthesis match display.
1178 @code{blink-matching-paren} turns the feature on or off; @code{nil}
1179 turns it off, but the default is @code{t} to turn match display on.
1180 @code{blink-matching-delay} says how many seconds to wait; the default
1181 is 1, but on some systems it is useful to specify a fraction of a
1182 second.  @code{blink-matching-paren-distance} specifies how many
1183 characters back to search to find the matching opening delimiter.  If
1184 the match is not found in that far, scanning stops, and nothing is
1185 displayed.  This is to prevent scanning for the matching delimiter from
1186 wasting lots of time when there is no match.  The default is 12,000.
1188 @cindex Show Paren mode
1189 @findex show-paren-mode
1190   When using X Windows, you can request a more powerful alternative kind
1191 of automatic parenthesis matching by enabling Show Paren mode.  This
1192 mode turns off the usual kind of matching parenthesis display and
1193 instead uses highlighting to show what matches.  Whenever point is after
1194 a close parenthesis, the close parenthesis and its matching open
1195 parenthesis are both highlighted; otherwise, if point is before an open
1196 parenthesis, the matching close parenthesis is highlighted.  (There is
1197 no need to highlight the open parenthesis after point because the cursor
1198 appears on top of that character.)  Use the command @kbd{M-x
1199 show-paren-mode} to enable or disable this mode.
1201 @node Comments
1202 @section Manipulating Comments
1203 @cindex comments
1205   Because comments are such an important part of programming, Emacs
1206 provides special commands for editing and inserting comments.
1208 @menu
1209 * Comment Commands::
1210 * Multi-Line Comments::
1211 * Options for Comments::
1212 @end menu
1214 @node Comment Commands
1215 @subsection Comment Commands
1217 @kindex M-;
1218 @cindex indentation for comments
1219 @findex indent-for-comment
1220 @findex comment-dwim
1222   The comment commands insert, kill and align comments.
1224 @c WideCommands
1225 @table @kbd
1226 @item M-;
1227 Call the comment command that is appropriate for the context
1228 (@code{comment-dwim}).
1229 @item M-x indent-for-comment
1230 Insert or align comment.
1231 @item C-x ;
1232 Set comment column (@code{set-comment-column}).
1233 @item C-u - C-x ;
1234 Kill comment on current line (@code{comment-kill}).
1235 @item C-M-j
1236 Like @key{RET} followed by inserting and aligning a comment
1237 (@code{indent-new-comment-line}).
1238 @item M-x comment-region
1239 Add or remove comment delimiters on all the lines in the region.
1240 @end table
1242   The command that creates a comment is @kbd{M-x indent-for-comment}.
1243 If there is no comment already on the line, a new comment is created,
1244 aligned at a specific column called the @dfn{comment column}.  The comment
1245 is created by inserting the string Emacs thinks comments should start with
1246 (the value of @code{comment-start}; see below).  Point is left after that
1247 string.  If the text of the line extends past the comment column, then the
1248 indentation is done to a suitable boundary (usually, at least one space is
1249 inserted).  If the major mode has specified a string to terminate comments,
1250 that is inserted after point, to keep the syntax valid.
1252   @kbd{M-x indent-for-comment} can also be used to align an existing
1253 comment.  If a line already contains the string that starts comments,
1254 then @kbd{M-x indent-for-comment} just moves point after it and
1255 reindents it to the conventional place.  Exception: comments starting in
1256 column 0 are not moved.
1258   @kbd{M-;} (@code{comment-dwim}) conveniently combines
1259 @code{indent-for-comment} with @code{comment-region} and
1260 @code{uncomment-region}, described below in @ref{Multi-Line Comments},
1261 as appropriate for the current context.  If the region is active and the
1262 Transient Mark mode is on (@pxref{Transient Mark}), @kbd{M-;} invokes
1263 @code{comment-region}, unless the region consists only of comments, in
1264 which case it invokes @code{uncomment-region}.  Otherwise, if the
1265 current line is empty, @kbd{M-;} inserts a comment and indents it.  If
1266 the current line is not empty, @kbd{M-;} invokes @code{comment-kill} if
1267 a numeric argument was given, else it reindents the comment on the
1268 current line.  (The @dfn{dwim} in @code{comment-dwim} is an acronym for
1269 ``Do What I Mean''.)
1271   Some major modes have special rules for indenting certain kinds of
1272 comments in certain contexts.  For example, in Lisp code, comments which
1273 start with two semicolons are indented as if they were lines of code,
1274 instead of at the comment column.  Comments which start with three
1275 semicolons are supposed to start at the left margin.  Emacs understands
1276 these conventions by indenting a double-semicolon comment using @key{TAB},
1277 and by not changing the indentation of a triple-semicolon comment at all.
1279 @example
1280 ;; This function is just an example
1281 ;;; Here either two or three semicolons are appropriate.
1282 (defun foo (x)
1283 ;;; And now, the first part of the function:
1284   ;; The following line adds one.
1285   (1+ x))           ; This line adds one.
1286 @end example
1288   In C code, a comment preceded on its line by nothing but whitespace
1289 is indented like a line of code.
1291   Even when an existing comment is properly aligned, @kbd{M-;} is still
1292 useful for moving directly to the start of the comment.
1294 @kindex C-u - C-x ;
1295 @findex kill-comment
1296 @findex comment-kill
1297   @kbd{C-u - C-x ;} (@code{comment-kill}) kills the comment on the current line,
1298 if there is one.  The indentation before the start of the comment is killed
1299 as well.  If there does not appear to be a comment in the line, nothing is
1300 done.  To reinsert the comment on another line, move to the end of that
1301 line, do @kbd{C-y}, and then do @kbd{M-;} to realign it.  Note that
1302 @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
1303 with a negative argument.  That command is programmed so that when it
1304 receives a negative argument it calls @code{comment-kill}.  However,
1305 @code{comment-kill} is a valid command which you could bind directly to a
1306 key if you wanted to.  (For compatibility with previous versions,
1307 @code{kill-comment} is provided as an alias to @code{comment-kill}.)
1309 @node Multi-Line Comments
1310 @subsection Multiple Lines of Comments
1312 @kindex C-M-j
1313 @cindex blank lines in programs
1314 @findex indent-new-comment-line
1315   If you are typing a comment and wish to continue it on another line,
1316 you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}).
1317 This terminates the comment you are typing, creates a new blank line
1318 afterward, and begins a new comment indented under the old one.  When
1319 Auto Fill mode is on, going past the fill column while typing a comment
1320 causes the comment to be continued in just this fashion.  If point is
1321 not at the end of the line when @kbd{C-M-j} is typed, the text on
1322 the rest of the line becomes part of the new comment line.
1324 @findex comment-region
1325   To turn existing lines into comment lines, use the @kbd{M-x
1326 comment-region} command.  It adds comment delimiters to the lines that start
1327 in the region, thus commenting them out.  With a negative argument, it
1328 does the opposite---it deletes comment delimiters from the lines in the
1329 region.
1331   With a positive argument, @code{comment-region} duplicates the last
1332 character of the comment start sequence it adds; the argument specifies
1333 how many copies of the character to insert.  Thus, in Lisp mode,
1334 @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.  Duplicating
1335 the comment delimiter is a way of calling attention to the comment.  It
1336 can also affect how the comment is indented.  In Lisp, for proper
1337 indentation, you should use an argument of two, if between defuns, and
1338 three, if within a defun.
1340 @vindex comment-padding
1341   The variable @code{comment-padding} specifies how many spaces
1342 @code{comment-region} should insert on each line between the
1343 comment delimiter and the line's original text.  The default is 1.
1345 @node Options for Comments
1346 @subsection Options Controlling Comments
1348 @vindex comment-column
1349 @kindex C-x ;
1350 @findex set-comment-column
1351   The comment column is stored in the variable @code{comment-column}.  You
1352 can set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
1353 (@code{set-comment-column}) sets the comment column to the column point is
1354 at.  @kbd{C-u C-x ;} sets the comment column to match the last comment
1355 before point in the buffer, and then does a @kbd{M-;} to align the
1356 current line's comment under the previous one.  Note that @kbd{C-u - C-x ;}
1357 runs the function @code{comment-kill} as described above.
1359   The variable @code{comment-column} is per-buffer: setting the variable
1360 in the normal fashion affects only the current buffer, but there is a
1361 default value which you can change with @code{setq-default}.
1362 @xref{Locals}.  Many major modes initialize this variable for the
1363 current buffer.
1365 @vindex comment-start-skip
1366   The comment commands recognize comments based on the regular
1367 expression that is the value of the variable @code{comment-start-skip}.
1368 Make sure this regexp does not match the null string.  It may match more
1369 than the comment starting delimiter in the strictest sense of the word;
1370 for example, in C mode the value of the variable is @code{@t{"/\\*+
1371 *"}}, which matches extra stars and spaces after the @samp{/*} itself.
1372 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
1373 the string, which is needed to deny the first star its special meaning
1374 in regexp syntax.  @xref{Regexps}.)
1376 @vindex comment-start
1377 @vindex comment-end
1378   When a comment command makes a new comment, it inserts the value of
1379 @code{comment-start} to begin it.  The value of @code{comment-end} is
1380 inserted after point, so that it will follow the text that you will insert
1381 into the comment.  In C mode, @code{comment-start} has the value
1382 @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
1384 @vindex comment-multi-line
1385   The variable @code{comment-multi-line} controls how @kbd{C-M-j}
1386 (@code{indent-new-comment-line}) behaves when used inside a comment.  If
1387 @code{comment-multi-line} is @code{nil}, as it normally is, then the
1388 comment on the starting line is terminated and a new comment is started
1389 on the new following line.  If @code{comment-multi-line} is not
1390 @code{nil}, then the new following line is set up as part of the same
1391 comment that was found on the starting line.  This is done by not
1392 inserting a terminator on the old line, and not inserting a starter on
1393 the new line.  In languages where multi-line comments work, the choice
1394 of value for this variable is a matter of taste.
1396 @vindex comment-indent-function
1397   The variable @code{comment-indent-function} should contain a function
1398 that will be called to compute the indentation for a newly inserted
1399 comment or for aligning an existing comment.  It is set differently by
1400 various major modes.  The function is called with no arguments, but with
1401 point at the beginning of the comment, or at the end of a line if a new
1402 comment is to be inserted.  It should return the column in which the
1403 comment ought to start.  For example, in Lisp mode, the indent hook
1404 function bases its decision on how many semicolons begin an existing
1405 comment, and on the code in the preceding lines.
1407 @node Balanced Editing
1408 @section Editing Without Unbalanced Parentheses
1410 @table @kbd
1411 @item M-(
1412 Put parentheses around next sexp(s) (@code{insert-parentheses}).
1413 @item M-)
1414 Move past next close parenthesis and reindent
1415 (@code{move-past-close-and-reindent}).
1416 @end table
1418 @kindex M-(
1419 @kindex M-)
1420 @findex insert-parentheses
1421 @findex move-past-close-and-reindent
1422   The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
1423 (@code{move-past-close-and-reindent}) are designed to facilitate a style
1424 of editing which keeps parentheses balanced at all times.  @kbd{M-(}
1425 inserts a pair of parentheses, either together as in @samp{()}, or, if
1426 given an argument, around the next several sexps.  It leaves point after
1427 the open parenthesis.  The command @kbd{M-)} moves past the close
1428 parenthesis, deleting any indentation preceding it, and indenting with
1429 @kbd{C-j} after it.
1431   For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
1432 F O O}, which has the same effect except for leaving the cursor before
1433 the close parenthesis.
1435 @vindex parens-require-spaces
1436   @kbd{M-(} may insert a space before the open parenthesis, depending on
1437 the syntax class of the preceding character.  Set
1438 @code{parens-require-spaces} to @code{nil} value if you wish to inhibit
1439 this.
1441 @findex check-parens
1442 @cindex unbalanced parentheses and quotes
1443 You can use @kbd{M-x check-parens} to find any unbalanced parentheses
1444 and unbalanced quotes in strings in a buffer.
1446 @node Symbol Completion
1447 @section Completion for Symbol Names
1448 @cindex completion (symbol names)
1450   Usually completion happens in the minibuffer.  But one kind of completion
1451 is available in all buffers: completion for symbol names.
1453 @kindex M-TAB
1454   The character @kbd{M-@key{TAB}} runs a command to complete the partial
1455 symbol before point against the set of meaningful symbol names.  Any
1456 additional characters determined by the partial name are inserted at
1457 point.
1459   If the partial name in the buffer has more than one possible completion
1460 and they have no additional characters in common, a list of all possible
1461 completions is displayed in another window.
1463 @cindex completion using tags
1464 @cindex tags completion
1465 @cindex Info index completion
1466 @findex complete-symbol
1467   In most programming language major modes, @kbd{M-@key{TAB}} runs the
1468 command @code{complete-symbol}, which provides two kinds of completion.
1469 Normally it does completion based on a tags table (@pxref{Tags}); with a
1470 numeric argument (regardless of the value), it does completion based on
1471 the names listed in the Info file indexes for your language.  Thus, to
1472 complete the name of a symbol defined in your own program, use
1473 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard
1474 library function, use @kbd{C-u M-@key{TAB}}.  Of course, Info-based
1475 completion works only if there is an Info file for the standard library
1476 functions of your language, and only if it is installed at your site.
1478 @cindex Lisp symbol completion
1479 @cindex completion in Lisp
1480 @findex lisp-complete-symbol
1481   In Emacs-Lisp mode, the name space for completion normally consists of
1482 nontrivial symbols present in Emacs---those that have function
1483 definitions, values or properties.  However, if there is an
1484 open-parenthesis immediately before the beginning of the partial symbol,
1485 only symbols with function definitions are considered as completions.
1486 The command which implements this is @code{lisp-complete-symbol}.
1488   In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1489 based on the spell-checker's dictionary.  @xref{Spelling}.
1491 @node Which Function
1492 @section Which Function Mode
1494   Which Function mode is a minor mode that displays the current function
1495 name in the mode line, as you move around in a buffer.
1497 @findex which-function-mode
1498 @vindex which-func-modes
1499   To enable (or disable) Which Function mode, use the command @kbd{M-x
1500 which-function-mode}.  This command is global; it applies to all
1501 buffers, both existing ones and those yet to be created.  However, this
1502 only affects certain major modes, those listed in the value of
1503 @code{which-func-modes}.  (If the value is @code{t}, then Which Function
1504 mode applies to all major modes that know how to support it---which are
1505 the major modes that support Imenu.)
1507 @node Hideshow
1508 @section Hideshow minor mode
1510 @findex hs-minor-mode
1511 Hideshow minor mode provides selective display of blocks.  Use @kbd{M-x
1512 hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the
1513 hook for major modes with which you want to use it and which support it.
1515 Blocks are defined dependent on the mode.  In C mode or C++ mode, they
1516 are delimited by braces, while in Lisp-ish modes they are delimited by
1517 parens.  Multi-line comments can also be hidden.
1519 @findex hs-hide-all
1520 @findex hs-hide-block
1521 @findex hs-show-all
1522 @findex hs-show-block
1523 @findex hs-show-region
1524 @findex hs-hide-level
1525 @findex hs-minor-mode
1526 @kindex C-c h
1527 @kindex C-c s
1528 @kindex C-c H
1529 @kindex C-c S
1530 @kindex C-c R
1531 @kindex C-c L
1532 @kindex S-mouse-2
1533 The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}),
1534 @kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x
1535 hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R}
1536 (@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level})
1537 with obvious functions and @kbd{S-mouse-2} toggles hiding of a block
1538 with the mouse.
1540 @vindex hs-hide-comments-when-hiding-all
1541 @vindex hs-show-hidden-short-form
1542 @vindex hs-isearch-open
1543 @vindex hs-special-modes-alist
1544 Hideshow is customized by the variables
1545 @table @code
1546 @item hs-hide-comments-when-hiding-all
1547 Specifies whether @kbd{hs-hide-all} should hide comments too.
1548 @item hs-show-hidden-short-form
1549 Specifies whether or not the last line in a form is omitted (saving
1550 screen space).
1551 @item hs-isearch-open
1552 Specifies what kind of hidden blocks to open in Isearch mode.
1553 @item hs-special-modes-alist
1554 Initializes Hideshow variables for different modes.
1555 @end table
1557 @node Glasses
1558 @section Glasses minor mode
1559 @cindex Glasses mode
1560 @cindex identifiers, unreadable
1561 @cindex StudlyCaps
1562 @findex glasses-mode
1564 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} readable
1565 by displaying underscores between all the pairs of lower and upper
1566 English letters or by emboldening the capitals.  The text is not
1567 altered, only the display, so that you can use this mode on code written
1568 with such a convention for separating words in identifiers without
1569 modifying the code.  It can be customized under the group
1570 @samp{glasses}.  You can use it by adding @code{glasses-mode} to the
1571 mode hook of appropriate programming modes.
1574 @node Documentation
1575 @section Documentation Commands
1577   As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
1578 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
1579 be used to print documentation of functions and variables that you want to
1580 call.  These commands use the minibuffer to read the name of a function or
1581 variable to document, and display the documentation in a window.
1583   For extra convenience, these commands provide default arguments based on
1584 the code in the neighborhood of point.  @kbd{C-h f} sets the default to the
1585 function called in the innermost list containing point.  @kbd{C-h v} uses
1586 the symbol name around or adjacent to point as its default.
1588 @cindex Eldoc mode
1589 @findex eldoc-mode
1590   For Emacs Lisp code, you can also use Eldoc mode.  This minor mode
1591 constantly displays in the echo area the argument list for the function
1592 being called at point.  (In other words, it finds the function call that
1593 point is contained in, and displays the argument list of that function.)
1594 Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only.  Use
1595 the command @kbd{M-x eldoc-mode} to enable or disable this feature.
1597 @findex info-lookup-symbol
1598 @findex info-lookup-file
1599 @kindex C-h C-i
1600   For C, Lisp, and other languages, you can use @kbd{C-h C-i}
1601 (@code{info-lookup-symbol}) to view the Info documentation for a symbol.
1602 You specify the symbol with the minibuffer; by default, it uses the
1603 symbol that appears in the buffer at point.  The major mode determines
1604 where to look for documentation for the symbol---which Info files and
1605 which indices.  You can also use @kbd{M-x info-lookup-file} to look for
1606 documentation for a file name.  Currently the modes supported by
1607 Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
1608 Makefile, Octave, Perl, Scheme and Texinfo.  The relevant Info files
1609 mostly must be obtained separately, typically from the appropriate GNU
1610 package.
1612 @findex manual-entry
1613 @cindex manual pages
1614   You can read the ``man page'' for an operating system command, library
1615 function, or system call, with the @kbd{M-x manual-entry} command.  It
1616 runs the @code{man} program to format the man page, and runs it
1617 asynchronously if your system permits, so that you can keep on editing
1618 while the page is being formatted.  (MS-DOS and MS-Windows 3 do not
1619 permit asynchronous subprocesses, so on these systems you cannot edit
1620 while Emacs waits for @code{man} to exit.)  The result goes in a buffer
1621 named @samp{*Man @var{topic}*}.  These buffers use a special major mode,
1622 Man mode, that facilitates scrolling and examining other manual pages.
1623 For details, type @kbd{C-h m} while in a man page buffer.
1625 @cindex sections of manual pages
1626   Man pages are subdivided into @dfn{sections}, and some man pages have
1627 identical names, but belong to different sections.  To read a man page
1628 from a certain section, type @kbd{@var{topic}(@var{section})} or
1629 @kbd{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts for
1630 the topic.  For example, to read the man page for the C library function
1631 @code{chmod} (as opposed to a command by the same name), type @kbd{M-x
1632 manual-entry @key{RET} chmod(2v) @key{RET}} (assuming @code{chmod} is in
1633 section @code{2v}).
1635   If you do not specify a section, the results depend on how the
1636 @code{man} command works on your system.  Some of them display only the
1637 first man page they find, others display all the man pages, and you can
1638 page between them with the @kbd{M-n} and @kbd{M-p} keys.  The mode line
1639 shows how many manual pages are available in the Man buffer.
1641 @vindex Man-fontify-manpage-flag
1642   For a long man page, setting the faces properly can take substantial
1643 time.  By default, Emacs uses faces in man pages if Emacs can display
1644 different fonts or colors.  You can turn off use of faces in man pages
1645 by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
1647 @findex Man-fontify-manpage
1648   If you insert the text of a man page into an Emacs buffer in some
1649 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
1650 perform the same conversions that @kbd{M-x manual-entry} does.
1652 @findex woman
1653 @cindex manual pages, on MS-DOS/MS-Windows
1654   An alternative way of reading manual pages is the @kbd{M-x woman}
1655 command@footnote{The name of the command, @code{woman}, is an acronym
1656 for ``w/o (without) man'', since it doesn't use the @code{man}
1657 program.}.  Unlike @kbd{M-x man}, it does not run any external programs
1658 to format and display the man pages, instead it does that entirely in
1659 Emacs Lisp.  Thus, it is useful on systems such as MS-Windows, where the
1660 @code{man} program and the programs it runs are not readily available.
1661 When invoked, @kbd{M-x woman} prompts for a name of a manual page and
1662 provides completion based on the list of manual pages that are installed
1663 on your machine; the list of available manual pages is computed
1664 automatically the first time you invoke @code{woman}.  The word at point
1665 in the current buffer is used to suggest the default name of the manual
1666 page.
1668   With a numeric argument, @kbd{M-x woman} recomputes the list of the
1669 manual pages used for completion.  This is useful if you add or delete
1670 manual pages.
1672   If you type a name of a manual page and @kbd{M-x woman} finds that
1673 several manual pages by the same name exist in different sections, it
1674 pops up a window with possible candidates asking you to choose one of
1675 them.
1677 @vindex woman-manpath
1678   By default, @kbd{M-x woman} looks up the manual pages in directories
1679 listed by the @code{MANPATH} environment variable.  (If @code{MANPATH}
1680 is not set, @code{woman} uses a suitable default value, which can be
1681 customized.)  More precisely, @code{woman} looks for subdirectories that
1682 match the shell wildcard @file{man*} in each one of these directories,
1683 and tries to find the manual pages in those subdirectories.  When first
1684 invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list
1685 of directory names and stores that list in the @code{woman-manpath}
1686 variable.  By changing the value of this variable, you can customize the
1687 list of directories where @code{woman} looks for manual pages.
1689 @vindex woman-path
1690   In addition, you can augment the list of directories searched by
1691 @code{woman} by setting the value of the @code{woman-path} variable.
1692 This variable should hold a list of specific directories which
1693 @code{woman} should search, in addition to those in
1694 @code{woman-manpath}.  Unlike @code{woman-manpath}, the directories in
1695 @code{woman-path} are searched for the manual pages, not for @file{man*}
1696 subdirectories.
1698 @findex woman-find-file
1699   Occasionally, you might need to display manual pages that are not in
1700 any of the directories listed by @code{woman-manpath} and
1701 @code{woman-path}.  The @kbd{M-x woman-find-file} command prompts for a
1702 name of a manual page file, with completion, and then formats and
1703 displays that file like @kbd{M-x woman} does.
1705 @vindex woman-dired-keys
1706   First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W}
1707 key to run the @code{woman-find-file} command on the current line's
1708 file.  You can disable this by setting the variable
1709 @code{woman-dired-keys} to @code{nil}.  @xref{Dired}.  In addition, the
1710 Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current
1711 line's archive member.
1713   For more information about setting up and using @kbd{M-x woman}, see
1714 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
1715 Manual}.
1717   Eventually the GNU project hopes to replace most man pages with
1718 better-organized manuals that you can browse with Info.  @xref{Misc
1719 Help}.  Since this process is only partially completed, it is still
1720 useful to read manual pages.
1722 @node Change Log
1723 @section Change Logs
1725 @cindex change log
1726 @kindex C-x 4 a
1727 @findex add-change-log-entry-other-window
1728   The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1729 file for the file you are editing
1730 (@code{add-change-log-entry-other-window}).  If that file is actually a
1731 backup file, it makes an entry appropriate for the file's parent.  This
1732 is useful for making log entries by comparing a version with deleted
1733 functions.
1735   A change log file contains a chronological record of when and why you
1736 have changed a program, consisting of a sequence of entries describing
1737 individual changes.  Normally it is kept in a file called
1738 @file{ChangeLog} in the same directory as the file you are editing, or
1739 one of its parent directories.  A single @file{ChangeLog} file can
1740 record changes for all the files in its directory and all its
1741 subdirectories.
1743   A change log entry starts with a header line that contains your name,
1744 your email address (taken from the variable @code{user-mail-address}),
1745 and the current date and time.  Aside from these header lines, every
1746 line in the change log starts with a space or a tab.  The bulk of the
1747 entry consists of @dfn{items}, each of which starts with a line starting
1748 with whitespace and a star.  Here are two entries, both dated in May
1749 1993, each with two items:
1751 @iftex
1752 @medbreak
1753 @end iftex
1754 @smallexample
1755 1993-05-25  Richard Stallman  <rms@@gnu.org>
1757         * man.el: Rename symbols `man-*' to `Man-*'.
1758         (manual-entry): Make prompt string clearer.
1760         * simple.el (blink-matching-paren-distance):
1761         Change default to 12,000.
1763 1993-05-24  Richard Stallman  <rms@@gnu.org>
1765         * vc.el (minor-mode-map-alist): Don't use it if it's void.
1766         (vc-cancel-version): Doc fix.
1767 @end smallexample
1769   One entry can describe several changes; each change should have its
1770 own item.  Normally there should be a blank line between items.  When
1771 items are related (parts of the same change, in different places), group
1772 them by leaving no blank line between them.  The second entry above
1773 contains two items grouped in this way.
1775 @vindex add-log-keep-changes-together
1776   @kbd{C-x 4 a} visits the change log file and creates a new entry
1777 unless the most recent entry is for today's date and your name.  It also
1778 creates a new item for the current file.  For many languages, it can
1779 even guess the name of the function or other object that was changed.
1780 When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4
1781 a} adds to any existing entry for the file rather than starting a new
1782 entry.
1784 @vindex change-log-version-info-enabled
1785 @vindex change-log-version-number-regexp-list
1786 @cindex file version in change log entries
1787   If the value of the variable @code{change-log-version-info-enabled} is
1788 non-nil, the file's version number is automatically added to change log
1789 entries.  The search for the file's version number is performed based on
1790 regular expressions from the variable
1791 @code{change-log-version-number-regexp-list}, which can be customized
1792 (versions of files that are under version control systems are known to
1793 Emacs through the version-control interface).
1795 @cindex Change Log mode
1796 @findex change-log-mode
1797   The change log file is visited in Change Log mode.  In this major
1798 mode, each bunch of grouped items counts as one paragraph, and each
1799 entry is considered a page.  This facilitates editing the entries.
1800 @kbd{C-j} and auto-fill indent each new line like the previous line;
1801 this is convenient for entering the contents of an entry.
1803 @findex change-log-merge
1804 The command @kbd{M-x change-log-merge} can be used to merge other log
1805 files into a buffer in Change Log Mode, preserving the date ordering
1806 of entries with either the current or old-style date formats.
1808 @findex change-log-redate
1809 @cindex converting change log date style
1810   Versions of Emacs before 20.1 used a different format for the time of
1811 the change log entry:
1813 @smallexample
1814 Fri May 25 11:23:23 1993 Richard Stallman  <rms@@gnu.org>
1815 @end smallexample
1817 @noindent
1818 The @kbd{M-x change-log-redate} command converts all the old-style date
1819 entries in the change log file visited in the current buffer to the new
1820 format, so that all entries are kept in unified format.  This is handy
1821 when the entries are contributed by many different people some of whom
1822 still use old versions of Emacs.
1824   Version control systems are another way to keep track of changes in your
1825 program and keep a change log.  @xref{Log Buffer}.
1827 @node Authors
1828 @section @file{AUTHORS} files
1829 @cindex @file{AUTHORS} file
1831   Programs which have many contributors usually include a file named
1832 @file{AUTHORS} in their distribution, which lists the individual
1833 contributions.  Emacs has a special command for maintaining the
1834 @file{AUTHORS} file that is part of the Emacs distribution.
1836 @findex authors
1837   The @kbd{M-x authors} command prompts for the name of the root of the
1838 Emacs source directory.  It then scans @file{ChageLog} files and Lisp
1839 source files under that directory for information about authors of
1840 individual packages and people who made changes in source files, and
1841 puts the information it gleans into a buffer named @samp{*Authors*}.
1842 You can then edit the contents of that buffer and merge it with the
1843 exisiting @file{AUTHORS} file.
1845 @node Tags
1846 @section Tags Tables
1847 @cindex tags table
1849   A @dfn{tags table} is a description of how a multi-file program is
1850 broken up into files.  It lists the names of the component files and the
1851 names and positions of the functions (or other named subunits) in each
1852 file.  Grouping the related files makes it possible to search or replace
1853 through all the files with one command.  Recording the function names
1854 and positions makes possible the @kbd{M-.} command which finds the
1855 definition of a function by looking up which of the files it is in.
1857   Tags tables are stored in files called @dfn{tags table files}.  The
1858 conventional name for a tags table file is @file{TAGS}.
1860   Each entry in the tags table records the name of one tag, the name of the
1861 file that the tag is defined in (implicitly), and the position in that file
1862 of the tag's definition.
1864   Just what names from the described files are recorded in the tags table
1865 depends on the programming language of the described file.  They
1866 normally include all functions and subroutines, and may also include
1867 global variables, data types, and anything else convenient.  Each name
1868 recorded is called a @dfn{tag}.
1870 @cindex C++ class browser, tags
1871 @cindex tags, C++
1872 @cindex class browser, C++
1873 @cindex Ebrowse
1874 The Ebrowse is a separate facility tailored for C++, with tags and a
1875 class browser.  @xref{,,, ebrowse, Ebrowse User's Manual}.
1877 @menu
1878 * Tag Syntax::          Tag syntax for various types of code and text files.
1879 * Create Tags Table::   Creating a tags table with @code{etags}.
1880 * Etags Regexps::       Create arbitrary tags using regular expressions.
1881 * Select Tags Table::   How to visit a tags table.
1882 * Find Tag::            Commands to find the definition of a specific tag.
1883 * Tags Search::         Using a tags table for searching and replacing.
1884 * List Tags::           Listing and finding tags defined in a file.
1885 @end menu
1887 @node Tag Syntax
1888 @subsection Source File Tag Syntax
1890   Here is how tag syntax is defined for the most popular languages:
1892 @itemize @bullet
1893 @item
1894 In C code, any C function or typedef is a tag, and so are definitions of
1895 @code{struct}, @code{union} and @code{enum}.  You can tag function
1896 declarations and external variables in addition to function definitions
1897 by giving the @samp{--declarations} option to @code{etags}.
1898 @code{#define} macro definitions and @code{enum} constants are also
1899 tags, unless you specify @samp{--no-defines} when making the tags table.
1900 Similarly, global variables are tags, unless you specify
1901 @samp{--no-globals}.  Use of @samp{--no-globals} and @samp{--no-defines}
1902 can make the tags table file much smaller.
1904 @item
1905 In C++ code, in addition to all the tag constructs of C code, member
1906 functions are also recognized, and optionally member variables if you
1907 use the @samp{--members} option.  Tags for variables and functions in
1908 classes are named @samp{@var{class}::@var{variable}} and
1909 @samp{@var{class}::@var{function}}.  @code{operator} functions tags are
1910 named, for example @samp{operator+}.
1912 @item
1913 In Java code, tags include all the constructs recognized in C++, plus
1914 the @code{interface}, @code{extends} and @code{implements} constructs.
1915 Tags for variables and functions in classes are named
1916 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1918 @item
1919 In La@TeX{} text, the argument of any of the commands @code{\chapter},
1920 @code{\section}, @code{\subsection}, @code{\subsubsection},
1921 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
1922 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
1923 tag.@refill
1925 Other commands can make tags as well, if you specify them in the
1926 environment variable @env{TEXTAGS} before invoking @code{etags}.  The
1927 value of this environment variable should be a colon-separated list of
1928 command names.  For example,
1930 @example
1931 TEXTAGS="def:newcommand:newenvironment"
1932 export TEXTAGS
1933 @end example
1935 @noindent
1936 specifies (using Bourne shell syntax) that the commands @samp{\def},
1937 @samp{\newcommand} and @samp{\newenvironment} also define tags.
1939 @item
1940 In Lisp code, any function defined with @code{defun}, any variable
1941 defined with @code{defvar} or @code{defconst}, and in general the first
1942 argument of any expression that starts with @samp{(def} in column zero, is
1943 a tag.
1945 @item
1946 In Scheme code, tags include anything defined with @code{def} or with a
1947 construct whose name starts with @samp{def}.  They also include variables
1948 set with @code{set!} at top level in the file.
1949 @end itemize
1951   Several other languages are also supported:
1953 @itemize @bullet
1955 @item
1956 In Ada code, functions, procedures, packages, tasks, and types are
1957 tags.  Use the @samp{--packages-only} option to create tags for packages
1958 only.
1960 @item
1961 In assembler code, labels appearing at the beginning of a line,
1962 followed by a colon, are tags.
1964 @item
1965 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1966 it constructs.  The portions of the file that contain C code are parsed
1967 as C code.
1969 @item
1970 In Cobol code, tags are paragraph names; that is, any word starting in
1971 column 8 and followed by a period.
1973 @item
1974 In Erlang code, the tags are the functions, records, and macros defined
1975 in the file.
1977 @item
1978 In Fortran code, functions, subroutines and blockdata are tags.
1980 @item
1981 In Objective C code, tags include Objective C definitions for classes,
1982 class categories, methods, and protocols.
1984 @item
1985 In Pascal code, the tags are the functions and procedures defined in
1986 the file.
1988 @item
1989 In Perl code, the tags are the procedures defined by the @code{sub},
1990 @code{my} and @code{local} keywords.  Use @samp{--globals} if you want
1991 to tag global variables.
1993 @item
1994 In PostScript code, the tags are the functions.
1996 @item
1997 In Prolog code, a tag name appears at the left margin.
1999 @item
2000 In Python code, @code{def} or @code{class} at the beginning of a line
2001 generate a tag.
2002 @end itemize
2004   You can also generate tags based on regexp matching (@pxref{Etags
2005 Regexps}) to handle other formats and languages.
2007 @node Create Tags Table
2008 @subsection Creating Tags Tables
2009 @cindex @code{etags} program
2011   The @code{etags} program is used to create a tags table file.  It knows
2012 the syntax of several languages, as described in
2013 @iftex
2014 the previous section.
2015 @end iftex
2016 @ifinfo
2017 @ref{Tag Syntax}.
2018 @end ifinfo
2019 Here is how to run @code{etags}:
2021 @example
2022 etags @var{inputfiles}@dots{}
2023 @end example
2025 @noindent
2026 The @code{etags} program reads the specified files, and writes a tags
2027 table named @file{TAGS} in the current working directory.  You can
2028 intermix compressed and plain text source file names.  @code{etags}
2029 knows about the most common compression formats, and does the right
2030 thing.  So you can compress all your source files and have @code{etags}
2031 look for compressed versions of its file name arguments, if it does not
2032 find uncompressed versions.  Under MS-DOS, @code{etags} also looks for
2033 file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
2034 command line and @samp{mycode.c} does not exist.
2036   @code{etags} recognizes the language used in an input file based on
2037 its file name and contents.  You can specify the language with the
2038 @samp{--language=@var{name}} option, described below.
2040   If the tags table data become outdated due to changes in the files
2041 described in the table, the way to update the tags table is the same way it
2042 was made in the first place.  It is not necessary to do this often.
2044   If the tags table fails to record a tag, or records it for the wrong
2045 file, then Emacs cannot possibly find its definition.  However, if the
2046 position recorded in the tags table becomes a little bit wrong (due to
2047 some editing in the file that the tag definition is in), the only
2048 consequence is a slight delay in finding the tag.  Even if the stored
2049 position is very wrong, Emacs will still find the tag, but it must
2050 search the entire file for it.
2052   So you should update a tags table when you define new tags that you want
2053 to have listed, or when you move tag definitions from one file to another,
2054 or when changes become substantial.  Normally there is no need to update
2055 the tags table after each edit, or even every day.
2057   One tags table can effectively include another.  Specify the included
2058 tags file name with the @samp{--include=@var{file}} option when creating
2059 the file that is to include it.  The latter file then acts as if it
2060 contained all the files specified in the included file, as well as the
2061 files it directly contains.
2063   If you specify the source files with relative file names when you run
2064 @code{etags}, the tags file will contain file names relative to the
2065 directory where the tags file was initially written.  This way, you can
2066 move an entire directory tree containing both the tags file and the
2067 source files, and the tags file will still refer correctly to the source
2068 files.
2070   If you specify absolute file names as arguments to @code{etags}, then
2071 the tags file will contain absolute file names.  This way, the tags file
2072 will still refer to the same files even if you move it, as long as the
2073 source files remain in the same place.  Absolute file names start with
2074 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
2076   When you want to make a tags table from a great number of files, you
2077 may have problems listing them on the command line, because some systems
2078 have a limit on its length.  The simplest way to circumvent this limit
2079 is to tell @code{etags} to read the file names from its standard input,
2080 by typing a dash in place of the file names, like this:
2082 @smallexample
2083 find . -name "*.[chCH]" -print | etags -
2084 @end smallexample
2086   Use the option @samp{--language=@var{name}} to specify the language
2087 explicitly.  You can intermix these options with file names; each one
2088 applies to the file names that follow it.  Specify
2089 @samp{--language=auto} to tell @code{etags} to resume guessing the
2090 language from the file names and file contents.  Specify
2091 @samp{--language=none} to turn off language-specific processing
2092 entirely; then @code{etags} recognizes tags by regexp matching alone
2093 (@pxref{Etags Regexps}).
2095   @samp{etags --help} prints the list of the languages @code{etags}
2096 knows, and the file name rules for guessing the language. It also prints
2097 a list of all the available @code{etags} options, together with a short
2098 explanation.
2100 @node Etags Regexps
2101 @subsection Etags Regexps
2103   The @samp{--regex} option provides a general way of recognizing tags
2104 based on regexp matching.  You can freely intermix it with file names.
2105 Each @samp{--regex} option adds to the preceding ones, and applies only
2106 to the following files.  The syntax is:
2108 @smallexample
2109 --regex=/@var{tagregexp}[/@var{nameregexp}]/
2110 @end smallexample
2112 @noindent
2113 where @var{tagregexp} is used to match the lines to tag.  It is always
2114 anchored, that is, it behaves as if preceded by @samp{^}.  If you want
2115 to account for indentation, just match any initial number of blanks by
2116 beginning your regular expression with @samp{[ \t]*}.  In the regular
2117 expressions, @samp{\} quotes the next character, and @samp{\t} stands
2118 for the tab character.  Note that @code{etags} does not handle the other
2119 C escape sequences for special characters.
2121 @cindex interval operator (in regexps)
2122   The syntax of regular expressions in @code{etags} is the same as in
2123 Emacs, augmented with the @dfn{interval operator}, which works as in
2124 @code{grep} and @code{ed}.  The syntax of an interval operator is
2125 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
2126 expression at least @var{m} times and up to @var{n} times.
2128   You should not match more characters with @var{tagregexp} than that
2129 needed to recognize what you want to tag.  If the match is such that
2130 more characters than needed are unavoidably matched by @var{tagregexp}
2131 (as will usually be the case), you should add a @var{nameregexp}, to
2132 pick out just the tag.  This will enable Emacs to find tags more
2133 accurately and to do completion on tag names more reliably.  You can
2134 find some examples below.
2136   The option @samp{--ignore-case-regex} (or @samp{-c}) is like
2137 @samp{--regex}, except that the regular expression provided will be
2138 matched without regard to case, which is appropriate for various
2139 programming languages.
2141   The @samp{-R} option deletes all the regexps defined with
2142 @samp{--regex} options.  It applies to the file names following it, as
2143 you can see from the following example:
2145 @smallexample
2146 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
2147     bar.ber -R --lang=lisp los.er
2148 @end smallexample
2150 @noindent
2151 Here @code{etags} chooses the parsing language for @file{voo.doo} and
2152 @file{bar.ber} according to their contents.  @code{etags} also uses
2153 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
2154 @var{reg1} and @var{reg2} to recognize additional tags in
2155 @file{bar.ber}.  @code{etags} uses the Lisp tags rules, and no regexp
2156 matching, to recognize tags in @file{los.er}.
2158   A regular expression can be bound to a given language, by prepending
2159 it with @samp{@{lang@}}.  When you do this, @code{etags} will use the
2160 regular expression only for files of that language.  @samp{etags --help}
2161 prints the list of languages recognised by @code{etags}.  The following
2162 example tags the @code{DEFVAR} macros in the Emacs source files.
2163 @code{etags} applies this regular expression to C files only:
2165 @smallexample
2166 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
2167 @end smallexample
2169 @noindent
2170 This feature is particularly useful when storing a list of regular
2171 expressions in a file.  The following option syntax instructs
2172 @code{etags} to read two files of regular expressions.  The regular
2173 expressions contained in the second file are matched without regard to
2174 case.
2176 @smallexample
2177 --regex=@@first-file --ignore-case-regex=@@second-file
2178 @end smallexample
2180 @noindent
2181 A regex file contains one regular expressions per line.  Empty lines,
2182 and lines beginning with space or tab are ignored.  When the first
2183 character in a line is @samp{@@}, @code{etags} assumes that the rest of
2184 the line is the name of a file of regular expressions.  This means that
2185 such files can be nested.  All the other lines are taken to be regular
2186 expressions.  For example, one can create a file called
2187 @samp{emacs.tags} with the following contents (the first line in the
2188 file is a comment):
2190 @smallexample
2191         -- This is for GNU Emacs source files
2192 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2193 @end smallexample
2195 @noindent
2196 and then use it like this:
2198 @smallexample
2199 etags --regex=@@emacs.tags *.[ch] */*.[ch]
2200 @end smallexample
2202   Here are some more examples.  The regexps are quoted to protect them
2203 from shell interpretation.
2205 @itemize @bullet
2207 @item
2208 Tag Octave files:
2210 @smallexample
2211 etags --language=none \
2212       --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2213       --regex='/###key \(.*\)/\1/' \
2214       --regex='/[ \t]*global[ \t].*/' \
2215       *.m
2216 @end smallexample
2218 @noindent
2219 Note that tags are not generated for scripts so that you have to add a
2220 line by yourself of the form `###key <script-name>' if you want to jump
2221 to it.
2223 @item
2224 Tag Tcl files:
2226 @smallexample
2227 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2228 @end smallexample
2230 @item
2231 Tag VHDL files:
2233 @smallexample
2234 --language=none \
2235 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2236 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2237 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2238 @end smallexample
2239 @end itemize
2241 @node Select Tags Table
2242 @subsection Selecting a Tags Table
2244 @vindex tags-file-name
2245 @findex visit-tags-table
2246   Emacs has at any time one @dfn{selected} tags table, and all the commands
2247 for working with tags tables use the selected one.  To select a tags table,
2248 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
2249 argument.  The name @file{TAGS} in the default directory is used as the
2250 default file name.
2252   All this command does is store the file name in the variable
2253 @code{tags-file-name}.  Emacs does not actually read in the tags table
2254 contents until you try to use them.  Setting this variable yourself is just
2255 as good as using @code{visit-tags-table}.  The variable's initial value is
2256 @code{nil}; that value tells all the commands for working with tags tables
2257 that they must ask for a tags table file name to use.
2259   Using @code{visit-tags-table} when a tags table is already loaded
2260 gives you a choice: you can add the new tags table to the current list
2261 of tags tables, or start a new list.  The tags commands use all the tags
2262 tables in the current list.  If you start a new list, the new tags table
2263 is used @emph{instead} of others.  If you add the new table to the
2264 current list, it is used @emph{as well as} the others.  When the tags
2265 commands scan the list of tags tables, they don't always start at the
2266 beginning of the list; they start with the first tags table (if any)
2267 that describes the current file, proceed from there to the end of the
2268 list, and then scan from the beginning of the list until they have
2269 covered all the tables in the list.
2271 @vindex tags-table-list
2272   You can specify a precise list of tags tables by setting the variable
2273 @code{tags-table-list} to a list of strings, like this:
2275 @c keep this on two lines for formatting in smallbook
2276 @example
2277 @group
2278 (setq tags-table-list
2279       '("~/emacs" "/usr/local/lib/emacs/src"))
2280 @end group
2281 @end example
2283 @noindent
2284 This tells the tags commands to look at the @file{TAGS} files in your
2285 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2286 directory.  The order depends on which file you are in and which tags
2287 table mentions that file, as explained above.
2289   Do not set both @code{tags-file-name} and @code{tags-table-list}.
2291 @node Find Tag
2292 @subsection Finding a Tag
2294   The most important thing that a tags table enables you to do is to find
2295 the definition of a specific tag.
2297 @table @kbd
2298 @item M-.@: @var{tag} @key{RET}
2299 Find first definition of @var{tag} (@code{find-tag}).
2300 @item C-u M-.
2301 Find next alternate definition of last tag specified.
2302 @item C-u - M-.
2303 Go back to previous tag found.
2304 @item C-M-. @var{pattern} @key{RET}
2305 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2306 @item C-u C-M-.
2307 Find the next tag whose name matches the last pattern used.
2308 @item C-x 4 .@: @var{tag} @key{RET}
2309 Find first definition of @var{tag}, but display it in another window
2310 (@code{find-tag-other-window}).
2311 @item C-x 5 .@: @var{tag} @key{RET}
2312 Find first definition of @var{tag}, and create a new frame to select the
2313 buffer (@code{find-tag-other-frame}).
2314 @item M-*
2315 Pop back to where you previously invoked @kbd{M-.} and friends.
2316 @end table
2318 @kindex M-.
2319 @findex find-tag
2320   @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
2321 a specified tag.  It searches through the tags table for that tag, as a
2322 string, and then uses the tags table info to determine the file that the
2323 definition is in and the approximate character position in the file of
2324 the definition.  Then @code{find-tag} visits that file, moves point to
2325 the approximate character position, and searches ever-increasing
2326 distances away to find the tag definition.
2328   If an empty argument is given (just type @key{RET}), the sexp in the
2329 buffer before or around point is used as the @var{tag} argument.
2330 @xref{Lists}, for info on sexps.
2332   You don't need to give @kbd{M-.} the full name of the tag; a part
2333 will do.  This is because @kbd{M-.} finds tags in the table which
2334 contain @var{tag} as a substring.  However, it prefers an exact match
2335 to a substring match.  To find other tags that match the same
2336 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
2337 M-.}; this does not read a tag name, but continues searching the tags
2338 table's text for another tag containing the same substring last used.
2339 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
2340 alternative to @kbd{C-u M-.}.
2342 @kindex C-x 4 .
2343 @findex find-tag-other-window
2344 @kindex C-x 5 .
2345 @findex find-tag-other-frame
2346   Like most commands that can switch buffers, @code{find-tag} has a
2347 variant that displays the new buffer in another window, and one that
2348 makes a new frame for it.  The former is @kbd{C-x 4 .}, which invokes
2349 the command @code{find-tag-other-window}.  The latter is @kbd{C-x 5 .},
2350 which invokes @code{find-tag-other-frame}.
2352   To move back to places you've found tags recently, use @kbd{C-u -
2353 M-.}; more generally, @kbd{M-.} with a negative numeric argument.  This
2354 command can take you to another buffer.  @kbd{C-x 4 .} with a negative
2355 argument finds the previous tag location in another window.
2357 @kindex M-*
2358 @findex pop-tag-mark
2359 @vindex find-tag-marker-ring-length
2360   As well as going back to places you've found tags recently, you can go
2361 back to places @emph{from where} you found them.  Use @kbd{M-*}, which
2362 invokes the command @code{pop-tag-mark}, for this.  Typically you would
2363 find and study the definition of something with @kbd{M-.} and then
2364 return to where you were with @kbd{M-*}.
2366   Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2367 a depth determined by the variable @code{find-tag-marker-ring-length}.
2369 @findex find-tag-regexp
2370 @kindex C-M-.
2371   The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2372 match a specified regular expression.  It is just like @kbd{M-.} except
2373 that it does regexp matching instead of substring matching.
2375 @node Tags Search
2376 @subsection Searching and Replacing with Tags Tables
2378   The commands in this section visit and search all the files listed in the
2379 selected tags table, one by one.  For these commands, the tags table serves
2380 only to specify a sequence of files to search.
2382 @table @kbd
2383 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2384 Search for @var{regexp} through the files in the selected tags
2385 table.
2386 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2387 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2388 @item M-,
2389 Restart one of the commands above, from the current location of point
2390 (@code{tags-loop-continue}).
2391 @end table
2393 @findex tags-search
2394   @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2395 searches for matches in all the files in the selected tags table, one
2396 file at a time.  It displays the name of the file being searched so you
2397 can follow its progress.  As soon as it finds an occurrence,
2398 @code{tags-search} returns.
2400 @kindex M-,
2401 @findex tags-loop-continue
2402   Having found one match, you probably want to find all the rest.  To find
2403 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2404 @code{tags-search}.  This searches the rest of the current buffer, followed
2405 by the remaining files of the tags table.@refill
2407 @findex tags-query-replace
2408   @kbd{M-x tags-query-replace} performs a single
2409 @code{query-replace-regexp} through all the files in the tags table.  It
2410 reads a regexp to search for and a string to replace with, just like
2411 ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
2412 tags-search}, but repeatedly, processing matches according to your
2413 input.  @xref{Replace}, for more information on query replace.
2415 @vindex tags-case-fold-search
2416 @cindex case-sensitivity, and tags search
2417   You can control the case-sensitivity of tags search commands by
2418 customizing the value of the variable @code{tags-case-fold-search}.  The
2419 default is to use the same setting as the value of
2420 @code{case-fold-search} (@pxref{Search Case}).
2422   It is possible to get through all the files in the tags table with a
2423 single invocation of @kbd{M-x tags-query-replace}.  But often it is
2424 useful to exit temporarily, which you can do with any input event that
2425 has no special query replace meaning.  You can resume the query replace
2426 subsequently by typing @kbd{M-,}; this command resumes the last tags
2427 search or replace command that you did.
2429   The commands in this section carry out much broader searches than the
2430 @code{find-tag} family.  The @code{find-tag} commands search only for
2431 definitions of tags that match your substring or regexp.  The commands
2432 @code{tags-search} and @code{tags-query-replace} find every occurrence
2433 of the regexp, as ordinary search commands and replace commands do in
2434 the current buffer.
2436   These commands create buffers only temporarily for the files that they
2437 have to search (those which are not already visited in Emacs buffers).
2438 Buffers in which no match is found are quickly killed; the others
2439 continue to exist.
2441   It may have struck you that @code{tags-search} is a lot like
2442 @code{grep}.  You can also run @code{grep} itself as an inferior of
2443 Emacs and have Emacs show you the matching lines one by one.  This works
2444 much like running a compilation; finding the source locations of the
2445 @code{grep} matches works like finding the compilation errors.
2446 @xref{Compilation}.
2448 @node List Tags
2449 @subsection Tags Table Inquiries
2451 @table @kbd
2452 @item M-x list-tags @key{RET} @var{file} @key{RET}
2453 Display a list of the tags defined in the program file @var{file}.
2454 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2455 Display a list of all tags matching @var{regexp}.
2456 @end table
2458 @findex list-tags
2459   @kbd{M-x list-tags} reads the name of one of the files described by
2460 the selected tags table, and displays a list of all the tags defined in
2461 that file.  The ``file name'' argument is really just a string to
2462 compare against the file names recorded in the tags table; it is read as
2463 a string rather than as a file name.  Therefore, completion and
2464 defaulting are not available, and you must enter the file name the same
2465 way it appears in the tags table.  Do not include a directory as part of
2466 the file name unless the file name recorded in the tags table includes a
2467 directory.
2469 @findex tags-apropos
2470   @kbd{M-x tags-apropos} is like @code{apropos} for tags
2471 (@pxref{Apropos}).  It reads a regexp, then finds all the tags in the
2472 selected tags table whose entries match that regexp, and displays the
2473 tag names found.
2474 @vindex tags-apropos-additional-actions
2475 You can display additional output with @kbd{M-x tags-apropos} by customizing
2476 the variable @code{tags-apropos-additional-actions}.  See its
2477 documentation for details.
2478 @vindex tags-apropos-verbose
2479 Setting the variable @code{tags-apropos-verbose} to a non-nil value
2480 causes @kbd{M-x tags-apropos} to display the names of the tags files
2481 together with the tag names.
2482 @vindex tags-tag-face
2483 The face @code{tags-tag-face} can be used to customize the appearance of
2484 tags in the output of @kbd{M-x tags-apropos}.
2486   You can also perform completion in the buffer on the name space of tag
2487 names in the current tags tables.  @xref{Symbol Completion}.
2489 @node Imenu
2490 @section Imenu
2491 @cindex indexes of buffer contents
2492 @cindex buffer content indexes
2493 @cindex tags
2495 The Imenu facility provides mode-specific indexes of the contents of
2496 single buffers and provides selection from a menu.  Selecting a menu
2497 item takes you to the indexed point in the buffer, in a similar way to
2498 the Tags facility.  Indexing is typically by names of program routines
2499 and variables but in Texinfo mode, for instance, node names are indexed.
2500 Most major modes for which it is appropriate have Imenu support.
2502 @findex imenu
2503 @findex imenu-add-menu-bar-index
2504 @kbd{M-x imenu} builds the index if necessary and presents you with an
2505 electric buffer menu from which to select an entry (with completion).
2506 If you bind @code{imenu} to a mouse event (@pxref{Mouse Buttons}) and
2507 invoke it that way, the index will appear as a popup menu; there is no
2508 such binding by default.  You can add an index menubar on the menubar
2509 with @kbd{imenu-add-menu-bar-index}.
2511 Some major modes provide facilities for invoking Imenu; otherwise you
2512 could add @code{imenu-add-menu-bar-index} to a major mode's hook to
2513 generate an index for each buffer created in that mode.  (If you do
2514 that, it takes sime time to generate the index when finding a file,
2515 depending on the file's size and the complexity of the indexing function
2516 for that mode.)
2518 @vindex imenu-auto-rescan
2519 The index should be regenerated (via the @samp{*Rescan*} menu item) when
2520 indexable items are added to or deleted from the buffer.  Rescanning is
2521 done when a menu selction is requested if the option
2522 @code{imenu-auto-rescan} is set.  By default buffer positions are in
2523 terms of markers, so that changing non-indexable text doesn't require
2524 rescanning.
2526 @vindex imenu-sort-function
2527 The way the menus are sorted can be customized via the option
2528 @code{imenu-sort-function}.  By default names are ordered as they occur
2529 in the buffer; alphabetic sorting is provided as an alternative.
2531 Imenu provides the information used by Which Function mode (@pxref{Which
2532 Function}).  It may also be used by Speedbar (@pxref{Speedbar}).
2534 @node Emerge, C Modes, Imenu, Programs
2535 @section Merging Files with Emerge
2536 @cindex Emerge
2537 @cindex merging files
2539 It's not unusual for programmers to get their signals crossed and modify
2540 the same program in two different directions.  To recover from this
2541 confusion, you need to merge the two versions.  Emerge makes this
2542 easier.  See also @ref{Comparing Files}, for commands to compare
2543 in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
2545 @menu
2546 * Overview of Emerge::  How to start Emerge.  Basic concepts.
2547 * Submodes of Emerge::  Fast mode vs. Edit mode.
2548                           Skip Prefers mode and Auto Advance mode.
2549 * State of Difference:: You do the merge by specifying state A or B
2550                           for each difference.
2551 * Merge Commands::      Commands for selecting a difference,
2552                           changing states of differences, etc.
2553 * Exiting Emerge::      What to do when you've finished the merge.
2554 * Combining in Emerge::     How to keep both alternatives for a difference.
2555 * Fine Points of Emerge::   Misc.
2556 @end menu
2558 @node Overview of Emerge
2559 @subsection Overview of Emerge
2561 To start Emerge, run one of these four commands:
2563 @table @kbd
2564 @item M-x emerge-files
2565 @findex emerge-files
2566 Merge two specified files.
2568 @item M-x emerge-files-with-ancestor
2569 @findex emerge-files-with-ancestor
2570 Merge two specified files, with reference to a common ancestor.
2572 @item M-x emerge-buffers
2573 @findex emerge-buffers
2574 Merge two buffers.
2576 @item M-x emerge-buffers-with-ancestor
2577 @findex emerge-buffers-with-ancestor
2578 Merge two buffers with reference to a common ancestor in a third
2579 buffer.
2580 @end table
2582 @cindex merge buffer (Emerge)
2583 @cindex A and B buffers (Emerge)
2584   The Emerge commands compare two files or buffers, and display the
2585 comparison in three buffers: one for each input text (the @dfn{A buffer}
2586 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
2587 takes place.  The merge buffer shows the full merged text, not just the
2588 differences.  Wherever the two input texts differ, you can choose which
2589 one of them to include in the merge buffer.
2591   The Emerge commands that take input from existing buffers use only the
2592 accessible portions of those buffers, if they are narrowed
2593 (@pxref{Narrowing}).
2595   If a common ancestor version is available, from which the two texts to
2596 be merged were both derived, Emerge can use it to guess which
2597 alternative is right.  Wherever one current version agrees with the
2598 ancestor, Emerge presumes that the other current version is a deliberate
2599 change which should be kept in the merged version.  Use the
2600 @samp{with-ancestor} commands if you want to specify a common ancestor
2601 text.  These commands read three file or buffer names---variant A,
2602 variant B, and the common ancestor.
2604   After the comparison is done and the buffers are prepared, the
2605 interactive merging starts.  You control the merging by typing special
2606 @dfn{merge commands} in the merge buffer.  The merge buffer shows you a
2607 full merged text, not just differences.  For each run of differences
2608 between the input texts, you can choose which one of them to keep, or
2609 edit them both together.
2611   The merge buffer uses a special major mode, Emerge mode, with commands
2612 for making these choices.  But you can also edit the buffer with
2613 ordinary Emacs commands.
2615   At any given time, the attention of Emerge is focused on one
2616 particular difference, called the @dfn{selected} difference.  This
2617 difference is marked off in the three buffers like this:
2619 @example
2620 vvvvvvvvvvvvvvvvvvvv
2621 @var{text that differs}
2622 ^^^^^^^^^^^^^^^^^^^^
2623 @end example
2625 @noindent
2626 Emerge numbers all the differences sequentially and the mode
2627 line always shows the number of the selected difference.
2629   Normally, the merge buffer starts out with the A version of the text.
2630 But when the A version of a difference agrees with the common ancestor,
2631 then the B version is initially preferred for that difference.
2633   Emerge leaves the merged text in the merge buffer when you exit.  At
2634 that point, you can save it in a file with @kbd{C-x C-w}.  If you give a
2635 numeric argument to @code{emerge-files} or
2636 @code{emerge-files-with-ancestor}, it reads the name of the output file
2637 using the minibuffer.  (This is the last file name those commands read.)
2638 Then exiting from Emerge saves the merged text in the output file.
2640   Normally, Emerge commands save the output buffer in its file when you
2641 exit.  If you abort Emerge with @kbd{C-]}, the Emerge command does not
2642 save the output buffer, but you can save it yourself if you wish.
2644 @node Submodes of Emerge
2645 @subsection Submodes of Emerge
2647   You can choose between two modes for giving merge commands: Fast mode
2648 and Edit mode.  In Fast mode, basic merge commands are single
2649 characters, but ordinary Emacs commands are disabled.  This is
2650 convenient if you use only merge commands.  In Edit mode, all merge
2651 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
2652 commands are also available.  This allows editing the merge buffer, but
2653 slows down Emerge operations.
2655   Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
2656 Fast mode.  The mode line indicates Edit and Fast modes with @samp{E}
2657 and @samp{F}.
2659   Emerge has two additional submodes that affect how particular merge
2660 commands work: Auto Advance mode and Skip Prefers mode.
2662   If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
2663 advance to the next difference.  This lets you go through the merge
2664 faster as long as you simply choose one of the alternatives from the
2665 input.  The mode line indicates Auto Advance mode with @samp{A}.
2667   If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
2668 skip over differences in states prefer-A and prefer-B (@pxref{State of
2669 Difference}).  Thus you see only differences for which neither version
2670 is presumed ``correct.''  The mode line indicates Skip Prefers mode with
2671 @samp{S}.
2673 @findex emerge-auto-advance-mode
2674 @findex emerge-skip-prefers-mode
2675   Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
2676 clear Auto Advance mode.  Use @kbd{s s}
2677 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
2678 These commands turn on the mode with a positive argument, turns it off
2679 with a negative or zero argument, and toggle the mode with no argument.
2681 @node State of Difference
2682 @subsection State of a Difference
2684   In the merge buffer, a difference is marked with lines of @samp{v} and
2685 @samp{^} characters.  Each difference has one of these seven states:
2687 @table @asis
2688 @item A
2689 The difference is showing the A version.  The @kbd{a} command always
2690 produces this state; the mode line indicates it with @samp{A}.
2692 @item B
2693 The difference is showing the B version.  The @kbd{b} command always
2694 produces this state; the mode line indicates it with @samp{B}.
2696 @item default-A
2697 @itemx default-B
2698 The difference is showing the A or the B state by default, because you
2699 haven't made a choice.  All differences start in the default-A state
2700 (and thus the merge buffer is a copy of the A buffer), except those for
2701 which one alternative is ``preferred'' (see below).
2703 When you select a difference, its state changes from default-A or
2704 default-B to plain A or B.  Thus, the selected difference never has
2705 state default-A or default-B, and these states are never displayed in
2706 the mode line.
2708 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
2709 b} chooses default-B.  This chosen default applies to all differences
2710 which you haven't ever selected and for which no alternative is preferred.
2711 If you are moving through the merge sequentially, the differences you
2712 haven't selected are those following the selected one.  Thus, while
2713 moving sequentially, you can effectively make the A version the default
2714 for some sections of the merge buffer and the B version the default for
2715 others by using @kbd{d a} and @kbd{d b} between sections.
2717 @item prefer-A
2718 @itemx prefer-B
2719 The difference is showing the A or B state because it is
2720 @dfn{preferred}.  This means that you haven't made an explicit choice,
2721 but one alternative seems likely to be right because the other
2722 alternative agrees with the common ancestor.  Thus, where the A buffer
2723 agrees with the common ancestor, the B version is preferred, because
2724 chances are it is the one that was actually changed.
2726 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
2728 @item combined
2729 The difference is showing a combination of the A and B states, as a
2730 result of the @kbd{x c} or @kbd{x C} commands.
2732 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
2733 don't do anything to it unless you give them a numeric argument.
2735 The mode line displays this state as @samp{comb}.
2736 @end table
2738 @node Merge Commands
2739 @subsection Merge Commands
2741   Here are the Merge commands for Fast mode; in Edit mode, precede them
2742 with @kbd{C-c C-c}:
2744 @table @kbd
2745 @item p
2746 Select the previous difference.
2748 @item n
2749 Select the next difference.
2751 @item a
2752 Choose the A version of this difference.
2754 @item b
2755 Choose the B version of this difference.
2757 @item C-u @var{n} j
2758 Select difference number @var{n}.
2760 @item .
2761 Select the difference containing point.  You can use this command in the
2762 merge buffer or in the A or B buffer.
2764 @item q
2765 Quit---finish the merge.
2767 @item C-]
2768 Abort---exit merging and do not save the output.
2770 @item f
2771 Go into Fast mode.  (In Edit mode, this is actually @kbd{C-c C-c f}.)
2773 @item e
2774 Go into Edit mode.
2776 @item l
2777 Recenter (like @kbd{C-l}) all three windows.
2779 @item -
2780 Specify part of a prefix numeric argument.
2782 @item @var{digit}
2783 Also specify part of a prefix numeric argument.
2785 @item d a
2786 Choose the A version as the default from here down in
2787 the merge buffer.
2789 @item d b
2790 Choose the B version as the default from here down in
2791 the merge buffer.
2793 @item c a
2794 Copy the A version of this difference into the kill ring.
2796 @item c b
2797 Copy the B version of this difference into the kill ring.
2799 @item i a
2800 Insert the A version of this difference at point.
2802 @item i b
2803 Insert the B version of this difference at point.
2805 @item m
2806 Put point and mark around the difference.
2808 @item ^
2809 Scroll all three windows down (like @kbd{M-v}).
2811 @item v
2812 Scroll all three windows up (like @kbd{C-v}).
2814 @item <
2815 Scroll all three windows left (like @kbd{C-x <}).
2817 @item >
2818 Scroll all three windows right (like @kbd{C-x >}).
2820 @item |
2821 Reset horizontal scroll on all three windows.
2823 @item x 1
2824 Shrink the merge window to one line.  (Use @kbd{C-u l} to restore it
2825 to full size.)
2827 @item x c
2828 Combine the two versions of this difference (@pxref{Combining in
2829 Emerge}).
2831 @item x f
2832 Show the names of the files/buffers Emerge is operating on, in a Help
2833 window.  (Use @kbd{C-u l} to restore windows.)
2835 @item x j
2836 Join this difference with the following one.
2837 (@kbd{C-u x j} joins this difference with the previous one.)
2839 @item x s
2840 Split this difference into two differences.  Before you use this
2841 command, position point in each of the three buffers at the place where
2842 you want to split the difference.
2844 @item x t
2845 Trim identical lines off the top and bottom of the difference.
2846 Such lines occur when the A and B versions are
2847 identical but differ from the ancestor version.
2848 @end table
2850 @node Exiting Emerge
2851 @subsection Exiting Emerge
2853   The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
2854 the results into the output file if you specified one.  It restores the
2855 A and B buffers to their proper contents, or kills them if they were
2856 created by Emerge and you haven't changed them.  It also disables the
2857 Emerge commands in the merge buffer, since executing them later could
2858 damage the contents of the various buffers.
2860   @kbd{C-]} aborts the merge.  This means exiting without writing the
2861 output file.  If you didn't specify an output file, then there is no
2862 real difference between aborting and finishing the merge.
2864   If the Emerge command was called from another Lisp program, then its
2865 return value is @code{t} for successful completion, or @code{nil} if you
2866 abort.
2868 @node Combining in Emerge
2869 @subsection Combining the Two Versions
2871   Sometimes you want to keep @emph{both} alternatives for a particular
2872 difference.  To do this, use @kbd{x c}, which edits the merge buffer
2873 like this:
2875 @example
2876 @group
2877 #ifdef NEW
2878 @var{version from A buffer}
2879 #else /* not NEW */
2880 @var{version from B buffer}
2881 #endif /* not NEW */
2882 @end group
2883 @end example
2885 @noindent
2886 @vindex emerge-combine-versions-template
2887 While this example shows C preprocessor conditionals delimiting the two
2888 alternative versions, you can specify the strings to use by setting
2889 the variable @code{emerge-combine-versions-template} to a string of your
2890 choice.  In the string, @samp{%a} says where to put version A, and
2891 @samp{%b} says where to put version B.  The default setting, which
2892 produces the results shown above, looks like this:
2894 @example
2895 @group
2896 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
2897 @end group
2898 @end example
2900 @node Fine Points of Emerge
2901 @subsection Fine Points of Emerge
2903   During the merge, you mustn't try to edit the A and B buffers yourself.
2904 Emerge modifies them temporarily, but ultimately puts them back the way
2905 they were.
2907   You can have any number of merges going at once---just don't use any one
2908 buffer as input to more than one merge at once, since the temporary
2909 changes made in these buffers would get in each other's way.
2911   Starting Emerge can take a long time because it needs to compare the
2912 files fully.  Emacs can't do anything else until @code{diff} finishes.
2913 Perhaps in the future someone will change Emerge to do the comparison in
2914 the background when the input files are large---then you could keep on
2915 doing other things with Emacs until Emerge is ready to accept
2916 commands.
2918 @vindex emerge-startup-hook
2919   After setting up the merge, Emerge runs the hook
2920 @code{emerge-startup-hook} (@pxref{Hooks}).
2922 @node C Modes
2923 @section C and Related Modes
2924 @cindex C mode
2925 @cindex Java mode
2926 @cindex Pike mode
2927 @cindex IDL mode
2928 @cindex CORBA IDL mode
2929 @cindex Objective C mode
2930 @cindex C++ mode
2931 @cindex mode, Java
2932 @cindex mode, C
2933 @cindex mode, Objective C
2934 @cindex mode, CORBA IDL
2935 @cindex mode, Pike
2937   This section describes special features available in C, C++,
2938 Objective-C, Java, CORBA IDL, and Pike modes.  When we say ``C mode and
2939 related modes,'' those are the modes we mean.
2941 Additional information is available in the separate manual for these
2942 modes.  @xref{Top, CC Mode, ccmode, , CC Mode}.
2944 @menu
2945 * Motion in C::
2946 * Electric C::
2947 * Hungry Delete::
2948 * Other C Commands::
2949 * Comments in C::
2950 @end menu
2952 @node Motion in C
2953 @subsection C Mode Motion Commands
2955   This section describes commands for moving point, in C mode and
2956 related modes.
2958 @table @code
2959 @item C-c C-u
2960 @kindex C-c C-u @r{(C mode)}
2961 @findex c-up-conditional
2962 Move point back to the containing preprocessor conditional, leaving the
2963 mark behind.  A prefix argument acts as a repeat count.  With a negative
2964 argument, move point forward to the end of the containing
2965 preprocessor conditional.  When going backwards, @code{#elif} is treated
2966 like @code{#else} followed by @code{#if}.  When going forwards,
2967 @code{#elif} is ignored.@refill
2969 @item C-c C-p
2970 @kindex C-c C-p @r{(C mode)}
2971 @findex c-backward-conditional
2972 Move point back over a preprocessor conditional, leaving the mark
2973 behind.  A prefix argument acts as a repeat count.  With a negative
2974 argument, move forward.
2976 @item C-c C-n
2977 @kindex C-c C-n @r{(C mode)}
2978 @findex c-forward-conditional
2979 Move point forward across a preprocessor conditional, leaving the mark
2980 behind.  A prefix argument acts as a repeat count.  With a negative
2981 argument, move backward.
2983 @item M-a
2984 @kindex ESC a
2985 @findex c-beginning-of-statement
2986 Move point to the beginning of the innermost C statement
2987 (@code{c-beginning-of-statement}).  If point is already at the beginning
2988 of a statement, move to the beginning of the preceding statement.  With
2989 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
2991 If point is within a string or comment, or next to a comment (only
2992 whitespace between them), this command moves by sentences instead of
2993 statements.
2995 When called from a program, this function takes three optional
2996 arguments: the numeric prefix argument, a buffer position limit
2997 (don't move back before that place), and a flag that controls whether
2998 to do sentence motion when inside of a comment.
3000 @item M-e
3001 @kindex ESC e
3002 @findex c-end-of-statement
3003 Move point to the end of the innermost C statement; like @kbd{M-a}
3004 except that it moves in the other direction (@code{c-end-of-statement}).
3006 @item M-x c-backward-into-nomenclature
3007 @findex c-backward-into-nomenclature
3008 Move point backward to beginning of a C++ nomenclature section or word.
3009 With prefix argument @var{n}, move @var{n} times.  If @var{n} is
3010 negative, move forward.  C++ nomenclature means a symbol name in the
3011 style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
3012 begins a section or word.
3014 In the GNU project, we recommend using underscores to separate words
3015 within an identifier in C or C++, rather than using case distinctions.
3017 @item M-x c-forward-into-nomenclature
3018 @findex c-forward-into-nomenclature
3019 Move point forward to end of a C++ nomenclature section or word.
3020 With prefix argument @var{n}, move @var{n} times.
3021 @end table
3023 @node Electric C
3024 @subsection Electric C Characters
3026   In C mode and related modes, certain printing characters are
3027 ``electric''---in addition to inserting themselves, they also reindent
3028 the current line and may insert newlines.  This feature is controlled by
3029 the variable @code{c-auto-newline}.  The ``electric'' characters are
3030 @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
3031 @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
3033   Electric characters insert newlines only when the @dfn{auto-newline}
3034 feature is enabled (indicated by @samp{/a} in the mode line after the
3035 mode name).  This feature is controlled by the variable
3036 @code{c-auto-newline}.  You can turn this feature on or off with the
3037 command @kbd{C-c C-a}:
3039 @table @kbd
3040 @item C-c C-a
3041 @kindex C-c C-a @r{(C mode)}
3042 @findex c-toggle-auto-state
3043 Toggle the auto-newline feature (@code{c-toggle-auto-state}).  With a
3044 prefix argument, this command turns the auto-newline feature on if the
3045 argument is positive, and off if it is negative.
3046 @end table
3048   The colon character is electric because that is appropriate for a
3049 single colon.  But when you want to insert a double colon in C++, the
3050 electric behavior of colon is inconvenient.  You can insert a double
3051 colon with no reindentation or newlines by typing @kbd{C-c :}:
3053 @table @kbd
3054 @item C-c :
3055 @kindex C-c : @r{(C mode)}
3056 @findex c-scope-operator
3057 Insert a double colon scope operator at point, without reindenting the
3058 line or adding any newlines (@code{c-scope-operator}).
3059 @end table
3061   The electric @kbd{#} key reindents the line if it appears to be the
3062 beginning of a preprocessor directive.  This happens when the value of
3063 @code{c-electric-pound-behavior} is @code{(alignleft)}.  You can turn
3064 this feature off by setting @code{c-electric-pound-behavior} to
3065 @code{nil}.
3067    The variable @code{c-hanging-braces-alist} controls the insertion of
3068 newlines before and after inserted braces.  It is an association list
3069 with elements of the following form: @code{(@var{syntactic-symbol}
3070 . @var{nl-list})}.  Most of the syntactic symbols that appear in
3071 @code{c-offsets-alist} are meaningful here as well.
3073    The list @var{nl-list} may contain either of the symbols
3074 @code{before} or @code{after}, or both; or it may be @code{nil}.  When a
3075 brace is inserted, the syntactic context it defines is looked up in
3076 @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
3077 to determine where newlines are inserted: either before the brace,
3078 after, or both.  If not found, the default is to insert a newline both
3079 before and after braces.
3081    The variable @code{c-hanging-colons-alist} controls the insertion of
3082 newlines before and after inserted colons.  It is an association list
3083 with elements of the following form: @code{(@var{syntactic-symbol}
3084 . @var{nl-list})}.  The list @var{nl-list} may contain either of the
3085 symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
3087    When a colon is inserted, the syntactic symbol it defines is looked
3088 up in this list, and if found, the @var{nl-list} is used to determine
3089 where newlines are inserted: either before the brace, after, or both.
3090 If the syntactic symbol is not found in this list, no newlines are
3091 inserted.
3093    Electric characters can also delete newlines automatically when the
3094 auto-newline feature is enabled.  This feature makes auto-newline more
3095 acceptable, by deleting the newlines in the most common cases where you
3096 do not want them.  Emacs can recognize several cases in which deleting a
3097 newline might be desirable; by setting the variable
3098 @code{c-cleanup-list}, you can specify @emph{which} of these cases that
3099 should happen.  The variable's value is a list of symbols, each
3100 describing one case for possible deletion of a newline.  Here are the
3101 meaningful symbols, and their meanings:
3103 @table @code
3104 @item brace-catch-brace
3105 Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
3106 entire construct on a single line.  The clean-up occurs when you type
3107 the @samp{@{}, if there is nothing between the braces aside from
3108 @code{catch} and @var{condition}.
3110 @item brace-else-brace
3111 Clean up @samp{@} else @{} constructs by placing the entire construct on
3112 a single line.  The clean-up occurs when you type the @samp{@{} after
3113 the @code{else}, but only if there is nothing but white space between
3114 the braces and the @code{else}.
3116 @item brace-elseif-brace
3117 Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
3118 construct on a single line.  The clean-up occurs when you type the
3119 @samp{@{}, if there is nothing but white space between the @samp{@}} and
3120 @samp{@{} aside from the keywords and the @code{if}-condition.
3122 @item empty-defun-braces
3123 Clean up empty defun braces by placing the braces on the same
3124 line.  Clean-up occurs when you type the closing brace.
3126 @item defun-close-semi
3127 Clean up the semicolon after a @code{struct} or similar type
3128 declaration, by placing the semicolon on the same line as the closing
3129 brace.  Clean-up occurs when you type the semicolon.
3131 @item list-close-comma
3132 Clean up commas following braces in array and aggregate
3133 initializers.  Clean-up occurs when you type the comma.
3135 @item scope-operator
3136 Clean up double colons which may designate a C++ scope operator, by
3137 placing the colons together.  Clean-up occurs when you type the second
3138 colon, but only when the two colons are separated by nothing but
3139 whitespace.
3140 @end table
3142 @node Hungry Delete
3143 @subsection Hungry Delete Feature in C
3145   When the @dfn{hungry-delete} feature is enabled (indicated by
3146 @samp{/h} or @samp{/ah} in the mode line after the mode name), a single
3147 @key{DEL} command deletes all preceding whitespace, not just one space.
3148 To turn this feature on or off, use @kbd{C-c C-d}:
3150 @table @kbd
3151 @item C-c C-d
3152 @kindex C-c C-d @r{(C mode)}
3153 @findex c-toggle-hungry-state
3154 Toggle the hungry-delete feature (@code{c-toggle-hungry-state}).  With a
3155 prefix argument, this command turns the hungry-delete feature on if the
3156 argument is positive, and off if it is negative.
3158 @item C-c C-t
3159 @kindex C-c C-t @r{(C mode)}
3160 @findex c-toggle-auto-hungry-state
3161 Toggle the auto-newline and hungry-delete features, both at once
3162 (@code{c-toggle-auto-hungry-state}).
3163 @end table
3165 @vindex c-hungry-delete-key
3166    The variable @code{c-hungry-delete-key} controls whether the
3167 hungry-delete feature is enabled.
3169 @node Other C Commands
3170 @subsection Other Commands for C Mode
3172 @table @kbd
3173 @item C-M-h
3174 @findex c-mark-function
3175 @kindex C-M-h @r{(C mode)}
3176 Put mark at the end of a function definition, and put point at the
3177 beginning (@code{c-mark-function}).
3179 @item M-q
3180 @kindex M-q @r{(C mode)}
3181 @findex c-fill-paragraph
3182 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
3183 If any part of the current line is a comment or within a comment, this
3184 command fills the comment or the paragraph of it that point is in,
3185 preserving the comment indentation and comment delimiters.
3187 @item C-c C-e
3188 @cindex macro expansion in C
3189 @cindex expansion of C macros
3190 @findex c-macro-expand
3191 @kindex C-c C-e @r{(C mode)}
3192 Run the C preprocessor on the text in the region, and show the result,
3193 which includes the expansion of all the macro calls
3194 (@code{c-macro-expand}).  The buffer text before the region is also
3195 included in preprocessing, for the sake of macros defined there, but the
3196 output from this part isn't shown.
3198 When you are debugging C code that uses macros, sometimes it is hard to
3199 figure out precisely how the macros expand.  With this command, you
3200 don't have to figure it out; you can see the expansions.
3202 @item C-c C-\
3203 @findex c-backslash-region
3204 @kindex C-c C-\ @r{(C mode)}
3205 Insert or align @samp{\} characters at the ends of the lines of the
3206 region (@code{c-backslash-region}).  This is useful after writing or
3207 editing a C macro definition.
3209 If a line already ends in @samp{\}, this command adjusts the amount of
3210 whitespace before it.  Otherwise, it inserts a new @samp{\}.  However,
3211 the last line in the region is treated specially; no @samp{\} is
3212 inserted on that line, and any @samp{\} there is deleted.
3214 @item M-x cpp-highlight-buffer
3215 @cindex preprocessor highlighting
3216 @findex cpp-highlight-buffer
3217 Highlight parts of the text according to its preprocessor conditionals.
3218 This command displays another buffer named @samp{*CPP Edit*}, which
3219 serves as a graphic menu for selecting how to display particular kinds
3220 of conditionals and their contents.  After changing various settings,
3221 click on @samp{[A]pply these settings} (or go to that buffer and type
3222 @kbd{a}) to rehighlight the C mode buffer accordingly.
3224 @item C-c C-s
3225 @findex c-show-syntactic-information
3226 @kindex C-c C-s @r{(C mode)}
3227 Display the syntactic information about the current source line
3228 (@code{c-show-syntactic-information}).  This is the information that
3229 directs how the line is indented.
3231 @item M-x cwarn-mode
3232 @itemx M-x global-cwarn-mode
3233 @findex cwarn-mode
3234 @findex global-cwarn-mode
3235 @cindex CWarn mode
3236 @cindex suspicious constructions in C, C++
3237 CWarn minor mode highlights suspicious C and C++ constructions:
3239 @itemize @bullet{}
3240 @item
3241 Assignments inside expressions, including variations like @samp{+=};
3242 @item
3243 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
3244 (except after a @samp{do @dots{} while} statement);
3245 @item
3246 C++ functions with reference parameters.
3247 @end itemize
3249 @noindent
3250 You can activate the mode either by customizing @code{global-cwarn-mode}
3251 or by adding @code{cwarn-mode} to @code{c-mode-common-hook}.  It
3252 requires Font Lock mode to be active.
3254 @item M-x hide-ifdef-mode
3255 @findex hide-ifdef-mode
3256 @cindex Hide-ifdef mode
3257 Hide-ifdef minor mode hides selected code within @samp{#if} and
3258 @samp{#ifdef} preprocessor blocks.  You can activate it by adding
3259 @code{hide-ifdef-mode} to @code{c-mode-common-hook}.  See the mode's
3260 help for more information.
3261 @end table
3263 @node Comments in C
3264 @subsection Comments in C Modes
3266    C mode and related modes use a number of variables for controlling
3267 comment format.
3269 @table @code
3270 @item c-comment-only-line-offset
3271 @vindex c-comment-only-line-offset
3272 Extra offset for line which contains only the start of a comment.  It
3273 can be either an integer or a cons cell of the form
3274 @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
3275 @var{non-anchored-offset} is the amount of offset given to
3276 non-column-zero anchored comment-only lines, and @var{anchored-offset}
3277 is the amount of offset to give column-zero anchored comment-only lines.
3278 Just an integer as value is equivalent to @code{(@var{val} . 0)}.
3280 @item c-comment-start-regexp
3281 @vindex c-comment-start-regexp
3282 This buffer-local variable specifies how to recognize the start of a comment.
3284 @item c-hanging-comment-ender-p
3285 @vindex c-hanging-comment-ender-p
3286 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
3287 comment terminator of a block comment on a line by itself.  The default
3288 value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
3289 end of the last line of the comment text.
3291 @item c-hanging-comment-starter-p
3292 @vindex c-hanging-comment-starter-p
3293 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
3294 starting delimiter of a block comment on a line by itself.  The default
3295 value is @code{t}, which puts the comment-start delimiter @samp{/*} at
3296 the beginning of the first line of the comment text.
3297 @end table
3300 @node Fortran
3301 @section Fortran Mode
3302 @cindex Fortran mode
3303 @cindex mode, Fortran
3305   Fortran mode provides special motion commands for Fortran statements and
3306 subprograms, and indentation commands that understand Fortran conventions
3307 of nesting, line numbers and continuation statements.  Fortran mode has
3308 its own Auto Fill mode that breaks long lines into proper Fortran
3309 continuation lines.
3311   Special commands for comments are provided because Fortran comments
3312 are unlike those of other languages.  Built-in abbrevs optionally save
3313 typing when you insert Fortran keywords.
3315 @findex fortran-mode
3316   Use @kbd{M-x fortran-mode} to switch to this major mode.  This command
3317 runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
3319 @cindex Fortran77
3320 @cindex Fortran90
3321 @findex f90-mode
3322 @findex fortran-mode
3323 Note that Fortan mode described here (obtained with the
3324 @code{fortran-mode} command) is for editing the old Fortran77
3325 idiosyncratic `fixed format' source form.  For editing the modern
3326 Fortran90 `free format' source form (which is supported by the GNU
3327 Fortran compiler) use @code{f90-mode}.
3329 By default @code{fortran-mode} is invoked on files with extension
3330 @samp{.f}, @samp{.F} or @samp{.for} and @code{f90-mode} is invoked for
3331 the extension @samp{.f90}.
3333 @menu
3334 * Motion: Fortran Motion.        Moving point by statements or subprograms.
3335 * Indent: Fortran Indent.        Indentation commands for Fortran.
3336 * Comments: Fortran Comments.    Inserting and aligning comments.
3337 * Autofill: Fortran Autofill.    Auto fill minor mode for Fortran.
3338 * Columns: Fortran Columns.      Measuring columns for valid Fortran.
3339 * Abbrev: Fortran Abbrev.        Built-in abbrevs for Fortran keywords.
3340 * Misc: Fortran Misc.            Other Fortran mode features.
3341 @end menu
3343 @node Fortran Motion
3344 @subsection Motion Commands
3346 In addition to the normal commands for moving by and operating on
3347 `defuns' (Fortran subprograms---functions
3348 and subroutines) Fortran mode provides special commands to move by statements.
3350 @kindex C-c C-p @r{(Fortran mode)}
3351 @kindex C-c C-n @r{(Fortran mode)}
3352 @findex fortran-previous-statement
3353 @findex fortran-next-statement
3355 @table @kbd
3356 @item C-c C-n
3357 Move to beginning of current or next statement
3358 (@code{fortran-next-statement}).
3359 @item C-c C-p
3360 Move to beginning of current or previous statement
3361 (@code{fortran-previous-statement}).
3362 @end table
3364 @node Fortran Indent
3365 @subsection Fortran Indentation
3367   Special commands and features are needed for indenting Fortran code in
3368 order to make sure various syntactic entities (line numbers, comment line
3369 indicators and continuation line flags) appear in the columns that are
3370 required for standard Fortran.
3372 @menu
3373 * Commands: ForIndent Commands.  Commands for indenting and filling Fortran.
3374 * Contline: ForIndent Cont.      How continuation lines indent.
3375 * Numbers:  ForIndent Num.       How line numbers auto-indent.
3376 * Conv:     ForIndent Conv.      Conventions you must obey to avoid trouble.
3377 * Vars:     ForIndent Vars.      Variables controlling Fortran indent style.
3378 @end menu
3380 @node ForIndent Commands
3381 @subsubsection Fortran-Specific Indentation and Filling Commands
3383 @table @kbd
3384 @item C-M-j
3385 Break the current line and set up a continuation line
3386 (@code{fortran-split-line}).
3387 @item M-^
3388 Join this line to the previous line (@code{fortran-join-line}).
3389 @item C-M-q
3390 Indent all the lines of the subprogram point is in
3391 (@code{fortran-indent-subprogram}).
3392 @item M-q
3393 Fill a comment block or statement.
3394 @end table
3396 @kindex C-M-q @r{(Fortran mode)}
3397 @findex fortran-indent-subprogram
3398   The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
3399 to reindent all the lines of the Fortran subprogram (function or
3400 subroutine) containing point.
3402 @kindex C-M-j @r{(Fortran mode)}
3403 @findex fortran-split-line
3404   The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
3405 a line in the appropriate fashion for Fortran.  In a non-comment line,
3406 the second half becomes a continuation line and is indented
3407 accordingly.  In a comment line, both halves become separate comment
3408 lines.
3410 @kindex M-^ @r{(Fortran mode)}
3411 @kindex C-c C-d @r{(Fortran mode)}
3412 @findex fortran-join-line
3413   @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
3414 which joins a continuation line back to the previous line, roughly as
3415 the inverse of @code{fortran-split-line}.  The point must be on a
3416 continuation line when this command is invoked.
3418 @kindex M-q @r{(Fortran mode)}
3419 Fortran mode defines the function for filling paragraphs such that
3420 @kbd{M-q} fills the comment block or statement around point.  Filling a
3421 statement removes excess statement continuations.
3423 @node ForIndent Cont
3424 @subsubsection Continuation Lines
3425 @cindex Fortran continuation lines
3427 @vindex fortran-continuation-string
3428   Most modern Fortran compilers allow two ways of writing continuation
3429 lines.  If the first non-space character on a line is in column 5, then
3430 that line is a continuation of the previous line.  We call this
3431 @dfn{fixed format}.  (In GNU Emacs we always count columns from 0.)  The
3432 variable @code{fortran-continuation-string} specifies what character to
3433 put on column 5.  A line that starts with a tab character followed by
3434 any digit except @samp{0} is also a continuation line.  We call this
3435 style of continuation @dfn{tab format}.
3437 @vindex indent-tabs-mode @r{(Fortran mode)}
3438   Fortran mode can make either style of continuation line, but you
3439 must specify which one you prefer.  The value of the variable
3440 @code{indent-tabs-mode} controls the choice: @code{nil} for fixed
3441 format, and non-@code{nil} for tab format.  You can tell which style
3442 is presently in effect by the presence or absence of the string
3443 @samp{Tab} in the mode line.
3445   If the text on a line starts with the conventional Fortran
3446 continuation marker @samp{$}, or if it begins with any non-whitespace
3447 character in column 5, Fortran mode treats it as a continuation line.
3448 When you indent a continuation line with @key{TAB}, it converts the line
3449 to the current continuation style.  When you split a Fortran statement
3450 with @kbd{C-M-j}, the continuation marker on the newline is created
3451 according to the continuation style.
3453   The setting of continuation style affects several other aspects of
3454 editing in Fortran mode.  In fixed format mode, the minimum column
3455 number for the body of a statement is 6.  Lines inside of Fortran
3456 blocks that are indented to larger column numbers always use only the
3457 space character for whitespace.  In tab format mode, the minimum
3458 column number for the statement body is 8, and the whitespace before
3459 column 8 must always consist of one tab character.
3461 @vindex fortran-tab-mode-default
3462 @vindex fortran-analyze-depth
3463   When you enter Fortran mode for an existing file, it tries to deduce the
3464 proper continuation style automatically from the file contents.  The first
3465 line that begins with either a tab character or six spaces determines the
3466 choice.  The variable @code{fortran-analyze-depth} specifies how many lines
3467 to consider (at the beginning of the file); if none of those lines
3468 indicates a style, then the variable @code{fortran-tab-mode-default}
3469 specifies the style.  If it is @code{nil}, that specifies fixed format, and
3470 non-@code{nil} specifies tab format.
3472 @node ForIndent Num
3473 @subsubsection Line Numbers
3475   If a number is the first non-whitespace in the line, Fortran
3476 indentation assumes it is a line number and moves it to columns 0
3477 through 4.  (Columns always count from 0 in GNU Emacs.)
3479 @vindex fortran-line-number-indent
3480   Line numbers of four digits or less are normally indented one space.
3481 The variable @code{fortran-line-number-indent} controls this; it
3482 specifies the maximum indentation a line number can have.  Line numbers
3483 are indented to right-justify them to end in column 4 unless that would
3484 require more than this maximum indentation.  The default value of the
3485 variable is 1.
3487 @vindex fortran-electric-line-number
3488   Simply inserting a line number is enough to indent it according to
3489 these rules.  As each digit is inserted, the indentation is recomputed.
3490 To turn off this feature, set the variable
3491 @code{fortran-electric-line-number} to @code{nil}.  Then inserting line
3492 numbers is like inserting anything else.
3494 @node ForIndent Conv
3495 @subsubsection Syntactic Conventions
3497   Fortran mode assumes that you follow certain conventions that simplify
3498 the task of understanding a Fortran program well enough to indent it
3499 properly:
3501 @itemize @bullet
3502 @item
3503 Two nested @samp{do} loops never share a @samp{continue} statement.
3505 @item
3506 Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
3507 and others are written without embedded whitespace or line breaks.
3509 Fortran compilers generally ignore whitespace outside of string
3510 constants, but Fortran mode does not recognize these keywords if they
3511 are not contiguous.  Constructs such as @samp{else if} or @samp{end do}
3512 are acceptable, but the second word should be on the same line as the
3513 first and not on a continuation line.
3514 @end itemize
3516 @noindent
3517 If you fail to follow these conventions, the indentation commands may
3518 indent some lines unaesthetically.  However, a correct Fortran program
3519 retains its meaning when reindented even if the conventions are not
3520 followed.
3522 @node ForIndent Vars
3523 @subsubsection Variables for Fortran Indentation
3525 @vindex fortran-do-indent
3526 @vindex fortran-if-indent
3527 @vindex fortran-structure-indent
3528 @vindex fortran-continuation-indent
3529 @vindex fortran-check-all-num@dots{}
3530 @vindex fortran-minimum-statement-indent@dots{}
3531   Several additional variables control how Fortran indentation works:
3533 @table @code
3534 @item fortran-do-indent
3535 Extra indentation within each level of @samp{do} statement (default 3).
3537 @item fortran-if-indent
3538 Extra indentation within each level of @samp{if} statement (default 3).
3539 This value is also used for extra indentation within each level of the
3540 Fortran 90 @samp{where} statement.
3542 @item fortran-structure-indent
3543 Extra indentation within each level of @samp{structure}, @samp{union}, or
3544 @samp{map} statements (default 3).
3546 @item fortran-continuation-indent
3547 Extra indentation for bodies of continuation lines (default 5).
3549 @item fortran-check-all-num-for-matching-do
3550 If this is @code{nil}, indentation assumes that each @samp{do} statement
3551 ends on a @samp{continue} statement.  Therefore, when computing
3552 indentation for a statement other than @samp{continue}, it can save time
3553 by not checking for a @samp{do} statement ending there.  If this is
3554 non-@code{nil}, indenting any numbered statement must check for a
3555 @samp{do} that ends there.  The default is @code{nil}.
3557 @item fortran-blink-matching-if
3558 If this is @code{t}, indenting an @samp{endif} statement moves the
3559 cursor momentarily to the matching @samp{if} statement to show where it
3560 is.  The default is @code{nil}.
3562 @item fortran-minimum-statement-indent-fixed
3563 Minimum indentation for fortran statements when using fixed format
3564 continuation line style.  Statement bodies are never indented less than
3565 this much.  The default is 6.
3567 @item fortran-minimum-statement-indent-tab
3568 Minimum indentation for fortran statements for tab format continuation line
3569 style.  Statement bodies are never indented less than this much.  The
3570 default is 8.
3571 @end table
3573 @node Fortran Comments
3574 @subsection Fortran Comments
3576   The usual Emacs comment commands assume that a comment can follow a line
3577 of code.  In Fortran, the standard comment syntax requires an entire line
3578 to be just a comment.  Therefore, Fortran mode replaces the standard Emacs
3579 comment commands and defines some new variables.
3581   Fortran mode can also handle the Fortran90 comment syntax where comments
3582 start with @samp{!} and can follow other text.  Because only some Fortran77
3583 compilers accept this syntax, Fortran mode will not insert such comments
3584 unless you have said in advance to do so.  To do this, set the variable
3585 @code{comment-start} to @samp{"!"} (@pxref{Variables}).
3587 @table @kbd
3588 @item M-;
3589 Align comment or insert new comment (@code{fortran-comment-indent}).
3591 @item C-x ;
3592 Applies to nonstandard @samp{!} comments only.
3594 @item C-c ;
3595 Turn all lines of the region into comments, or (with argument) turn them back
3596 into real code (@code{fortran-comment-region}).
3597 @end table
3599   @kbd{M-;} in Fortran mode is redefined as the command
3600 @code{fortran-comment-indent}.  Like the usual @kbd{M-;} command, this
3601 recognizes any kind of existing comment and aligns its text appropriately;
3602 if there is no existing comment, a comment is inserted and aligned.  But
3603 inserting and aligning comments are not the same in Fortran mode as in
3604 other modes.
3606   When a new comment must be inserted, if the current line is blank, a
3607 full-line comment is inserted.  On a non-blank line, a nonstandard @samp{!}
3608 comment is inserted if you have said you want to use them.  Otherwise a
3609 full-line comment is inserted on a new line before the current line.
3611   Nonstandard @samp{!} comments are aligned like comments in other
3612 languages, but full-line comments are different.  In a standard full-line
3613 comment, the comment delimiter itself must always appear in column zero.
3614 What can be aligned is the text within the comment.  You can choose from
3615 three styles of alignment by setting the variable
3616 @code{fortran-comment-indent-style} to one of these values:
3618 @vindex fortran-comment-indent-style
3619 @vindex fortran-comment-line-extra-indent
3620 @table @code
3621 @item fixed
3622 Align the text at a fixed column, which is the sum of
3623 @code{fortran-comment-line-extra-indent} and the minimum statement
3624 indentation.  This is the default.
3626 The minimum statement indentation is
3627 @code{fortran-minimum-statement-indent-fixed} for fixed format
3628 continuation line style and @code{fortran-minimum-statement-indent-tab}
3629 for tab format style.
3631 @item relative
3632 Align the text as if it were a line of code, but with an additional
3633 @code{fortran-comment-line-extra-indent} columns of indentation.
3635 @item nil
3636 Don't move text in full-line comments automatically at all.
3637 @end table
3639 @vindex fortran-comment-indent-char
3640   In addition, you can specify the character to be used to indent within
3641 full-line comments by setting the variable
3642 @code{fortran-comment-indent-char} to the single-character string you want
3643 to use.
3645 @vindex comment-line-start
3646 @vindex comment-line-start-skip
3647   Fortran mode introduces two variables @code{comment-line-start} and
3648 @code{comment-line-start-skip}, which play for full-line comments the same
3649 roles played by @code{comment-start} and @code{comment-start-skip} for
3650 ordinary text-following comments.  Normally these are set properly by
3651 Fortran mode, so you do not need to change them.
3653   The normal Emacs comment command @kbd{C-x ;} has not been redefined.  If
3654 you use @samp{!} comments, this command can be used with them.  Otherwise
3655 it is useless in Fortran mode.
3657 @kindex C-c ; @r{(Fortran mode)}
3658 @findex fortran-comment-region
3659 @vindex fortran-comment-region
3660   The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
3661 lines of the region into comments by inserting the string @samp{C$$$} at
3662 the front of each one.  With a numeric argument, it turns the region
3663 back into live code by deleting @samp{C$$$} from the front of each line
3664 in it.  The string used for these comments can be controlled by setting
3665 the variable @code{fortran-comment-region}.  Note that here we have an
3666 example of a command and a variable with the same name; these two uses
3667 of the name never conflict because in Lisp and in Emacs it is always
3668 clear from the context which one is meant.
3670 @node Fortran Autofill
3671 @subsection Fortran Auto Fill Mode
3673   Fortran Auto Fill mode is a minor mode which automatically splits
3674 Fortran statements as you insert them when they become too wide.
3675 Splitting a statement involves making continuation lines using
3676 @code{fortran-continuation-string} (@pxref{ForIndent Cont}).  This
3677 splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
3678 also in the Fortran indentation commands.
3680 @findex fortran-auto-fill-mode
3681   @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
3682 was off, or off if it was on.  This command works the same as @kbd{M-x
3683 auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}).  A
3684 positive numeric argument turns Fortran Auto Fill mode on, and a
3685 negative argument turns it off.  You can see when Fortran Auto Fill mode
3686 is in effect by the presence of the word @samp{Fill} in the mode line,
3687 inside the parentheses.  Fortran Auto Fill mode is a minor mode, turned
3688 on or off for each buffer individually.  @xref{Minor Modes}.
3690 @vindex fortran-break-before-delimiters
3691    Fortran Auto Fill mode breaks lines at spaces or delimiters when the
3692 lines get longer than the desired width (the value of @code{fill-column}).
3693 The delimiters that Fortran Auto Fill mode may break at are @samp{,},
3694 @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
3695 The line break comes after the delimiter if the variable
3696 @code{fortran-break-before-delimiters} is @code{nil}.  Otherwise (and by
3697 default), the break comes before the delimiter.
3699   By default, Fortran Auto Fill mode is not enabled.  If you want this
3700 feature turned on permanently, add a hook function to
3701 @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
3702 @xref{Hooks}.
3704 @node Fortran Columns
3705 @subsection Checking Columns in Fortran
3707 @table @kbd
3708 @item C-c C-r
3709 Display a ``column ruler'' momentarily above the current line
3710 (@code{fortran-column-ruler}).
3711 @item C-c C-w
3712 Split the current window horizontally temporarily so that it is 72
3713 columns wide.  This may help you avoid making lines longer than the
3714 72-character limit that some Fortran compilers impose
3715 (@code{fortran-window-create-momentarily}).
3716 @end table
3718 @kindex C-c C-r @r{(Fortran mode)}
3719 @findex fortran-column-ruler
3720 @vindex fortran-column-ruler
3721   The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
3722 ruler momentarily above the current line.  The comment ruler is two lines
3723 of text that show you the locations of columns with special significance in
3724 Fortran programs.  Square brackets show the limits of the columns for line
3725 numbers, and curly brackets show the limits of the columns for the
3726 statement body.  Column numbers appear above them.
3728   Note that the column numbers count from zero, as always in GNU Emacs.
3729 As a result, the numbers may be one less than those you are familiar
3730 with; but the positions they indicate in the line are standard for
3731 Fortran.
3733   The text used to display the column ruler depends on the value of
3734 the variable @code{indent-tabs-mode}.  If @code{indent-tabs-mode} is
3735 @code{nil}, then the value of the variable
3736 @code{fortran-column-ruler-fixed} is used as the column ruler.
3737 Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
3738 By changing these variables, you can change the column ruler display.
3740 @kindex C-u C-c C-w @r{(Fortran mode)}
3741 @findex fortran-window-create
3742   For even more help, use @kbd{M-x fortran-window-create}), a
3743 command which splits the current window horizontally, making a window 72
3744 columns wide.  By editing in this window you can immediately see when you
3745 make a line too wide to be correct Fortran.
3747 @kindex C-c C-w @r{(Fortran mode)}
3748 @findex fortran-window-create-momentarily
3749 Also, @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) can be
3750 used temporarily to split the current window horizontally, making a
3751 window 72 columns wide to check column widths rather than to edit in
3752 this mode.  The normal width is restored when you type a space.
3754 @node Fortran Abbrev
3755 @subsection Fortran Keyword Abbrevs
3757   Fortran mode provides many built-in abbrevs for common keywords and
3758 declarations.  These are the same sort of abbrev that you can define
3759 yourself.  To use them, you must turn on Abbrev mode.  @xref{Abbrevs}.
3761   The built-in abbrevs are unusual in one way: they all start with a
3762 semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
3763 mode makes this possible by changing the syntax of semicolon to ``word
3764 constituent.''
3766   For example, one built-in Fortran abbrev is @samp{;c} for
3767 @samp{continue}.  If you insert @samp{;c} and then insert a punctuation
3768 character such as a space or a newline, the @samp{;c} expands automatically
3769 to @samp{continue}, provided Abbrev mode is enabled.@refill
3771   Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
3772 Fortran abbrevs and what they stand for.
3774 @node Fortran Misc
3775 @subsection Other Fortran Mode Commands
3777 The command @kbd{fortran-strip-sqeuence-nos} can be used to remove text
3778 past Fortran column 72, which is typically old `sequence numbers'.
3780 @node Asm Mode
3781 @section Asm Mode
3783 @cindex Asm mode
3784 @cindex Assembler mode
3785 Asm mode is a major mode for editing files of assembler code.  It
3786 defines these commands:
3788 @table @kbd
3789 @item @key{TAB}
3790 @code{tab-to-tab-stop}.
3791 @item C-j
3792 Insert a newline and then indent using @code{tab-to-tab-stop}.
3793 @item :
3794 Insert a colon and then remove the indentation from before the label
3795 preceding colon.  Then do @code{tab-to-tab-stop}.
3796 @item ;
3797 Insert or align a comment.
3798 @end table
3800   The variable @code{asm-comment-char} specifies which character
3801 starts comments in assembler syntax.