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