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