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