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