Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
85750656 | 2 | @c Copyright (C) 1985,86,87,93,94,95,97,99,2000 Free Software Foundation, Inc. |
6bf7aab6 DL |
3 | @c See file emacs.texi for copying conditions. |
4 | @node Programs, Building, Text, Top | |
5 | @chapter Editing Programs | |
6 | @cindex Lisp editing | |
7 | @cindex C editing | |
8 | @cindex program editing | |
9 | ||
10 | Emacs has many commands designed to understand the syntax of programming | |
11 | languages such as Lisp and C. These commands can | |
12 | ||
13 | @itemize @bullet | |
14 | @item | |
15 | Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}). | |
16 | @item | |
17 | Move over or mark top-level expressions---@dfn{defuns}, in Lisp; | |
18 | functions, in C (@pxref{Defuns}). | |
19 | @item | |
20 | Show how parentheses balance (@pxref{Matching}). | |
21 | @item | |
22 | Insert, kill or align comments (@pxref{Comments}). | |
23 | @item | |
24 | Follow the usual indentation conventions of the language | |
25 | (@pxref{Program Indent}). | |
26 | @end itemize | |
27 | ||
28 | The commands for words, sentences and paragraphs are very useful in | |
29 | editing code even though their canonical application is for editing | |
30 | human language text. Most symbols contain words (@pxref{Words}); | |
31 | sentences can be found in strings and comments (@pxref{Sentences}). | |
32 | Paragraphs per se don't exist in code, but the paragraph commands are | |
33 | useful anyway, because programming language major modes define | |
34 | paragraphs to begin and end at blank lines (@pxref{Paragraphs}). | |
35 | Judicious use of blank lines to make the program clearer will also | |
36 | provide useful chunks of text for the paragraph commands to work | |
37 | on. | |
38 | ||
51ed0ea0 DL |
39 | @cindex selective display |
40 | @cindex outline | |
41 | @cindex folding | |
42 | @findex outline-minor-mode | |
43 | @cindex outlines | |
6bf7aab6 | 44 | The selective display feature is useful for looking at the overall |
85750656 DL |
45 | structure of a function (@pxref{Selective Display}). This feature |
46 | causes only the lines that are indented less than a specified amount to | |
51ed0ea0 DL |
47 | appear on the screen. Programming modes often support Outline minor |
48 | mode (@pxref{Outline Mode}). The Foldout package (@pxref{Foldout}) can | |
49 | provide convenient folding-editor features on top of the minor mode. | |
50 | The Hideshow package (@pxref{Hideshow}) can also be used to display | |
51 | bocks of code selectively. | |
85750656 DL |
52 | |
53 | The `automatic typing' features may be useful when writing programs. | |
54 | @xref{Top, Autotyping, autotype, Features for Automatic Typing}. | |
6bf7aab6 DL |
55 | |
56 | @menu | |
57 | * Program Modes:: Major modes for editing programs. | |
58 | * Lists:: Expressions with balanced parentheses. | |
59 | * List Commands:: The commands for working with list and sexps. | |
60 | * Defuns:: Each program is made up of separate functions. | |
61 | There are editing commands to operate on them. | |
62 | * Program Indent:: Adjusting indentation to show the nesting. | |
63 | * Matching:: Insertion of a close-delimiter flashes matching open. | |
64 | * Comments:: Inserting, killing, and aligning comments. | |
65 | * Balanced Editing:: Inserting two matching parentheses at once, etc. | |
66 | * Symbol Completion:: Completion on symbol names of your program or language. | |
67 | * Which Function:: Which Function mode shows which function you are in. | |
51ed0ea0 | 68 | * Hideshow:: Displaying blocks selectively. |
6bf7aab6 DL |
69 | * Documentation:: Getting documentation of functions you plan to call. |
70 | * Change Log:: Maintaining a change history for your program. | |
71 | * Tags:: Go direct to any function in your program in one | |
72 | command. Tags remembers which file it is in. | |
51ed0ea0 | 73 | * Imenu:: Making buffer indexes as menus. |
6bf7aab6 | 74 | * Emerge:: A convenient way of merging two versions of a program. |
79214ddf | 75 | * C Modes:: Special commands of C, C++, Objective-C, |
6bf7aab6 | 76 | Java, and Pike modes. |
51ed0ea0 DL |
77 | * Fortran:: Fortran mode and its special features. |
78 | * Asm Mode:: Asm mode and its special features. | |
6bf7aab6 DL |
79 | @end menu |
80 | ||
81 | @node Program Modes | |
82 | @section Major Modes for Programming Languages | |
83 | ||
84 | @cindex modes for programming languages | |
85 | @cindex Perl mode | |
86 | @cindex Icon mode | |
87 | @cindex Awk mode | |
88 | @cindex Makefile mode | |
89 | @cindex Tcl mode | |
90 | @cindex CPerl mode | |
138a8f12 DL |
91 | @cindex DSSSL mode |
92 | @cindex Octave mode | |
93 | @cindex Metafont mode | |
94 | @cindex Modula2 mode | |
95 | @cindex Prolog mode | |
96 | @cindex Simula mode | |
97 | @cindex VHDL mode | |
98 | @cindex M4 mode | |
99 | @cindex Shell-script mode | |
6bf7aab6 | 100 | Emacs also has major modes for the programming languages Lisp, Scheme |
51ed0ea0 DL |
101 | (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada, |
102 | Awk, C, C++, Fortran (free and fixed format), Icon, IDLWAVE, | |
103 | Java, Metafont (@TeX{}'s companion for font creation), Modula2, | |
104 | Objective-C, Octave, Pascal, Perl, Pike, Prolog, Simula, VHDL, CORBA | |
105 | IDL, and Tcl. There is also a major mode for makefiles, called Makefile | |
106 | mode. An alternative mode for Perl is called CPerl mode. Modes | |
107 | are available for scripts for the common Unix shells, VMS DCL and | |
108 | MS-DOS/MS-Windows `BAT' files. In a similar fashion to programming | |
109 | languages, modes are provided for editing various sorts of configuration | |
110 | files. | |
111 | ||
112 | Separate manuals are available for th modes for Ada (@pxref{Top, , Ada Mode, | |
113 | ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL (@pxref{Top, , CC Mode, | |
114 | ccmode, CC Mode}) and the IDLWAVE modes (@pxref{Top, , IDLWAVE, | |
115 | idlwave, IDLWAVE User Manual}). | |
6bf7aab6 DL |
116 | |
117 | Ideally, a major mode should be implemented for each programming | |
118 | language that you might want to edit with Emacs; but often the mode for | |
119 | one language can serve for other syntactically similar languages. The | |
120 | language modes that exist are those that someone decided to take the | |
121 | trouble to write. | |
122 | ||
123 | There are several forms of Lisp mode, which differ in the way they | |
124 | interface to Lisp execution. @xref{Executing Lisp}. | |
125 | ||
126 | Each of the programming language major modes defines the @key{TAB} key | |
127 | to run an indentation function that knows the indentation conventions of | |
128 | that language and updates the current line's indentation accordingly. | |
129 | For example, in C mode @key{TAB} is bound to @code{c-indent-line}. | |
130 | @kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB}; | |
131 | thus, it too indents in a mode-specific fashion. | |
132 | ||
133 | @kindex DEL @r{(programming modes)} | |
134 | @findex backward-delete-char-untabify | |
135 | In most programming languages, indentation is likely to vary from line to | |
136 | line. So the major modes for those languages rebind @key{DEL} to treat a | |
137 | tab as if it were the equivalent number of spaces (using the command | |
138 | @code{backward-delete-char-untabify}). This makes it possible to rub out | |
139 | indentation one column at a time without worrying whether it is made up of | |
140 | spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point, | |
141 | in these modes. | |
142 | ||
143 | Programming language modes define paragraphs to be separated only by | |
144 | blank lines, so that the paragraph commands remain useful. Auto Fill mode, | |
145 | if enabled in a programming language major mode, indents the new lines | |
146 | which it creates. | |
147 | ||
148 | @cindex mode hook | |
149 | @vindex c-mode-hook | |
150 | @vindex lisp-mode-hook | |
151 | @vindex emacs-lisp-mode-hook | |
152 | @vindex lisp-interaction-mode-hook | |
153 | @vindex scheme-mode-hook | |
6bf7aab6 DL |
154 | Turning on a major mode runs a normal hook called the @dfn{mode hook}, |
155 | which is the value of a Lisp variable. Each major mode has a mode hook, | |
156 | and the hook's name is always made from the mode command's name by | |
157 | adding @samp{-hook}. For example, turning on C mode runs the hook | |
158 | @code{c-mode-hook}, while turning on Lisp mode runs the hook | |
159 | @code{lisp-mode-hook}. @xref{Hooks}. | |
160 | ||
161 | @node Lists | |
162 | @section Lists and Sexps | |
163 | ||
164 | @cindex Control-Meta | |
165 | By convention, Emacs keys for dealing with balanced expressions are | |
166 | usually Control-Meta characters. They tend to be analogous in | |
167 | function to their Control and Meta equivalents. These commands are | |
168 | usually thought of as pertaining to expressions in programming | |
169 | languages, but can be useful with any language in which some sort of | |
170 | parentheses exist (including human languages). | |
171 | ||
172 | @cindex list | |
173 | @cindex sexp | |
174 | @cindex expression | |
175 | @cindex parentheses, moving across | |
176 | @cindex matching parenthesis, moving to | |
177 | These commands fall into two classes. Some deal only with @dfn{lists} | |
178 | (parenthetical groupings). They see nothing except parentheses, brackets, | |
179 | braces (whichever ones must balance in the language you are working with), | |
180 | and escape characters that might be used to quote those. | |
181 | ||
182 | The other commands deal with expressions or @dfn{sexps}. The word `sexp' | |
183 | is derived from @dfn{s-expression}, the ancient term for an expression in | |
184 | Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It | |
185 | refers to an expression in whatever language your program is written in. | |
186 | Each programming language has its own major mode, which customizes the | |
187 | syntax tables so that expressions in that language count as sexps. | |
188 | ||
189 | Sexps typically include symbols, numbers, and string constants, as well | |
190 | as anything contained in parentheses, brackets or braces. | |
191 | ||
192 | In languages that use prefix and infix operators, such as C, it is not | |
193 | possible for all expressions to be sexps. For example, C mode does not | |
194 | recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression; | |
195 | it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the | |
196 | @samp{+} as punctuation between them. This is a fundamental ambiguity: | |
197 | both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to | |
198 | move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a | |
199 | single sexp in C mode. | |
200 | ||
201 | Some languages have obscure forms of expression syntax that nobody | |
202 | has bothered to make Emacs understand properly. | |
203 | ||
204 | @node List Commands | |
205 | @section List And Sexp Commands | |
206 | ||
207 | @c doublewidecommands | |
208 | @table @kbd | |
209 | @item C-M-f | |
210 | Move forward over a sexp (@code{forward-sexp}). | |
211 | @item C-M-b | |
212 | Move backward over a sexp (@code{backward-sexp}). | |
213 | @item C-M-k | |
214 | Kill sexp forward (@code{kill-sexp}). | |
215 | @item C-M-@key{DEL} | |
216 | Kill sexp backward (@code{backward-kill-sexp}). | |
217 | @item C-M-u | |
218 | Move up and backward in list structure (@code{backward-up-list}). | |
219 | @item C-M-d | |
220 | Move down and forward in list structure (@code{down-list}). | |
221 | @item C-M-n | |
222 | Move forward over a list (@code{forward-list}). | |
223 | @item C-M-p | |
224 | Move backward over a list (@code{backward-list}). | |
225 | @item C-M-t | |
226 | Transpose expressions (@code{transpose-sexps}). | |
227 | @item C-M-@@ | |
228 | Put mark after following expression (@code{mark-sexp}). | |
229 | @end table | |
230 | ||
231 | @kindex C-M-f | |
232 | @kindex C-M-b | |
233 | @findex forward-sexp | |
234 | @findex backward-sexp | |
235 | To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If | |
236 | the first significant character after point is an opening delimiter | |
237 | (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f} | |
238 | moves past the matching closing delimiter. If the character begins a | |
239 | symbol, string, or number, @kbd{C-M-f} moves over that. | |
240 | ||
241 | The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a | |
242 | sexp. The detailed rules are like those above for @kbd{C-M-f}, but with | |
243 | directions reversed. If there are any prefix characters (single-quote, | |
244 | backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back | |
245 | over them as well. The sexp commands move across comments as if they | |
246 | were whitespace in most modes. | |
247 | ||
248 | @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the | |
249 | specified number of times; with a negative argument, it moves in the | |
250 | opposite direction. | |
251 | ||
252 | @kindex C-M-k | |
253 | @findex kill-sexp | |
254 | @kindex C-M-DEL | |
255 | @findex backward-kill-sexp | |
256 | Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp}) | |
257 | or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills | |
258 | the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}} | |
259 | kills the characters that @kbd{C-M-b} would move over. | |
260 | ||
261 | @kindex C-M-n | |
262 | @kindex C-M-p | |
263 | @findex forward-list | |
264 | @findex backward-list | |
265 | The @dfn{list commands} move over lists, as the sexp commands do, but skip | |
266 | blithely over any number of other kinds of sexps (symbols, strings, etc.). | |
267 | They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p} | |
268 | (@code{backward-list}). The main reason they are useful is that they | |
269 | usually ignore comments (since the comments usually do not contain any | |
270 | lists).@refill | |
271 | ||
272 | @kindex C-M-u | |
273 | @kindex C-M-d | |
274 | @findex backward-up-list | |
275 | @findex down-list | |
276 | @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when | |
277 | that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u} | |
278 | (@code{backward-up-list}). | |
279 | @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A | |
280 | positive argument serves as a repeat count; a negative argument reverses | |
281 | direction of motion and also requests repetition, so it moves forward and | |
282 | up one or more levels.@refill | |
283 | ||
284 | To move @emph{down} in list structure, use @kbd{C-M-d} | |
285 | (@code{down-list}). In Lisp mode, where @samp{(} is the only opening | |
286 | delimiter, this is nearly the same as searching for a @samp{(}. An | |
287 | argument specifies the number of levels of parentheses to go down. | |
288 | ||
289 | @cindex transposition | |
290 | @kindex C-M-t | |
291 | @findex transpose-sexps | |
292 | A somewhat random-sounding command which is nevertheless handy is | |
293 | @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp | |
294 | across the next one. An argument serves as a repeat count, and a | |
295 | negative argument drags backwards (thus canceling out the effect of | |
296 | @kbd{C-M-t} with a positive argument). An argument of zero, rather than | |
297 | doing nothing, transposes the sexps ending after point and the mark. | |
298 | ||
299 | @kindex C-M-@@ | |
300 | @findex mark-sexp | |
301 | To set the region around the next sexp in the buffer, use @kbd{C-M-@@} | |
302 | (@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f} | |
303 | would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In | |
304 | particular, a negative argument is useful for putting the mark at the | |
305 | beginning of the previous sexp. | |
306 | ||
307 | The list and sexp commands' understanding of syntax is completely | |
308 | controlled by the syntax table. Any character can, for example, be | |
309 | declared to be an opening delimiter and act like an open parenthesis. | |
310 | @xref{Syntax}. | |
311 | ||
312 | @node Defuns | |
313 | @section Defuns | |
314 | @cindex defuns | |
315 | ||
316 | In Emacs, a parenthetical grouping at the top level in the buffer is | |
317 | called a @dfn{defun}. The name derives from the fact that most top-level | |
318 | lists in a Lisp file are instances of the special form @code{defun}, but | |
319 | any top-level parenthetical grouping counts as a defun in Emacs parlance | |
320 | regardless of what its contents are, and regardless of the programming | |
321 | language in use. For example, in C, the body of a function definition is a | |
322 | defun. | |
323 | ||
324 | @c doublewidecommands | |
325 | @table @kbd | |
326 | @item C-M-a | |
327 | Move to beginning of current or preceding defun | |
328 | (@code{beginning-of-defun}). | |
329 | @item C-M-e | |
330 | Move to end of current or following defun (@code{end-of-defun}). | |
331 | @item C-M-h | |
332 | Put region around whole current or following defun (@code{mark-defun}). | |
333 | @end table | |
334 | ||
335 | @kindex C-M-a | |
336 | @kindex C-M-e | |
337 | @kindex C-M-h | |
338 | @findex beginning-of-defun | |
339 | @findex end-of-defun | |
340 | @findex mark-defun | |
341 | The commands to move to the beginning and end of the current defun are | |
342 | @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}). | |
343 | ||
344 | @findex c-mark-function | |
345 | If you wish to operate on the current defun, use @kbd{C-M-h} | |
346 | (@code{mark-defun}) which puts point at the beginning and mark at the end | |
347 | of the current or next defun. For example, this is the easiest way to get | |
348 | ready to move the defun to a different place in the text. In C mode, | |
349 | @kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the | |
350 | same as @code{mark-defun}; the difference is that it backs up over the | |
351 | argument declarations, function name and returned data type so that the | |
352 | entire C function is inside the region. @xref{Marking Objects}. | |
353 | ||
85750656 DL |
354 | @cindex open-parenthesis in leftmost column |
355 | @cindex ( in leftmost column | |
6bf7aab6 DL |
356 | Emacs assumes that any open-parenthesis found in the leftmost column |
357 | is the start of a defun. Therefore, @strong{never put an | |
358 | open-parenthesis at the left margin in a Lisp file unless it is the | |
359 | start of a top-level list. Never put an open-brace or other opening | |
360 | delimiter at the beginning of a line of C code unless it starts the body | |
361 | of a function.} The most likely problem case is when you want an | |
362 | opening delimiter at the start of a line inside a string. To avoid | |
363 | trouble, put an escape character (@samp{\}, in C and Emacs Lisp, | |
364 | @samp{/} in some other Lisp dialects) before the opening delimiter. It | |
365 | will not affect the contents of the string. | |
366 | ||
367 | In the remotest past, the original Emacs found defuns by moving upward a | |
368 | level of parentheses until there were no more levels to go up. This always | |
369 | required scanning all the way back to the beginning of the buffer, even for | |
370 | a small function. To speed up the operation, Emacs was changed to assume | |
371 | that any @samp{(} (or other character assigned the syntactic class of | |
372 | opening-delimiter) at the left margin is the start of a defun. This | |
373 | heuristic is nearly always right and avoids the costly scan; however, | |
374 | it mandates the convention described above. | |
375 | ||
376 | @node Program Indent | |
377 | @section Indentation for Programs | |
378 | @cindex indentation for programs | |
379 | ||
380 | The best way to keep a program properly indented is to use Emacs to | |
381 | reindent it as you change it. Emacs has commands to indent properly | |
382 | either a single line, a specified number of lines, or all of the lines | |
383 | inside a single parenthetical grouping. | |
384 | ||
385 | @menu | |
386 | * Basic Indent:: Indenting a single line. | |
387 | * Multi-line Indent:: Commands to reindent many lines at once. | |
388 | * Lisp Indent:: Specifying how each Lisp function should be indented. | |
389 | * C Indent:: Extra features for indenting C and related modes. | |
390 | * Custom C Indent:: Controlling indentation style for C and related modes. | |
391 | @end menu | |
392 | ||
393 | Emacs also provides a Lisp pretty-printer in the library @code{pp}. | |
394 | This program reformats a Lisp object with indentation chosen to look nice. | |
395 | ||
396 | @node Basic Indent | |
397 | @subsection Basic Program Indentation Commands | |
398 | ||
399 | @c WideCommands | |
400 | @table @kbd | |
401 | @item @key{TAB} | |
402 | Adjust indentation of current line. | |
403 | @item C-j | |
404 | Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
405 | @end table | |
406 | ||
407 | @kindex TAB @r{(programming modes)} | |
408 | @findex c-indent-line | |
409 | @findex lisp-indent-line | |
410 | The basic indentation command is @key{TAB}, which gives the current line | |
411 | the correct indentation as determined from the previous lines. The | |
412 | function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line} | |
413 | in Lisp mode, @code{c-indent-line} in C mode, etc. These functions | |
414 | understand different syntaxes for different languages, but they all do | |
415 | about the same thing. @key{TAB} in any programming-language major mode | |
416 | inserts or deletes whitespace at the beginning of the current line, | |
417 | independent of where point is in the line. If point is inside the | |
418 | whitespace at the beginning of the line, @key{TAB} leaves it at the end of | |
419 | that whitespace; otherwise, @key{TAB} leaves point fixed with respect to | |
420 | the characters around it. | |
421 | ||
422 | Use @kbd{C-q @key{TAB}} to insert a tab at point. | |
423 | ||
424 | @kindex C-j | |
425 | @findex newline-and-indent | |
426 | When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}), | |
427 | which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates | |
428 | a blank line and then gives it the appropriate indentation. | |
429 | ||
430 | @key{TAB} indents the second and following lines of the body of a | |
431 | parenthetical grouping each under the preceding one; therefore, if you | |
432 | alter one line's indentation to be nonstandard, the lines below will | |
433 | tend to follow it. This behavior is convenient in cases where you have | |
434 | overridden the standard result of @key{TAB} because you find it | |
435 | unaesthetic for a particular line. | |
436 | ||
437 | Remember that an open-parenthesis, open-brace or other opening delimiter | |
438 | at the left margin is assumed by Emacs (including the indentation routines) | |
439 | to be the start of a function. Therefore, you must never have an opening | |
440 | delimiter in column zero that is not the beginning of a function, not even | |
441 | inside a string. This restriction is vital for making the indentation | |
442 | commands fast; you must simply accept it. @xref{Defuns}, for more | |
443 | information on this. | |
444 | ||
445 | @node Multi-line Indent | |
446 | @subsection Indenting Several Lines | |
447 | ||
448 | When you wish to reindent several lines of code which have been altered | |
449 | or moved to a different level in the list structure, you have several | |
450 | commands available. | |
451 | ||
452 | @table @kbd | |
453 | @item C-M-q | |
454 | Reindent all the lines within one list (@code{indent-sexp}). | |
455 | @item C-u @key{TAB} | |
456 | Shift an entire list rigidly sideways so that its first line | |
457 | is properly indented. | |
458 | @item C-M-\ | |
459 | Reindent all lines in the region (@code{indent-region}). | |
460 | @end table | |
461 | ||
462 | @kindex C-M-q | |
463 | @findex indent-sexp | |
464 | You can reindent the contents of a single list by positioning point | |
465 | before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in | |
466 | Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable | |
467 | commands in other modes). The indentation of the line the sexp starts on | |
468 | is not changed; therefore, only the relative indentation within the list, | |
469 | and not its position, is changed. To correct the position as well, type a | |
470 | @key{TAB} before the @kbd{C-M-q}. | |
471 | ||
472 | @kindex C-u TAB | |
473 | If the relative indentation within a list is correct but the | |
474 | indentation of its first line is not, go to that line and type @kbd{C-u | |
475 | @key{TAB}}. @key{TAB} with a numeric argument reindents the current | |
476 | line as usual, then reindents by the same amount all the lines in the | |
477 | grouping starting on the current line. In other words, it reindents the | |
478 | whole grouping rigidly as a unit. It is clever, though, and does not | |
479 | alter lines that start inside strings, or C preprocessor lines when in C | |
480 | mode. | |
481 | ||
482 | Another way to specify the range to be reindented is with the region. | |
483 | The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to | |
484 | every line whose first character is between point and mark. | |
485 | ||
486 | @node Lisp Indent | |
487 | @subsection Customizing Lisp Indentation | |
488 | @cindex customizing Lisp indentation | |
489 | ||
490 | The indentation pattern for a Lisp expression can depend on the function | |
491 | called by the expression. For each Lisp function, you can choose among | |
492 | several predefined patterns of indentation, or define an arbitrary one with | |
493 | a Lisp program. | |
494 | ||
495 | The standard pattern of indentation is as follows: the second line of the | |
496 | expression is indented under the first argument, if that is on the same | |
497 | line as the beginning of the expression; otherwise, the second line is | |
498 | indented underneath the function name. Each following line is indented | |
499 | under the previous line whose nesting depth is the same. | |
500 | ||
501 | @vindex lisp-indent-offset | |
502 | If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides | |
503 | the usual indentation pattern for the second line of an expression, so that | |
504 | such lines are always indented @code{lisp-indent-offset} more columns than | |
505 | the containing list. | |
506 | ||
507 | @vindex lisp-body-indent | |
508 | The standard pattern is overridden for certain functions. Functions | |
509 | whose names start with @code{def} always indent the second line by | |
510 | @code{lisp-body-indent} extra columns beyond the open-parenthesis | |
511 | starting the expression. | |
512 | ||
513 | The standard pattern can be overridden in various ways for individual | |
514 | functions, according to the @code{lisp-indent-function} property of the | |
515 | function name. There are four possibilities for this property: | |
516 | ||
517 | @table @asis | |
518 | @item @code{nil} | |
519 | This is the same as no property; the standard indentation pattern is used. | |
520 | @item @code{defun} | |
521 | The pattern used for function names that start with @code{def} is used for | |
522 | this function also. | |
523 | @item a number, @var{number} | |
524 | The first @var{number} arguments of the function are | |
525 | @dfn{distinguished} arguments; the rest are considered the @dfn{body} | |
526 | of the expression. A line in the expression is indented according to | |
527 | whether the first argument on it is distinguished or not. If the | |
528 | argument is part of the body, the line is indented @code{lisp-body-indent} | |
529 | more columns than the open-parenthesis starting the containing | |
530 | expression. If the argument is distinguished and is either the first | |
531 | or second argument, it is indented @emph{twice} that many extra columns. | |
532 | If the argument is distinguished and not the first or second argument, | |
533 | the standard pattern is followed for that line. | |
534 | @item a symbol, @var{symbol} | |
535 | @var{symbol} should be a function name; that function is called to | |
536 | calculate the indentation of a line within this expression. The | |
537 | function receives two arguments: | |
538 | @table @asis | |
539 | @item @var{state} | |
540 | The value returned by @code{parse-partial-sexp} (a Lisp primitive for | |
541 | indentation and nesting computation) when it parses up to the | |
542 | beginning of this line. | |
543 | @item @var{pos} | |
544 | The position at which the line being indented begins. | |
545 | @end table | |
546 | @noindent | |
547 | It should return either a number, which is the number of columns of | |
548 | indentation for that line, or a list whose car is such a number. The | |
549 | difference between returning a number and returning a list is that a | |
550 | number says that all following lines at the same nesting level should | |
551 | be indented just like this one; a list says that following lines might | |
552 | call for different indentations. This makes a difference when the | |
553 | indentation is being computed by @kbd{C-M-q}; if the value is a | |
554 | number, @kbd{C-M-q} need not recalculate indentation for the following | |
555 | lines until the end of the list. | |
556 | @end table | |
557 | ||
558 | @node C Indent | |
559 | @subsection Commands for C Indentation | |
560 | ||
561 | Here are the commands for indentation in C mode and related modes: | |
562 | ||
563 | @table @code | |
564 | @item C-c C-q | |
565 | @kindex C-c C-q @r{(C mode)} | |
566 | @findex c-indent-defun | |
567 | Reindent the current top-level function definition or aggregate type | |
568 | declaration (@code{c-indent-defun}). | |
569 | ||
570 | @item C-M-q | |
571 | @kindex C-M-q @r{(C mode)} | |
572 | @findex c-indent-exp | |
573 | Reindent each line in the balanced expression that follows point | |
574 | (@code{c-indent-exp}). A prefix argument inhibits error checking and | |
575 | warning messages about invalid syntax. | |
576 | ||
577 | @item @key{TAB} | |
578 | @findex c-indent-command | |
579 | Reindent the current line, and/or in some cases insert a tab character | |
580 | (@code{c-indent-command}). | |
581 | ||
582 | If @code{c-tab-always-indent} is @code{t}, this command always reindents | |
583 | the current line and does nothing else. This is the default. | |
584 | ||
585 | If that variable is @code{nil}, this command reindents the current line | |
586 | only if point is at the left margin or in the line's indentation; | |
587 | otherwise, it inserts a tab (or the equivalent number of spaces, | |
588 | if @code{indent-tabs-mode} is @code{nil}). | |
589 | ||
590 | Any other value (not @code{nil} or @code{t}) means always reindent the | |
591 | line, and also insert a tab if within a comment, a string, or a | |
592 | preprocessor directive. | |
593 | ||
594 | @item C-u @key{TAB} | |
595 | Reindent the current line according to its syntax; also rigidly reindent | |
596 | any other lines of the expression that starts on the current line. | |
597 | @xref{Multi-line Indent}. | |
598 | @end table | |
599 | ||
600 | To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This | |
601 | first selects the whole buffer as the region, then reindents that | |
602 | region. | |
603 | ||
604 | To reindent the current block, use @kbd{C-M-u C-M-q}. This moves | |
605 | to the front of the block and then reindents it all. | |
606 | ||
607 | @node Custom C Indent | |
608 | @subsection Customizing C Indentation | |
609 | ||
610 | C mode and related modes use a simple yet flexible mechanism for | |
611 | customizing indentation. The mechanism works in two steps: first it | |
612 | classifies the line syntactically according to its contents and context; | |
613 | second, it associates each kind of syntactic construct with an | |
614 | indentation offset which you can customize. | |
615 | ||
616 | @menu | |
617 | * Syntactic Analysis:: | |
618 | * Indentation Calculation:: | |
619 | * Changing Indent Style:: | |
620 | * Syntactic Symbols:: | |
621 | * Variables for C Indent:: | |
622 | * C Indent Styles:: | |
623 | @end menu | |
624 | ||
625 | @node Syntactic Analysis | |
626 | @subsubsection Step 1---Syntactic Analysis | |
627 | @cindex syntactic analysis | |
628 | ||
629 | In the first step, the C indentation mechanism looks at the line | |
630 | before the one you are currently indenting and determines the syntactic | |
631 | components of the construct on that line. It builds a list of these | |
632 | syntactic components, each of which contains a @dfn{syntactic symbol} | |
633 | and sometimes also a buffer position. Some syntactic symbols describe | |
634 | grammatical elements, for example @code{statement} and | |
635 | @code{substatement}; others describe locations amidst grammatical | |
636 | elements, for example @code{class-open} and @code{knr-argdecl}. | |
637 | ||
638 | Conceptually, a line of C code is always indented relative to the | |
639 | indentation of some line higher up in the buffer. This is represented | |
640 | by the buffer positions in the syntactic component list. | |
641 | ||
642 | Here is an example. Suppose we have the following code in a C++ mode | |
643 | buffer (the line numbers don't actually appear in the buffer): | |
644 | ||
645 | @example | |
646 | 1: void swap (int& a, int& b) | |
647 | 2: @{ | |
648 | 3: int tmp = a; | |
649 | 4: a = b; | |
650 | 5: b = tmp; | |
651 | 6: @} | |
652 | @end example | |
653 | ||
654 | If you type @kbd{C-c C-s} (which runs the command | |
655 | @code{c-show-syntactic-information}) on line 4, it shows the result of | |
656 | the indentation mechanism for that line: | |
657 | ||
658 | @example | |
659 | ((statement . 32)) | |
660 | @end example | |
661 | ||
662 | This indicates that the line is a statement and it is indented | |
663 | relative to buffer position 32, which happens to be the @samp{i} in | |
664 | @code{int} on line 3. If you move the cursor to line 3 and type | |
665 | @kbd{C-c C-s}, it displays this: | |
666 | ||
667 | @example | |
668 | ((defun-block-intro . 28)) | |
669 | @end example | |
670 | ||
671 | This indicates that the @code{int} line is the first statement in a | |
672 | block, and is indented relative to buffer position 28, which is the | |
673 | brace just after the function header. | |
674 | ||
675 | @noindent | |
676 | Here is another example: | |
677 | ||
678 | @example | |
679 | 1: int add (int val, int incr, int doit) | |
680 | 2: @{ | |
681 | 3: if (doit) | |
682 | 4: @{ | |
683 | 5: return (val + incr); | |
684 | 6: @} | |
685 | 7: return (val); | |
686 | 8: @} | |
687 | @end example | |
688 | ||
689 | @noindent | |
690 | Typing @kbd{C-c C-s} on line 4 displays this: | |
691 | ||
692 | @example | |
693 | ((substatement-open . 43)) | |
694 | @end example | |
695 | ||
696 | This says that the brace @emph{opens} a substatement block. By the | |
697 | way, a @dfn{substatement} indicates the line after an @code{if}, | |
698 | @code{else}, @code{while}, @code{do}, @code{switch}, @code{for}, | |
699 | @code{try}, @code{catch}, @code{finally}, or @code{synchronized} | |
700 | statement. | |
701 | ||
702 | @cindex syntactic component | |
703 | @cindex syntactic symbol | |
704 | @vindex c-syntactic-context | |
705 | Within the C indentation commands, after a line has been analyzed | |
706 | syntactically for indentation, the variable @code{c-syntactic-context} | |
707 | contains a list that describes the results. Each element in this list | |
708 | is a @dfn{syntactic component}: a cons cell containing a syntactic | |
709 | symbol and (optionally) its corresponding buffer position. There may be | |
710 | several elements in a component list; typically only one element has a | |
711 | buffer position. | |
712 | ||
713 | @node Indentation Calculation | |
714 | @subsubsection Step 2---Indentation Calculation | |
715 | @cindex Indentation Calculation | |
716 | ||
717 | The C indentation mechanism calculates the indentation for the current | |
718 | line using the list of syntactic components, @code{c-syntactic-context}, | |
719 | derived from syntactic analysis. Each component is a cons cell that | |
720 | contains a syntactic symbol and may also contain a buffer position. | |
721 | ||
722 | Each component contributes to the final total indentation of the line | |
723 | in two ways. First, the syntactic symbol identifies an element of | |
724 | @code{c-offsets-alist}, which is an association list mapping syntactic | |
725 | symbols into indentation offsets. Each syntactic symbol's offset adds | |
726 | to the total indentation. Second, if the component includes a buffer | |
727 | position, the column number of that position adds to the indentation. | |
728 | All these offsets and column numbers, added together, give the total | |
729 | indentation. | |
730 | ||
731 | The following examples demonstrate the workings of the C indentation | |
732 | mechanism: | |
733 | ||
734 | @example | |
735 | 1: void swap (int& a, int& b) | |
736 | 2: @{ | |
737 | 3: int tmp = a; | |
738 | 4: a = b; | |
739 | 5: b = tmp; | |
740 | 6: @} | |
741 | @end example | |
742 | ||
743 | Suppose that point is on line 3 and you type @key{TAB} to reindent the | |
744 | line. As explained above (@pxref{Syntactic Analysis}), the syntactic | |
745 | component list for that line is: | |
746 | ||
747 | @example | |
748 | ((defun-block-intro . 28)) | |
749 | @end example | |
750 | ||
751 | In this case, the indentation calculation first looks up | |
752 | @code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose | |
753 | that it finds the integer 2; it adds this to the running total | |
754 | (initialized to zero), yielding a updated total indentation of 2 spaces. | |
755 | ||
756 | The next step is to find the column number of buffer position 28. | |
757 | Since the brace at buffer position 28 is in column zero, this adds 0 to | |
758 | the running total. Since this line has only one syntactic component, | |
759 | the total indentation for the line is 2 spaces. | |
760 | ||
761 | @example | |
762 | 1: int add (int val, int incr, int doit) | |
763 | 2: @{ | |
764 | 3: if (doit) | |
765 | 4: @{ | |
766 | 5: return(val + incr); | |
767 | 6: @} | |
768 | 7: return(val); | |
769 | 8: @} | |
770 | @end example | |
771 | ||
772 | If you type @key{TAB} on line 4, the same process is performed, but | |
773 | with different data. The syntactic component list for this line is: | |
774 | ||
775 | @example | |
776 | ((substatement-open . 43)) | |
777 | @end example | |
778 | ||
779 | Here, the indentation calculation's first job is to look up the | |
780 | symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume | |
781 | that the offset for this symbol is 2. At this point the running total | |
782 | is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43, | |
783 | which is the @samp{i} in @code{if} on line 3. This character is in | |
784 | column 2 on that line. Adding this yields a total indentation of 4 | |
785 | spaces. | |
786 | ||
787 | @vindex c-strict-syntax-p | |
788 | If a syntactic symbol in the analysis of a line does not appear in | |
789 | @code{c-offsets-alist}, it is ignored; if in addition the variable | |
790 | @code{c-strict-syntax-p} is non-@code{nil}, it is an error. | |
791 | ||
792 | @node Changing Indent Style | |
793 | @subsubsection Changing Indentation Style | |
794 | ||
795 | There are two ways to customize the indentation style for the C-like | |
796 | modes. First, you can select one of several predefined styles, each of | |
797 | which specifies offsets for all the syntactic symbols. For more | |
798 | flexibility, you can customize the handling of individual syntactic | |
799 | symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic | |
800 | symbols. | |
801 | ||
802 | @table @kbd | |
803 | @item M-x c-set-style @key{RET} @var{style} @key{RET} | |
804 | Select predefined indentation style @var{style}. Type @kbd{?} when | |
805 | entering @var{style} to see a list of supported styles; to find out what | |
806 | a style looks like, select it and reindent some C code. | |
807 | ||
808 | @item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET} | |
809 | Set the indentation offset for syntactic symbol @var{symbol} | |
810 | (@code{c-set-offset}). The second argument @var{offset} specifies the | |
811 | new indentation offset. | |
812 | @end table | |
813 | ||
814 | The @code{c-offsets-alist} variable controls the amount of | |
815 | indentation to give to each syntactic symbol. Its value is an | |
816 | association list, and each element of the list has the form | |
817 | @code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets | |
818 | for various syntactic symbols, you can customize indentation in fine | |
819 | detail. To change this alist, use @code{c-set-offset} (see below). | |
820 | ||
821 | Each offset value in @code{c-offsets-alist} can be an integer, a | |
822 | function or variable name, a list, or one of the following symbols: @code{+}, | |
823 | @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative | |
824 | multiples of the variable @code{c-basic-offset}. Thus, if you want to | |
825 | change the levels of indentation to be 3 spaces instead of 2 spaces, set | |
826 | @code{c-basic-offset} to 3. | |
827 | ||
828 | Using a function as the offset value provides the ultimate flexibility | |
829 | in customizing indentation. The function is called with a single | |
830 | argument containing the @code{cons} of the syntactic symbol and | |
831 | the buffer position, if any. The function should return an integer | |
832 | offset. | |
79214ddf | 833 | |
6bf7aab6 DL |
834 | If the offset value is a list, its elements are processed according |
835 | to the rules above until a non-@code{nil} value is found. That value is | |
836 | then added to the total indentation in the normal manner. The primary | |
837 | use for this is to combine the results of several functions. | |
838 | ||
839 | @kindex C-c C-o @r{(C mode)} | |
840 | @findex c-set-offset | |
841 | The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to | |
842 | set offsets, both interactively or in your @file{~/.emacs} file. First | |
843 | specify the syntactic symbol, then the offset you want. @xref{Syntactic | |
844 | Symbols}, for a list of valid syntactic symbols and their meanings. | |
845 | ||
846 | @node Syntactic Symbols | |
847 | @subsubsection Syntactic Symbols | |
848 | ||
849 | Here is a table of valid syntactic symbols for indentation in C and | |
850 | related modes, with their syntactic meanings. Normally, most of these | |
851 | symbols are assigned offsets in @code{c-offsets-alist}. | |
852 | ||
853 | @table @code | |
854 | @item string | |
855 | Inside a multi-line string. | |
856 | ||
857 | @item c | |
858 | Inside a multi-line C style block comment. | |
859 | ||
860 | @item defun-open | |
861 | On a brace that opens a function definition. | |
862 | ||
863 | @item defun-close | |
864 | On a brace that closes a function definition. | |
865 | ||
866 | @item defun-block-intro | |
867 | In the first line in a top-level defun. | |
868 | ||
869 | @item class-open | |
870 | On a brace that opens a class definition. | |
871 | ||
872 | @item class-close | |
873 | On a brace that closes a class definition. | |
874 | ||
875 | @item inline-open | |
876 | On a brace that opens an in-class inline method. | |
877 | ||
878 | @item inline-close | |
879 | On a brace that closes an in-class inline method. | |
880 | ||
881 | @item extern-lang-open | |
882 | On a brace that opens an external language block. | |
883 | ||
884 | @item extern-lang-close | |
885 | On a brace that closes an external language block. | |
886 | ||
887 | @item func-decl-cont | |
888 | The region between a function definition's argument list and the defun | |
889 | opening brace (excluding K&R function definitions). In C, you cannot | |
890 | put anything but whitespace and comments between them; in C++ and Java, | |
891 | @code{throws} declarations and other things can appear in this context. | |
892 | ||
893 | @item knr-argdecl-intro | |
894 | On the first line of a K&R C argument declaration. | |
895 | ||
896 | @item knr-argdecl | |
897 | In one of the subsequent lines in a K&R C argument declaration. | |
898 | ||
899 | @item topmost-intro | |
900 | On the first line in a topmost construct definition. | |
901 | ||
902 | @item topmost-intro-cont | |
903 | On the topmost definition continuation lines. | |
904 | ||
905 | @item member-init-intro | |
906 | On the first line in a member initialization list. | |
907 | ||
908 | @item member-init-cont | |
909 | On one of the subsequent member initialization list lines. | |
910 | ||
911 | @item inher-intro | |
912 | On the first line of a multiple inheritance list. | |
913 | ||
914 | @item inher-cont | |
915 | On one of the subsequent multiple inheritance lines. | |
916 | ||
917 | @item block-open | |
918 | On a statement block open brace. | |
919 | ||
920 | @item block-close | |
921 | On a statement block close brace. | |
922 | ||
923 | @item brace-list-open | |
924 | On the opening brace of an @code{enum} or @code{static} array list. | |
925 | ||
926 | @item brace-list-close | |
927 | On the closing brace of an @code{enum} or @code{static} array list. | |
928 | ||
929 | @item brace-list-intro | |
930 | On the first line in an @code{enum} or @code{static} array list. | |
931 | ||
932 | @item brace-list-entry | |
933 | On one of the subsequent lines in an @code{enum} or @code{static} array | |
934 | list. | |
935 | ||
936 | @item brace-entry-open | |
937 | On one of the subsequent lines in an @code{enum} or @code{static} array | |
938 | list, when the line begins with an open brace. | |
939 | ||
940 | @item statement | |
941 | On an ordinary statement. | |
942 | ||
943 | @item statement-cont | |
944 | On a continuation line of a statement. | |
945 | ||
946 | @item statement-block-intro | |
947 | On the first line in a new statement block. | |
948 | ||
949 | @item statement-case-intro | |
950 | On the first line in a @code{case} ``block.'' | |
951 | ||
952 | @item statement-case-open | |
953 | On the first line in a @code{case} block starting with brace. | |
954 | ||
955 | @item inexpr-statement | |
956 | On a statement block inside an expression. This is used for a GNU | |
957 | extension to the C language, and for Pike special functions that take a | |
958 | statement block as an argument. | |
959 | ||
960 | @item inexpr-class | |
961 | On a class definition inside an expression. This is used for anonymous | |
962 | classes and anonymous array initializers in Java. | |
963 | ||
964 | @item substatement | |
965 | On the first line after an @code{if}, @code{while}, @code{for}, | |
966 | @code{do}, or @code{else}. | |
967 | ||
968 | @item substatement-open | |
969 | On the brace that opens a substatement block. | |
970 | ||
971 | @item case-label | |
972 | On a @code{case} or @code{default} label. | |
973 | ||
974 | @item access-label | |
975 | On a C++ @code{private}, @code{protected}, or @code{public} access label. | |
976 | ||
977 | @item label | |
978 | On any ordinary label. | |
979 | ||
980 | @item do-while-closure | |
981 | On the @code{while} that ends a @code{do}-@code{while} construct. | |
982 | ||
983 | @item else-clause | |
984 | On the @code{else} of an @code{if}-@code{else} construct. | |
985 | ||
986 | @item catch-clause | |
987 | On the @code{catch} and @code{finally} lines in | |
988 | @code{try}@dots{}@code{catch} constructs in C++ and Java. | |
989 | ||
990 | @item comment-intro | |
991 | On a line containing only a comment introduction. | |
992 | ||
993 | @item arglist-intro | |
994 | On the first line in an argument list. | |
995 | ||
996 | @item arglist-cont | |
997 | On one of the subsequent argument list lines when no arguments follow on | |
998 | the same line as the arglist opening parenthesis. | |
999 | ||
1000 | @item arglist-cont-nonempty | |
1001 | On one of the subsequent argument list lines when at least one argument | |
1002 | follows on the same line as the arglist opening parenthesis. | |
1003 | ||
1004 | @item arglist-close | |
1005 | On the closing parenthesis of an argument list. | |
1006 | ||
1007 | @item stream-op | |
1008 | On one of the lines continuing a stream operator construct. | |
1009 | ||
1010 | @item inclass | |
1011 | On a construct that is nested inside a class definition. The | |
1012 | indentation is relative to the open brace of the class definition. | |
1013 | ||
1014 | @item inextern-lang | |
1015 | On a construct that is nested inside an external language block. | |
1016 | ||
1017 | @item inexpr-statement | |
1018 | On the first line of statement block inside an expression. This is used | |
1019 | for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}. | |
1020 | It is also used for the special functions that takes a statement block | |
1021 | as an argument in Pike. | |
1022 | ||
1023 | @item inexpr-class | |
1024 | On the first line of a class definition inside an expression. This is | |
1025 | used for anonymous classes and anonymous array initializers in Java. | |
1026 | ||
1027 | @item cpp-macro | |
1028 | On the start of a cpp macro. | |
1029 | ||
1030 | @item friend | |
1031 | On a C++ @code{friend} declaration. | |
1032 | ||
1033 | @item objc-method-intro | |
1034 | On the first line of an Objective-C method definition. | |
1035 | ||
1036 | @item objc-method-args-cont | |
1037 | On one of the lines continuing an Objective-C method definition. | |
1038 | ||
1039 | @item objc-method-call-cont | |
1040 | On one of the lines continuing an Objective-C method call. | |
1041 | ||
1042 | @item inlambda | |
1043 | Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only | |
1044 | used in Pike. | |
1045 | ||
1046 | @item lambda-intro-cont | |
1047 | On a line continuing the header of a lambda function, between the | |
1048 | @code{lambda} keyword and the function body. Only used in Pike. | |
1049 | @end table | |
1050 | ||
1051 | @node Variables for C Indent | |
1052 | @subsubsection Variables for C Indentation | |
1053 | ||
1054 | This section describes additional variables which control the | |
1055 | indentation behavior of C mode and related mode. | |
1056 | ||
1057 | @table @code | |
1058 | @item c-offsets-alist | |
1059 | @vindex c-offsets-alist | |
1060 | Association list of syntactic symbols and their indentation offsets. | |
1061 | You should not set this directly, only with @code{c-set-offset}. | |
1062 | @xref{Changing Indent Style}, for details. | |
1063 | ||
1064 | @item c-style-alist | |
1065 | @vindex c-style-alist | |
1066 | Variable for defining indentation styles; see below. | |
1067 | ||
1068 | @item c-basic-offset | |
1069 | @vindex c-basic-offset | |
1070 | Amount of basic offset used by @code{+} and @code{-} symbols in | |
79214ddf | 1071 | @code{c-offsets-alist}.@refill |
6bf7aab6 DL |
1072 | |
1073 | @item c-special-indent-hook | |
1074 | @vindex c-special-indent-hook | |
1075 | Hook for user-defined special indentation adjustments. This hook is | |
1076 | called after a line is indented by C mode and related modes. | |
1077 | @end table | |
1078 | ||
1079 | The variable @code{c-style-alist} specifies the predefined indentation | |
1080 | styles. Each element has form @code{(@var{name} | |
1081 | @var{variable-setting}@dots{})}, where @var{name} is the name of the | |
1082 | style. Each @var{variable-setting} has the form @code{(@var{variable} | |
1083 | . @var{value})}; @var{variable} is one of the customization variables | |
1084 | used by C mode, and @var{value} is the value for that variable when | |
1085 | using the selected style. | |
1086 | ||
1087 | When @var{variable} is @code{c-offsets-alist}, that is a special case: | |
1088 | @var{value} is appended to the front of the value of @code{c-offsets-alist} | |
1089 | instead of replacing that value outright. Therefore, it is not necessary | |
1090 | for @var{value} to specify each and every syntactic symbol---only those | |
1091 | for which the style differs from the default. | |
1092 | ||
1093 | The indentation of lines containing only comments is also affected by | |
1094 | the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}). | |
1095 | ||
1096 | @node C Indent Styles | |
1097 | @subsubsection C Indentation Styles | |
1098 | @cindex c indentation styles | |
1099 | ||
1100 | A @dfn{C style} is a collection of indentation style customizations. | |
1101 | Emacs comes with several predefined indentation styles for C and related | |
1102 | modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup}, | |
1103 | @code{linux}, @code{python}, @code{java}, @code{whitesmith}, | |
1104 | @code{ellemtel}, and @code{cc-mode}. The default style is @code{gnu}. | |
1105 | ||
1106 | @findex c-set-style | |
1107 | @vindex c-default-style | |
1108 | To choose the style you want, use the command @kbd{M-x c-set-style}. | |
1109 | Specify a style name as an argument (case is not significant in C style | |
1110 | names). The chosen style only affects newly visited buffers, not those | |
1111 | you are already editing. You can also set the variable | |
1112 | @code{c-default-style} to specify the style for various major modes. | |
1113 | Its value should be an alist, in which each element specifies one major | |
1114 | mode and which indentation style to use for it. For example, | |
1115 | ||
1116 | @example | |
1117 | (setq c-default-style | |
1118 | '((java-mode . "java") (other . "gnu"))) | |
1119 | @end example | |
1120 | ||
1121 | @noindent | |
1122 | specifies an explicit choice for Java mode, and the default @samp{gnu} | |
1123 | style for the other C-like modes. | |
1124 | ||
1125 | @findex c-add-style | |
1126 | To define a new C indentation style, call the function | |
1127 | @code{c-add-style}: | |
1128 | ||
1129 | @example | |
1130 | (c-add-style @var{name} @var{values} @var{use-now}) | |
1131 | @end example | |
1132 | ||
1133 | @noindent | |
1134 | Here @var{name} is the name of the new style (a string), and | |
1135 | @var{values} is an alist whose elements have the form | |
1136 | @code{(@var{variable} . @var{value})}. The variables you specify should | |
1137 | be among those documented in @ref{Variables for C Indent}. | |
1138 | ||
1139 | If @var{use-now} is non-@code{nil}, @code{c-add-style} switches to the | |
1140 | new style after defining it. | |
1141 | ||
1142 | @node Matching | |
1143 | @section Automatic Display Of Matching Parentheses | |
1144 | @cindex matching parentheses | |
1145 | @cindex parentheses, displaying matches | |
1146 | ||
1147 | The Emacs parenthesis-matching feature is designed to show | |
1148 | automatically how parentheses match in the text. Whenever you type a | |
1149 | self-inserting character that is a closing delimiter, the cursor moves | |
1150 | momentarily to the location of the matching opening delimiter, provided | |
1151 | that is on the screen. If it is not on the screen, some text near it is | |
1152 | displayed in the echo area. Either way, you can tell what grouping is | |
1153 | being closed off. | |
1154 | ||
1155 | In Lisp, automatic matching applies only to parentheses. In C, it | |
1156 | applies to braces and brackets too. Emacs knows which characters to regard | |
1157 | as matching delimiters based on the syntax table, which is set by the major | |
1158 | mode. @xref{Syntax}. | |
1159 | ||
1160 | If the opening delimiter and closing delimiter are mismatched---such as | |
1161 | in @samp{[x)}---a warning message is displayed in the echo area. The | |
1162 | correct matches are specified in the syntax table. | |
1163 | ||
1164 | @vindex blink-matching-paren | |
1165 | @vindex blink-matching-paren-distance | |
1166 | @vindex blink-matching-delay | |
1167 | Three variables control parenthesis match display. | |
1168 | @code{blink-matching-paren} turns the feature on or off; @code{nil} | |
1169 | turns it off, but the default is @code{t} to turn match display on. | |
1170 | @code{blink-matching-delay} says how many seconds to wait; the default | |
1171 | is 1, but on some systems it is useful to specify a fraction of a | |
1172 | second. @code{blink-matching-paren-distance} specifies how many | |
1173 | characters back to search to find the matching opening delimiter. If | |
1174 | the match is not found in that far, scanning stops, and nothing is | |
1175 | displayed. This is to prevent scanning for the matching delimiter from | |
1176 | wasting lots of time when there is no match. The default is 12,000. | |
1177 | ||
1178 | @cindex Show Paren mode | |
1179 | @findex show-paren-mode | |
1180 | When using X Windows, you can request a more powerful alternative kind | |
1181 | of automatic parenthesis matching by enabling Show Paren mode. This | |
1182 | mode turns off the usual kind of matching parenthesis display and | |
1183 | instead uses highlighting to show what matches. Whenever point is after | |
1184 | a close parenthesis, the close parenthesis and its matching open | |
1185 | parenthesis are both highlighted; otherwise, if point is before an open | |
1186 | parenthesis, the matching close parenthesis is highlighted. (There is | |
1187 | no need to highlight the open parenthesis after point because the cursor | |
1188 | appears on top of that character.) Use the command @kbd{M-x | |
1189 | show-paren-mode} to enable or disable this mode. | |
1190 | ||
1191 | @node Comments | |
1192 | @section Manipulating Comments | |
1193 | @cindex comments | |
1194 | ||
1195 | Because comments are such an important part of programming, Emacs | |
1196 | provides special commands for editing and inserting comments. | |
1197 | ||
1198 | @menu | |
1199 | * Comment Commands:: | |
1200 | * Multi-Line Comments:: | |
1201 | * Options for Comments:: | |
1202 | @end menu | |
1203 | ||
1204 | @node Comment Commands | |
1205 | @subsection Comment Commands | |
1206 | ||
1207 | @kindex M-; | |
1208 | @cindex indentation for comments | |
1209 | @findex indent-for-comment | |
1210 | ||
1211 | The comment commands insert, kill and align comments. | |
1212 | ||
1213 | @c WideCommands | |
1214 | @table @kbd | |
1215 | @item M-; | |
1216 | Insert or align comment (@code{indent-for-comment}). | |
1217 | @item C-x ; | |
1218 | Set comment column (@code{set-comment-column}). | |
1219 | @item C-u - C-x ; | |
1220 | Kill comment on current line (@code{kill-comment}). | |
1221 | @item C-M-j | |
1222 | Like @key{RET} followed by inserting and aligning a comment | |
1223 | (@code{indent-new-comment-line}). | |
1224 | @item M-x comment-region | |
1225 | Add or remove comment delimiters on all the lines in the region. | |
1226 | @end table | |
1227 | ||
1228 | The command that creates a comment is @kbd{M-;} (@code{indent-for-comment}). | |
1229 | If there is no comment already on the line, a new comment is created, | |
1230 | aligned at a specific column called the @dfn{comment column}. The comment | |
1231 | is created by inserting the string Emacs thinks comments should start with | |
1232 | (the value of @code{comment-start}; see below). Point is left after that | |
1233 | string. If the text of the line extends past the comment column, then the | |
1234 | indentation is done to a suitable boundary (usually, at least one space is | |
1235 | inserted). If the major mode has specified a string to terminate comments, | |
1236 | that is inserted after point, to keep the syntax valid. | |
1237 | ||
1238 | @kbd{M-;} can also be used to align an existing comment. If a line | |
1239 | already contains the string that starts comments, then @kbd{M-;} just moves | |
1240 | point after it and reindents it to the conventional place. Exception: | |
1241 | comments starting in column 0 are not moved. | |
1242 | ||
1243 | Some major modes have special rules for indenting certain kinds of | |
1244 | comments in certain contexts. For example, in Lisp code, comments which | |
1245 | start with two semicolons are indented as if they were lines of code, | |
1246 | instead of at the comment column. Comments which start with three | |
1247 | semicolons are supposed to start at the left margin. Emacs understands | |
1248 | these conventions by indenting a double-semicolon comment using @key{TAB}, | |
1249 | and by not changing the indentation of a triple-semicolon comment at all. | |
1250 | ||
1251 | @example | |
1252 | ;; This function is just an example | |
1253 | ;;; Here either two or three semicolons are appropriate. | |
1254 | (defun foo (x) | |
1255 | ;;; And now, the first part of the function: | |
1256 | ;; The following line adds one. | |
1257 | (1+ x)) ; This line adds one. | |
1258 | @end example | |
1259 | ||
1260 | In C code, a comment preceded on its line by nothing but whitespace | |
1261 | is indented like a line of code. | |
1262 | ||
1263 | Even when an existing comment is properly aligned, @kbd{M-;} is still | |
1264 | useful for moving directly to the start of the comment. | |
1265 | ||
1266 | @kindex C-u - C-x ; | |
1267 | @findex kill-comment | |
1268 | @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line, | |
1269 | if there is one. The indentation before the start of the comment is killed | |
1270 | as well. If there does not appear to be a comment in the line, nothing is | |
1271 | done. To reinsert the comment on another line, move to the end of that | |
1272 | line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that | |
1273 | @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column}) | |
1274 | with a negative argument. That command is programmed so that when it | |
1275 | receives a negative argument it calls @code{kill-comment}. However, | |
1276 | @code{kill-comment} is a valid command which you could bind directly to a | |
1277 | key if you wanted to. | |
1278 | ||
1279 | @node Multi-Line Comments | |
1280 | @subsection Multiple Lines of Comments | |
1281 | ||
1282 | @kindex C-M-j | |
1283 | @cindex blank lines in programs | |
1284 | @findex indent-new-comment-line | |
1285 | If you are typing a comment and wish to continue it on another line, | |
1286 | you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}). | |
1287 | This terminates the comment you are typing, creates a new blank line | |
1288 | afterward, and begins a new comment indented under the old one. When | |
1289 | Auto Fill mode is on, going past the fill column while typing a comment | |
1290 | causes the comment to be continued in just this fashion. If point is | |
1291 | not at the end of the line when @kbd{C-M-j} is typed, the text on | |
1292 | the rest of the line becomes part of the new comment line. | |
1293 | ||
1294 | @findex comment-region | |
1295 | To turn existing lines into comment lines, use the @kbd{M-x | |
1296 | comment-region} command. It adds comment delimiters to the lines that start | |
1297 | in the region, thus commenting them out. With a negative argument, it | |
1298 | does the opposite---it deletes comment delimiters from the lines in the | |
1299 | region. | |
1300 | ||
1301 | With a positive argument, @code{comment-region} duplicates the last | |
1302 | character of the comment start sequence it adds; the argument specifies | |
1303 | how many copies of the character to insert. Thus, in Lisp mode, | |
1304 | @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating | |
1305 | the comment delimiter is a way of calling attention to the comment. It | |
1306 | can also affect how the comment is indented. In Lisp, for proper | |
1307 | indentation, you should use an argument of two, if between defuns, and | |
1308 | three, if within a defun. | |
1309 | ||
1310 | @vindex comment-padding | |
1311 | The variable @code{comment-padding} specifies how many spaces | |
1312 | @code{comment-region} should insert on each line between the | |
1313 | comment delimiter and the line's original text. The default is 1. | |
1314 | ||
1315 | @node Options for Comments | |
1316 | @subsection Options Controlling Comments | |
1317 | ||
1318 | @vindex comment-column | |
1319 | @kindex C-x ; | |
1320 | @findex set-comment-column | |
1321 | The comment column is stored in the variable @code{comment-column}. You | |
1322 | can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} | |
1323 | (@code{set-comment-column}) sets the comment column to the column point is | |
1324 | at. @kbd{C-u C-x ;} sets the comment column to match the last comment | |
1325 | before point in the buffer, and then does a @kbd{M-;} to align the | |
1326 | current line's comment under the previous one. Note that @kbd{C-u - C-x ;} | |
1327 | runs the function @code{kill-comment} as described above. | |
1328 | ||
1329 | The variable @code{comment-column} is per-buffer: setting the variable | |
1330 | in the normal fashion affects only the current buffer, but there is a | |
1331 | default value which you can change with @code{setq-default}. | |
1332 | @xref{Locals}. Many major modes initialize this variable for the | |
1333 | current buffer. | |
1334 | ||
1335 | @vindex comment-start-skip | |
1336 | The comment commands recognize comments based on the regular | |
1337 | expression that is the value of the variable @code{comment-start-skip}. | |
1338 | Make sure this regexp does not match the null string. It may match more | |
1339 | than the comment starting delimiter in the strictest sense of the word; | |
1340 | for example, in C mode the value of the variable is @code{@t{"/\\*+ | |
1341 | *"}}, which matches extra stars and spaces after the @samp{/*} itself. | |
1342 | (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in | |
1343 | the string, which is needed to deny the first star its special meaning | |
1344 | in regexp syntax. @xref{Regexps}.) | |
1345 | ||
1346 | @vindex comment-start | |
1347 | @vindex comment-end | |
1348 | When a comment command makes a new comment, it inserts the value of | |
1349 | @code{comment-start} to begin it. The value of @code{comment-end} is | |
1350 | inserted after point, so that it will follow the text that you will insert | |
1351 | into the comment. In C mode, @code{comment-start} has the value | |
1352 | @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}. | |
1353 | ||
1354 | @vindex comment-multi-line | |
1355 | The variable @code{comment-multi-line} controls how @kbd{C-M-j} | |
1356 | (@code{indent-new-comment-line}) behaves when used inside a comment. If | |
1357 | @code{comment-multi-line} is @code{nil}, as it normally is, then the | |
1358 | comment on the starting line is terminated and a new comment is started | |
1359 | on the new following line. If @code{comment-multi-line} is not | |
1360 | @code{nil}, then the new following line is set up as part of the same | |
1361 | comment that was found on the starting line. This is done by not | |
1362 | inserting a terminator on the old line, and not inserting a starter on | |
1363 | the new line. In languages where multi-line comments work, the choice | |
1364 | of value for this variable is a matter of taste. | |
1365 | ||
1366 | @vindex comment-indent-function | |
1367 | The variable @code{comment-indent-function} should contain a function | |
1368 | that will be called to compute the indentation for a newly inserted | |
1369 | comment or for aligning an existing comment. It is set differently by | |
1370 | various major modes. The function is called with no arguments, but with | |
1371 | point at the beginning of the comment, or at the end of a line if a new | |
1372 | comment is to be inserted. It should return the column in which the | |
1373 | comment ought to start. For example, in Lisp mode, the indent hook | |
1374 | function bases its decision on how many semicolons begin an existing | |
1375 | comment, and on the code in the preceding lines. | |
1376 | ||
1377 | @node Balanced Editing | |
1378 | @section Editing Without Unbalanced Parentheses | |
1379 | ||
1380 | @table @kbd | |
1381 | @item M-( | |
1382 | Put parentheses around next sexp(s) (@code{insert-parentheses}). | |
1383 | @item M-) | |
1384 | Move past next close parenthesis and reindent | |
1385 | (@code{move-past-close-and-reindent}). | |
1386 | @end table | |
1387 | ||
1388 | @kindex M-( | |
1389 | @kindex M-) | |
1390 | @findex insert-parentheses | |
1391 | @findex move-past-close-and-reindent | |
1392 | The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)} | |
1393 | (@code{move-past-close-and-reindent}) are designed to facilitate a style | |
1394 | of editing which keeps parentheses balanced at all times. @kbd{M-(} | |
1395 | inserts a pair of parentheses, either together as in @samp{()}, or, if | |
1396 | given an argument, around the next several sexps. It leaves point after | |
1397 | the open parenthesis. The command @kbd{M-)} moves past the close | |
1398 | parenthesis, deleting any indentation preceding it, and indenting with | |
1399 | @kbd{C-j} after it. | |
1400 | ||
1401 | For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-( | |
1402 | F O O}, which has the same effect except for leaving the cursor before | |
1403 | the close parenthesis. | |
1404 | ||
1405 | @vindex parens-require-spaces | |
1406 | @kbd{M-(} may insert a space before the open parenthesis, depending on | |
1407 | the syntax class of the preceding character. Set | |
1408 | @code{parens-require-spaces} to @code{nil} value if you wish to inhibit | |
1409 | this. | |
1410 | ||
85750656 DL |
1411 | @findex check-parens |
1412 | You can use @kbd{M-x check-parens} to find any unbalanced parentheses in | |
1413 | a buffer. | |
1414 | ||
6bf7aab6 DL |
1415 | @node Symbol Completion |
1416 | @section Completion for Symbol Names | |
1417 | @cindex completion (symbol names) | |
1418 | ||
1419 | Usually completion happens in the minibuffer. But one kind of completion | |
1420 | is available in all buffers: completion for symbol names. | |
1421 | ||
1422 | @kindex M-TAB | |
1423 | The character @kbd{M-@key{TAB}} runs a command to complete the partial | |
1424 | symbol before point against the set of meaningful symbol names. Any | |
1425 | additional characters determined by the partial name are inserted at | |
1426 | point. | |
1427 | ||
1428 | If the partial name in the buffer has more than one possible completion | |
1429 | and they have no additional characters in common, a list of all possible | |
1430 | completions is displayed in another window. | |
1431 | ||
1432 | @cindex completion using tags | |
1433 | @cindex tags completion | |
1434 | @cindex Info index completion | |
1435 | @findex complete-symbol | |
1436 | In most programming language major modes, @kbd{M-@key{TAB}} runs the | |
1437 | command @code{complete-symbol}, which provides two kinds of completion. | |
1438 | Normally it does completion based on a tags table (@pxref{Tags}); with a | |
1439 | numeric argument (regardless of the value), it does completion based on | |
1440 | the names listed in the Info file indexes for your language. Thus, to | |
1441 | complete the name of a symbol defined in your own program, use | |
1442 | @kbd{M-@key{TAB}} with no argument; to complete the name of a standard | |
1443 | library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based | |
1444 | completion works only if there is an Info file for the standard library | |
1445 | functions of your language, and only if it is installed at your site. | |
1446 | ||
1447 | @cindex Lisp symbol completion | |
1448 | @cindex completion in Lisp | |
1449 | @findex lisp-complete-symbol | |
1450 | In Emacs-Lisp mode, the name space for completion normally consists of | |
1451 | nontrivial symbols present in Emacs---those that have function | |
1452 | definitions, values or properties. However, if there is an | |
1453 | open-parenthesis immediately before the beginning of the partial symbol, | |
1454 | only symbols with function definitions are considered as completions. | |
1455 | The command which implements this is @code{lisp-complete-symbol}. | |
1456 | ||
1457 | In Text mode and related modes, @kbd{M-@key{TAB}} completes words | |
1458 | based on the spell-checker's dictionary. @xref{Spelling}. | |
1459 | ||
1460 | @node Which Function | |
1461 | @section Which Function Mode | |
1462 | ||
1463 | Which Function mode is a minor mode that displays the current function | |
1464 | name in the mode line, as you move around in a buffer. | |
1465 | ||
1466 | @findex which-function-mode | |
1467 | @vindex which-func-modes | |
1468 | To enable (or disable) Which Function mode, use the command @kbd{M-x | |
1469 | which-function-mode}. This command is global; it applies to all | |
1470 | buffers, both existing ones and those yet to be created. However, this | |
1471 | only affects certain major modes, those listed in the value of | |
1472 | @code{which-func-modes}. (If the value is @code{t}, then Which Function | |
1473 | mode applies to all major modes that know how to support it---which are | |
1474 | the major modes that support Imenu.) | |
1475 | ||
51ed0ea0 DL |
1476 | @node Hideshow |
1477 | @section Hideshow minor mode | |
1478 | ||
1479 | @findex hs-minor-mode | |
1480 | Hideshow minor mode provides selective display of blocks. Use @kbd{M-x | |
1481 | hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the | |
1482 | hook for major modes with which you want to use it and which support it. | |
1483 | ||
1484 | Blocks are defined dependent on the mode. In C mode or C++ mode, they | |
1485 | are delimited by braces, while in Lisp-ish modes they are delimited by | |
1486 | parens. Multi-line comments can also be hidden. | |
1487 | ||
1488 | @findex hs-hide-all | |
1489 | @findex hs-hide-block | |
1490 | @findex hs-show-all | |
1491 | @findex hs-show-block | |
1492 | @findex hs-show-region | |
1493 | @findex hs-hide-level | |
1494 | @findex hs-minor-mode | |
1495 | @kindex C-c h | |
1496 | @kindex C-c s | |
1497 | @kindex C-c H | |
1498 | @kindex C-c S | |
1499 | @kindex C-c R | |
1500 | @kindex C-c L | |
1501 | @kindex S-mouse-2 | |
1502 | The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}), | |
1503 | @kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x | |
1504 | hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R} | |
1505 | (@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level}) | |
1506 | with obvious functions and @kbd{S-mouse-2} toggles hiding of a block | |
1507 | with the mouse. | |
1508 | ||
1509 | @vindex hs-hide-comments-when-hiding-all | |
1510 | @vindex hs-show-hidden-short-form | |
1511 | @vindex hs-isearch-open | |
1512 | @vindex hs-special-modes-alist | |
1513 | Hideshow is customized by the variables | |
1514 | @table @code | |
1515 | @item hs-hide-comments-when-hiding-all | |
1516 | Specifies whether @kbd{hs-hide-all} should hide comments too. | |
1517 | @item hs-show-hidden-short-form | |
1518 | Specifies whether or not the last line in a form is omitted (saving | |
1519 | screen space). | |
1520 | @item hs-isearch-open | |
1521 | Specifies what kind of hidden blocks to open in Isearch mode. | |
1522 | @item hs-special-modes-alist | |
1523 | Initializes Hideshow variables for different modes. | |
1524 | @end table | |
1525 | ||
1526 | @node Documentation, Change Log, Hideshow, Programs | |
6bf7aab6 DL |
1527 | @section Documentation Commands |
1528 | ||
1529 | As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f} | |
1530 | (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can | |
1531 | be used to print documentation of functions and variables that you want to | |
1532 | call. These commands use the minibuffer to read the name of a function or | |
1533 | variable to document, and display the documentation in a window. | |
1534 | ||
1535 | For extra convenience, these commands provide default arguments based on | |
1536 | the code in the neighborhood of point. @kbd{C-h f} sets the default to the | |
1537 | function called in the innermost list containing point. @kbd{C-h v} uses | |
1538 | the symbol name around or adjacent to point as its default. | |
1539 | ||
1540 | @cindex Eldoc mode | |
1541 | @findex eldoc-mode | |
1542 | For Emacs Lisp code, you can also use Eldoc mode. This minor mode | |
1543 | constantly displays in the echo area the argument list for the function | |
1544 | being called at point. (In other words, it finds the function call that | |
1545 | point is contained in, and displays the argument list of that function.) | |
1546 | Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use | |
1547 | the command @kbd{M-x eldoc-mode} to enable or disable this feature. | |
1548 | ||
1549 | @findex info-lookup-symbol | |
1550 | @findex info-lookup-file | |
1551 | @kindex C-h C-i | |
1552 | For C, Lisp, and other languages, you can use @kbd{C-h C-i} | |
1553 | (@code{info-lookup-symbol}) to view the Info documentation for a symbol. | |
1554 | You specify the symbol with the minibuffer; by default, it uses the | |
1555 | symbol that appears in the buffer at point. The major mode determines | |
1556 | where to look for documentation for the symbol---which Info files and | |
1557 | which indices. You can also use @kbd{M-x info-lookup-file} to look for | |
51ed0ea0 DL |
1558 | documentation for a file name. Currently the modes supported by |
1559 | Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4, | |
1560 | Makefile, Octave, Perl, Scheme and Texinfo. The relevant Info files | |
1561 | mostly must be obtained separately, typically from the appropriate GNU | |
1562 | package. | |
6bf7aab6 DL |
1563 | |
1564 | @findex manual-entry | |
1565 | You can read the ``man page'' for an operating system command, library | |
1566 | function, or system call, with the @kbd{M-x manual-entry} command. It | |
1567 | runs the @code{man} program to format the man page, and runs it | |
1568 | asynchronously if your system permits, so that you can keep on editing | |
1569 | while the page is being formatted. (MS-DOS and MS-Windows 3 do not | |
1570 | permit asynchronous subprocesses, so on these systems you cannot edit | |
1571 | while Emacs waits for @code{man} to exit.) The result goes in a buffer | |
1572 | named @samp{*Man @var{topic}*}. These buffers use a special major mode, | |
1573 | Man mode, that facilitates scrolling and examining other manual pages. | |
1574 | For details, type @kbd{C-h m} while in a man page buffer. | |
1575 | ||
1576 | @vindex Man-fontify-manpage-flag | |
1577 | For a long man page, setting the faces properly can take substantial | |
1578 | time. By default, Emacs uses faces in man pages if Emacs can display | |
1579 | different fonts or colors. You can turn off use of faces in man pages | |
1580 | by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}. | |
1581 | ||
1582 | @findex Man-fontify-manpage | |
1583 | If you insert the text of a man page into an Emacs buffer in some | |
1584 | other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to | |
1585 | perform the same conversions that @kbd{M-x manual-entry} does. | |
1586 | ||
1587 | Eventually the GNU project hopes to replace most man pages with | |
1588 | better-organized manuals that you can browse with Info. @xref{Misc | |
1589 | Help}. Since this process is only partially completed, it is still | |
1590 | useful to read manual pages. | |
1591 | ||
1592 | @node Change Log | |
1593 | @section Change Logs | |
1594 | ||
1595 | @cindex change log | |
1596 | @kindex C-x 4 a | |
1597 | @findex add-change-log-entry-other-window | |
1598 | The Emacs command @kbd{C-x 4 a} adds a new entry to the change log | |
1599 | file for the file you are editing | |
1600 | (@code{add-change-log-entry-other-window}). | |
1601 | ||
1602 | A change log file contains a chronological record of when and why you | |
1603 | have changed a program, consisting of a sequence of entries describing | |
1604 | individual changes. Normally it is kept in a file called | |
1605 | @file{ChangeLog} in the same directory as the file you are editing, or | |
1606 | one of its parent directories. A single @file{ChangeLog} file can | |
1607 | record changes for all the files in its directory and all its | |
1608 | subdirectories. | |
1609 | ||
1610 | A change log entry starts with a header line that contains your name, | |
1611 | your email address (taken from the variable @code{user-mail-address}), | |
1612 | and the current date and time. Aside from these header lines, every | |
1613 | line in the change log starts with a space or a tab. The bulk of the | |
1614 | entry consists of @dfn{items}, each of which starts with a line starting | |
1615 | with whitespace and a star. Here are two entries, both dated in May | |
1616 | 1993, each with two items: | |
1617 | ||
1618 | @iftex | |
1619 | @medbreak | |
1620 | @end iftex | |
1621 | @smallexample | |
1622 | 1993-05-25 Richard Stallman <rms@@gnu.org> | |
1623 | ||
1624 | * man.el: Rename symbols `man-*' to `Man-*'. | |
1625 | (manual-entry): Make prompt string clearer. | |
1626 | ||
1627 | * simple.el (blink-matching-paren-distance): | |
1628 | Change default to 12,000. | |
1629 | ||
1630 | 1993-05-24 Richard Stallman <rms@@gnu.org> | |
1631 | ||
1632 | * vc.el (minor-mode-map-alist): Don't use it if it's void. | |
1633 | (vc-cancel-version): Doc fix. | |
1634 | @end smallexample | |
1635 | ||
1636 | @noindent | |
1637 | (Previous Emacs versions used a different format for the date.) | |
1638 | ||
1639 | One entry can describe several changes; each change should have its | |
1640 | own item. Normally there should be a blank line between items. When | |
1641 | items are related (parts of the same change, in different places), group | |
1642 | them by leaving no blank line between them. The second entry above | |
1643 | contains two items grouped in this way. | |
1644 | ||
85750656 | 1645 | @vindex add-log-keep-changes-together |
6bf7aab6 DL |
1646 | @kbd{C-x 4 a} visits the change log file and creates a new entry |
1647 | unless the most recent entry is for today's date and your name. It also | |
1648 | creates a new item for the current file. For many languages, it can | |
1649 | even guess the name of the function or other object that was changed. | |
85750656 DL |
1650 | When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4 |
1651 | a} adds to any existing entry for the file rather than starting a new | |
1652 | entry. | |
6bf7aab6 DL |
1653 | |
1654 | @cindex Change Log mode | |
1655 | @findex change-log-mode | |
1656 | The change log file is visited in Change Log mode. In this major | |
1657 | mode, each bunch of grouped items counts as one paragraph, and each | |
1658 | entry is considered a page. This facilitates editing the entries. | |
1659 | @kbd{C-j} and auto-fill indent each new line like the previous line; | |
1660 | this is convenient for entering the contents of an entry. | |
1661 | ||
85750656 DL |
1662 | @findex change-log-merge |
1663 | The command @kbd{M-x change-log-merge} can be used to merge other log | |
1664 | files into a buffer in Change Log Mode, preserving the date ordering | |
1665 | of entries with either the current or old-style date formats. | |
1666 | ||
6bf7aab6 DL |
1667 | Version control systems are another way to keep track of changes in your |
1668 | program and keep a change log. @xref{Log Buffer}. | |
1669 | ||
1670 | @node Tags | |
1671 | @section Tags Tables | |
1672 | @cindex tags table | |
1673 | ||
1674 | A @dfn{tags table} is a description of how a multi-file program is | |
1675 | broken up into files. It lists the names of the component files and the | |
1676 | names and positions of the functions (or other named subunits) in each | |
1677 | file. Grouping the related files makes it possible to search or replace | |
1678 | through all the files with one command. Recording the function names | |
1679 | and positions makes possible the @kbd{M-.} command which finds the | |
1680 | definition of a function by looking up which of the files it is in. | |
1681 | ||
1682 | Tags tables are stored in files called @dfn{tags table files}. The | |
1683 | conventional name for a tags table file is @file{TAGS}. | |
1684 | ||
1685 | Each entry in the tags table records the name of one tag, the name of the | |
1686 | file that the tag is defined in (implicitly), and the position in that file | |
1687 | of the tag's definition. | |
1688 | ||
1689 | Just what names from the described files are recorded in the tags table | |
1690 | depends on the programming language of the described file. They | |
1691 | normally include all functions and subroutines, and may also include | |
1692 | global variables, data types, and anything else convenient. Each name | |
1693 | recorded is called a @dfn{tag}. | |
1694 | ||
1695 | @menu | |
79214ddf | 1696 | * Tag Syntax:: Tag syntax for various types of code and text files. |
6bf7aab6 | 1697 | * Create Tags Table:: Creating a tags table with @code{etags}. |
aca0be23 | 1698 | * Etags Regexps:: Create arbitrary tags using regular expressions. |
6bf7aab6 | 1699 | * Select Tags Table:: How to visit a tags table. |
79214ddf | 1700 | * Find Tag:: Commands to find the definition of a specific tag. |
6bf7aab6 DL |
1701 | * Tags Search:: Using a tags table for searching and replacing. |
1702 | * List Tags:: Listing and finding tags defined in a file. | |
1703 | @end menu | |
1704 | ||
1705 | @node Tag Syntax | |
1706 | @subsection Source File Tag Syntax | |
1707 | ||
1708 | Here is how tag syntax is defined for the most popular languages: | |
1709 | ||
1710 | @itemize @bullet | |
1711 | @item | |
1712 | In C code, any C function or typedef is a tag, and so are definitions of | |
79214ddf | 1713 | @code{struct}, @code{union} and @code{enum}. You can tag function |
8dc78b52 FP |
1714 | declarations and external variables in addition to function definitions |
1715 | by giving the @samp{--declarations} option to @code{etags}. | |
1716 | @code{#define} macro definitions and @code{enum} constants are also | |
1717 | tags, unless you specify @samp{--no-defines} when making the tags table. | |
1718 | Similarly, global variables are tags, unless you specify | |
1719 | @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines} | |
1720 | can make the tags table file much smaller. | |
6bf7aab6 DL |
1721 | |
1722 | @item | |
1723 | In C++ code, in addition to all the tag constructs of C code, member | |
1724 | functions are also recognized, and optionally member variables if you | |
1725 | use the @samp{--members} option. Tags for variables and functions in | |
1726 | classes are named @samp{@var{class}::@var{variable}} and | |
79214ddf FP |
1727 | @samp{@var{class}::@var{function}}. @code{operator} functions tags are |
1728 | named, for example @samp{operator+}. | |
6bf7aab6 DL |
1729 | |
1730 | @item | |
1731 | In Java code, tags include all the constructs recognized in C++, plus | |
79214ddf FP |
1732 | the @code{interface}, @code{extends} and @code{implements} constructs. |
1733 | Tags for variables and functions in classes are named | |
1734 | @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. | |
6bf7aab6 DL |
1735 | |
1736 | @item | |
1737 | In La@TeX{} text, the argument of any of the commands @code{\chapter}, | |
1738 | @code{\section}, @code{\subsection}, @code{\subsubsection}, | |
1739 | @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, | |
1740 | @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a | |
1741 | tag.@refill | |
1742 | ||
1743 | Other commands can make tags as well, if you specify them in the | |
1744 | environment variable @code{TEXTAGS} before invoking @code{etags}. The | |
1745 | value of this environment variable should be a colon-separated list of | |
1746 | command names. For example, | |
1747 | ||
1748 | @example | |
1749 | TEXTAGS="def:newcommand:newenvironment" | |
1750 | export TEXTAGS | |
1751 | @end example | |
1752 | ||
1753 | @noindent | |
1754 | specifies (using Bourne shell syntax) that the commands @samp{\def}, | |
1755 | @samp{\newcommand} and @samp{\newenvironment} also define tags. | |
1756 | ||
1757 | @item | |
1758 | In Lisp code, any function defined with @code{defun}, any variable | |
1759 | defined with @code{defvar} or @code{defconst}, and in general the first | |
1760 | argument of any expression that starts with @samp{(def} in column zero, is | |
1761 | a tag. | |
1762 | ||
1763 | @item | |
1764 | In Scheme code, tags include anything defined with @code{def} or with a | |
1765 | construct whose name starts with @samp{def}. They also include variables | |
1766 | set with @code{set!} at top level in the file. | |
1767 | @end itemize | |
1768 | ||
1769 | Several other languages are also supported: | |
1770 | ||
1771 | @itemize @bullet | |
79214ddf FP |
1772 | |
1773 | @item | |
8dc78b52 FP |
1774 | In Ada code, functions, procedures, packages, tasks, and types are |
1775 | tags. Use the @samp{--packages-only} option to create tags for packages | |
1776 | only. | |
79214ddf | 1777 | |
6bf7aab6 DL |
1778 | @item |
1779 | In assembler code, labels appearing at the beginning of a line, | |
1780 | followed by a colon, are tags. | |
1781 | ||
1782 | @item | |
1783 | In Bison or Yacc input files, each rule defines as a tag the nonterminal | |
1784 | it constructs. The portions of the file that contain C code are parsed | |
1785 | as C code. | |
1786 | ||
1787 | @item | |
1788 | In Cobol code, tags are paragraph names; that is, any word starting in | |
1789 | column 8 and followed by a period. | |
1790 | ||
1791 | @item | |
1792 | In Erlang code, the tags are the functions, records, and macros defined | |
1793 | in the file. | |
1794 | ||
1795 | @item | |
1796 | In Fortran code, functions, subroutines and blockdata are tags. | |
1797 | ||
1798 | @item | |
1799 | In Objective C code, tags include Objective C definitions for classes, | |
1800 | class categories, methods, and protocols. | |
1801 | ||
1802 | @item | |
1803 | In Pascal code, the tags are the functions and procedures defined in | |
1804 | the file. | |
1805 | ||
1806 | @item | |
79214ddf FP |
1807 | In Perl code, the tags are the procedures defined by the @code{sub}, |
1808 | @code{my} and @code{local} keywords. Use @samp{--globals} if you want | |
1809 | to tag global variables. | |
6bf7aab6 DL |
1810 | |
1811 | @item | |
85750656 | 1812 | In PostScript code, the tags are the functions. |
6bf7aab6 DL |
1813 | |
1814 | @item | |
1815 | In Prolog code, a tag name appears at the left margin. | |
6bf7aab6 | 1816 | |
79214ddf FP |
1817 | @item |
1818 | In Python code, @code{def} or @code{class} at the beginning of a line | |
1819 | generate a tag. | |
8dc78b52 | 1820 | @end itemize |
79214ddf | 1821 | |
c0e1bdfd | 1822 | You can also generate tags based on regexp matching (@pxref{Etags |
79214ddf | 1823 | Regexps}) to handle other formats and languages. |
6bf7aab6 DL |
1824 | |
1825 | @node Create Tags Table | |
1826 | @subsection Creating Tags Tables | |
1827 | @cindex @code{etags} program | |
1828 | ||
1829 | The @code{etags} program is used to create a tags table file. It knows | |
1830 | the syntax of several languages, as described in | |
1831 | @iftex | |
1832 | the previous section. | |
1833 | @end iftex | |
1834 | @ifinfo | |
1835 | @ref{Tag Syntax}. | |
1836 | @end ifinfo | |
1837 | Here is how to run @code{etags}: | |
1838 | ||
1839 | @example | |
1840 | etags @var{inputfiles}@dots{} | |
1841 | @end example | |
1842 | ||
1843 | @noindent | |
79214ddf FP |
1844 | The @code{etags} program reads the specified files, and writes a tags |
1845 | table named @file{TAGS} in the current working directory. You can | |
1846 | intermix compressed and plain text source file names. @code{etags} | |
1847 | knows about the most common compression formats, and does the right | |
1848 | thing. So you can compress all your source files and have @code{etags} | |
1849 | look for compressed versions of its file name arguments, if it does not | |
1850 | find uncompressed versions. Under MS-DOS, @code{etags} also looks for | |
1851 | file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the | |
1852 | command line and @samp{mycode.c} does not exist. | |
1853 | ||
1854 | @code{etags} recognizes the language used in an input file based on | |
1855 | its file name and contents. You can specify the language with the | |
6bf7aab6 DL |
1856 | @samp{--language=@var{name}} option, described below. |
1857 | ||
1858 | If the tags table data become outdated due to changes in the files | |
1859 | described in the table, the way to update the tags table is the same way it | |
1860 | was made in the first place. It is not necessary to do this often. | |
1861 | ||
1862 | If the tags table fails to record a tag, or records it for the wrong | |
1863 | file, then Emacs cannot possibly find its definition. However, if the | |
1864 | position recorded in the tags table becomes a little bit wrong (due to | |
1865 | some editing in the file that the tag definition is in), the only | |
1866 | consequence is a slight delay in finding the tag. Even if the stored | |
1867 | position is very wrong, Emacs will still find the tag, but it must | |
1868 | search the entire file for it. | |
1869 | ||
1870 | So you should update a tags table when you define new tags that you want | |
1871 | to have listed, or when you move tag definitions from one file to another, | |
1872 | or when changes become substantial. Normally there is no need to update | |
1873 | the tags table after each edit, or even every day. | |
1874 | ||
1875 | One tags table can effectively include another. Specify the included | |
1876 | tags file name with the @samp{--include=@var{file}} option when creating | |
1877 | the file that is to include it. The latter file then acts as if it | |
1878 | contained all the files specified in the included file, as well as the | |
1879 | files it directly contains. | |
1880 | ||
1881 | If you specify the source files with relative file names when you run | |
1882 | @code{etags}, the tags file will contain file names relative to the | |
1883 | directory where the tags file was initially written. This way, you can | |
1884 | move an entire directory tree containing both the tags file and the | |
1885 | source files, and the tags file will still refer correctly to the source | |
1886 | files. | |
1887 | ||
1888 | If you specify absolute file names as arguments to @code{etags}, then | |
1889 | the tags file will contain absolute file names. This way, the tags file | |
1890 | will still refer to the same files even if you move it, as long as the | |
1891 | source files remain in the same place. Absolute file names start with | |
1892 | @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. | |
1893 | ||
1894 | When you want to make a tags table from a great number of files, you | |
1895 | may have problems listing them on the command line, because some systems | |
1896 | have a limit on its length. The simplest way to circumvent this limit | |
1897 | is to tell @code{etags} to read the file names from its standard input, | |
1898 | by typing a dash in place of the file names, like this: | |
1899 | ||
aca0be23 | 1900 | @smallexample |
6bf7aab6 | 1901 | find . -name "*.[chCH]" -print | etags - |
aca0be23 | 1902 | @end smallexample |
6bf7aab6 DL |
1903 | |
1904 | Use the option @samp{--language=@var{name}} to specify the language | |
1905 | explicitly. You can intermix these options with file names; each one | |
1906 | applies to the file names that follow it. Specify | |
1907 | @samp{--language=auto} to tell @code{etags} to resume guessing the | |
1908 | language from the file names and file contents. Specify | |
1909 | @samp{--language=none} to turn off language-specific processing | |
79214ddf | 1910 | entirely; then @code{etags} recognizes tags by regexp matching alone |
aca0be23 FP |
1911 | (@pxref{Etags Regexps}). |
1912 | ||
1913 | @samp{etags --help} prints the list of the languages @code{etags} | |
1914 | knows, and the file name rules for guessing the language. It also prints | |
1915 | a list of all the available @code{etags} options, together with a short | |
1916 | explanation. | |
79214ddf | 1917 | |
aca0be23 FP |
1918 | @node Etags Regexps |
1919 | @subsection Etags Regexps | |
6bf7aab6 DL |
1920 | |
1921 | The @samp{--regex} option provides a general way of recognizing tags | |
1922 | based on regexp matching. You can freely intermix it with file names. | |
1923 | Each @samp{--regex} option adds to the preceding ones, and applies only | |
1924 | to the following files. The syntax is: | |
1925 | ||
aca0be23 | 1926 | @smallexample |
6bf7aab6 | 1927 | --regex=/@var{tagregexp}[/@var{nameregexp}]/ |
aca0be23 | 1928 | @end smallexample |
79214ddf | 1929 | |
6bf7aab6 | 1930 | @noindent |
aca0be23 FP |
1931 | where @var{tagregexp} is used to match the lines to tag. It is always |
1932 | anchored, that is, it behaves as if preceded by @samp{^}. If you want | |
1933 | to account for indentation, just match any initial number of blanks by | |
1934 | beginning your regular expression with @samp{[ \t]*}. In the regular | |
1935 | expressions, @samp{\} quotes the next character, and @samp{\t} stands | |
1936 | for the tab character. Note that @code{etags} does not handle the other | |
1937 | C escape sequences for special characters. | |
6bf7aab6 DL |
1938 | |
1939 | @cindex interval operator (in regexps) | |
1940 | The syntax of regular expressions in @code{etags} is the same as in | |
1941 | Emacs, augmented with the @dfn{interval operator}, which works as in | |
1942 | @code{grep} and @code{ed}. The syntax of an interval operator is | |
1943 | @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding | |
1944 | expression at least @var{m} times and up to @var{n} times. | |
1945 | ||
1946 | You should not match more characters with @var{tagregexp} than that | |
1947 | needed to recognize what you want to tag. If the match is such that | |
138a8f12 DL |
1948 | more characters than needed are unavoidably matched by @var{tagregexp} |
1949 | (as will usually be the case), you should add a @var{nameregexp}, to | |
1950 | pick out just the tag. This will enable Emacs to find tags more | |
1951 | accurately and to do completion on tag names more reliably. You can | |
1952 | find some examples below. | |
1953 | ||
aca0be23 | 1954 | The option @samp{--ignore-case-regex} (or @samp{-c}) is like |
138a8f12 | 1955 | @samp{--regex}, except that the regular expression provided will be |
aca0be23 FP |
1956 | matched without regard to case, which is appropriate for various |
1957 | programming languages. | |
6bf7aab6 DL |
1958 | |
1959 | The @samp{-R} option deletes all the regexps defined with | |
1960 | @samp{--regex} options. It applies to the file names following it, as | |
1961 | you can see from the following example: | |
1962 | ||
aca0be23 | 1963 | @smallexample |
6bf7aab6 DL |
1964 | etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \ |
1965 | bar.ber -R --lang=lisp los.er | |
aca0be23 | 1966 | @end smallexample |
6bf7aab6 DL |
1967 | |
1968 | @noindent | |
1969 | Here @code{etags} chooses the parsing language for @file{voo.doo} and | |
1970 | @file{bar.ber} according to their contents. @code{etags} also uses | |
1971 | @var{reg1} to recognize additional tags in @file{voo.doo}, and both | |
1972 | @var{reg1} and @var{reg2} to recognize additional tags in | |
1973 | @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp | |
1974 | matching, to recognize tags in @file{los.er}. | |
1975 | ||
aca0be23 FP |
1976 | A regular expression can be bound to a given language, by prepending |
1977 | it with @samp{@{lang@}}. When you do this, @code{etags} will use the | |
1978 | regular expression only for files of that language. @samp{etags --help} | |
1979 | prints the list of languages recognised by @code{etags}. The following | |
1980 | example tags the @code{DEFVAR} macros in the Emacs source files. | |
1981 | @code{etags} applies this regular expression to C files only: | |
6bf7aab6 | 1982 | |
aca0be23 FP |
1983 | @smallexample |
1984 | --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' | |
1985 | @end smallexample | |
1986 | ||
1987 | @noindent | |
1988 | This feature is particularly useful when storing a list of regular | |
1989 | expressions in a file. The following option syntax instructs | |
1990 | @code{etags} to read two files of regular expressions. The regular | |
1991 | expressions contained in the second file are matched without regard to | |
1992 | case. | |
1993 | ||
1994 | @smallexample | |
1995 | --regex=@@first-file --ignore-case-regex=@@second-file | |
1996 | @end smallexample | |
1997 | ||
1998 | @noindent | |
1999 | A regex file contains one regular expressions per line. Empty lines, | |
2000 | and lines beginning with space or tab are ignored. When the first | |
2001 | character in a line is @samp{@@}, @code{etags} assumes that the rest of | |
2002 | the line is the name of a file of regular expressions. This means that | |
2003 | such files can be nested. All the other lines are taken to be regular | |
2004 | expressions. For example, one can create a file called | |
2005 | @samp{emacs.tags} with the following contents (the first line in the | |
2006 | file is a comment): | |
2007 | ||
2008 | @smallexample | |
2009 | -- This is for GNU Emacs source files | |
2010 | @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ | |
2011 | @end smallexample | |
2012 | ||
2013 | @noindent | |
2014 | and then use it like this: | |
6bf7aab6 DL |
2015 | |
2016 | @smallexample | |
aca0be23 | 2017 | etags --regex=@@emacs.tags *.[ch] */*.[ch] |
6bf7aab6 DL |
2018 | @end smallexample |
2019 | ||
aca0be23 FP |
2020 | Here are some more examples. The regexps are quoted to protect them |
2021 | from shell interpretation. | |
2022 | ||
2023 | @itemize @bullet | |
2024 | ||
6bf7aab6 | 2025 | @item |
8dc78b52 | 2026 | Tag Octave files: |
6bf7aab6 DL |
2027 | |
2028 | @smallexample | |
8dc78b52 FP |
2029 | etags --language=none \ |
2030 | --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ | |
2031 | --regex='/###key \(.*\)/\1/' \ | |
2032 | --regex='/[ \t]*global[ \t].*/' \ | |
2033 | *.m | |
6bf7aab6 DL |
2034 | @end smallexample |
2035 | ||
8dc78b52 FP |
2036 | @noindent |
2037 | Note that tags are not generated for scripts so that you have to add a | |
2038 | line by yourself of the form `###key <script-name>' if you want to jump | |
2039 | to it. | |
2040 | ||
6bf7aab6 | 2041 | @item |
8dc78b52 | 2042 | Tag Tcl files: |
6bf7aab6 DL |
2043 | |
2044 | @smallexample | |
8dc78b52 FP |
2045 | etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl |
2046 | @end smallexample | |
2047 | ||
2048 | @item | |
2049 | Tag VHDL files: | |
2050 | ||
2051 | @smallexample | |
2052 | --language=none \ | |
2053 | --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ | |
2054 | --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ | |
2055 | \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' | |
6bf7aab6 DL |
2056 | @end smallexample |
2057 | @end itemize | |
2058 | ||
6bf7aab6 DL |
2059 | @node Select Tags Table |
2060 | @subsection Selecting a Tags Table | |
2061 | ||
2062 | @vindex tags-file-name | |
2063 | @findex visit-tags-table | |
2064 | Emacs has at any time one @dfn{selected} tags table, and all the commands | |
2065 | for working with tags tables use the selected one. To select a tags table, | |
2066 | type @kbd{M-x visit-tags-table}, which reads the tags table file name as an | |
2067 | argument. The name @file{TAGS} in the default directory is used as the | |
2068 | default file name. | |
2069 | ||
2070 | All this command does is store the file name in the variable | |
2071 | @code{tags-file-name}. Emacs does not actually read in the tags table | |
2072 | contents until you try to use them. Setting this variable yourself is just | |
2073 | as good as using @code{visit-tags-table}. The variable's initial value is | |
2074 | @code{nil}; that value tells all the commands for working with tags tables | |
2075 | that they must ask for a tags table file name to use. | |
2076 | ||
2077 | Using @code{visit-tags-table} when a tags table is already loaded | |
2078 | gives you a choice: you can add the new tags table to the current list | |
2079 | of tags tables, or start a new list. The tags commands use all the tags | |
2080 | tables in the current list. If you start a new list, the new tags table | |
2081 | is used @emph{instead} of others. If you add the new table to the | |
2082 | current list, it is used @emph{as well as} the others. When the tags | |
2083 | commands scan the list of tags tables, they don't always start at the | |
2084 | beginning of the list; they start with the first tags table (if any) | |
2085 | that describes the current file, proceed from there to the end of the | |
2086 | list, and then scan from the beginning of the list until they have | |
2087 | covered all the tables in the list. | |
2088 | ||
2089 | @vindex tags-table-list | |
2090 | You can specify a precise list of tags tables by setting the variable | |
2091 | @code{tags-table-list} to a list of strings, like this: | |
2092 | ||
2093 | @c keep this on two lines for formatting in smallbook | |
2094 | @example | |
2095 | @group | |
2096 | (setq tags-table-list | |
2097 | '("~/emacs" "/usr/local/lib/emacs/src")) | |
2098 | @end group | |
2099 | @end example | |
2100 | ||
2101 | @noindent | |
2102 | This tells the tags commands to look at the @file{TAGS} files in your | |
2103 | @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} | |
2104 | directory. The order depends on which file you are in and which tags | |
2105 | table mentions that file, as explained above. | |
2106 | ||
2107 | Do not set both @code{tags-file-name} and @code{tags-table-list}. | |
2108 | ||
2109 | @node Find Tag | |
2110 | @subsection Finding a Tag | |
2111 | ||
2112 | The most important thing that a tags table enables you to do is to find | |
2113 | the definition of a specific tag. | |
2114 | ||
2115 | @table @kbd | |
2116 | @item M-.@: @var{tag} @key{RET} | |
2117 | Find first definition of @var{tag} (@code{find-tag}). | |
2118 | @item C-u M-. | |
2119 | Find next alternate definition of last tag specified. | |
2120 | @item C-u - M-. | |
2121 | Go back to previous tag found. | |
2122 | @item C-M-. @var{pattern} @key{RET} | |
2123 | Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). | |
2124 | @item C-u C-M-. | |
2125 | Find the next tag whose name matches the last pattern used. | |
2126 | @item C-x 4 .@: @var{tag} @key{RET} | |
2127 | Find first definition of @var{tag}, but display it in another window | |
2128 | (@code{find-tag-other-window}). | |
2129 | @item C-x 5 .@: @var{tag} @key{RET} | |
2130 | Find first definition of @var{tag}, and create a new frame to select the | |
2131 | buffer (@code{find-tag-other-frame}). | |
2132 | @item M-* | |
2133 | Pop back to where you previously invoked @kbd{M-.} and friends. | |
2134 | @end table | |
2135 | ||
2136 | @kindex M-. | |
2137 | @findex find-tag | |
2138 | @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of | |
2139 | a specified tag. It searches through the tags table for that tag, as a | |
2140 | string, and then uses the tags table info to determine the file that the | |
2141 | definition is in and the approximate character position in the file of | |
2142 | the definition. Then @code{find-tag} visits that file, moves point to | |
2143 | the approximate character position, and searches ever-increasing | |
2144 | distances away to find the tag definition. | |
2145 | ||
2146 | If an empty argument is given (just type @key{RET}), the sexp in the | |
2147 | buffer before or around point is used as the @var{tag} argument. | |
2148 | @xref{Lists}, for info on sexps. | |
2149 | ||
2150 | You don't need to give @kbd{M-.} the full name of the tag; a part | |
2151 | will do. This is because @kbd{M-.} finds tags in the table which | |
2152 | contain @var{tag} as a substring. However, it prefers an exact match | |
2153 | to a substring match. To find other tags that match the same | |
2154 | substring, give @code{find-tag} a numeric argument, as in @kbd{C-u | |
2155 | M-.}; this does not read a tag name, but continues searching the tags | |
2156 | table's text for another tag containing the same substring last used. | |
2157 | If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier | |
2158 | alternative to @kbd{C-u M-.}. | |
2159 | ||
2160 | @kindex C-x 4 . | |
2161 | @findex find-tag-other-window | |
2162 | @kindex C-x 5 . | |
2163 | @findex find-tag-other-frame | |
2164 | Like most commands that can switch buffers, @code{find-tag} has a | |
2165 | variant that displays the new buffer in another window, and one that | |
2166 | makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes | |
2167 | the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .}, | |
2168 | which invokes @code{find-tag-other-frame}. | |
2169 | ||
2170 | To move back to places you've found tags recently, use @kbd{C-u - | |
2171 | M-.}; more generally, @kbd{M-.} with a negative numeric argument. This | |
2172 | command can take you to another buffer. @kbd{C-x 4 .} with a negative | |
2173 | argument finds the previous tag location in another window. | |
2174 | ||
2175 | @kindex M-* | |
2176 | @findex pop-tag-mark | |
2177 | @vindex find-tag-marker-ring-length | |
2178 | As well as going back to places you've found tags recently, you can go | |
2179 | back to places @emph{from where} you found them. Use @kbd{M-*}, which | |
2180 | invokes the command @code{pop-tag-mark}, for this. Typically you would | |
2181 | find and study the definition of something with @kbd{M-.} and then | |
2182 | return to where you were with @kbd{M-*}. | |
2183 | ||
2184 | Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to | |
2185 | a depth determined by the variable @code{find-tag-marker-ring-length}. | |
2186 | ||
2187 | @findex find-tag-regexp | |
2188 | @kindex C-M-. | |
2189 | The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that | |
2190 | match a specified regular expression. It is just like @kbd{M-.} except | |
2191 | that it does regexp matching instead of substring matching. | |
2192 | ||
2193 | @node Tags Search | |
2194 | @subsection Searching and Replacing with Tags Tables | |
2195 | ||
2196 | The commands in this section visit and search all the files listed in the | |
2197 | selected tags table, one by one. For these commands, the tags table serves | |
2198 | only to specify a sequence of files to search. | |
2199 | ||
2200 | @table @kbd | |
2201 | @item M-x tags-search @key{RET} @var{regexp} @key{RET} | |
2202 | Search for @var{regexp} through the files in the selected tags | |
2203 | table. | |
2204 | @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} | |
2205 | Perform a @code{query-replace-regexp} on each file in the selected tags table. | |
2206 | @item M-, | |
2207 | Restart one of the commands above, from the current location of point | |
2208 | (@code{tags-loop-continue}). | |
2209 | @end table | |
2210 | ||
2211 | @findex tags-search | |
2212 | @kbd{M-x tags-search} reads a regexp using the minibuffer, then | |
2213 | searches for matches in all the files in the selected tags table, one | |
2214 | file at a time. It displays the name of the file being searched so you | |
2215 | can follow its progress. As soon as it finds an occurrence, | |
2216 | @code{tags-search} returns. | |
2217 | ||
2218 | @kindex M-, | |
2219 | @findex tags-loop-continue | |
2220 | Having found one match, you probably want to find all the rest. To find | |
2221 | one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the | |
2222 | @code{tags-search}. This searches the rest of the current buffer, followed | |
2223 | by the remaining files of the tags table.@refill | |
2224 | ||
2225 | @findex tags-query-replace | |
2226 | @kbd{M-x tags-query-replace} performs a single | |
2227 | @code{query-replace-regexp} through all the files in the tags table. It | |
2228 | reads a regexp to search for and a string to replace with, just like | |
2229 | ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x | |
2230 | tags-search}, but repeatedly, processing matches according to your | |
2231 | input. @xref{Replace}, for more information on query replace. | |
2232 | ||
2233 | It is possible to get through all the files in the tags table with a | |
2234 | single invocation of @kbd{M-x tags-query-replace}. But often it is | |
2235 | useful to exit temporarily, which you can do with any input event that | |
2236 | has no special query replace meaning. You can resume the query replace | |
2237 | subsequently by typing @kbd{M-,}; this command resumes the last tags | |
2238 | search or replace command that you did. | |
2239 | ||
2240 | The commands in this section carry out much broader searches than the | |
2241 | @code{find-tag} family. The @code{find-tag} commands search only for | |
2242 | definitions of tags that match your substring or regexp. The commands | |
2243 | @code{tags-search} and @code{tags-query-replace} find every occurrence | |
2244 | of the regexp, as ordinary search commands and replace commands do in | |
2245 | the current buffer. | |
2246 | ||
2247 | These commands create buffers only temporarily for the files that they | |
2248 | have to search (those which are not already visited in Emacs buffers). | |
2249 | Buffers in which no match is found are quickly killed; the others | |
2250 | continue to exist. | |
2251 | ||
2252 | It may have struck you that @code{tags-search} is a lot like | |
2253 | @code{grep}. You can also run @code{grep} itself as an inferior of | |
2254 | Emacs and have Emacs show you the matching lines one by one. This works | |
2255 | much like running a compilation; finding the source locations of the | |
2256 | @code{grep} matches works like finding the compilation errors. | |
2257 | @xref{Compilation}. | |
79214ddf | 2258 | |
6bf7aab6 DL |
2259 | @node List Tags |
2260 | @subsection Tags Table Inquiries | |
2261 | ||
2262 | @table @kbd | |
2263 | @item M-x list-tags @key{RET} @var{file} @key{RET} | |
2264 | Display a list of the tags defined in the program file @var{file}. | |
2265 | @item M-x tags-apropos @key{RET} @var{regexp} @key{RET} | |
2266 | Display a list of all tags matching @var{regexp}. | |
2267 | @end table | |
2268 | ||
2269 | @findex list-tags | |
2270 | @kbd{M-x list-tags} reads the name of one of the files described by | |
2271 | the selected tags table, and displays a list of all the tags defined in | |
2272 | that file. The ``file name'' argument is really just a string to | |
2273 | compare against the file names recorded in the tags table; it is read as | |
2274 | a string rather than as a file name. Therefore, completion and | |
2275 | defaulting are not available, and you must enter the file name the same | |
2276 | way it appears in the tags table. Do not include a directory as part of | |
2277 | the file name unless the file name recorded in the tags table includes a | |
2278 | directory. | |
2279 | ||
2280 | @findex tags-apropos | |
2281 | @kbd{M-x tags-apropos} is like @code{apropos} for tags | |
2282 | (@pxref{Apropos}). It reads a regexp, then finds all the tags in the | |
2283 | selected tags table whose entries match that regexp, and displays the | |
2284 | tag names found. | |
85750656 DL |
2285 | @vindex tags-apropos-additional-actions |
2286 | You can display additional output with @kbd{M-x tags-apropos} by customizing | |
2287 | the variable @code{tags-apropos-additional-actions}. See its | |
2288 | documentation for details. | |
6bf7aab6 DL |
2289 | |
2290 | You can also perform completion in the buffer on the name space of tag | |
2291 | names in the current tags tables. @xref{Symbol Completion}. | |
2292 | ||
51ed0ea0 DL |
2293 | @node Imenu |
2294 | @section Imenu | |
2295 | @cindex indexes of buffer contents | |
2296 | @cindex buffer content indexes | |
2297 | @cindex tags | |
2298 | ||
2299 | The Imenu package provides mode-specific indexes of the contents of | |
2300 | single buffers and provides selection from a menu. Selecting a menu | |
2301 | item takes you to the indexed point in the buffer, in a similar way to | |
2302 | the Tags facility. Indexing is typically by names of program routines | |
2303 | and variables but in Texinfo mode, for instance, node names are indexed. | |
2304 | Most major modes for which it is appropriate have Imenu support. | |
2305 | ||
2306 | @findex imenu | |
2307 | @findex imenu-add-menu-bar-index | |
2308 | @kbd{M-x imenu} builds the index if necessary and presents you with an | |
2309 | electric buffer menu from which to select an entry (with completion). | |
2310 | You can add an index menubar on the menubar with | |
2311 | @kbd{imenu-add-menu-bar-index}. | |
2312 | ||
2313 | Some major modes provide facilities for invoking Imenu; otherwise you | |
2314 | could add @code{imenu-add-menu-bar-index} to a major mode's hook to | |
2315 | generate an index for each buffer created in that mode. (If you do | |
2316 | that, it takes sime time to generate the index when finding a file, | |
2317 | depending on the file's size and the complexity of the indexing function | |
2318 | for that mode.) | |
2319 | ||
2320 | @vindex imenu-auto-rescan | |
2321 | The index should be regenerated (via the @samp{*Rescan*} menu item) when | |
2322 | indexable items are added to or deleted from the buffer. Rescanning is | |
2323 | done when a menu selction is requested if the option | |
2324 | @code{imenu-auto-rescan} is set. By default buffer positions are in | |
2325 | terms of markers, so that changing non-indexable text doesn't require | |
2326 | rescanning. | |
2327 | ||
2328 | @vindex imenu-sort-function | |
2329 | The way the menus are sorted can be customized via the option | |
2330 | @code{imenu-sort-function}. By default names are ordered as they occur | |
2331 | in the buffer; alphabetic sorting is provided as an alternative. | |
2332 | ||
2333 | Imenu provides the information used by Which Function mode (@pxref{Which | |
2334 | Function}). It may also be used by Speedbar (@pxref{Hyperlinking}). | |
2335 | ||
2336 | @node Emerge, C Modes, Imenu, Programs | |
6bf7aab6 DL |
2337 | @section Merging Files with Emerge |
2338 | @cindex Emerge | |
2339 | @cindex merging files | |
2340 | ||
2341 | It's not unusual for programmers to get their signals crossed and modify | |
2342 | the same program in two different directions. To recover from this | |
2343 | confusion, you need to merge the two versions. Emerge makes this | |
2344 | easier. See also @ref{Comparing Files}, for commands to compare | |
2345 | in a more manual fashion, and @ref{Emerge,,, ediff, The Ediff Manual}. | |
2346 | ||
2347 | @menu | |
2348 | * Overview of Emerge:: How to start Emerge. Basic concepts. | |
2349 | * Submodes of Emerge:: Fast mode vs. Edit mode. | |
2350 | Skip Prefers mode and Auto Advance mode. | |
2351 | * State of Difference:: You do the merge by specifying state A or B | |
2352 | for each difference. | |
2353 | * Merge Commands:: Commands for selecting a difference, | |
2354 | changing states of differences, etc. | |
2355 | * Exiting Emerge:: What to do when you've finished the merge. | |
2356 | * Combining in Emerge:: How to keep both alternatives for a difference. | |
2357 | * Fine Points of Emerge:: Misc. | |
2358 | @end menu | |
2359 | ||
2360 | @node Overview of Emerge | |
2361 | @subsection Overview of Emerge | |
2362 | ||
2363 | To start Emerge, run one of these four commands: | |
2364 | ||
2365 | @table @kbd | |
2366 | @item M-x emerge-files | |
2367 | @findex emerge-files | |
2368 | Merge two specified files. | |
2369 | ||
2370 | @item M-x emerge-files-with-ancestor | |
2371 | @findex emerge-files-with-ancestor | |
2372 | Merge two specified files, with reference to a common ancestor. | |
2373 | ||
2374 | @item M-x emerge-buffers | |
2375 | @findex emerge-buffers | |
2376 | Merge two buffers. | |
2377 | ||
2378 | @item M-x emerge-buffers-with-ancestor | |
2379 | @findex emerge-buffers-with-ancestor | |
2380 | Merge two buffers with reference to a common ancestor in a third | |
2381 | buffer. | |
2382 | @end table | |
2383 | ||
2384 | @cindex merge buffer (Emerge) | |
2385 | @cindex A and B buffers (Emerge) | |
2386 | The Emerge commands compare two files or buffers, and display the | |
2387 | comparison in three buffers: one for each input text (the @dfn{A buffer} | |
2388 | and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging | |
2389 | takes place. The merge buffer shows the full merged text, not just the | |
2390 | differences. Wherever the two input texts differ, you can choose which | |
2391 | one of them to include in the merge buffer. | |
2392 | ||
2393 | The Emerge commands that take input from existing buffers use only the | |
2394 | accessible portions of those buffers, if they are narrowed | |
2395 | (@pxref{Narrowing}). | |
2396 | ||
2397 | If a common ancestor version is available, from which the two texts to | |
2398 | be merged were both derived, Emerge can use it to guess which | |
2399 | alternative is right. Wherever one current version agrees with the | |
2400 | ancestor, Emerge presumes that the other current version is a deliberate | |
2401 | change which should be kept in the merged version. Use the | |
2402 | @samp{with-ancestor} commands if you want to specify a common ancestor | |
2403 | text. These commands read three file or buffer names---variant A, | |
2404 | variant B, and the common ancestor. | |
2405 | ||
2406 | After the comparison is done and the buffers are prepared, the | |
2407 | interactive merging starts. You control the merging by typing special | |
2408 | @dfn{merge commands} in the merge buffer. The merge buffer shows you a | |
2409 | full merged text, not just differences. For each run of differences | |
2410 | between the input texts, you can choose which one of them to keep, or | |
2411 | edit them both together. | |
2412 | ||
2413 | The merge buffer uses a special major mode, Emerge mode, with commands | |
2414 | for making these choices. But you can also edit the buffer with | |
2415 | ordinary Emacs commands. | |
2416 | ||
2417 | At any given time, the attention of Emerge is focused on one | |
2418 | particular difference, called the @dfn{selected} difference. This | |
2419 | difference is marked off in the three buffers like this: | |
2420 | ||
2421 | @example | |
2422 | vvvvvvvvvvvvvvvvvvvv | |
2423 | @var{text that differs} | |
2424 | ^^^^^^^^^^^^^^^^^^^^ | |
2425 | @end example | |
2426 | ||
2427 | @noindent | |
2428 | Emerge numbers all the differences sequentially and the mode | |
2429 | line always shows the number of the selected difference. | |
2430 | ||
2431 | Normally, the merge buffer starts out with the A version of the text. | |
2432 | But when the A version of a difference agrees with the common ancestor, | |
2433 | then the B version is initially preferred for that difference. | |
2434 | ||
2435 | Emerge leaves the merged text in the merge buffer when you exit. At | |
2436 | that point, you can save it in a file with @kbd{C-x C-w}. If you give a | |
2437 | numeric argument to @code{emerge-files} or | |
2438 | @code{emerge-files-with-ancestor}, it reads the name of the output file | |
2439 | using the minibuffer. (This is the last file name those commands read.) | |
2440 | Then exiting from Emerge saves the merged text in the output file. | |
2441 | ||
2442 | Normally, Emerge commands save the output buffer in its file when you | |
2443 | exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not | |
2444 | save the output buffer, but you can save it yourself if you wish. | |
2445 | ||
2446 | @node Submodes of Emerge | |
2447 | @subsection Submodes of Emerge | |
2448 | ||
2449 | You can choose between two modes for giving merge commands: Fast mode | |
2450 | and Edit mode. In Fast mode, basic merge commands are single | |
2451 | characters, but ordinary Emacs commands are disabled. This is | |
2452 | convenient if you use only merge commands. In Edit mode, all merge | |
2453 | commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs | |
2454 | commands are also available. This allows editing the merge buffer, but | |
2455 | slows down Emerge operations. | |
2456 | ||
2457 | Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to | |
2458 | Fast mode. The mode line indicates Edit and Fast modes with @samp{E} | |
2459 | and @samp{F}. | |
2460 | ||
2461 | Emerge has two additional submodes that affect how particular merge | |
2462 | commands work: Auto Advance mode and Skip Prefers mode. | |
2463 | ||
2464 | If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands | |
2465 | advance to the next difference. This lets you go through the merge | |
2466 | faster as long as you simply choose one of the alternatives from the | |
2467 | input. The mode line indicates Auto Advance mode with @samp{A}. | |
2468 | ||
2469 | If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands | |
2470 | skip over differences in states prefer-A and prefer-B (@pxref{State of | |
2471 | Difference}). Thus you see only differences for which neither version | |
2472 | is presumed ``correct.'' The mode line indicates Skip Prefers mode with | |
2473 | @samp{S}. | |
2474 | ||
2475 | @findex emerge-auto-advance-mode | |
2476 | @findex emerge-skip-prefers-mode | |
2477 | Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or | |
2478 | clear Auto Advance mode. Use @kbd{s s} | |
2479 | (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. | |
2480 | These commands turn on the mode with a positive argument, turns it off | |
2481 | with a negative or zero argument, and toggle the mode with no argument. | |
2482 | ||
2483 | @node State of Difference | |
2484 | @subsection State of a Difference | |
2485 | ||
2486 | In the merge buffer, a difference is marked with lines of @samp{v} and | |
2487 | @samp{^} characters. Each difference has one of these seven states: | |
2488 | ||
2489 | @table @asis | |
2490 | @item A | |
2491 | The difference is showing the A version. The @kbd{a} command always | |
2492 | produces this state; the mode line indicates it with @samp{A}. | |
2493 | ||
2494 | @item B | |
2495 | The difference is showing the B version. The @kbd{b} command always | |
2496 | produces this state; the mode line indicates it with @samp{B}. | |
2497 | ||
2498 | @item default-A | |
2499 | @itemx default-B | |
2500 | The difference is showing the A or the B state by default, because you | |
2501 | haven't made a choice. All differences start in the default-A state | |
2502 | (and thus the merge buffer is a copy of the A buffer), except those for | |
2503 | which one alternative is ``preferred'' (see below). | |
2504 | ||
2505 | When you select a difference, its state changes from default-A or | |
2506 | default-B to plain A or B. Thus, the selected difference never has | |
2507 | state default-A or default-B, and these states are never displayed in | |
2508 | the mode line. | |
2509 | ||
2510 | The command @kbd{d a} chooses default-A as the default state, and @kbd{d | |
2511 | b} chooses default-B. This chosen default applies to all differences | |
2512 | which you haven't ever selected and for which no alternative is preferred. | |
2513 | If you are moving through the merge sequentially, the differences you | |
2514 | haven't selected are those following the selected one. Thus, while | |
2515 | moving sequentially, you can effectively make the A version the default | |
2516 | for some sections of the merge buffer and the B version the default for | |
2517 | others by using @kbd{d a} and @kbd{d b} between sections. | |
2518 | ||
2519 | @item prefer-A | |
2520 | @itemx prefer-B | |
2521 | The difference is showing the A or B state because it is | |
2522 | @dfn{preferred}. This means that you haven't made an explicit choice, | |
2523 | but one alternative seems likely to be right because the other | |
2524 | alternative agrees with the common ancestor. Thus, where the A buffer | |
2525 | agrees with the common ancestor, the B version is preferred, because | |
2526 | chances are it is the one that was actually changed. | |
2527 | ||
2528 | These two states are displayed in the mode line as @samp{A*} and @samp{B*}. | |
2529 | ||
2530 | @item combined | |
2531 | The difference is showing a combination of the A and B states, as a | |
2532 | result of the @kbd{x c} or @kbd{x C} commands. | |
2533 | ||
2534 | Once a difference is in this state, the @kbd{a} and @kbd{b} commands | |
2535 | don't do anything to it unless you give them a numeric argument. | |
2536 | ||
2537 | The mode line displays this state as @samp{comb}. | |
2538 | @end table | |
2539 | ||
2540 | @node Merge Commands | |
2541 | @subsection Merge Commands | |
2542 | ||
2543 | Here are the Merge commands for Fast mode; in Edit mode, precede them | |
2544 | with @kbd{C-c C-c}: | |
2545 | ||
2546 | @table @kbd | |
2547 | @item p | |
2548 | Select the previous difference. | |
2549 | ||
2550 | @item n | |
2551 | Select the next difference. | |
2552 | ||
2553 | @item a | |
2554 | Choose the A version of this difference. | |
2555 | ||
2556 | @item b | |
2557 | Choose the B version of this difference. | |
2558 | ||
2559 | @item C-u @var{n} j | |
2560 | Select difference number @var{n}. | |
2561 | ||
2562 | @item . | |
2563 | Select the difference containing point. You can use this command in the | |
2564 | merge buffer or in the A or B buffer. | |
2565 | ||
2566 | @item q | |
2567 | Quit---finish the merge. | |
2568 | ||
2569 | @item C-] | |
2570 | Abort---exit merging and do not save the output. | |
2571 | ||
2572 | @item f | |
2573 | Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) | |
2574 | ||
2575 | @item e | |
2576 | Go into Edit mode. | |
2577 | ||
2578 | @item l | |
2579 | Recenter (like @kbd{C-l}) all three windows. | |
2580 | ||
79214ddf | 2581 | @item - |
6bf7aab6 DL |
2582 | Specify part of a prefix numeric argument. |
2583 | ||
2584 | @item @var{digit} | |
2585 | Also specify part of a prefix numeric argument. | |
2586 | ||
2587 | @item d a | |
2588 | Choose the A version as the default from here down in | |
2589 | the merge buffer. | |
2590 | ||
2591 | @item d b | |
2592 | Choose the B version as the default from here down in | |
2593 | the merge buffer. | |
2594 | ||
2595 | @item c a | |
2596 | Copy the A version of this difference into the kill ring. | |
2597 | ||
2598 | @item c b | |
2599 | Copy the B version of this difference into the kill ring. | |
2600 | ||
2601 | @item i a | |
2602 | Insert the A version of this difference at point. | |
2603 | ||
2604 | @item i b | |
2605 | Insert the B version of this difference at point. | |
2606 | ||
2607 | @item m | |
2608 | Put point and mark around the difference. | |
2609 | ||
2610 | @item ^ | |
2611 | Scroll all three windows down (like @kbd{M-v}). | |
2612 | ||
2613 | @item v | |
2614 | Scroll all three windows up (like @kbd{C-v}). | |
2615 | ||
2616 | @item < | |
2617 | Scroll all three windows left (like @kbd{C-x <}). | |
2618 | ||
2619 | @item > | |
2620 | Scroll all three windows right (like @kbd{C-x >}). | |
2621 | ||
2622 | @item | | |
2623 | Reset horizontal scroll on all three windows. | |
2624 | ||
2625 | @item x 1 | |
2626 | Shrink the merge window to one line. (Use @kbd{C-u l} to restore it | |
2627 | to full size.) | |
2628 | ||
2629 | @item x c | |
2630 | Combine the two versions of this difference (@pxref{Combining in | |
2631 | Emerge}). | |
2632 | ||
2633 | @item x f | |
2634 | Show the names of the files/buffers Emerge is operating on, in a Help | |
2635 | window. (Use @kbd{C-u l} to restore windows.) | |
2636 | ||
2637 | @item x j | |
2638 | Join this difference with the following one. | |
2639 | (@kbd{C-u x j} joins this difference with the previous one.) | |
2640 | ||
2641 | @item x s | |
2642 | Split this difference into two differences. Before you use this | |
2643 | command, position point in each of the three buffers at the place where | |
2644 | you want to split the difference. | |
2645 | ||
2646 | @item x t | |
2647 | Trim identical lines off the top and bottom of the difference. | |
2648 | Such lines occur when the A and B versions are | |
2649 | identical but differ from the ancestor version. | |
2650 | @end table | |
2651 | ||
2652 | @node Exiting Emerge | |
2653 | @subsection Exiting Emerge | |
2654 | ||
2655 | The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing | |
2656 | the results into the output file if you specified one. It restores the | |
2657 | A and B buffers to their proper contents, or kills them if they were | |
2658 | created by Emerge and you haven't changed them. It also disables the | |
2659 | Emerge commands in the merge buffer, since executing them later could | |
2660 | damage the contents of the various buffers. | |
2661 | ||
2662 | @kbd{C-]} aborts the merge. This means exiting without writing the | |
2663 | output file. If you didn't specify an output file, then there is no | |
2664 | real difference between aborting and finishing the merge. | |
2665 | ||
2666 | If the Emerge command was called from another Lisp program, then its | |
2667 | return value is @code{t} for successful completion, or @code{nil} if you | |
2668 | abort. | |
2669 | ||
2670 | @node Combining in Emerge | |
2671 | @subsection Combining the Two Versions | |
2672 | ||
2673 | Sometimes you want to keep @emph{both} alternatives for a particular | |
2674 | difference. To do this, use @kbd{x c}, which edits the merge buffer | |
2675 | like this: | |
2676 | ||
2677 | @example | |
2678 | @group | |
2679 | #ifdef NEW | |
2680 | @var{version from A buffer} | |
2681 | #else /* not NEW */ | |
2682 | @var{version from B buffer} | |
2683 | #endif /* not NEW */ | |
2684 | @end group | |
2685 | @end example | |
2686 | ||
2687 | @noindent | |
2688 | @vindex emerge-combine-versions-template | |
2689 | While this example shows C preprocessor conditionals delimiting the two | |
2690 | alternative versions, you can specify the strings to use by setting | |
2691 | the variable @code{emerge-combine-versions-template} to a string of your | |
2692 | choice. In the string, @samp{%a} says where to put version A, and | |
2693 | @samp{%b} says where to put version B. The default setting, which | |
2694 | produces the results shown above, looks like this: | |
2695 | ||
2696 | @example | |
2697 | @group | |
2698 | "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" | |
2699 | @end group | |
2700 | @end example | |
2701 | ||
2702 | @node Fine Points of Emerge | |
2703 | @subsection Fine Points of Emerge | |
2704 | ||
2705 | During the merge, you mustn't try to edit the A and B buffers yourself. | |
2706 | Emerge modifies them temporarily, but ultimately puts them back the way | |
2707 | they were. | |
2708 | ||
2709 | You can have any number of merges going at once---just don't use any one | |
2710 | buffer as input to more than one merge at once, since the temporary | |
2711 | changes made in these buffers would get in each other's way. | |
2712 | ||
2713 | Starting Emerge can take a long time because it needs to compare the | |
2714 | files fully. Emacs can't do anything else until @code{diff} finishes. | |
2715 | Perhaps in the future someone will change Emerge to do the comparison in | |
2716 | the background when the input files are large---then you could keep on | |
2717 | doing other things with Emacs until Emerge is ready to accept | |
2718 | commands. | |
2719 | ||
2720 | @vindex emerge-startup-hook | |
2721 | After setting up the merge, Emerge runs the hook | |
2722 | @code{emerge-startup-hook} (@pxref{Hooks}). | |
2723 | ||
2724 | @node C Modes | |
2725 | @section C and Related Modes | |
2726 | @cindex C mode | |
2727 | @cindex Java mode | |
2728 | @cindex Pike mode | |
2729 | @cindex IDL mode | |
2730 | @cindex CORBA IDL mode | |
2731 | @cindex Objective C mode | |
2732 | @cindex C++ mode | |
2733 | @cindex mode, Java | |
2734 | @cindex mode, C | |
2735 | @cindex mode, Objective C | |
2736 | @cindex mode, CORBA IDL | |
2737 | @cindex mode, Pike | |
2738 | ||
2739 | This section describes special features available in C, C++, | |
2740 | Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and | |
2741 | related modes,'' those are the modes we mean. | |
2742 | ||
51ed0ea0 DL |
2743 | Additional information is available in the separate manual for these |
2744 | modes. @xref{Top, CC Mode, ccmode, , CC Mode}. | |
2745 | ||
6bf7aab6 DL |
2746 | @menu |
2747 | * Motion in C:: | |
2748 | * Electric C:: | |
2749 | * Hungry Delete:: | |
2750 | * Other C Commands:: | |
2751 | * Comments in C:: | |
2752 | @end menu | |
2753 | ||
2754 | @node Motion in C | |
2755 | @subsection C Mode Motion Commands | |
2756 | ||
2757 | This section describes commands for moving point, in C mode and | |
2758 | related modes. | |
2759 | ||
2760 | @table @code | |
2761 | @item C-c C-u | |
2762 | @kindex C-c C-u @r{(C mode)} | |
2763 | @findex c-up-conditional | |
2764 | Move point back to the containing preprocessor conditional, leaving the | |
2765 | mark behind. A prefix argument acts as a repeat count. With a negative | |
2766 | argument, move point forward to the end of the containing | |
2767 | preprocessor conditional. When going backwards, @code{#elif} is treated | |
2768 | like @code{#else} followed by @code{#if}. When going forwards, | |
2769 | @code{#elif} is ignored.@refill | |
2770 | ||
2771 | @item C-c C-p | |
2772 | @kindex C-c C-p @r{(C mode)} | |
2773 | @findex c-backward-conditional | |
2774 | Move point back over a preprocessor conditional, leaving the mark | |
2775 | behind. A prefix argument acts as a repeat count. With a negative | |
2776 | argument, move forward. | |
2777 | ||
2778 | @item C-c C-n | |
2779 | @kindex C-c C-n @r{(C mode)} | |
2780 | @findex c-forward-conditional | |
2781 | Move point forward across a preprocessor conditional, leaving the mark | |
2782 | behind. A prefix argument acts as a repeat count. With a negative | |
2783 | argument, move backward. | |
2784 | ||
2785 | @item M-a | |
2786 | @kindex ESC a | |
2787 | @findex c-beginning-of-statement | |
2788 | Move point to the beginning of the innermost C statement | |
2789 | (@code{c-beginning-of-statement}). If point is already at the beginning | |
2790 | of a statement, move to the beginning of the preceding statement. With | |
2791 | prefix argument @var{n}, move back @var{n} @minus{} 1 statements. | |
2792 | ||
2793 | If point is within a string or comment, or next to a comment (only | |
2794 | whitespace between them), this command moves by sentences instead of | |
2795 | statements. | |
2796 | ||
2797 | When called from a program, this function takes three optional | |
2798 | arguments: the numeric prefix argument, a buffer position limit | |
2799 | (don't move back before that place), and a flag that controls whether | |
2800 | to do sentence motion when inside of a comment. | |
2801 | ||
2802 | @item M-e | |
2803 | @kindex ESC e | |
2804 | @findex c-end-of-statement | |
2805 | Move point to the end of the innermost C statement; like @kbd{M-a} | |
2806 | except that it moves in the other direction (@code{c-end-of-statement}). | |
2807 | ||
2808 | @item M-x c-backward-into-nomenclature | |
2809 | @findex c-backward-into-nomenclature | |
2810 | Move point backward to beginning of a C++ nomenclature section or word. | |
2811 | With prefix argument @var{n}, move @var{n} times. If @var{n} is | |
2812 | negative, move forward. C++ nomenclature means a symbol name in the | |
2813 | style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter | |
2814 | begins a section or word. | |
2815 | ||
2816 | In the GNU project, we recommend using underscores to separate words | |
2817 | within an identifier in C or C++, rather than using case distinctions. | |
2818 | ||
2819 | @item M-x c-forward-into-nomenclature | |
2820 | @findex c-forward-into-nomenclature | |
2821 | Move point forward to end of a C++ nomenclature section or word. | |
2822 | With prefix argument @var{n}, move @var{n} times. | |
2823 | @end table | |
2824 | ||
2825 | @node Electric C | |
2826 | @subsection Electric C Characters | |
2827 | ||
2828 | In C mode and related modes, certain printing characters are | |
2829 | ``electric''---in addition to inserting themselves, they also reindent | |
2830 | the current line and may insert newlines. This feature is controlled by | |
2831 | the variable @code{c-auto-newline}. The ``electric'' characters are | |
2832 | @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, | |
2833 | @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. | |
2834 | ||
2835 | Electric characters insert newlines only when the @dfn{auto-newline} | |
2836 | feature is enabled (indicated by @samp{/a} in the mode line after the | |
2837 | mode name). This feature is controlled by the variable | |
2838 | @code{c-auto-newline}. You can turn this feature on or off with the | |
2839 | command @kbd{C-c C-a}: | |
2840 | ||
2841 | @table @kbd | |
2842 | @item C-c C-a | |
2843 | @kindex C-c C-a @r{(C mode)} | |
2844 | @findex c-toggle-auto-state | |
2845 | Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a | |
2846 | prefix argument, this command turns the auto-newline feature on if the | |
2847 | argument is positive, and off if it is negative. | |
2848 | @end table | |
2849 | ||
2850 | The colon character is electric because that is appropriate for a | |
2851 | single colon. But when you want to insert a double colon in C++, the | |
2852 | electric behavior of colon is inconvenient. You can insert a double | |
2853 | colon with no reindentation or newlines by typing @kbd{C-c :}: | |
2854 | ||
2855 | @table @kbd | |
2856 | @item C-c : | |
2857 | @kindex C-c : @r{(C mode)} | |
2858 | @findex c-scope-operator | |
2859 | Insert a double colon scope operator at point, without reindenting the | |
2860 | line or adding any newlines (@code{c-scope-operator}). | |
2861 | @end table | |
2862 | ||
2863 | The electric @kbd{#} key reindents the line if it appears to be the | |
2864 | beginning of a preprocessor directive. This happens when the value of | |
2865 | @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn | |
2866 | this feature off by setting @code{c-electric-pound-behavior} to | |
2867 | @code{nil}. | |
2868 | ||
2869 | The variable @code{c-hanging-braces-alist} controls the insertion of | |
2870 | newlines before and after inserted braces. It is an association list | |
2871 | with elements of the following form: @code{(@var{syntactic-symbol} | |
2872 | . @var{nl-list})}. Most of the syntactic symbols that appear in | |
2873 | @code{c-offsets-alist} are meaningful here as well. | |
2874 | ||
2875 | The list @var{nl-list} may contain either of the symbols | |
2876 | @code{before} or @code{after}, or both; or it may be @code{nil}. When a | |
2877 | brace is inserted, the syntactic context it defines is looked up in | |
2878 | @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used | |
2879 | to determine where newlines are inserted: either before the brace, | |
2880 | after, or both. If not found, the default is to insert a newline both | |
2881 | before and after braces. | |
2882 | ||
2883 | The variable @code{c-hanging-colons-alist} controls the insertion of | |
2884 | newlines before and after inserted colons. It is an association list | |
2885 | with elements of the following form: @code{(@var{syntactic-symbol} | |
2886 | . @var{nl-list})}. The list @var{nl-list} may contain either of the | |
2887 | symbols @code{before} or @code{after}, or both; or it may be @code{nil}. | |
2888 | ||
2889 | When a colon is inserted, the syntactic symbol it defines is looked | |
2890 | up in this list, and if found, the @var{nl-list} is used to determine | |
2891 | where newlines are inserted: either before the brace, after, or both. | |
2892 | If the syntactic symbol is not found in this list, no newlines are | |
2893 | inserted. | |
2894 | ||
2895 | Electric characters can also delete newlines automatically when the | |
2896 | auto-newline feature is enabled. This feature makes auto-newline more | |
2897 | acceptable, by deleting the newlines in the most common cases where you | |
2898 | do not want them. Emacs can recognize several cases in which deleting a | |
2899 | newline might be desirable; by setting the variable | |
2900 | @code{c-cleanup-list}, you can specify @emph{which} of these cases that | |
2901 | should happen. The variable's value is a list of symbols, each | |
2902 | describing one case for possible deletion of a newline. Here are the | |
2903 | meaningful symbols, and their meanings: | |
2904 | ||
2905 | @table @code | |
2906 | @item brace-catch-brace | |
2907 | Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the | |
2908 | entire construct on a single line. The clean-up occurs when you type | |
2909 | the @samp{@{}, if there is nothing between the braces aside from | |
2910 | @code{catch} and @var{condition}. | |
2911 | ||
2912 | @item brace-else-brace | |
2913 | Clean up @samp{@} else @{} constructs by placing the entire construct on | |
2914 | a single line. The clean-up occurs when you type the @samp{@{} after | |
2915 | the @code{else}, but only if there is nothing but white space between | |
2916 | the braces and the @code{else}. | |
2917 | ||
2918 | @item brace-elseif-brace | |
2919 | Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire | |
2920 | construct on a single line. The clean-up occurs when you type the | |
2921 | @samp{@{}, if there is nothing but white space between the @samp{@}} and | |
2922 | @samp{@{} aside from the keywords and the @code{if}-condition. | |
2923 | ||
2924 | @item empty-defun-braces | |
2925 | Clean up empty defun braces by placing the braces on the same | |
2926 | line. Clean-up occurs when you type the closing brace. | |
2927 | ||
2928 | @item defun-close-semi | |
2929 | Clean up the semicolon after a @code{struct} or similar type | |
2930 | declaration, by placing the semicolon on the same line as the closing | |
2931 | brace. Clean-up occurs when you type the semicolon. | |
2932 | ||
2933 | @item list-close-comma | |
2934 | Clean up commas following braces in array and aggregate | |
2935 | initializers. Clean-up occurs when you type the comma. | |
2936 | ||
2937 | @item scope-operator | |
2938 | Clean up double colons which may designate a C++ scope operator, by | |
2939 | placing the colons together. Clean-up occurs when you type the second | |
2940 | colon, but only when the two colons are separated by nothing but | |
2941 | whitespace. | |
2942 | @end table | |
2943 | ||
2944 | @node Hungry Delete | |
2945 | @subsection Hungry Delete Feature in C | |
2946 | ||
2947 | When the @dfn{hungry-delete} feature is enabled (indicated by | |
2948 | @samp{/h} or @samp{/ah} in the mode line after the mode name), a single | |
2949 | @key{DEL} command deletes all preceding whitespace, not just one space. | |
2950 | To turn this feature on or off, use @kbd{C-c C-d}: | |
2951 | ||
2952 | @table @kbd | |
2953 | @item C-c C-d | |
2954 | @kindex C-c C-d @r{(C mode)} | |
2955 | @findex c-toggle-hungry-state | |
2956 | Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a | |
2957 | prefix argument, this command turns the hungry-delete feature on if the | |
2958 | argument is positive, and off if it is negative. | |
2959 | ||
2960 | @item C-c C-t | |
2961 | @kindex C-c C-t @r{(C mode)} | |
2962 | @findex c-toggle-auto-hungry-state | |
2963 | Toggle the auto-newline and hungry-delete features, both at once | |
2964 | (@code{c-toggle-auto-hungry-state}). | |
2965 | @end table | |
2966 | ||
2967 | @vindex c-hungry-delete-key | |
2968 | The variable @code{c-hungry-delete-key} controls whether the | |
2969 | hungry-delete feature is enabled. | |
2970 | ||
2971 | @node Other C Commands | |
2972 | @subsection Other Commands for C Mode | |
2973 | ||
2974 | @table @kbd | |
2975 | @item C-M-h | |
2976 | @findex c-mark-function | |
2977 | @kindex C-M-h @r{(C mode)} | |
2978 | Put mark at the end of a function definition, and put point at the | |
2979 | beginning (@code{c-mark-function}). | |
2980 | ||
2981 | @item M-q | |
2982 | @kindex M-q @r{(C mode)} | |
2983 | @findex c-fill-paragraph | |
2984 | Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). | |
2985 | If any part of the current line is a comment or within a comment, this | |
2986 | command fills the comment or the paragraph of it that point is in, | |
2987 | preserving the comment indentation and comment delimiters. | |
2988 | ||
2989 | @item C-c C-e | |
2990 | @cindex macro expansion in C | |
2991 | @cindex expansion of C macros | |
2992 | @findex c-macro-expand | |
2993 | @kindex C-c C-e @r{(C mode)} | |
2994 | Run the C preprocessor on the text in the region, and show the result, | |
2995 | which includes the expansion of all the macro calls | |
2996 | (@code{c-macro-expand}). The buffer text before the region is also | |
2997 | included in preprocessing, for the sake of macros defined there, but the | |
2998 | output from this part isn't shown. | |
2999 | ||
3000 | When you are debugging C code that uses macros, sometimes it is hard to | |
3001 | figure out precisely how the macros expand. With this command, you | |
3002 | don't have to figure it out; you can see the expansions. | |
3003 | ||
3004 | @item C-c C-\ | |
3005 | @findex c-backslash-region | |
3006 | @kindex C-c C-\ @r{(C mode)} | |
3007 | Insert or align @samp{\} characters at the ends of the lines of the | |
3008 | region (@code{c-backslash-region}). This is useful after writing or | |
3009 | editing a C macro definition. | |
3010 | ||
3011 | If a line already ends in @samp{\}, this command adjusts the amount of | |
3012 | whitespace before it. Otherwise, it inserts a new @samp{\}. However, | |
3013 | the last line in the region is treated specially; no @samp{\} is | |
3014 | inserted on that line, and any @samp{\} there is deleted. | |
3015 | ||
3016 | @item M-x cpp-highlight-buffer | |
3017 | @cindex preprocessor highlighting | |
3018 | @findex cpp-highlight-buffer | |
3019 | Highlight parts of the text according to its preprocessor conditionals. | |
3020 | This command displays another buffer named @samp{*CPP Edit*}, which | |
3021 | serves as a graphic menu for selecting how to display particular kinds | |
3022 | of conditionals and their contents. After changing various settings, | |
3023 | click on @samp{[A]pply these settings} (or go to that buffer and type | |
3024 | @kbd{a}) to rehighlight the C mode buffer accordingly. | |
3025 | ||
3026 | @item C-c C-s | |
3027 | @findex c-show-syntactic-information | |
3028 | @kindex C-c C-s @r{(C mode)} | |
3029 | Display the syntactic information about the current source line | |
3030 | (@code{c-show-syntactic-information}). This is the information that | |
3031 | directs how the line is indented. | |
3032 | @end table | |
3033 | ||
3034 | @node Comments in C | |
3035 | @subsection Comments in C Modes | |
3036 | ||
3037 | C mode and related modes use a number of variables for controlling | |
3038 | comment format. | |
3039 | ||
3040 | @table @code | |
3041 | @item c-comment-only-line-offset | |
3042 | @vindex c-comment-only-line-offset | |
3043 | Extra offset for line which contains only the start of a comment. It | |
3044 | can be either an integer or a cons cell of the form | |
3045 | @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where | |
3046 | @var{non-anchored-offset} is the amount of offset given to | |
3047 | non-column-zero anchored comment-only lines, and @var{anchored-offset} | |
3048 | is the amount of offset to give column-zero anchored comment-only lines. | |
3049 | Just an integer as value is equivalent to @code{(@var{val} . 0)}. | |
3050 | ||
3051 | @item c-comment-start-regexp | |
3052 | @vindex c-comment-start-regexp | |
3053 | This buffer-local variable specifies how to recognize the start of a comment. | |
3054 | ||
3055 | @item c-hanging-comment-ender-p | |
3056 | @vindex c-hanging-comment-ender-p | |
3057 | If this variable is @code{nil}, @code{c-fill-paragraph} leaves the | |
3058 | comment terminator of a block comment on a line by itself. The default | |
3059 | value is @code{t}, which puts the comment-end delimiter @samp{*/} at the | |
3060 | end of the last line of the comment text. | |
3061 | ||
3062 | @item c-hanging-comment-starter-p | |
3063 | @vindex c-hanging-comment-starter-p | |
3064 | If this variable is @code{nil}, @code{c-fill-paragraph} leaves the | |
3065 | starting delimiter of a block comment on a line by itself. The default | |
3066 | value is @code{t}, which puts the comment-start delimiter @samp{/*} at | |
3067 | the beginning of the first line of the comment text. | |
3068 | @end table | |
3069 | ||
3070 | @node Fortran | |
3071 | @section Fortran Mode | |
3072 | @cindex Fortran mode | |
3073 | @cindex mode, Fortran | |
3074 | ||
3075 | Fortran mode provides special motion commands for Fortran statements and | |
3076 | subprograms, and indentation commands that understand Fortran conventions | |
3077 | of nesting, line numbers and continuation statements. Fortran mode has | |
3078 | its own Auto Fill mode that breaks long lines into proper Fortran | |
3079 | continuation lines. | |
3080 | ||
3081 | Special commands for comments are provided because Fortran comments | |
3082 | are unlike those of other languages. Built-in abbrevs optionally save | |
3083 | typing when you insert Fortran keywords. | |
3084 | ||
3085 | @findex fortran-mode | |
3086 | Use @kbd{M-x fortran-mode} to switch to this major mode. This command | |
3087 | runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). | |
3088 | ||
138a8f12 DL |
3089 | @cindex Fortran77 |
3090 | @cindex Fortran90 | |
3091 | @findex f90-mode | |
3092 | @findex fortran-mode | |
3093 | Note that Fortan mode described here (obtained with the | |
3094 | @code{fortran-mode} command) is for editing the old Fortran77 | |
3095 | idiosyncratic `fixed format' source form. For editing the modern | |
3096 | Fortran90 `free format' source form (which is supported by the GNU | |
3097 | Fortran compiler) use @code{f90-mode}. | |
3098 | ||
3099 | By default @code{fortran-mode} is invoked on files with extension | |
3100 | @samp{.f}, @samp{.F} or @samp{.for} and @code{f90-mode} is invoked for | |
3101 | the extension @samp{.f90}. | |
3102 | ||
6bf7aab6 DL |
3103 | @menu |
3104 | * Motion: Fortran Motion. Moving point by statements or subprograms. | |
3105 | * Indent: Fortran Indent. Indentation commands for Fortran. | |
3106 | * Comments: Fortran Comments. Inserting and aligning comments. | |
3107 | * Autofill: Fortran Autofill. Auto fill minor mode for Fortran. | |
3108 | * Columns: Fortran Columns. Measuring columns for valid Fortran. | |
3109 | * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. | |
3110 | * Misc: Fortran Misc. Other Fortran mode features. | |
3111 | @end menu | |
3112 | ||
3113 | @node Fortran Motion | |
3114 | @subsection Motion Commands | |
3115 | ||
85750656 DL |
3116 | In addition to the normal commands for moving by and operating on |
3117 | `defuns' (Fortran subprograms---functions | |
3118 | and subroutines) Fortran mode provides special commands to move by statements. | |
6bf7aab6 | 3119 | |
6bf7aab6 DL |
3120 | @kindex C-c C-p @r{(Fortran mode)} |
3121 | @kindex C-c C-n @r{(Fortran mode)} | |
6bf7aab6 DL |
3122 | @findex fortran-previous-statement |
3123 | @findex fortran-next-statement | |
3124 | ||
3125 | @table @kbd | |
6bf7aab6 DL |
3126 | @item C-c C-n |
3127 | Move to beginning of current or next statement | |
3128 | (@code{fortran-next-statement}). | |
3129 | @item C-c C-p | |
3130 | Move to beginning of current or previous statement | |
3131 | (@code{fortran-previous-statement}). | |
3132 | @end table | |
3133 | ||
3134 | @node Fortran Indent | |
3135 | @subsection Fortran Indentation | |
3136 | ||
3137 | Special commands and features are needed for indenting Fortran code in | |
3138 | order to make sure various syntactic entities (line numbers, comment line | |
3139 | indicators and continuation line flags) appear in the columns that are | |
3140 | required for standard Fortran. | |
3141 | ||
3142 | @menu | |
85750656 | 3143 | * Commands: ForIndent Commands. Commands for indenting and filling Fortran. |
6bf7aab6 DL |
3144 | * Contline: ForIndent Cont. How continuation lines indent. |
3145 | * Numbers: ForIndent Num. How line numbers auto-indent. | |
3146 | * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. | |
3147 | * Vars: ForIndent Vars. Variables controlling Fortran indent style. | |
3148 | @end menu | |
3149 | ||
3150 | @node ForIndent Commands | |
85750656 | 3151 | @subsubsection Fortran-Specific Indentation and Filling Commands |
6bf7aab6 DL |
3152 | |
3153 | @table @kbd | |
6bf7aab6 | 3154 | @item C-M-j |
85750656 DL |
3155 | Break the current line and set up a continuation line |
3156 | (@code{fortran-split-line}). | |
6bf7aab6 | 3157 | @item M-^ |
85750656 | 3158 | Join this line to the previous line (@code{fortran-join-line}). |
6bf7aab6 DL |
3159 | @item C-M-q |
3160 | Indent all the lines of the subprogram point is in | |
3161 | (@code{fortran-indent-subprogram}). | |
85750656 DL |
3162 | @item M-q |
3163 | Fill a comment block or statement. | |
6bf7aab6 DL |
3164 | @end table |
3165 | ||
6bf7aab6 DL |
3166 | @kindex C-M-q @r{(Fortran mode)} |
3167 | @findex fortran-indent-subprogram | |
3168 | The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command | |
3169 | to reindent all the lines of the Fortran subprogram (function or | |
3170 | subroutine) containing point. | |
3171 | ||
3172 | @kindex C-M-j @r{(Fortran mode)} | |
3173 | @findex fortran-split-line | |
3174 | The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits | |
3175 | a line in the appropriate fashion for Fortran. In a non-comment line, | |
3176 | the second half becomes a continuation line and is indented | |
3177 | accordingly. In a comment line, both halves become separate comment | |
3178 | lines. | |
3179 | ||
3180 | @kindex M-^ @r{(Fortran mode)} | |
138a8f12 DL |
3181 | @kindex C-c C-d @r{(Fortran mode)} |
3182 | @findex fortran-join-line | |
85750656 DL |
3183 | @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, |
3184 | which joins a continuation line back to the previous line, roughly as | |
3185 | the inverse of @code{fortran-split-line}. The point must be on a | |
138a8f12 DL |
3186 | continuation line when this command is invoked. |
3187 | ||
85750656 DL |
3188 | @kindex M-q @r{(Fortran mode)} |
3189 | Fortran mode defines the function for filling paragraphs such that | |
3190 | @kbd{M-q} fills the comment block or statement around point. Filling a | |
3191 | statement removes excess statement continuations. | |
3192 | ||
6bf7aab6 DL |
3193 | @node ForIndent Cont |
3194 | @subsubsection Continuation Lines | |
3195 | @cindex Fortran continuation lines | |
3196 | ||
3197 | @vindex fortran-continuation-string | |
3198 | Most modern Fortran compilers allow two ways of writing continuation | |
3199 | lines. If the first non-space character on a line is in column 5, then | |
3200 | that line is a continuation of the previous line. We call this | |
3201 | @dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The | |
3202 | variable @code{fortran-continuation-string} specifies what character to | |
3203 | put on column 5. A line that starts with a tab character followed by | |
3204 | any digit except @samp{0} is also a continuation line. We call this | |
3205 | style of continuation @dfn{tab format}. | |
3206 | ||
3207 | @vindex indent-tabs-mode @r{(Fortran mode)} | |
3208 | Fortran mode can make either style of continuation line, but you | |
3209 | must specify which one you prefer. The value of the variable | |
3210 | @code{indent-tabs-mode} controls the choice: @code{nil} for fixed | |
3211 | format, and non-@code{nil} for tab format. You can tell which style | |
3212 | is presently in effect by the presence or absence of the string | |
3213 | @samp{Tab} in the mode line. | |
3214 | ||
3215 | If the text on a line starts with the conventional Fortran | |
3216 | continuation marker @samp{$}, or if it begins with any non-whitespace | |
3217 | character in column 5, Fortran mode treats it as a continuation line. | |
3218 | When you indent a continuation line with @key{TAB}, it converts the line | |
3219 | to the current continuation style. When you split a Fortran statement | |
3220 | with @kbd{C-M-j}, the continuation marker on the newline is created | |
3221 | according to the continuation style. | |
3222 | ||
3223 | The setting of continuation style affects several other aspects of | |
3224 | editing in Fortran mode. In fixed format mode, the minimum column | |
3225 | number for the body of a statement is 6. Lines inside of Fortran | |
3226 | blocks that are indented to larger column numbers always use only the | |
3227 | space character for whitespace. In tab format mode, the minimum | |
3228 | column number for the statement body is 8, and the whitespace before | |
3229 | column 8 must always consist of one tab character. | |
3230 | ||
3231 | @vindex fortran-tab-mode-default | |
3232 | @vindex fortran-analyze-depth | |
3233 | When you enter Fortran mode for an existing file, it tries to deduce the | |
3234 | proper continuation style automatically from the file contents. The first | |
3235 | line that begins with either a tab character or six spaces determines the | |
3236 | choice. The variable @code{fortran-analyze-depth} specifies how many lines | |
3237 | to consider (at the beginning of the file); if none of those lines | |
3238 | indicates a style, then the variable @code{fortran-tab-mode-default} | |
3239 | specifies the style. If it is @code{nil}, that specifies fixed format, and | |
3240 | non-@code{nil} specifies tab format. | |
3241 | ||
3242 | @node ForIndent Num | |
3243 | @subsubsection Line Numbers | |
3244 | ||
3245 | If a number is the first non-whitespace in the line, Fortran | |
3246 | indentation assumes it is a line number and moves it to columns 0 | |
3247 | through 4. (Columns always count from 0 in GNU Emacs.) | |
3248 | ||
3249 | @vindex fortran-line-number-indent | |
3250 | Line numbers of four digits or less are normally indented one space. | |
3251 | The variable @code{fortran-line-number-indent} controls this; it | |
3252 | specifies the maximum indentation a line number can have. Line numbers | |
3253 | are indented to right-justify them to end in column 4 unless that would | |
3254 | require more than this maximum indentation. The default value of the | |
3255 | variable is 1. | |
3256 | ||
3257 | @vindex fortran-electric-line-number | |
3258 | Simply inserting a line number is enough to indent it according to | |
3259 | these rules. As each digit is inserted, the indentation is recomputed. | |
3260 | To turn off this feature, set the variable | |
3261 | @code{fortran-electric-line-number} to @code{nil}. Then inserting line | |
3262 | numbers is like inserting anything else. | |
3263 | ||
3264 | @node ForIndent Conv | |
3265 | @subsubsection Syntactic Conventions | |
3266 | ||
3267 | Fortran mode assumes that you follow certain conventions that simplify | |
3268 | the task of understanding a Fortran program well enough to indent it | |
3269 | properly: | |
3270 | ||
3271 | @itemize @bullet | |
3272 | @item | |
3273 | Two nested @samp{do} loops never share a @samp{continue} statement. | |
3274 | ||
3275 | @item | |
3276 | Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} | |
3277 | and others are written without embedded whitespace or line breaks. | |
3278 | ||
3279 | Fortran compilers generally ignore whitespace outside of string | |
3280 | constants, but Fortran mode does not recognize these keywords if they | |
3281 | are not contiguous. Constructs such as @samp{else if} or @samp{end do} | |
3282 | are acceptable, but the second word should be on the same line as the | |
3283 | first and not on a continuation line. | |
3284 | @end itemize | |
3285 | ||
3286 | @noindent | |
3287 | If you fail to follow these conventions, the indentation commands may | |
3288 | indent some lines unaesthetically. However, a correct Fortran program | |
3289 | retains its meaning when reindented even if the conventions are not | |
3290 | followed. | |
3291 | ||
3292 | @node ForIndent Vars | |
3293 | @subsubsection Variables for Fortran Indentation | |
3294 | ||
3295 | @vindex fortran-do-indent | |
3296 | @vindex fortran-if-indent | |
3297 | @vindex fortran-structure-indent | |
3298 | @vindex fortran-continuation-indent | |
3299 | @vindex fortran-check-all-num@dots{} | |
3300 | @vindex fortran-minimum-statement-indent@dots{} | |
3301 | Several additional variables control how Fortran indentation works: | |
3302 | ||
3303 | @table @code | |
3304 | @item fortran-do-indent | |
3305 | Extra indentation within each level of @samp{do} statement (default 3). | |
3306 | ||
3307 | @item fortran-if-indent | |
3308 | Extra indentation within each level of @samp{if} statement (default 3). | |
3309 | This value is also used for extra indentation within each level of the | |
3310 | Fortran 90 @samp{where} statement. | |
3311 | ||
3312 | @item fortran-structure-indent | |
3313 | Extra indentation within each level of @samp{structure}, @samp{union}, or | |
3314 | @samp{map} statements (default 3). | |
3315 | ||
3316 | @item fortran-continuation-indent | |
3317 | Extra indentation for bodies of continuation lines (default 5). | |
3318 | ||
3319 | @item fortran-check-all-num-for-matching-do | |
3320 | If this is @code{nil}, indentation assumes that each @samp{do} statement | |
3321 | ends on a @samp{continue} statement. Therefore, when computing | |
3322 | indentation for a statement other than @samp{continue}, it can save time | |
3323 | by not checking for a @samp{do} statement ending there. If this is | |
3324 | non-@code{nil}, indenting any numbered statement must check for a | |
3325 | @samp{do} that ends there. The default is @code{nil}. | |
3326 | ||
3327 | @item fortran-blink-matching-if | |
3328 | If this is @code{t}, indenting an @samp{endif} statement moves the | |
3329 | cursor momentarily to the matching @samp{if} statement to show where it | |
3330 | is. The default is @code{nil}. | |
3331 | ||
3332 | @item fortran-minimum-statement-indent-fixed | |
3333 | Minimum indentation for fortran statements when using fixed format | |
3334 | continuation line style. Statement bodies are never indented less than | |
3335 | this much. The default is 6. | |
3336 | ||
3337 | @item fortran-minimum-statement-indent-tab | |
3338 | Minimum indentation for fortran statements for tab format continuation line | |
3339 | style. Statement bodies are never indented less than this much. The | |
3340 | default is 8. | |
3341 | @end table | |
3342 | ||
3343 | @node Fortran Comments | |
3344 | @subsection Fortran Comments | |
3345 | ||
3346 | The usual Emacs comment commands assume that a comment can follow a line | |
3347 | of code. In Fortran, the standard comment syntax requires an entire line | |
3348 | to be just a comment. Therefore, Fortran mode replaces the standard Emacs | |
3349 | comment commands and defines some new variables. | |
3350 | ||
85750656 DL |
3351 | Fortran mode can also handle the Fortran90 comment syntax where comments |
3352 | start with @samp{!} and can follow other text. Because only some Fortran77 | |
6bf7aab6 DL |
3353 | compilers accept this syntax, Fortran mode will not insert such comments |
3354 | unless you have said in advance to do so. To do this, set the variable | |
3355 | @code{comment-start} to @samp{"!"} (@pxref{Variables}). | |
3356 | ||
3357 | @table @kbd | |
3358 | @item M-; | |
3359 | Align comment or insert new comment (@code{fortran-comment-indent}). | |
3360 | ||
3361 | @item C-x ; | |
3362 | Applies to nonstandard @samp{!} comments only. | |
3363 | ||
3364 | @item C-c ; | |
3365 | Turn all lines of the region into comments, or (with argument) turn them back | |
3366 | into real code (@code{fortran-comment-region}). | |
3367 | @end table | |
3368 | ||
3369 | @kbd{M-;} in Fortran mode is redefined as the command | |
3370 | @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this | |
3371 | recognizes any kind of existing comment and aligns its text appropriately; | |
3372 | if there is no existing comment, a comment is inserted and aligned. But | |
3373 | inserting and aligning comments are not the same in Fortran mode as in | |
3374 | other modes. | |
3375 | ||
3376 | When a new comment must be inserted, if the current line is blank, a | |
3377 | full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} | |
3378 | comment is inserted if you have said you want to use them. Otherwise a | |
3379 | full-line comment is inserted on a new line before the current line. | |
3380 | ||
3381 | Nonstandard @samp{!} comments are aligned like comments in other | |
3382 | languages, but full-line comments are different. In a standard full-line | |
3383 | comment, the comment delimiter itself must always appear in column zero. | |
3384 | What can be aligned is the text within the comment. You can choose from | |
3385 | three styles of alignment by setting the variable | |
3386 | @code{fortran-comment-indent-style} to one of these values: | |
3387 | ||
3388 | @vindex fortran-comment-indent-style | |
3389 | @vindex fortran-comment-line-extra-indent | |
3390 | @table @code | |
3391 | @item fixed | |
3392 | Align the text at a fixed column, which is the sum of | |
3393 | @code{fortran-comment-line-extra-indent} and the minimum statement | |
3394 | indentation. This is the default. | |
3395 | ||
3396 | The minimum statement indentation is | |
3397 | @code{fortran-minimum-statement-indent-fixed} for fixed format | |
3398 | continuation line style and @code{fortran-minimum-statement-indent-tab} | |
3399 | for tab format style. | |
3400 | ||
3401 | @item relative | |
3402 | Align the text as if it were a line of code, but with an additional | |
3403 | @code{fortran-comment-line-extra-indent} columns of indentation. | |
3404 | ||
3405 | @item nil | |
3406 | Don't move text in full-line comments automatically at all. | |
3407 | @end table | |
3408 | ||
3409 | @vindex fortran-comment-indent-char | |
3410 | In addition, you can specify the character to be used to indent within | |
3411 | full-line comments by setting the variable | |
3412 | @code{fortran-comment-indent-char} to the single-character string you want | |
3413 | to use. | |
3414 | ||
3415 | @vindex comment-line-start | |
3416 | @vindex comment-line-start-skip | |
3417 | Fortran mode introduces two variables @code{comment-line-start} and | |
3418 | @code{comment-line-start-skip}, which play for full-line comments the same | |
3419 | roles played by @code{comment-start} and @code{comment-start-skip} for | |
3420 | ordinary text-following comments. Normally these are set properly by | |
3421 | Fortran mode, so you do not need to change them. | |
3422 | ||
3423 | The normal Emacs comment command @kbd{C-x ;} has not been redefined. If | |
3424 | you use @samp{!} comments, this command can be used with them. Otherwise | |
3425 | it is useless in Fortran mode. | |
3426 | ||
3427 | @kindex C-c ; @r{(Fortran mode)} | |
3428 | @findex fortran-comment-region | |
3429 | @vindex fortran-comment-region | |
3430 | The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the | |
3431 | lines of the region into comments by inserting the string @samp{C$$$} at | |
3432 | the front of each one. With a numeric argument, it turns the region | |
3433 | back into live code by deleting @samp{C$$$} from the front of each line | |
3434 | in it. The string used for these comments can be controlled by setting | |
3435 | the variable @code{fortran-comment-region}. Note that here we have an | |
3436 | example of a command and a variable with the same name; these two uses | |
3437 | of the name never conflict because in Lisp and in Emacs it is always | |
3438 | clear from the context which one is meant. | |
3439 | ||
3440 | @node Fortran Autofill | |
3441 | @subsection Fortran Auto Fill Mode | |
3442 | ||
3443 | Fortran Auto Fill mode is a minor mode which automatically splits | |
3444 | Fortran statements as you insert them when they become too wide. | |
3445 | Splitting a statement involves making continuation lines using | |
3446 | @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This | |
3447 | splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and | |
3448 | also in the Fortran indentation commands. | |
3449 | ||
3450 | @findex fortran-auto-fill-mode | |
3451 | @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it | |
3452 | was off, or off if it was on. This command works the same as @kbd{M-x | |
3453 | auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A | |
3454 | positive numeric argument turns Fortran Auto Fill mode on, and a | |
3455 | negative argument turns it off. You can see when Fortran Auto Fill mode | |
3456 | is in effect by the presence of the word @samp{Fill} in the mode line, | |
3457 | inside the parentheses. Fortran Auto Fill mode is a minor mode, turned | |
3458 | on or off for each buffer individually. @xref{Minor Modes}. | |
3459 | ||
3460 | @vindex fortran-break-before-delimiters | |
3461 | Fortran Auto Fill mode breaks lines at spaces or delimiters when the | |
3462 | lines get longer than the desired width (the value of @code{fill-column}). | |
3463 | The delimiters that Fortran Auto Fill mode may break at are @samp{,}, | |
3464 | @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}. | |
3465 | The line break comes after the delimiter if the variable | |
3466 | @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by | |
3467 | default), the break comes before the delimiter. | |
3468 | ||
3469 | By default, Fortran Auto Fill mode is not enabled. If you want this | |
3470 | feature turned on permanently, add a hook function to | |
3471 | @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}. | |
3472 | @xref{Hooks}. | |
3473 | ||
3474 | @node Fortran Columns | |
3475 | @subsection Checking Columns in Fortran | |
3476 | ||
3477 | @table @kbd | |
3478 | @item C-c C-r | |
3479 | Display a ``column ruler'' momentarily above the current line | |
3480 | (@code{fortran-column-ruler}). | |
3481 | @item C-c C-w | |
3482 | Split the current window horizontally temporarily so that it is 72 | |
3483 | columns wide. This may help you avoid making lines longer than the | |
3484 | 72-character limit that some Fortran compilers impose | |
3485 | (@code{fortran-window-create-momentarily}). | |
3486 | @end table | |
3487 | ||
3488 | @kindex C-c C-r @r{(Fortran mode)} | |
3489 | @findex fortran-column-ruler | |
3490 | @vindex fortran-column-ruler | |
3491 | The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column | |
3492 | ruler momentarily above the current line. The comment ruler is two lines | |
3493 | of text that show you the locations of columns with special significance in | |
3494 | Fortran programs. Square brackets show the limits of the columns for line | |
3495 | numbers, and curly brackets show the limits of the columns for the | |
3496 | statement body. Column numbers appear above them. | |
3497 | ||
3498 | Note that the column numbers count from zero, as always in GNU Emacs. | |
3499 | As a result, the numbers may be one less than those you are familiar | |
3500 | with; but the positions they indicate in the line are standard for | |
3501 | Fortran. | |
3502 | ||
79214ddf | 3503 | The text used to display the column ruler depends on the value of |
6bf7aab6 DL |
3504 | the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is |
3505 | @code{nil}, then the value of the variable | |
3506 | @code{fortran-column-ruler-fixed} is used as the column ruler. | |
3507 | Otherwise, the variable @code{fortran-column-ruler-tab} is displayed. | |
3508 | By changing these variables, you can change the column ruler display. | |
3509 | ||
138a8f12 | 3510 | @kindex C-u C-c C-w @r{(Fortran mode)} |
6bf7aab6 | 3511 | @findex fortran-window-create |
138a8f12 | 3512 | For even more help, use @kbd{M-x fortran-window-create}), a |
6bf7aab6 DL |
3513 | command which splits the current window horizontally, making a window 72 |
3514 | columns wide. By editing in this window you can immediately see when you | |
3515 | make a line too wide to be correct Fortran. | |
3516 | ||
138a8f12 DL |
3517 | @kindex C-c C-w @r{(Fortran mode)} |
3518 | @findex fortran-window-create-momentarily | |
3519 | Also, @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) can be | |
3520 | used temporarily to split the current window horizontally, making a | |
3521 | window 72 columns wide to check column widths rather than to edit in | |
3522 | this mode. The normal width is restored when you type a space. | |
3523 | ||
6bf7aab6 DL |
3524 | @node Fortran Abbrev |
3525 | @subsection Fortran Keyword Abbrevs | |
3526 | ||
3527 | Fortran mode provides many built-in abbrevs for common keywords and | |
3528 | declarations. These are the same sort of abbrev that you can define | |
3529 | yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. | |
3530 | ||
3531 | The built-in abbrevs are unusual in one way: they all start with a | |
3532 | semicolon. You cannot normally use semicolon in an abbrev, but Fortran | |
3533 | mode makes this possible by changing the syntax of semicolon to ``word | |
3534 | constituent.'' | |
3535 | ||
3536 | For example, one built-in Fortran abbrev is @samp{;c} for | |
3537 | @samp{continue}. If you insert @samp{;c} and then insert a punctuation | |
3538 | character such as a space or a newline, the @samp{;c} expands automatically | |
3539 | to @samp{continue}, provided Abbrev mode is enabled.@refill | |
3540 | ||
3541 | Type @samp{;?} or @samp{;C-h} to display a list of all the built-in | |
3542 | Fortran abbrevs and what they stand for. | |
3543 | ||
3544 | @node Fortran Misc | |
3545 | @subsection Other Fortran Mode Commands | |
3546 | ||
85750656 DL |
3547 | The command @kbd{fortran-strip-sqeuence-nos} can be used to remove text |
3548 | past Fortran column 72, which is typically old `sequence numbers'. | |
6bf7aab6 DL |
3549 | |
3550 | @node Asm Mode | |
3551 | @section Asm Mode | |
3552 | ||
3553 | @cindex Asm mode | |
138a8f12 | 3554 | @cindex Assembler mode |
6bf7aab6 DL |
3555 | Asm mode is a major mode for editing files of assembler code. It |
3556 | defines these commands: | |
3557 | ||
3558 | @table @kbd | |
3559 | @item @key{TAB} | |
3560 | @code{tab-to-tab-stop}. | |
3561 | @item C-j | |
3562 | Insert a newline and then indent using @code{tab-to-tab-stop}. | |
3563 | @item : | |
3564 | Insert a colon and then remove the indentation from before the label | |
3565 | preceding colon. Then do @code{tab-to-tab-stop}. | |
3566 | @item ; | |
3567 | Insert or align a comment. | |
3568 | @end table | |
3569 | ||
3570 | The variable @code{asm-comment-char} specifies which character | |
3571 | starts comments in assembler syntax. |