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