Mercurial > hg > xemacs-beta
annotate man/xemacs/programs.texi @ 5797:a1808d52a34a
If the position of a window's cached point is deleted, use buffer point instead
src/ChangeLog addition:
2014-06-17 Aidan Kehoe <kehoea@parhasard.net>
* extents.h:
* window.c:
* window.c (unshow_buffer):
* window.c (Fset_window_buffer):
Use extents, rather than markers, for the window buffer point
cache, so that when the text containing that window buffer point
is deleted, the window display code uses the buffer's actual point
instead of the position that the marker had been moved to.
Fixes Michael Heinrich's problem of
http://mid.gmane.org/6zr42uxtf5.fsf@elektra.science-computing.de ,
introduced by Ben's patch of
https://bitbucket.org/xemacs/xemacs/commits/047d37eb70d70f43803 .
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Tue, 17 Jun 2014 20:55:45 +0100 |
| parents | 9fae6227ede5 |
| 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. |