update.
[chise/xemacs-chise.git.1] / man / xemacs / programs.texi
1
2 @node Programs, Running, Text, Top
3 @chapter Editing Programs
4 @cindex Programming Languages
5 @cindex Lisp
6
7   XEmacs provides specialized support for editing source files for many
8 different programming languages. For example it is possible to 
9
10 @itemize @bullet
11 @item
12 Follow the usual indentation conventions of the language
13 (@pxref{Grinding}).
14 @item
15 Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
16 @item
17 Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
18 functions, in C).
19 @item
20 Show how parentheses balance (@pxref{Matching}).
21 @item
22 Insert, kill, or align comments (@pxref{Comments}).
23 @item
24 Find functions and symbols in program by name (@pxref{Tags}).
25 @end itemize
26
27   The commands available for words, sentences, and paragraphs are useful in
28 editing code even though their canonical application is for editing human
29 language text.  Most symbols contain words (@pxref{Words}); sentences can
30 be found in strings and comments (@pxref{Sentences}).  Paragraphs per se
31 are not present in code, but the paragraph commands are useful anyway,
32 because Lisp mode and C mode define paragraphs to begin and end at blank
33 lines (@pxref{Paragraphs}).  Judicious use of blank lines to make the
34 program clearer also provides interesting chunks of text for the
35 paragraph commands to work on.
36
37   The selective display feature is useful for looking at the overall
38 structure of a function (@pxref{Selective Display}).  This feature causes
39 only the lines that are indented less than a specified amount to appear
40 on the screen.
41
42 @menu
43 * Program Modes::       Major modes for editing programs.
44 * Lists::               Expressions with balanced parentheses.
45                          There are editing commands to operate on them.
46 * Defuns::              Each program is made up of separate functions.
47                          There are editing commands to operate on them.
48 * Grinding::            Adjusting indentation to show the nesting.
49 * Matching::            Insertion of a close-delimiter flashes matching open.
50 * Comments::            Inserting, filling and aligning comments.
51 * Balanced Editing::    Inserting two matching parentheses at once, etc.
52 * Lisp Completion::     Completion on symbol names in Lisp code.
53 * Documentation::       Getting documentation of functions you plan to call.
54 * Change Log::          Maintaining a change history for your program.
55 * Tags::                Go direct to any function in your program in one
56                          command.  Tags remembers which file it is in.
57 * CC Mode::             Modes for C, C++, Java and similar languages
58 * Fortran::             Fortran mode and its special features.
59 * Asm Mode::            Asm mode and its special features.
60 @end menu
61
62 @node Program Modes, Lists, Programs, Programs
63 @section Major Modes for Programming Languages
64
65 @cindex Lisp mode
66   Emacs has several major modes (@pxref{Major Modes}) to support
67 programming languages. These major modes will typically understand
68 language syntax, provide automatic indentation features, syntax based
69 highlighting of text, and will often provide interfaces to the
70 programming environment to assist in compiling, executing and debugging
71 programs.
72
73   A language mode exist when someone decides to take the trouble to
74 write it. At this time many widely used programming languages are
75 supported by XEmacs. Examples include Ada, Awk, C, C++, CORBA (IDL),
76 Fortran, Java, Lisp, Modula 2, Objective-C, Perl, Pike, Prolog, Python,
77 Ruby, Scheme, Simula, SQL, Tcl, Unix Shell scripts, and VHDL. Some of
78 these language have seperate manuals, and some times more than one mode
79 may be available for a language.  For example, there are several
80 variants of Lisp mode, which differ in the way they interface to Lisp
81 execution.  @xref{Lisp Modes}. 
82
83   Major modes for programming language support are distributed in
84 optional XEmacs packages (@pxref{Packages}) that must be installed
85 before use. A notable exception to this rule is that a Lisp Mode is
86 integral to XEmacs. The Programming Mode Package (@file{prog-modes})
87 contains many such modes. Some languages are supported by packages of
88 their own; prominent examples of such packages include @file{cc-mode}
89 for C, C++, Java, Objective C etc.@:, @file{python-modes} for Python,
90 and @file{scheme} for Scheme.
91
92   For a language named @var{lang} the major mode for the language will
93 typically be named @code{@var{lang}-mode}.  For example, the mode for C
94 is called @code{c-mode}, that for Bourne shell scripts is called
95 @code{sh-mode} and so on.  These modes will invoke the functions listed
96 in the corresponding hook variables as a last step. @xref{Mode Hooks}.
97
98   A mode can be invoked by typing @kbd{M-x @var{lang}-mode
99 @key{RET}}. However this step is not normally required. If the package
100 for a language mode is installed XEmacs usually knows when to
101 automatically invoke the mode. This is normally done based on examining
102 the file name to determine the language. @ref{Choosing Modes}.
103
104   Each of the programming language modes defines the @key{TAB} key to
105 run an indentation function that knows the indentation conventions of
106 that language and updates the current line's indentation accordingly.
107 @key{LFD} is normally defined to do @key{RET} followed by @key{TAB};
108 thus it, too, indents in a mode-specific fashion.
109
110 @kindex DEL
111 @findex backward-delete-char-untabify
112   In most programming languages, indentation is likely to vary from line to
113 line.  So the major modes for those languages rebind @key{DEL} to treat a
114 tab as if it were the equivalent number of spaces (using the command
115 @code{backward-delete-char-untabify}).  This makes it possible to rub out
116 indentation one column at a time without worrying whether it is made up of
117 spaces or tabs.  In these modes, use @kbd{C-b C-d} to delete a tab
118 character before point. 
119
120   Programming language modes define paragraphs to be separated only by
121 blank lines, so that the paragraph commands remain useful.  Auto Fill mode,
122 if enabled in a programming language major mode, indents the new lines
123 which it creates.
124
125 @node Lists, Defuns, Program Modes, Programs
126 @section Lists and Sexps
127
128 @cindex Control-Meta
129   By convention, Emacs keys for dealing with balanced expressions are
130 usually @kbd{Control-Meta-} characters.  They tend to be analogous in
131 function to their @kbd{Control-} and @kbd{Meta-} equivalents.  These commands
132 are usually thought of as pertaining to expressions in programming
133 languages, but can be useful with any language in which some sort of
134 parentheses exist (including English).
135
136 @cindex list
137 @cindex sexp
138 @cindex expression
139   The commands fall into two classes.  Some commands deal only with
140 @dfn{lists} (parenthetical groupings).  They see nothing except
141 parentheses, brackets, braces (depending on what must balance in the
142 language you are working with), and escape characters that might be used
143 to quote those.
144
145   The other commands deal with expressions or @dfn{sexps}.  The word `sexp'
146 is derived from @dfn{s-expression}, the term for a symbolic expression in
147 Lisp.  In Emacs, the notion of `sexp' is not limited to Lisp.  It
148 refers to an expression in the language  your program is written in.
149 Each programming language has its own major mode, which customizes the
150 syntax tables so that expressions in that language count as sexps.
151
152   Sexps typically include symbols, numbers, and string constants, as well
153 as anything contained in parentheses, brackets, or braces.
154
155   In languages that use prefix and infix operators, such as C, it is not
156 possible for all expressions to be sexps.  For example, C mode does not
157 recognize @samp{foo + bar} as an sexp, even though it @i{is} a C expression;
158 it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
159 @samp{+} as punctuation between them.  This is a fundamental ambiguity:
160 both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
161 move over if point is at the @samp{f}.  Note that @samp{(foo + bar)} is a
162 sexp in C mode.
163
164   Some languages have obscure forms of syntax for expressions that nobody
165 has bothered to make Emacs understand properly.
166
167 @c doublewidecommands
168 @table @kbd
169 @item C-M-f
170 Move forward over an sexp (@code{forward-sexp}).
171 @item C-M-b
172 Move backward over an sexp (@code{backward-sexp}).
173 @item C-M-k
174 Kill sexp forward (@code{kill-sexp}).
175 @item C-M-u
176 Move up and backward in list structure (@code{backward-up-list}).
177 @item C-M-d
178 Move down and forward in list structure (@code{down-list}).
179 @item C-M-n
180 Move forward over a list (@code{forward-list}).
181 @item C-M-p
182 Move backward over a list (@code{backward-list}).
183 @item C-M-t
184 Transpose expressions (@code{transpose-sexps}).
185 @item C-M-@@
186 Put mark after following expression (@code{mark-sexp}).
187 @end table
188
189 @kindex C-M-f
190 @kindex C-M-b
191 @findex forward-sexp
192 @findex backward-sexp
193   To move forward over an sexp, use @kbd{C-M-f} (@code{forward-sexp}).  If
194 the first significant character after point is an opening delimiter
195 (@samp{(} in Lisp; @samp{(}, @samp{[}, or @samp{@{} in C), @kbd{C-M-f}
196 moves past the matching closing delimiter.  If the character begins a
197 symbol, string, or number, @kbd{C-M-f} moves over that.  If the character
198 after point is a closing delimiter, @kbd{C-M-f} just moves past it.  (This
199 last is not really moving across an sexp; it is an exception which is
200 included in the definition of @kbd{C-M-f} because it is as useful a
201 behavior as anyone can think of for that situation.)@refill
202
203   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
204 sexp.  The detailed rules are like those above for @kbd{C-M-f}, but with
205 directions reversed.  If there are any prefix characters (single quote,
206 back quote, and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
207 over them as well.
208
209   @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
210 specified number of times; with a negative argument, it moves in the
211 opposite direction.
212
213 @kindex C-M-k
214 @findex kill-sexp
215   Killing an sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
216 @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
217
218 @kindex C-M-n
219 @kindex C-M-p
220 @findex forward-list
221 @findex backward-list
222   The @dfn{list commands}, @kbd{C-M-n} (@code{forward-list}) and
223 @kbd{C-M-p} (@code{backward-list}), move over lists like the sexp
224 commands but skip over any number of other kinds of sexps (symbols,
225 strings, etc).  In some situations, these commands are useful because
226 they usually ignore comments, since the comments usually do not contain
227 any lists.@refill
228
229 @kindex C-M-u
230 @kindex C-M-d
231 @findex backward-up-list
232 @findex down-list
233   @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
234 that is possible.  To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
235 (@code{backward-up-list}).
236 @kbd{C-M-u} moves backward up past one unmatched opening delimiter.  A
237 positive argument serves as a repeat count; a negative argument reverses
238 direction of motion and also requests repetition, so it moves forward and
239 up one or more levels.@refill
240
241   To move @i{down} in list structure, use @kbd{C-M-d}
242 (@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
243 delimiter, this is nearly the same as searching for a @samp{(}.  An
244 argument specifies the number of levels of parentheses to go down.
245
246 @cindex transposition
247 @kindex C-M-t
248 @findex transpose-sexps
249 @kbd{C-M-t} (@code{transpose-sexps}) drags the previous sexp across
250 the next one.  An argument serves as a repeat count, and a negative
251 argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
252 a positive argument).  An argument of zero, rather than doing nothing,
253 transposes the sexps ending after point and the mark.
254
255 @kindex C-M-@@
256 @findex mark-sexp
257   To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
258 (@code{mark-sexp}) which sets the mark at the same place that
259 @kbd{C-M-f} would move to.  @kbd{C-M-@@} takes arguments like
260 @kbd{C-M-f}.  In particular, a negative argument is useful for putting
261 the mark at the beginning of the previous sexp.
262
263   The list and sexp commands' understanding of syntax is completely
264 controlled by the syntax table.  Any character can, for example, be
265 declared to be an opening delimiter and act like an open parenthesis.
266 @xref{Syntax}.
267
268 @node Defuns, Grinding, Lists, Programs
269 @section Defuns
270 @cindex defuns
271
272   In Emacs, a parenthetical grouping at the top level in the buffer is
273 called a @dfn{defun}.  The name derives from the fact that most
274 top-level lists in Lisp are instances of the special form
275 @code{defun}, but Emacs calls any top-level parenthetical
276 grouping counts a defun regardless of its contents or
277 the programming language.  For example, in C, the body of a
278 function definition is a defun.
279
280 @c doublewidecommands
281 @table @kbd
282 @item C-M-a
283 Move to beginning of current or preceding defun
284 (@code{beginning-of-defun}).
285 @item C-M-e
286 Move to end of current or following defun (@code{end-of-defun}).
287 @item C-M-h
288 Put region around whole current or following defun (@code{mark-defun}).
289 @end table
290
291 @kindex C-M-a
292 @kindex C-M-e
293 @kindex C-M-h
294 @findex beginning-of-defun
295 @findex end-of-defun
296 @findex mark-defun
297   The commands to move to the beginning and end of the current defun are
298 @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
299
300    To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
301 which puts point at the beginning and the mark at the end of the current
302 or next defun.  This is the easiest way to prepare for moving the defun
303 to a different place.  In C mode, @kbd{C-M-h} runs the function
304 @code{mark-c-function}, which is almost the same as @code{mark-defun},
305 but which backs up over the argument declarations, function name, and
306 returned data type so that the entire C function is inside the region.
307
308 @findex compile-defun
309 To compile and evaluate the current defun, use @kbd{M-x compile-defun}. 
310 This function prints the results in the minibuffer. If you include an 
311 argument, it inserts the value in the current buffer after the defun.
312
313   Emacs assumes that any open-parenthesis found in the leftmost column is
314 the start of a defun.  Therefore, @i{never put an open-parenthesis at the
315 left margin in a Lisp file unless it is the start of a top level list.
316 Never put an open-brace or other opening delimiter at the beginning of a
317 line of C code unless it starts the body of a function.}  The most likely
318 problem case is when you want an opening delimiter at the start of a line
319 inside a string.  To avoid trouble, put an escape character (@samp{\} in C
320 and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
321 delimiter.  It will not affect the contents of the string.
322
323   The original Emacs found defuns by moving upward a
324 level of parentheses until there were no more levels to go up.  This
325 required scanning back to the beginning of the buffer for every
326 function.  To speed this up, Emacs was changed to assume
327 that any @samp{(} (or other character assigned the syntactic class of
328 opening-delimiter) at the left margin is the start of a defun.  This
329 heuristic is nearly always right; however, it mandates the convention 
330 described above.
331
332 @node Grinding, Matching, Defuns, Programs
333 @section Indentation for Programs
334 @cindex indentation
335 @cindex grinding
336
337   The best way to keep a program properly indented (``ground'') is to
338 use Emacs to re-indent it as you change the program.  Emacs has commands
339 to indent properly either a single line, a specified number of lines, or
340 all of the lines inside a single parenthetical grouping.
341
342 @menu
343 * Basic Indent::
344 * Multi-line Indent::   Commands to reindent many lines at once.
345 * Lisp Indent::         Specifying how each Lisp function should be indented.
346 @end menu
347
348 @node Basic Indent, Multi-line Indent, Grinding, Grinding
349 @subsection Basic Program Indentation Commands
350
351 @c WideCommands
352 @table @kbd
353 @item @key{TAB}
354 Adjust indentation of current line.
355 @item @key{LFD}
356 Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
357 @end table
358
359 @kindex TAB
360 @findex c-indent-line
361 @findex lisp-indent-line
362   The basic indentation command is @key{TAB}, which gives the current
363 line the correct indentation as determined from the previous lines.  The
364 function that @key{TAB} runs depends on the major mode; it is
365 @code{lisp-indent-line} in Lisp mode, @code{c-indent-line} in C mode,
366 etc.  These functions understand different syntaxes for different
367 languages, but they all do about the same thing.  @key{TAB} in any
368 programming language major mode inserts or deletes whitespace at the
369 beginning of the current line, independent of where point is in the
370 line.  If point is inside the whitespace at the beginning of the line,
371 @key{TAB} leaves it at the end of that whitespace; otherwise, @key{TAB}
372 leaves point fixed with respect to the characters around it.
373
374   Use @kbd{C-q @key{TAB}} to insert a tab at point.
375
376 @kindex LFD
377 @findex newline-and-indent
378   When entering a large amount of new code, use @key{LFD}
379 (@code{newline-and-indent}), which is equivalent to a @key{RET} followed
380 by a @key{TAB}.  @key{LFD} creates a blank line, then gives it the
381 appropriate indentation.
382
383   @key{TAB} indents the second and following lines of the body of a
384 parenthetical grouping each under the preceding one; therefore, if you
385 alter one line's indentation to be nonstandard, the lines below tend
386 to follow it.  This is the right behavior in cases where the standard
387 result of @key{TAB} does not look good.
388
389   Remember that Emacs assumes that an open-parenthesis, open-brace, or
390 other opening delimiter at the left margin (including the indentation
391 routines) is the start of a function.  You should therefore never have
392 an opening delimiter in column zero that is not the beginning of a
393 function, not even inside a string.  This restriction is vital for
394 making the indentation commands fast. @xref{Defuns}, for more
395 information on this behavior.
396
397 @node Multi-line Indent, Lisp Indent, Basic Indent, Grinding
398 @subsection Indenting Several Lines
399
400   Several commands are available to re-indent several lines of code
401 which have been altered or moved to a different level in a list
402 structure.
403
404
405 @table @kbd
406 @item C-M-q
407 Re-indent all the lines within one list (@code{indent-sexp}).
408 @item C-u @key{TAB}
409 Shift an entire list rigidly sideways so that its first line
410 is properly indented.
411 @item C-M-\
412 Re-indent all lines in the region (@code{indent-region}).
413 @end table
414
415 @kindex C-M-q
416 @findex indent-sexp
417 @findex indent-c-exp
418  To re-indent the contents of a single list, position point before the
419 beginning of it and type @kbd{C-M-q}. This key is bound to
420 @code{indent-sexp} in Lisp mode, @code{indent-c-exp} in C mode, and
421 bound to other suitable functions in other modes.  The indentation of
422 the line the sexp starts on is not changed; therefore, only the relative
423 indentation within the list, and not its position, is changed.  To
424 correct the position as well, type a @key{TAB} before @kbd{C-M-q}.
425
426 @kindex C-u TAB
427   If the relative indentation within a list is correct but the
428 indentation of its beginning is not, go to the line on which the list
429 begins and type @kbd{C-u @key{TAB}}.  When you give @key{TAB} a numeric
430 argument, it moves all the lines in the group, starting on the current
431 line, sideways the same amount that the current line moves.  The command
432 does not move lines that start inside strings, or C
433 preprocessor lines when in C mode.
434
435 @kindex C-M-\
436 @findex indent-region
437   Another way to specify a range to be re-indented is with point and
438 mark.  The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB}
439 to every line whose first character is between point and mark.
440
441 @node Lisp Indent,  , Multi-line Indent, Grinding
442 @subsection Customizing Lisp Indentation
443 @cindex customization
444
445   The indentation pattern for a Lisp expression can depend on the function
446 called by the expression.  For each Lisp function, you can choose among
447 several predefined patterns of indentation, or define an arbitrary one with
448 a Lisp program.
449
450   The standard pattern of indentation is as follows: the second line of the
451 expression is indented under the first argument, if that is on the same
452 line as the beginning of the expression; otherwise, the second line is
453 indented underneath the function name.  Each following line is indented
454 under the previous line whose nesting depth is the same.
455
456 @vindex lisp-indent-offset
457   If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
458 the usual indentation pattern for the second line of an expression, so that
459 such lines are always indented @code{lisp-indent-offset} more columns than
460 the containing list.
461
462 @vindex lisp-body-indention
463   Certain functions override the standard pattern.  Functions
464 whose names start with @code{def} always indent the second line by
465 @code{lisp-body-indention} extra columns beyond the open-parenthesis
466 starting the expression.
467
468   Individual functions can override the standard pattern in various
469 ways, according to the @code{lisp-indent-function} property of the
470 function name.  (Note: @code{lisp-indent-function} was formerly called
471 @code{lisp-indent-hook}).  There are four possibilities for this
472 property:
473
474 @table @asis
475 @item @code{nil}
476 This is the same as no property; the standard indentation pattern is used.
477 @item @code{defun}
478 The pattern used for function names that start with @code{def} is used for
479 this function also.
480 @item a number, @var{number}
481 The first @var{number} arguments of the function are
482 @dfn{distinguished} arguments; the rest are considered the @dfn{body}
483 of the expression.  A line in the expression is indented according to
484 whether the first argument on it is distinguished or not.  If the
485 argument is part of the body, the line is indented @code{lisp-body-indent}
486 more columns than the open-parenthesis starting the containing
487 expression.  If the argument is distinguished and is either the first
488 or second argument, it is indented @i{twice} that many extra columns.
489 If the argument is distinguished and not the first or second argument,
490 the standard pattern is followed for that line.
491 @item a symbol, @var{symbol}
492 @var{symbol} should be a function name; that function is called to
493 calculate the indentation of a line within this expression.  The
494 function receives two arguments:
495 @table @asis
496 @item @var{state}
497 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
498 indentation and nesting computation) when it parses up to the
499 beginning of this line.
500 @item @var{pos}
501 The position at which the line being indented begins.
502 @end table
503 @noindent
504 It should return either a number, which is the number of columns of
505 indentation for that line, or a list whose first element is such a
506 number.  The difference between returning a number and returning a list
507 is that a number says that all following lines at the same nesting level
508 should be indented just like this one; a list says that following lines
509 might call for different indentations.  This makes a difference when the
510 indentation is computed by @kbd{C-M-q}; if the value is a number,
511 @kbd{C-M-q} need not recalculate indentation for the following lines
512 until the end of the list.
513 @end table
514
515
516 @node Matching, Comments, Grinding, Programs
517 @section Automatic Display of Matching Parentheses
518 @cindex matching parentheses
519 @cindex parentheses
520
521   The Emacs parenthesis-matching feature shows you automatically how
522 parentheses match in the text.  Whenever a self-inserting character that
523 is a closing delimiter is typed, the cursor moves momentarily to the
524 location of the matching opening delimiter, provided that is visible on
525 the screen.  If it is not on the screen, some text starting with that
526 opening delimiter is displayed in the echo area.  Either way, you see
527 the grouping you are closing off. 
528
529   In Lisp, automatic matching applies only to parentheses.  In C, it
530 also applies to braces and brackets.  Emacs knows which characters to regard
531 as matching delimiters based on the syntax table set by the major
532 mode.  @xref{Syntax}.
533
534   If the opening delimiter and closing delimiter are mismatched---as
535 in @samp{[x)}---the echo area displays a warning message.  The
536 correct matches are specified in the syntax table.
537
538 @vindex blink-matching-paren
539 @vindex blink-matching-paren-distance
540   Two variables control parenthesis matching displays.
541 @code{blink-matching-paren} turns the feature on or off. The default is 
542 @code{t} (match display is on); @code{nil} turns it off.
543 @code{blink-matching-paren-distance} specifies how many characters back
544 Emacs searches to find a matching opening delimiter.  If the match is
545 not found in the specified region, scanning stops, and nothing is
546 displayed.  This prevents wasting lots of time scanning when there is no
547 match.  The default is 4000.
548
549 @node Comments, Balanced Editing, Matching, Programs
550 @section Manipulating Comments
551 @cindex comments
552 @kindex M-;
553 @cindex indentation
554 @findex indent-for-comment
555
556   The comment commands insert, kill and align comments.
557
558 @c WideCommands
559 @table @kbd
560 @item M-;
561 Insert or align comment (@code{indent-for-comment}).
562 @item C-x ;
563 Set comment column (@code{set-comment-column}).
564 @item C-u - C-x ;
565 Kill comment on current line (@code{kill-comment}).
566 @item M-@key{LFD}
567 Like @key{RET} followed by inserting and aligning a comment
568 (@code{indent-new-comment-line}).
569 @end table
570
571   The command that creates a comment is @kbd{Meta-;}
572 (@code{indent-for-comment}).  If there is no comment already on the
573 line, a new comment is created and aligned at a specific column called
574 the @dfn{comment column}.  Emacs creates the comment by inserting the
575 string at the value of @code{comment-start}; see below.  Point is left
576 after that string.  If the text of the line extends past the comment
577 column, indentation is done to a suitable boundary (usually, at least
578 one space is inserted).  If the major mode has specified a string to
579 terminate comments, that string is inserted after point, to keep the
580 syntax valid.
581
582   You can also use @kbd{Meta-;} to align an existing comment.  If a line
583 already contains the string that starts comments, @kbd{M-;} just moves
584 point after it and re-indents it to the conventional place.  Exception:
585 comments starting in column 0 are not moved.
586
587   Some major modes have special rules for indenting certain kinds of
588 comments in certain contexts.  For example, in Lisp code, comments which
589 start with two semicolons are indented as if they were lines of code,
590 instead of at the comment column.  Comments which start with three
591 semicolons are supposed to start at the left margin.  Emacs understands
592 these conventions by indenting a double-semicolon comment using @key{TAB}
593 and by not changing the indentation of a triple-semicolon comment at all.
594
595 @example
596 ;; This function is just an example.
597 ;;; Here either two or three semicolons are appropriate.
598 (defun foo (x)
599 ;;; And now, the first part of the function:
600   ;; The following line adds one.
601   (1+ x))           ; This line adds one.
602 @end example
603
604   In C code, a comment preceded on its line by nothing but whitespace
605 is indented like a line of code.
606
607   Even when an existing comment is properly aligned, @kbd{M-;} is still
608 useful for moving directly to the start of the comment.
609
610 @kindex C-u - C-x ;
611 @findex kill-comment
612   @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the
613 current line, if there is one.  The indentation before the start of the
614 comment is killed as well.  If there does not appear to be a comment in
615 the line, nothing happens.  To reinsert the comment on another line,
616 move to the end of that line, type first @kbd{C-y}, and then @kbd{M-;}
617 to realign the comment.  Note that @kbd{C-u - C-x ;} is not a distinct
618 key; it is @kbd{C-x ;} (@code{set-comment-column}) with a negative
619 argument.  That command is programmed to call @code{kill-comment} when
620 called with a negative argument.  However, @code{kill-comment} is a
621 valid command which you could bind directly to a key if you wanted to.
622
623 @subsection Multiple Lines of Comments
624
625 @kindex M-LFD
626 @cindex blank lines
627 @cindex Auto Fill mode
628 @findex indent-new-comment-line
629   If you are typing a comment and want to continue it on another line,
630 use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
631 which terminates the comment you are typing, creates a new blank line
632 afterward, and begins a new comment indented under the old one.  If
633 Auto Fill mode is on and you go past the fill column while typing, the 
634 comment is continued in just this fashion.  If point is
635 not at the end of the line when you type @kbd{M-@key{LFD}}, the text on
636 the rest of the line becomes part of the new comment line.
637
638 @subsection Options Controlling Comments
639
640 @vindex comment-column
641 @kindex C-x ;
642 @findex set-comment-column
643   The comment column is stored in the variable @code{comment-column}.  You
644 can explicitly set it to a number.  Alternatively, the command @kbd{C-x ;}
645 (@code{set-comment-column}) sets the comment column to the column point is
646 at.  @kbd{C-u C-x ;} sets the comment column to match the last comment
647 before point in the buffer, and then calls @kbd{Meta-;} to align the
648 current line's comment under the previous one.  Note that @kbd{C-u - C-x ;}
649 runs the function @code{kill-comment} as described above.
650
651   @code{comment-column} is a per-buffer variable; altering the variable
652 affects only the current buffer.  You can also change the default value.
653 @xref{Locals}.  Many major modes initialize this variable
654 for the current buffer.
655
656 @vindex comment-start-skip
657   The comment commands recognize comments based on the regular expression
658 that is the value of the variable @code{comment-start-skip}.  This regexp
659 should not match the null string.  It may match more than the comment
660 starting delimiter in the strictest sense of the word; for example, in C
661 mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
662 stars and spaces after the @samp{/*} itself.  (Note that @samp{\\} is
663 needed in Lisp syntax to include a @samp{\} in the string, which is needed
664 to deny the first star its special meaning in regexp syntax.  @xref{Regexps}.)
665
666 @vindex comment-start
667 @vindex comment-end
668   When a comment command makes a new comment, it inserts the value of
669 @code{comment-start} to begin it.  The value of @code{comment-end} is
670 inserted after point and will follow the text you will insert
671 into the comment.  In C mode, @code{comment-start} has the value
672 @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
673
674 @vindex comment-multi-line
675   @code{comment-multi-line} controls how @kbd{M-@key{LFD}}
676 (@code{indent-new-comment-line}) behaves when used inside a comment.  If
677 @code{comment-multi-line} is @code{nil}, as it normally is, then
678 @kbd{M-@key{LFD}} terminates the comment on the starting line and starts
679 a new comment on the new following line.  If @code{comment-multi-line}
680 is not @code{nil}, then @kbd{M-@key{LFD}} sets up the new following line
681 as part of the same comment that was found on the starting line.  This
682 is done by not inserting a terminator on the old line and not inserting
683 a starter on the new line.  In languages where multi-line comments are legal,
684 the value you choose for this variable is a matter of taste.
685
686 @vindex comment-indent-hook
687   The variable @code{comment-indent-hook} should contain a function that
688 is called to compute the indentation for a newly inserted comment or for
689 aligning an existing comment.  Major modes set this variable differently.
690 The function is called with no arguments, but with point at the
691 beginning of the comment, or at the end of a line if a new comment is to
692 be inserted.  The function should return the column in which the comment
693 ought to start.  For example, in Lisp mode, the indent hook function
694 bases its decision on the number of semicolons that begin an existing
695 comment and on the code in the preceding lines.
696
697 @node Balanced Editing, Lisp Completion, Comments, Programs
698 @section Editing Without Unbalanced Parentheses
699
700 @table @kbd
701 @item M-(
702 Put parentheses around next sexp(s) (@code{insert-parentheses}).
703 @item M-)
704 Move past next close parenthesis and re-indent
705 (@code{move-over-close-and-reindent}).
706 @end table
707
708 @kindex M-(
709 @kindex M-)
710 @findex insert-parentheses
711 @findex move-over-close-and-reindent
712   The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
713 (@code{move-over-close-and-reindent}) are designed to facilitate a style of
714 editing which keeps parentheses balanced at all times.  @kbd{M-(} inserts a
715 pair of parentheses, either together as in @samp{()}, or, if given an
716 argument, around the next several sexps, and leaves point after the open
717 parenthesis.  Instead of typing @kbd{( F O O )}, you can type @kbd{M-( F O
718 O}, which has the same effect except for leaving the cursor before the
719 close parenthesis.  You can then type @kbd{M-)}, which moves past the
720 close parenthesis, deletes any indentation preceding it (in this example
721 there is none), and indents with @key{LFD} after it.
722
723 @node Lisp Completion, Documentation, Balanced Editing, Programs
724 @section Completion for Lisp Symbols
725 @cindex completion (symbol names)
726
727    Completion usually happens in the minibuffer.  An exception is
728 completion for Lisp symbol names, which is available in all buffers.
729
730 @kindex M-TAB
731 @findex lisp-complete-symbol
732   The command @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) takes the
733 partial Lisp symbol before point to be an abbreviation, and compares it
734 against all non-trivial Lisp symbols currently known to Emacs.  Any
735 additional characters that they all have in common are inserted at point.
736 Non-trivial symbols are those that have function definitions, values, or
737 properties.
738
739   If there is an open-parenthesis immediately before the beginning of
740 the partial symbol, only symbols with function definitions are considered
741 as completions.
742
743   If the partial name in the buffer has more than one possible completion
744 and they have no additional characters in common, a list of all possible
745 completions is displayed in another window.
746
747 @node Documentation, Change Log, Lisp Completion, Programs
748 @section Documentation Commands
749
750 @kindex C-h f
751 @findex describe-function
752 @kindex C-h v
753 @findex describe-variable
754   As you edit Lisp code to be run in Emacs, you can use the commands
755 @kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
756 (@code{describe-variable}) to print documentation of functions and
757 variables you want to call.  These commands use the minibuffer to
758 read the name of a function or variable to document, and display the
759 documentation in a window.
760
761   For extra convenience, these commands provide default arguments based on
762 the code in the neighborhood of point.  @kbd{C-h f} sets the default to the
763 function called in the innermost list containing point.  @kbd{C-h v} uses
764 the symbol name around or adjacent to point as its default.
765
766 @findex manual-entry
767   The @kbd{M-x manual-entry} command gives you access to documentation
768 on Unix commands, system calls, and libraries.  The command reads a
769 topic as an argument, and displays the Unix manual page for that topic. 
770 @code{manual-entry} always searches all 8 sections of the
771 manual and concatenates all the entries it finds.  For example,
772 the topic @samp{termcap} finds the description of the termcap library
773 from section 3, followed by the description of the termcap data base
774 from section 5.
775
776 @node Change Log, Tags, Documentation, Programs
777 @section Change Logs
778
779 @cindex change log
780 @findex add-change-log-entry
781   The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
782 of when and why you have changed a program.  It assumes that you have a
783 file in which you write a chronological sequence of entries describing
784 individual changes.  The default is to store the change entries in a file
785 called @file{ChangeLog} in the same directory as the file you are editing.
786 The same @file{ChangeLog} file therefore records changes for all the files
787 in a directory.
788
789   A change log entry starts with a header line that contains your name
790 and the current date.  Except for these header lines, every line in the
791 change log starts with a tab.  One entry can describe several changes;
792 each change starts with a line starting with a tab and a star.  @kbd{M-x
793 add-change-log-entry} visits the change log file and creates a new entry
794 unless the most recent entry is for today's date and your name.  In
795 either case, it adds a new line to start the description of another
796 change just after the header line of the entry.  When @kbd{M-x
797 add-change-log-entry} is finished, all is prepared for you to edit in
798 the description of what you changed and how.  You must then save the
799 change log file yourself.
800
801   The change log file is always visited in Indented Text mode, which means
802 that @key{LFD} and auto-filling indent each new line like the previous
803 line.  This is convenient for entering the contents of an entry, which must
804 be indented.  @xref{Text Mode}.
805
806   Here is an example of the formatting conventions used in the change log
807 for Emacs:
808
809 @smallexample
810 Wed Jun 26 19:29:32 1985  Richard M. Stallman  (rms at mit-prep)
811
812         * xdisp.c (try_window_id):
813         If C-k is done at end of next-to-last line,
814         this fn updates window_end_vpos and cannot leave
815         window_end_pos nonnegative (it is zero, in fact).
816         If display is preempted before lines are output,
817         this is inconsistent.  Fix by setting
818         blank_end_of_window to nonzero.
819
820 Tue Jun 25 05:25:33 1985  Richard M. Stallman  (rms at mit-prep)
821
822         * cmds.c (Fnewline):
823         Call the auto fill hook if appropriate.
824
825         * xdisp.c (try_window_id):
826         If point is found by compute_motion after xp, record that
827         permanently.  If display_text_line sets point position wrong
828         (case where line is killed, point is at eob and that line is
829         not displayed), set it again in final compute_motion.
830 @end smallexample
831
832 @node Tags, CC Mode, Change Log, Programs
833 @section Tags Tables
834 @cindex tags table
835
836   A @dfn{tags table} is a description of how a multi-file program is
837 broken up into files.  It lists the names of the component files and the
838 names and positions of the functions (or other named subunits) in each
839 file.  Grouping the related files makes it possible to search or replace
840 through all the files with one command.  Recording the function names
841 and positions makes possible the @kbd{M-.} command which finds the
842 definition of a function by looking up which of the files it is in.
843
844   Tags tables are stored in files called @dfn{tags table files}.  The
845 conventional name for a tags table file is @file{TAGS}.
846
847   Each entry in the tags table records the name of one tag, the name of the
848 file that the tag is defined in (implicitly), and the position in that file
849 of the tag's definition.
850
851   Just what names from the described files are recorded in the tags table
852 depends on the programming language of the described file.  They
853 normally include all functions and subroutines, and may also include
854 global variables, data types, and anything else convenient.  Each name
855 recorded is called a @dfn{tag}.
856
857 @cindex C++ class browser, tags
858 @cindex tags, C++
859 @cindex class browser, C++
860 @cindex Ebrowse
861 The Ebrowse is a separate facility tailored for C++, with tags and a
862 class browser.  @xref{Top,,, ebrowse, Ebrowse User's Manual}.
863
864 @menu
865 * Tag Syntax::          Tag syntax for various types of code and text files.
866 * Create Tags Table::   Creating a tags table with @code{etags}.
867 * Etags Regexps::       Create arbitrary tags using regular expressions.
868 * Select Tags Table::   How to visit a tags table.
869 * Find Tag::            Commands to find the definition of a specific tag.
870 * Tags Search::         Using a tags table for searching and replacing.
871 * List Tags::           Listing and finding tags defined in a file.
872 @end menu
873
874 @node Tag Syntax
875 @subsection Source File Tag Syntax
876
877   Here is how tag syntax is defined for the most popular languages:
878
879 @itemize @bullet
880 @item
881 In C code, any C function or typedef is a tag, and so are definitions of
882 @code{struct}, @code{union} and @code{enum}.  You can tag function
883 declarations and external variables in addition to function definitions
884 by giving the @samp{--declarations} option to @code{etags}.
885 @code{#define} macro definitions and @code{enum} constants are also
886 tags, unless you specify @samp{--no-defines} when making the tags table.
887 Similarly, global variables are tags, unless you specify
888 @samp{--no-globals}.  Use of @samp{--no-globals} and @samp{--no-defines}
889 can make the tags table file much smaller.
890
891 @item
892 In C++ code, in addition to all the tag constructs of C code, member
893 functions are also recognized, and optionally member variables if you
894 use the @samp{--members} option.  Tags for variables and functions in
895 classes are named @samp{@var{class}::@var{variable}} and
896 @samp{@var{class}::@var{function}}.  @code{operator} functions tags are
897 named, for example @samp{operator+}.
898
899 @item
900 In Java code, tags include all the constructs recognized in C++, plus
901 the @code{interface}, @code{extends} and @code{implements} constructs.
902 Tags for variables and functions in classes are named
903 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
904
905 @item
906 In La@TeX{} text, the argument of any of the commands @code{\chapter},
907 @code{\section}, @code{\subsection}, @code{\subsubsection},
908 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
909 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
910 tag.@refill
911
912 Other commands can make tags as well, if you specify them in the
913 environment variable @code{TEXTAGS} before invoking @code{etags}.  The
914 value of this environment variable should be a colon-separated list of
915 command names.  For example,
916
917 @example
918 TEXTAGS="def:newcommand:newenvironment"
919 export TEXTAGS
920 @end example
921
922 @noindent
923 specifies (using Bourne shell syntax) that the commands @samp{\def},
924 @samp{\newcommand} and @samp{\newenvironment} also define tags.
925
926 @item
927 In Lisp code, any function defined with @code{defun}, any variable
928 defined with @code{defvar} or @code{defconst}, and in general the first
929 argument of any expression that starts with @samp{(def} in column zero, is
930 a tag.
931
932 @item
933 In Scheme code, tags include anything defined with @code{def} or with a
934 construct whose name starts with @samp{def}.  They also include variables
935 set with @code{set!} at top level in the file.
936 @end itemize
937
938   Several other languages are also supported:
939
940 @itemize @bullet
941
942 @item
943 In Ada code, functions, procedures, packages, tasks, and types are
944 tags.  Use the @samp{--packages-only} option to create tags for
945 packages only.
946
947 With Ada, it is possible to have the same name used for different
948 entity kinds (e.g.@: the same name for a procedure and a function).  Also,
949 for things like packages, procedures and functions, there is the spec
950 (i.e.@: the interface) and the body (i.e.@: the implementation).  To
951 facilitate the choice to the user, a tag value is appended with a
952 qualifier:
953
954 @table @asis
955 @item function
956  @kbd{/f}
957 @item procedure
958  @kbd{/p}
959 @item package spec
960  @kbd{/s}
961 @item package body
962  @kbd{/b}
963 @item type
964  @kbd{/t}
965 @item task
966  @kbd{/k}
967 @end table
968
969 So, as an example, @kbd{M-x find-tag bidule/b} will go directly to the
970 body of the package @var{bidule} while @kbd{M-x find-tag bidule} will
971 just search for any tag @var{bidule}.
972
973 @item
974 In assembler code, labels appearing at the beginning of a line,
975 followed by a colon, are tags.
976
977 @item
978 In Bison or Yacc input files, each rule defines as a tag the nonterminal
979 it constructs.  The portions of the file that contain C code are parsed
980 as C code.
981
982 @item
983 In Cobol code, tags are paragraph names; that is, any word starting in
984 column 8 and followed by a period.
985
986 @item
987 In Erlang code, the tags are the functions, records, and macros defined
988 in the file.
989
990 @item
991 In Fortran code, functions, subroutines and blockdata are tags.
992
993 @item
994 In makefiles, targets are tags.
995
996 @item
997 In Objective C code, tags include Objective C definitions for classes,
998 class categories, methods, and protocols.
999
1000 @item
1001 In Pascal code, the tags are the functions and procedures defined in
1002 the file.
1003
1004 @item
1005 In Perl code, the tags are the procedures defined by the @code{sub},
1006 @code{my} and @code{local} keywords.  Use @samp{--globals} if you want
1007 to tag global variables.
1008
1009 @item
1010 In PostScript code, the tags are the functions.
1011
1012 @item
1013 In Prolog code, a tag name appears at the left margin.
1014
1015 @item
1016 In Python code, @code{def} or @code{class} at the beginning of a line
1017 generate a tag.
1018 @end itemize
1019
1020   You can also generate tags based on regexp matching (@pxref{Etags
1021 Regexps}) to handle other formats and languages.
1022
1023 @node Create Tags Table
1024 @subsection Creating Tags Tables
1025 @cindex @code{etags} program
1026
1027   The @code{etags} program is used to create a tags table file.  It knows
1028 the syntax of several languages, as described in
1029 @iftex
1030 the previous section.
1031 @end iftex
1032 @ifinfo
1033 @ref{Tag Syntax}.
1034 @end ifinfo
1035 Here is how to run @code{etags}:
1036
1037 @example
1038 etags @var{inputfiles}@dots{}
1039 @end example
1040
1041 @noindent
1042 The @code{etags} program reads the specified files, and writes a tags
1043 table named @file{TAGS} in the current working directory.  You can
1044 intermix compressed and plain text source file names.  @code{etags}
1045 knows about the most common compression formats, and does the right
1046 thing.  So you can compress all your source files and have @code{etags}
1047 look for compressed versions of its file name arguments, if it does not
1048 find uncompressed versions.  Under MS-DOS, @code{etags} also looks for
1049 file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
1050 command line and @samp{mycode.c} does not exist.
1051
1052   @code{etags} recognizes the language used in an input file based on
1053 its file name and contents.  You can specify the language with the
1054 @samp{--language=@var{name}} option, described below.
1055
1056   If the tags table data become outdated due to changes in the files
1057 described in the table, the way to update the tags table is the same way it
1058 was made in the first place.  It is not necessary to do this often.
1059
1060   If the tags table fails to record a tag, or records it for the wrong
1061 file, then Emacs cannot possibly find its definition.  However, if the
1062 position recorded in the tags table becomes a little bit wrong (due to
1063 some editing in the file that the tag definition is in), the only
1064 consequence is a slight delay in finding the tag.  Even if the stored
1065 position is very wrong, Emacs will still find the tag, but it must
1066 search the entire file for it.
1067
1068   So you should update a tags table when you define new tags that you want
1069 to have listed, or when you move tag definitions from one file to another,
1070 or when changes become substantial.  Normally there is no need to update
1071 the tags table after each edit, or even every day.
1072
1073   One tags table can effectively include another.  Specify the included
1074 tags file name with the @samp{--include=@var{file}} option when creating
1075 the file that is to include it.  The latter file then acts as if it
1076 contained all the files specified in the included file, as well as the
1077 files it directly contains.
1078
1079   If you specify the source files with relative file names when you run
1080 @code{etags}, the tags file will contain file names relative to the
1081 directory where the tags file was initially written.  This way, you can
1082 move an entire directory tree containing both the tags file and the
1083 source files, and the tags file will still refer correctly to the source
1084 files.
1085
1086   If you specify absolute file names as arguments to @code{etags}, then
1087 the tags file will contain absolute file names.  This way, the tags file
1088 will still refer to the same files even if you move it, as long as the
1089 source files remain in the same place.  Absolute file names start with
1090 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1091
1092   When you want to make a tags table from a great number of files, you
1093 may have problems listing them on the command line, because some systems
1094 have a limit on its length.  The simplest way to circumvent this limit
1095 is to tell @code{etags} to read the file names from its standard input,
1096 by typing a dash in place of the file names, like this:
1097
1098 @smallexample
1099 find . -name "*.[chCH]" -print | etags -
1100 @end smallexample
1101
1102   Use the option @samp{--language=@var{name}} to specify the language
1103 explicitly.  You can intermix these options with file names; each one
1104 applies to the file names that follow it.  Specify
1105 @samp{--language=auto} to tell @code{etags} to resume guessing the
1106 language from the file names and file contents.  Specify
1107 @samp{--language=none} to turn off language-specific processing
1108 entirely; then @code{etags} recognizes tags by regexp matching alone
1109 (@pxref{Etags Regexps}).
1110
1111   @samp{etags --help} prints the list of the languages @code{etags}
1112 knows, and the file name rules for guessing the language. It also prints
1113 a list of all the available @code{etags} options, together with a short
1114 explanation.
1115
1116 @node Etags Regexps
1117 @subsection Etags Regexps
1118
1119   The @samp{--regex} option provides a general way of recognizing tags
1120 based on regexp matching.  You can freely intermix it with file names.
1121 Each @samp{--regex} option adds to the preceding ones, and applies only
1122 to the following files.  The syntax is:
1123
1124 @smallexample
1125 --regex=/@var{tagregexp}[/@var{nameregexp}]/
1126 @end smallexample
1127
1128 @noindent
1129 where @var{tagregexp} is used to match the lines to tag.  It is always
1130 anchored, that is, it behaves as if preceded by @samp{^}.  If you want
1131 to account for indentation, just match any initial number of blanks by
1132 beginning your regular expression with @samp{[ \t]*}.  In the regular
1133 expressions, @samp{\} quotes the next character, and @samp{\t} stands
1134 for the tab character.  Note that @code{etags} does not handle the other
1135 C escape sequences for special characters.
1136
1137 @cindex interval operator (in regexps)
1138   The syntax of regular expressions in @code{etags} is the same as in
1139 Emacs, augmented with the @dfn{interval operator}, which works as in
1140 @code{grep} and @code{ed}.  The syntax of an interval operator is
1141 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
1142 expression at least @var{m} times and up to @var{n} times.
1143
1144   You should not match more characters with @var{tagregexp} than that
1145 needed to recognize what you want to tag.  If the match is such that
1146 more characters than needed are unavoidably matched by @var{tagregexp}
1147 (as will usually be the case), you should add a @var{nameregexp}, to
1148 pick out just the tag.  This will enable Emacs to find tags more
1149 accurately and to do completion on tag names more reliably.  You can
1150 find some examples below.
1151
1152   The option @samp{--ignore-case-regex} (or @samp{-c}) is like
1153 @samp{--regex}, except that the regular expression provided will be
1154 matched without regard to case, which is appropriate for various
1155 programming languages.
1156
1157   The @samp{-R} option deletes all the regexps defined with
1158 @samp{--regex} options.  It applies to the file names following it, as
1159 you can see from the following example:
1160
1161 @smallexample
1162 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
1163     bar.ber -R --lang=lisp los.er
1164 @end smallexample
1165
1166 @noindent
1167 Here @code{etags} chooses the parsing language for @file{voo.doo} and
1168 @file{bar.ber} according to their contents.  @code{etags} also uses
1169 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
1170 @var{reg1} and @var{reg2} to recognize additional tags in
1171 @file{bar.ber}.  @code{etags} uses the Lisp tags rules, and no regexp
1172 matching, to recognize tags in @file{los.er}.
1173
1174   A regular expression can be bound to a given language, by prepending
1175 it with @samp{@{lang@}}.  When you do this, @code{etags} will use the
1176 regular expression only for files of that language.  @samp{etags --help}
1177 prints the list of languages recognised by @code{etags}.  The following
1178 example tags the @code{DEFVAR} macros in the Emacs source files.
1179 @code{etags} applies this regular expression to C files only:
1180
1181 @smallexample
1182 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
1183 @end smallexample
1184
1185 @noindent
1186 This feature is particularly useful when storing a list of regular
1187 expressions in a file.  The following option syntax instructs
1188 @code{etags} to read two files of regular expressions.  The regular
1189 expressions contained in the second file are matched without regard to
1190 case.
1191
1192 @smallexample
1193 --regex=@@first-file --ignore-case-regex=@@second-file
1194 @end smallexample
1195
1196 @noindent
1197 A regex file contains one regular expressions per line.  Empty lines,
1198 and lines beginning with space or tab are ignored.  When the first
1199 character in a line is @samp{@@}, @code{etags} assumes that the rest of
1200 the line is the name of a file of regular expressions.  This means that
1201 such files can be nested.  All the other lines are taken to be regular
1202 expressions.  For example, one can create a file called
1203 @samp{emacs.tags} with the following contents (the first line in the
1204 file is a comment):
1205
1206 @smallexample
1207         -- This is for GNU Emacs source files
1208 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
1209 @end smallexample
1210
1211 @noindent
1212 and then use it like this:
1213
1214 @smallexample
1215 etags --regex=@@emacs.tags *.[ch] */*.[ch]
1216 @end smallexample
1217
1218   Here are some more examples.  The regexps are quoted to protect them
1219 from shell interpretation.
1220
1221 @itemize @bullet
1222
1223 @item
1224 Tag Octave files:
1225
1226 @smallexample
1227 etags --language=none \
1228       --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
1229       --regex='/###key \(.*\)/\1/' \
1230       --regex='/[ \t]*global[ \t].*/' \
1231       *.m
1232 @end smallexample
1233
1234 @noindent
1235 Note that tags are not generated for scripts so that you have to add a
1236 line by yourself of the form `###key <script-name>' if you want to jump
1237 to it.
1238
1239 @item
1240 Tag Tcl files:
1241
1242 @smallexample
1243 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
1244 @end smallexample
1245
1246 @item
1247 Tag VHDL files:
1248
1249 @smallexample
1250 --language=none \
1251 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
1252 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
1253 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
1254 @end smallexample
1255 @end itemize
1256
1257 @node Select Tags Table, Find Tag, Etags Regexps, Tags
1258 @subsection Selecting a Tags Table
1259
1260 @vindex tag-table-alist
1261    At any time Emacs has one @dfn{selected} tags table, and all the commands
1262 for working with tags tables use the selected one.  To select a tags table,
1263 use the variable @code{tag-table-alist}.
1264
1265 The value of @code{tag-table-alist} is a list that determines which
1266 @code{TAGS} files should be active for a given buffer.  This is not
1267 really an association list, in that all elements are checked.  The car
1268 of each element of this list is a pattern against which the buffers file
1269 name is compared; if it matches, then the cdr of the list should be the
1270 name of the tags table to use.  If more than one element of this list
1271 matches the buffers file name, all of the associated tags tables are
1272 used.  Earlier ones are searched first.
1273
1274 If the car of elements of this list are strings, they are treated
1275 as regular-expressions against which the file is compared (like the
1276 @code{auto-mode-alist}).  If they are not strings, they are evaluated.
1277 If they evaluate to non-@code{nil}, the current buffer is considered to
1278 match.
1279
1280 If the cdr of the elements of this list are strings, they are
1281 assumed to name a tags file.  If they name a directory, the string
1282 @file{tags} is appended to them to get the file name.  If they are not 
1283 strings, they are evaluated and must return an appropriate string.
1284
1285 For example:
1286
1287 @example
1288   (setq tag-table-alist
1289         '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
1290           ("\\.el$" . "/usr/local/emacs/src/")
1291           ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
1292           ("" . "/usr/local/emacs/src/")
1293           ))
1294 @end example
1295
1296 The example defines the tags table alist in the following way:
1297  
1298 @itemize @bullet
1299 @item
1300 Anything in the directory @file{/usr/src/public/perl/} 
1301 should use the @file{TAGS} file @file{/usr/src/public/perl/perl-3.0/TAGS}. 
1302 @item
1303 Files ending in @file{.el} should use the @file{TAGS} file
1304 @file{/usr/local/emacs/src/TAGS}. 
1305 @item
1306 Anything in or below the directory @file{/jbw/gnu/} should use the 
1307 @file{TAGS} file @file{/usr15/degree/stud/jbw/gnu/TAGS}.  
1308 @end itemize
1309
1310 If you had a file called @file{/usr/jbw/foo.el}, it would use both
1311 @file{TAGS} files, @* @file{/usr/local/emacs/src/TAGS} and
1312 @file{/usr15/degree/stud/jbw/gnu/TAGS} (in that order), because it
1313 matches both patterns.
1314
1315 If the buffer-local variable @code{buffer-tag-table} is set, it names a
1316 tags table that is searched before all others when @code{find-tag} is
1317 executed from this buffer.
1318
1319 If there is a file called @file{TAGS} in the same directory as the file
1320 in question, then that tags file will always be used as well (after the
1321 @code{buffer-tag-table} but before the tables specified by this list).
1322
1323 If the variable @code{tags-file-name} is set, the @file{TAGS} file it names
1324 will apply to all buffers (for backwards compatibility.)  It is searched
1325 first.
1326
1327 @vindex tags-always-build-completion-table
1328 If the value of the variable @code{tags-always-build-completion-table}
1329 is @code{t}, the tags file will always be added to the completion table
1330 without asking first, regardless of the size of the tags file.
1331
1332 @vindex tags-file-name
1333 @findex visit-tags-table
1334 The function @kbd{M-x visit-tags-table}, is largely made obsolete by
1335 the variable @code{tag-table-alist}, tells tags commands to use the tags
1336 table file @var{file} first.  The @var{file} should be the name of a
1337 file created with the @code{etags} program.  A directory name is also
1338 acceptable; it means the file @file{TAGS} in that directory.  The
1339 function only stores the file name you provide in the variable
1340 @code{tags-file-name}.  Emacs does not actually read in the tags table
1341 contents until you try to use them.  You can set the variable explicitly
1342 instead of using @code{visit-tags-table}.  The value of the variable
1343 @code{tags-file-name} is the name of the tags table used by all buffers.
1344 This is for backward compatibility, and is largely supplanted by the
1345 variable @code{tag-table-alist}.
1346  
1347 @node Find Tag, Tags Search, Select Tags Table, Tags
1348 @subsection Finding a Tag
1349
1350   The most important thing that a tags table enables you to do is to find
1351 the definition of a specific tag.
1352
1353 @table @kbd
1354 @item M-.@: @var{tag &optional other-window}
1355 Find first definition of @var{tag} (@code{find-tag}).
1356 @item C-u M-.
1357 Find next alternate definition of last tag specified.
1358 @item C-x 4 . @var{tag}
1359 Find first definition of @var{tag}, but display it in another window
1360 (@code{find-tag-other-window}).
1361 @end table
1362
1363 @kindex M-.
1364 @findex find-tag
1365   @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
1366 a specified tag.  It searches through the tags table for that tag, as a
1367 string, then uses the tags table information to determine the file in
1368 which the definition is used and the approximate character position of
1369 the definition in the file.  Then @code{find-tag} visits the file,
1370 moves point to the approximate character position, and starts searching
1371 ever-increasing distances away for the text that should appear at
1372 the beginning of the definition.
1373
1374   If an empty argument is given (by typing @key{RET}), the sexp in the
1375 buffer before or around point is used as the name of the tag to find.
1376 @xref{Lists}, for information on sexps.
1377
1378   The argument to @code{find-tag} need not be the whole tag name; it can
1379 be a substring of a tag name.  However, there can be many tag names
1380 containing the substring you specify.  Since @code{find-tag} works by
1381 searching the text of the tags table, it finds the first tag in the table
1382 that the specified substring appears in.  To find other tags that match
1383 the substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
1384 M-.}.  This does not read a tag name, but continues searching the tag
1385 table's text for another tag containing the same substring last used.
1386 If your keyboard has a real @key{META} key, @kbd{M-0 M-.}@: is an easier
1387 alternative to @kbd{C-u M-.}.
1388
1389 If the optional second argument @var{other-window} is non-@code{nil}, it uses
1390 another window to display the tag.
1391 Multiple active tags tables and completion are supported.
1392
1393 Variables of note include the following:
1394
1395 @vindex tag-table-alist
1396 @vindex tags-file-name
1397 @vindex tags-build-completion-table
1398 @vindex buffer-tag-table
1399 @vindex make-tags-files-invisible
1400 @vindex tag-mark-stack-max
1401
1402 @table @kbd
1403 @item tag-table-alist
1404 Controls which tables apply to which buffers.
1405 @item tags-file-name
1406 Stores a default tags table.
1407 @item tags-build-completion-table
1408 Controls completion behavior.
1409 @item buffer-tag-table
1410 Specifies a buffer-local table.
1411 @item make-tags-files-invisible
1412 Sets whether tags tables should be very hidden.
1413 @item tag-mark-stack-max
1414 Specifies how many tags-based hops to remember.
1415 @end table
1416
1417 @kindex C-x 4 .
1418 @findex find-tag-other-window
1419   Like most commands that can switch buffers, @code{find-tag} has another
1420 similar command that displays the new buffer in another window.  @kbd{C-x 4
1421 .}@: invokes the function @code{find-tag-other-window}.  (This key sequence
1422 ends with a period.)
1423
1424   Emacs comes with a tags table file @file{TAGS} (in the directory
1425 containing Lisp libraries) that includes all the Lisp libraries and all
1426 the C sources of Emacs.  By specifying this file with @code{visit-tags-table}
1427 and then using @kbd{M-.}@: you can quickly look at the source of any Emacs
1428 function.
1429
1430 @node Tags Search, List Tags, Find Tag, Tags
1431 @subsection Searching and Replacing with Tags Tables
1432
1433   The commands in this section visit and search all the files listed in the
1434 selected tags table, one by one.  For these commands, the tags table serves
1435 only to specify a sequence of files to search.  A related command is
1436 @kbd{M-x grep} (@pxref{Compilation}).
1437
1438 @table @kbd
1439 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
1440 Search for @var{regexp} through the files in the selected tags
1441 table.
1442 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
1443 Perform a @code{query-replace-regexp} on each file in the selected tags table.
1444 @item M-,
1445 Restart one of the commands above, from the current location of point
1446 (@code{tags-loop-continue}).
1447 @end table
1448
1449 @findex tags-search
1450   @kbd{M-x tags-search} reads a regexp using the minibuffer, then
1451 searches for matches in all the files in the selected tags table, one
1452 file at a time.  It displays the name of the file being searched so you
1453 can follow its progress.  As soon as it finds an occurrence,
1454 @code{tags-search} returns.
1455
1456 @kindex M-,
1457 @findex tags-loop-continue
1458   Having found one match, you probably want to find all the rest.  To find
1459 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
1460 @code{tags-search}.  This searches the rest of the current buffer, followed
1461 by the remaining files of the tags table.@refill
1462
1463 @findex tags-query-replace
1464   @kbd{M-x tags-query-replace} performs a single
1465 @code{query-replace-regexp} through all the files in the tags table.  It
1466 reads a regexp to search for and a string to replace with, just like
1467 ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
1468 tags-search}, but repeatedly, processing matches according to your
1469 input.  @xref{Replace}, for more information on query replace.
1470
1471   It is possible to get through all the files in the tags table with a
1472 single invocation of @kbd{M-x tags-query-replace}.  But often it is
1473 useful to exit temporarily, which you can do with any input event that
1474 has no special query replace meaning.  You can resume the query replace
1475 subsequently by typing @kbd{M-,}; this command resumes the last tags
1476 search or replace command that you did.
1477
1478   The commands in this section carry out much broader searches than the
1479 @code{find-tag} family.  The @code{find-tag} commands search only for
1480 definitions of tags that match your substring or regexp.  The commands
1481 @code{tags-search} and @code{tags-query-replace} find every occurrence
1482 of the regexp, as ordinary search commands and replace commands do in
1483 the current buffer.
1484
1485   These commands create buffers only temporarily for the files that they
1486 have to search (those which are not already visited in Emacs buffers).
1487 Buffers in which no match is found are quickly killed; the others
1488 continue to exist.
1489
1490   It may have struck you that @code{tags-search} is a lot like
1491 @code{grep}.  You can also run @code{grep} itself as an inferior of
1492 Emacs and have Emacs show you the matching lines one by one.  This works
1493 much like running a compilation; finding the source locations of the
1494 @code{grep} matches works like finding the compilation errors.
1495 @xref{Compilation}.
1496
1497   If you wish to process all the files in a selected tags table, but
1498 @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} are not giving
1499 you the desired result, you can use @kbd{M-x next-file}.
1500
1501 @table @kbd
1502 @item C-u M-x next-file
1503 With a numeric argument, regardless of its value, visit the first
1504 file in the tags table and prepare to advance sequentially by files.
1505 @item M-x next-file
1506 Visit the next file in the selected tags table.
1507 @end table
1508
1509 @node List Tags,  , Tags Search, Tags
1510 @subsection Tags Table Inquiries
1511
1512 @table @kbd
1513 @item M-x list-tags
1514 Display a list of the tags defined in a specific program file.
1515 @item M-x tags-apropos
1516 Display a list of all tags matching a specified regexp.
1517 @end table
1518
1519 @findex list-tags
1520   @kbd{M-x list-tags} reads the name of one of the files described by the
1521 selected tags table, and displays a list of all the tags defined in that
1522 file.  The ``file name'' argument is really just a string to compare
1523 against the names recorded in the tags table; it is read as a string rather
1524 than a file name.  Therefore, completion and defaulting are not
1525 available, and you must enter the string the same way it appears in the tag
1526 table.  Do not include a directory as part of the file name unless the file
1527 name recorded in the tags table contains that directory.
1528
1529 @findex tags-apropos
1530   @kbd{M-x tags-apropos} is like @code{apropos} for tags.  It reads a regexp,
1531 then finds all the tags in the selected tags table whose entries match that
1532 regexp, and displays the tag names found.
1533
1534 @node CC Mode, Fortran, Tags, Programs
1535 @section Modes for C, C++, Java and similar languages
1536 @cindex C Mode
1537 @cindex C++ Mode
1538 @cindex Java Mode
1539 @cindex AWK Mode
1540 @cindex Objective C Mode
1541 @cindex CORBA IDL Mode
1542 @findex c-mode
1543 @findex c++-mode
1544 @findex java-mode
1545 @findex idl-mode
1546 @findex awk-mode
1547 @findex pike-mode
1548 @findex objc-mode
1549 @vindex c-mode-hook
1550 @vindex c++-mode-hook
1551 @vindex java-mode-hook
1552 @vindex idl-mode-hook
1553 @vindex awk-mode-hook
1554 @vindex pike-mode-hook
1555 @vindex objc-mode-hook
1556 @vindex c-mode-common-hook
1557 @vindex c-initialization-hook
1558
1559   The recommended means for supporting the ``C--like'' programming
1560 languages in XEmacs is the @file{cc-mode} package.  CC Mode is not
1561 included in the basic XEmacs distribution but is available as an
1562 optional package. If loading a file whose names ends in the @file{.cc}
1563 extension does not automatically invoke a C++ Mode then the
1564 @file{cc-mode} package is probably not yet installed. @xref{Packages}.
1565
1566   CC Mode provides modes for editing source files in Awk
1567 (@code{awk-mode}), C (@code{c-mode}), C++ (@code{c++-mode}), CORBA IDL
1568 (@code{idl-mode}), Java (@code{java-mode}), Objective C
1569 (@code{objc-mode}), and Pike (@code{pike-mode}). All these languages are
1570 supported with an sophisticated ``indentation engine'' that is feature
1571 rich, customizable and quite efficient.
1572
1573   Each language major mode runs hooks in the conventionally named hook
1574 variables (@pxref{Mode Hooks}). In addition to this conventional
1575 behavior all the CC Mode major modes will also run hooks in
1576 @code{c-mode-common-hook} @emph{before} invoking the major mode specific
1577 hook. 
1578
1579   CC Mode runs any hooks in @code{c-initialization-hook} exactly once
1580 when it is first loaded.
1581   
1582   CC Mode is a very comprehensive and flexible system and full
1583 description of its capabilities is beyond the scope of this manual.  It
1584 is strongly recommended that the reader consult the CC Mode
1585 documentation for details once the package has been
1586 installed. @xref{Top,CC Mode,,cc-mode, The CC Mode Manual}.
1587
1588 @menu
1589 * Older Modes::             Older Modes for C and AWK
1590 * Customizing CC Mode::     An Introduction to Customizing CC Mode.
1591 @end menu
1592
1593
1594 @node Older Modes, Customizing CC Mode, CC Mode, CC Mode
1595 @subsection Older Modes for C and AWK
1596 @cindex Old C Mode
1597 @cindex Old AWK Mode
1598 @cindex C Mode without CC Mode
1599 @cindex AWK Mode without CC Mode
1600 @cindex old-c-mode
1601
1602   XEmacs provides older versions of a C Mode and an AWK Mode in the
1603 @file{prog-modes} package. These older modes do not share the
1604 indentation engine in CC Mode have have their own specific means of
1605 customizing indentation. To use these modes the @file{prog-modes}
1606 package must be installed.
1607
1608   This older C mode is known simply as the ``Old C Mode''. It supports
1609 only the C language and it lacks many of the features of CC Mode.
1610 However the old C mode offers modest space requirements and very fast
1611 operation.  Old C Mode might be useful in space constrained
1612 environments, on slow machines, or for editing very large files. This
1613 old C mode is available in the @file{old-c-mode}
1614 library. @xref{old-c-mode,Old C Mode,old-c-mode,prog-modes,The
1615 Programming Modes Package Manual}.
1616
1617   The old AWK mode exists for similar reasons. It is available in the
1618 @file{awk-mode} library.  @xref{awk-mode,Old AWK
1619 Mode,awk-mode,prog-modes,The Programming Modes Package Manual}.
1620
1621   Note that the prog-modes package will never automatically invoke these
1622 older modes for a user. However installing the @file{cc-mode} package
1623 @emph{will} make CC Mode's versions available automatically.  As a
1624 result a user who wants to use these older modes must explicitly load
1625 the old libraries to use them.
1626
1627 @node Customizing CC Mode,  , Older Modes, CC Mode
1628 @subsection Customizing Indentation in CC Mode
1629
1630   A very brief introduction is included here on customizing CC Mode. CC
1631 Mode has many features, including useful minor modes, that are
1632 completely documented in its own manual.
1633
1634   CC Mode implements several different ``styles'' for C code (and the
1635 other languages supported by CC Mode). If you need to change the
1636 indentation style for CC Mode it is recommended that you first see if an
1637 existing style meets your requirements. The style chosen will affect the
1638 placement of language elements like braces, function declarations and
1639 comments. You can choose a style interactively by typing @kbd{C-c .} and
1640 pressing the space bar at the prompt to get a list of supported
1641 styles. @kbd{C-c .} runs the function @code{c-set-style} which applies
1642 to all CC Mode language modes though its name might suggest otherwise. A
1643 few of the the supported styles are listed below.
1644
1645 @itemize @bullet
1646 @item
1647 ``gnu'' --- The recommeded style from the Free Software Foundation for
1648 GNU software. 
1649 @item
1650 ``k&r'' --- The classic style from Kernighan and Ritchie.
1651 @item
1652 ``linux'' --- The style recommended for code in the Linux kernel.
1653 @item
1654 ``bsd'' --- The style recommended for software developed in BSD.
1655 @item
1656 ``java --- The ``traditional'' Java style.
1657 @end itemize
1658
1659   The default style in XEmacs is ``gnu'' except for Java mode where it
1660 is the ``java'' style (this is governed by the variable
1661 @code{c-default-style}).
1662
1663   The styles included in CC Mode all use a buffer local variable called
1664 @code{c-basic-offset} as the basic indentation level (this buffer local
1665 variable is used in all CC Mode language modes though its name might
1666 suggest otherwise). All indentation is, by default, expressed in
1667 multiples of @code{c-basic-offset}. 
1668
1669   Each style defines a default value for @code{c-basic-offset}, for the
1670 ``gnu'' style sets it to 2. A very common customization scenario is
1671 where a user wants to use an existing style but with a different basic
1672 offset value. An easy way to do this is to set @code{c-basic-offset} in
1673 the language mode hook after selecting the chosen style.
1674
1675   For example, a user might want to follow a local coding convention of
1676 using the ``k&r'' style for C code with indentation in two columns
1677 multiples (instead of the five column default provided by the CC Mode
1678 ``k&r'' style). This can be achieved with the following code in the
1679 initialization file (@pxref{Init File})
1680
1681 @example
1682 (defun my-c-mode-hook ()
1683   (c-set-style "k&r")
1684   (setq c-basic-offset 2))
1685 (add-hook 'c-mode-hook 'my-c-mode-hook)
1686 @end example
1687
1688   Most customizations for indentation in various CC modes can be
1689 accomplished by choosing a style and then choosing value for
1690 @code{c-basic-offset} that meets the local coding convention. CC Mode
1691 has a very customizable indentation engine and a furthur discussion is
1692 really beyond the scope of this manual. @xref{Indentation
1693 Engine,,,cc-mode,The CC Mode Manual}.
1694
1695
1696 @node Fortran, Asm Mode, CC Mode, Programs
1697 @section Fortran Mode
1698 @cindex Fortran mode
1699
1700   Fortran mode provides special motion commands for Fortran statements and
1701 subprograms, and indentation commands that understand Fortran conventions
1702 of nesting, line numbers, and continuation statements.
1703
1704   Special commands for comments are provided because Fortran comments are
1705 unlike those of other languages.
1706
1707   Built-in abbrevs optionally save typing when you insert Fortran keywords.
1708
1709 @findex fortran-mode
1710   Use @kbd{M-x fortran-mode} to switch to this major mode.  Doing so calls
1711 the value of @code{fortran-mode-hook} as a function of no arguments if
1712 that variable has a non-@code{nil} value.
1713
1714 @menu
1715 * Motion: Fortran Motion.     Moving point by statements or subprograms.
1716 * Indent: Fortran Indent.     Indentation commands for Fortran.
1717 * Comments: Fortran Comments. Inserting and aligning comments.
1718 * Columns: Fortran Columns.   Measuring columns for valid Fortran.
1719 * Abbrev: Fortran Abbrev.     Built-in abbrevs for Fortran keywords.
1720 @end menu
1721
1722   Fortran mode was contributed by Michael Prange.
1723
1724 @node Fortran Motion, Fortran Indent, Fortran, Fortran
1725 @subsection Motion Commands
1726
1727   Fortran mode provides special commands to move by subprograms (functions
1728 and subroutines) and by statements.  There is also a command to put the
1729 region around one subprogram, which is convenient for killing it or moving it.
1730
1731 @kindex C-M-a (Fortran mode)
1732 @kindex C-M-e (Fortran mode)
1733 @kindex C-M-h (Fortran mode)
1734 @kindex C-c C-p (Fortran mode)
1735 @kindex C-c C-n (Fortran mode)
1736 @findex beginning-of-fortran-subprogram
1737 @findex end-of-fortran-subprogram
1738 @findex mark-fortran-subprogram
1739 @findex fortran-previous-statement
1740 @findex fortran-next-statement
1741
1742 @table @kbd
1743 @item C-M-a
1744 Move to beginning of subprogram@*
1745 (@code{beginning-of-fortran-subprogram}).
1746 @item C-M-e
1747 Move to end of subprogram (@code{end-of-fortran-subprogram}).
1748 @item C-M-h
1749 Put point at beginning of subprogram and mark at end
1750 (@code{mark-fortran-subprogram}).
1751 @item C-c C-n
1752 Move to beginning of current or next statement
1753 (@code{fortran-next-@*statement}).
1754 @item C-c C-p
1755 Move to beginning of current or previous statement
1756 (@code{fortran-@*previous-statement}).
1757 @end table
1758
1759 @node Fortran Indent, Fortran Comments, Fortran Motion, Fortran
1760 @subsection Fortran Indentation
1761
1762   Special commands and features are available for indenting Fortran
1763 code.  They make sure various syntactic entities (line numbers, comment line
1764 indicators, and continuation line flags) appear in the columns that are
1765 required for standard Fortran.
1766
1767 @menu
1768 * Commands: ForIndent Commands. Commands for indenting Fortran.
1769 * Numbers:  ForIndent Num.      How line numbers auto-indent.
1770 * Conv:     ForIndent Conv.     Conventions you must obey to avoid trouble.
1771 * Vars:     ForIndent Vars.     Variables controlling Fortran indent style.
1772 @end menu
1773
1774 @node ForIndent Commands, ForIndent Num, Fortran Indent, Fortran Indent
1775 @subsubsection Fortran Indentation Commands
1776
1777 @table @kbd
1778 @item @key{TAB}
1779 Indent the current line (@code{fortran-indent-line}).
1780 @item M-@key{LFD}
1781 Break the current line and set up a continuation line.
1782 @item C-M-q
1783 Indent all the lines of the subprogram point is in
1784 (@code{fortran-indent-subprogram}).
1785 @end table
1786
1787 @findex fortran-indent-line
1788   @key{TAB} is redefined by Fortran mode to reindent the current line for
1789 Fortran (@code{fortran-indent-line}).  Line numbers and continuation
1790 markers are indented to their required columns, and the body of the
1791 statement is independently indented, based on its nesting in the program.
1792
1793 @kindex C-M-q (Fortran mode)
1794 @findex fortran-indent-subprogram
1795   The key @kbd{C-M-q} is redefined as @code{fortran-indent-subprogram}, a
1796 command that reindents all the lines of the Fortran subprogram (function or
1797 subroutine) containing point.
1798
1799 @kindex M-LFD (Fortran mode)
1800 @findex fortran-split-line
1801   The key @kbd{M-@key{LFD}} is redefined as @code{fortran-split-line}, a
1802 command to split a line in the appropriate fashion for Fortran.  In a
1803 non-comment line, the second half becomes a continuation line and is
1804 indented accordingly.  In a comment line, both halves become separate
1805 comment lines.
1806
1807 @node ForIndent Num, ForIndent Conv, ForIndent Commands, Fortran Indent
1808 @subsubsection Line Numbers and Continuation
1809
1810   If a number is the first non-whitespace in the line, it is assumed to be
1811 a line number and is moved to columns 0 through 4.  (Columns are always
1812 counted from 0 in XEmacs.)  If the text on the line starts with the
1813 conventional Fortran continuation marker @samp{$}, it is moved to column 5.
1814 If the text begins with any non whitespace character in column 5, it is
1815 assumed to be an unconventional continuation marker and remains in column
1816 5.
1817
1818 @vindex fortran-line-number-indent
1819   Line numbers of four digits or less are normally indented one space.
1820 This amount is controlled by the variable @code{fortran-line-number-indent},
1821 which is the maximum indentation a line number can have.  Line numbers
1822 are indented to right-justify them to end in column 4 unless that would
1823 require more than the maximum indentation.  The default value of the
1824 variable is 1.
1825
1826 @vindex fortran-electric-line-number
1827   Simply inserting a line number is enough to indent it according to these
1828 rules.  As each digit is inserted, the indentation is recomputed.  To turn
1829 off this feature, set the variable @code{fortran-electric-line-number} to
1830 @code{nil}.  Then inserting line numbers is like inserting anything else.
1831
1832 @node ForIndent Conv, ForIndent Vars, ForIndent Num, Fortran Indent
1833 @subsubsection Syntactic Conventions
1834
1835   Fortran mode assumes that you follow certain conventions that simplify
1836 the task of understanding a Fortran program well enough to indent it
1837 properly:
1838
1839 @vindex fortran-continuation-char
1840 @itemize @bullet
1841 @item
1842 Two nested @samp{do} loops never share a @samp{continue} statement.
1843
1844 @item
1845 The same character appears in column 5 of all continuation lines.  It
1846 is the value of the variable @code{fortran-continuation-char}.
1847 By default, this character is @samp{$}.
1848 @end itemize
1849
1850 @noindent
1851 If you fail to follow these conventions, the indentation commands may
1852 indent some lines unaesthetically.  However, a correct Fortran program will
1853 retain its meaning when reindented even if the conventions are not
1854 followed.
1855
1856 @node ForIndent Vars,  , ForIndent Conv, Fortran Indent
1857 @subsubsection Variables for Fortran Indentation
1858
1859 @vindex fortran-do-indent
1860 @vindex fortran-if-indent
1861 @vindex fortran-continuation-indent
1862 @vindex fortran-check-all-num-for-matching-do
1863 @vindex fortran-minimum-statement-indent
1864   Several additional variables control how Fortran indentation works.
1865
1866 @table @code
1867 @item fortran-do-indent
1868 Extra indentation within each level of @samp{do} statement (the default is 3).
1869
1870 @item fortran-if-indent
1871 Extra indentation within each level of @samp{if} statement (the default is 3).
1872
1873 @item fortran-continuation-indent
1874 Extra indentation for bodies of continuation lines (the default is 5).
1875
1876 @item fortran-check-all-num-for-matching-do
1877 If this is @code{nil}, indentation assumes that each @samp{do}
1878 statement ends on a @samp{continue} statement.  Therefore, when
1879 computing indentation for a statement other than @samp{continue}, it
1880 can save time by not checking for a @samp{do} statement ending there.
1881 If this is non-@code{nil}, indenting any numbered statement must check
1882 for a @samp{do} that ends there.  The default is @code{nil}.
1883
1884 @item fortran-minimum-statement-indent
1885 Minimum indentation for Fortran statements.  For standard Fortran,
1886 this is 6.  Statement bodies are always indented at least this much.
1887 @end table
1888
1889 @node Fortran Comments, Fortran Columns, Fortran Indent, Fortran
1890 @subsection Comments
1891
1892   The usual Emacs comment commands assume that a comment can follow a line
1893 of code.  In Fortran, the standard comment syntax requires an entire line
1894 to be just a comment.  Therefore, Fortran mode replaces the standard Emacs
1895 comment commands and defines some new variables.
1896
1897   Fortran mode can also handle a non-standard comment syntax where comments
1898 start with @samp{!} and can follow other text.  Because only some Fortran
1899 compilers accept this syntax, Fortran mode will not insert such comments
1900 unless you have specified to do so in advance by setting the variable
1901 @code{comment-start} to @samp{"!"} (@pxref{Variables}).
1902
1903 @table @kbd
1904 @item M-;
1905 Align comment or insert new comment (@code{fortran-comment-indent}).
1906
1907 @item C-x ;
1908 Applies to nonstandard @samp{!} comments only.
1909
1910 @item C-c ;
1911 Turn all lines of the region into comments, or (with arg)
1912 turn them back into real code (@code{fortran-comment-region}).
1913 @end table
1914
1915   @kbd{M-;} in Fortran mode is redefined as the command
1916 @code{fortran-comment-indent}.  Like the usual @kbd{M-;} command,
1917 it recognizes an existing comment and aligns its text appropriately.
1918 If there is no existing comment, a comment is inserted and aligned.
1919
1920 Inserting and aligning comments is not the same in Fortran mode as in
1921 other modes.  When a new comment must be inserted, a full-line comment is
1922 inserted if the current line is blank.  On a non-blank line, a
1923 non-standard @samp{!} comment is inserted if you previously specified
1924 you wanted to use them.  Otherwise a full-line comment is inserted on a
1925 new line before the current line.
1926
1927   Non-standard @samp{!} comments are aligned like comments in other
1928 languages, but full-line comments are aligned differently.  In a
1929 standard full-line comment, the comment delimiter itself must always
1930 appear in column zero.  What can be aligned is the text within the
1931 comment.  You can choose from three styles of alignment by setting the
1932 variable @code{fortran-comment-indent-style} to one of these values:
1933
1934 @vindex fortran-comment-indent-style
1935 @vindex fortran-comment-line-column
1936 @table @code
1937 @item fixed
1938 The text is aligned at a fixed column, which is the value of
1939 @code{fortran-comment-line-column}.  This is the default.
1940 @item relative
1941 The text is aligned as if it were a line of code, but with an
1942 additional @code{fortran-comment-line-column} columns of indentation.
1943 @item nil
1944 Text in full-line columns is not moved automatically.
1945 @end table
1946
1947 @vindex fortran-comment-indent-char
1948   You can also specify the character to be used to indent within
1949 full-line comments by setting the variable @code{fortran-comment-indent-char}
1950 to the character you want to use.
1951
1952 @vindex comment-line-start
1953 @vindex comment-line-start-skip
1954   Fortran mode introduces two variables @code{comment-line-start} and
1955 @code{comment-line-start-skip}, which do for full-line comments what
1956 @code{comment-start} and @code{comment-start-skip} do for
1957 ordinary text-following comments.  Normally these are set properly by
1958 Fortran mode, so you do not need to change them.
1959
1960   The normal Emacs comment command @kbd{C-x ;} has not been redefined.
1961 It can therefore be used if you use @samp{!} comments, but is useless in
1962 Fortran mode otherwise. 
1963
1964 @kindex C-c ; (Fortran mode)
1965 @findex fortran-comment-region
1966 @vindex fortran-comment-region
1967   The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
1968 lines of the region into comments by inserting the string @samp{C$$$} at
1969 the front of each one.  With a numeric arg, the region is turned back into
1970 live code by deleting @samp{C$$$} from the front of each line.  You can
1971 control the string used for the comments by setting the variable
1972 @code{fortran-comment-region}.  Note that here we have an example of a
1973 command and a variable with the same name; the two uses of the name never
1974 conflict because in Lisp and in Emacs it is always clear from the context
1975 which one is referred to.
1976
1977 @node Fortran Columns, Fortran Abbrev, Fortran Comments, Fortran
1978 @subsection Columns
1979
1980 @table @kbd
1981 @item C-c C-r
1982 Displays a ``column ruler'' momentarily above the current line
1983 (@code{fortran-column-ruler}).
1984 @item C-c C-w
1985 Splits the current window horizontally so that it is 72 columns wide.
1986 This may help you avoid going over that limit (@code{fortran-window-create}).
1987 @end table
1988
1989 @kindex C-c C-r (Fortran mode)
1990 @findex fortran-column-ruler
1991   The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
1992 ruler above the current line.  The comment ruler consists of two lines
1993 of text that show you the locations of columns with special significance
1994 in Fortran programs.  Square brackets show the limits of the columns for
1995 line numbers, and curly brackets show the limits of the columns for the
1996 statement body.  Column numbers appear above them.
1997
1998   Note that the column numbers count from zero, as always in XEmacs.  As
1999 a result, the numbers may not be those you are familiar with; but the
2000 actual positions in the line are standard Fortran.
2001
2002   The text used to display the column ruler is the value of the variable
2003 @code{fortran-comment-ruler}.  By changing this variable, you can change
2004 the display.
2005
2006 @kindex C-c C-w (Fortran mode)
2007 @findex fortran-window-create
2008   For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a
2009 command which splits the current window horizontally, resulting in a window 72
2010 columns wide.  When you edit in this window, you can immediately see
2011 when a line gets too wide to be correct Fortran.
2012
2013 @node Fortran Abbrev,  , Fortran Columns, Fortran
2014 @subsection Fortran Keyword Abbrevs
2015
2016   Fortran mode provides many built-in abbrevs for common keywords and
2017 declarations.  These are the same sort of abbrevs that you can define
2018 yourself.  To use them, you must turn on Abbrev mode.  @pxref{Abbrevs}.
2019
2020   The built-in abbrevs are unusual in one way: they all start with a
2021 semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
2022 mode makes this possible by changing the syntax of semicolon to ``word
2023 constituent''.
2024
2025   For example, one built-in Fortran abbrev is @samp{;c} for
2026 @samp{continue}.  If you insert @samp{;c} and then insert a punctuation
2027 character such as a space or a newline, the @samp{;c} changes
2028 automatically to @samp{continue}, provided Abbrev mode is enabled.@refill
2029
2030   Type @samp{;?} or @samp{;C-h} to display a list of all built-in
2031 Fortran abbrevs and what they stand for.
2032
2033 @node Asm Mode,  , Fortran, Programs
2034 @section Asm Mode
2035
2036 @cindex Asm mode
2037 Asm mode is a major mode for editing files of assembler code.  It
2038 defines these commands:
2039
2040 @table @kbd
2041 @item @key{TAB}
2042 @code{tab-to-tab-stop}.
2043 @item @key{LFD}
2044 Insert a newline and then indent using @code{tab-to-tab-stop}.
2045 @item :
2046 Insert a colon and then remove the indentation from before the label
2047 preceding colon.  Then do @code{tab-to-tab-stop}.
2048 @item ;
2049 Insert or align a comment.
2050 @end table
2051
2052   The variable @code{asm-comment-char} specifies which character
2053 starts comments in assembler syntax.