Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
93da5dff | 2 | @c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 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 | ||
e79c6b89 RS |
10 | Emacs provides many features to facilitate editing programs. Some |
11 | of these features can | |
6bf7aab6 DL |
12 | |
13 | @itemize @bullet | |
14 | @item | |
93da5dff | 15 | Find or move over top-level definitions (@pxref{Defuns}). |
6bf7aab6 | 16 | @item |
93da5dff RS |
17 | Apply the usual indentation conventions of the language |
18 | (@pxref{Program Indent}). | |
6bf7aab6 DL |
19 | @item |
20 | Insert, kill or align comments (@pxref{Comments}). | |
21 | @item | |
93da5dff | 22 | Balance parentheses (@pxref{Parentheses}). |
cf1c48d4 RS |
23 | @item |
24 | Highlight program syntax (@pxref{Font Lock}). | |
6bf7aab6 DL |
25 | @end itemize |
26 | ||
e79c6b89 RS |
27 | This chapter describes these features and many more. |
28 | ||
6bf7aab6 DL |
29 | @menu |
30 | * Program Modes:: Major modes for editing programs. | |
93da5dff RS |
31 | * Defuns:: Commands to operate on major top-level parts |
32 | of a program. | |
6bf7aab6 | 33 | * Program Indent:: Adjusting indentation to show the nesting. |
6bf7aab6 | 34 | * Comments:: Inserting, killing, and aligning comments. |
93da5dff RS |
35 | * Parentheses:: Commands that operate on parentheses. |
36 | * Documentation:: Getting documentation of functions you plan to call. | |
51ed0ea0 | 37 | * Hideshow:: Displaying blocks selectively. |
93da5dff | 38 | * Symbol Completion:: Completion on symbol names of your program or language. |
3b8b8888 | 39 | * Glasses:: Making identifiersLikeThis more readable. |
93da5dff | 40 | * Misc for Programs:: Other Emacs features useful for editing programs. |
79214ddf | 41 | * C Modes:: Special commands of C, C++, Objective-C, |
6bf7aab6 | 42 | Java, and Pike modes. |
51ed0ea0 DL |
43 | * Fortran:: Fortran mode and its special features. |
44 | * Asm Mode:: Asm mode and its special features. | |
6bf7aab6 DL |
45 | @end menu |
46 | ||
47 | @node Program Modes | |
48 | @section Major Modes for Programming Languages | |
6bf7aab6 | 49 | @cindex modes for programming languages |
cf1c48d4 RS |
50 | |
51 | Emacs has specialized major modes for various programming languages. | |
52 | @xref{Major Modes}. A programming language major mode typically | |
53 | specifies the syntax of expressions, the customary rules for | |
54 | indentation, how to do syntax highlighting for the language, and how | |
e79c6b89 RS |
55 | to find the beginning of a function definition. It often customizes |
56 | or provides facilities for compiling and debugging programs as well. | |
cf1c48d4 RS |
57 | |
58 | Ideally, Emacs should provide a major mode for each programming | |
59 | language that you might want to edit; if it doesn't have a mode for | |
60 | your favorite language, you can contribute one. But often the mode | |
61 | for one language can serve for other syntactically similar languages. | |
62 | The major mode for language @var{l} is called @code{@var{l}-mode}, | |
e79c6b89 | 63 | and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. |
cf1c48d4 RS |
64 | @xref{Choosing Modes}. |
65 | ||
6bf7aab6 DL |
66 | @cindex Perl mode |
67 | @cindex Icon mode | |
68 | @cindex Awk mode | |
69 | @cindex Makefile mode | |
70 | @cindex Tcl mode | |
71 | @cindex CPerl mode | |
138a8f12 DL |
72 | @cindex DSSSL mode |
73 | @cindex Octave mode | |
74 | @cindex Metafont mode | |
75 | @cindex Modula2 mode | |
76 | @cindex Prolog mode | |
77 | @cindex Simula mode | |
78 | @cindex VHDL mode | |
79 | @cindex M4 mode | |
80 | @cindex Shell-script mode | |
3b8b8888 DL |
81 | @cindex Delphi mode |
82 | @cindex PostScript mode | |
cf1c48d4 RS |
83 | The existing programming language major modes include Lisp, Scheme (a |
84 | variant of Lisp) and the Scheme-based DSSSL expression language, Ada, | |
85 | Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed | |
86 | format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s | |
87 | companion for font creation), Modula2, Objective-C, Octave, Pascal, | |
93da5dff | 88 | Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There is |
cf1c48d4 RS |
89 | also a major mode for makefiles, called Makefile mode. An alternative |
90 | mode for Perl is called CPerl mode. Modes are available for the | |
e79c6b89 | 91 | scripting languages of the common GNU and Unix shells, VMS DCL, and |
cf1c48d4 RS |
92 | MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for |
93 | editing various sorts of configuration files. | |
6bf7aab6 DL |
94 | |
95 | @kindex DEL @r{(programming modes)} | |
4f7666dc | 96 | @findex c-electric-backspace |
93da5dff RS |
97 | In most programming languages, indentation should vary from line to |
98 | line to illustrate the structure of the program. So the major modes | |
e79c6b89 RS |
99 | for programming languages arrange for @key{TAB} to update the |
100 | indentation of the current line. They also rebind @key{DEL} to treat | |
101 | a tab as if it were the equivalent number of spaces; this lets you | |
102 | delete one column of indentation without worrying whether the | |
103 | whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a | |
104 | tab character before point, in these modes. | |
6bf7aab6 | 105 | |
cf1c48d4 RS |
106 | Separate manuals are available for the modes for Ada (@pxref{Top, , Ada |
107 | Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL | |
108 | (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes | |
109 | (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). | |
f9fd7fbc | 110 | |
6bf7aab6 DL |
111 | @cindex mode hook |
112 | @vindex c-mode-hook | |
113 | @vindex lisp-mode-hook | |
114 | @vindex emacs-lisp-mode-hook | |
115 | @vindex lisp-interaction-mode-hook | |
116 | @vindex scheme-mode-hook | |
d2fab838 RS |
117 | Turning on a major mode runs a normal hook called the @dfn{mode |
118 | hook}, which is the value of a Lisp variable. Each major mode has a | |
119 | mode hook, and the hook's name is always made from the mode command's | |
120 | name by adding @samp{-hook}. For example, turning on C mode runs the | |
121 | hook @code{c-mode-hook}, while turning on Lisp mode runs the hook | |
122 | @code{lisp-mode-hook}. The purpose of the mode hook is to give you a | |
123 | place to set up customizations for that major mode. @xref{Hooks}. | |
6bf7aab6 | 124 | |
93da5dff RS |
125 | @node Defuns |
126 | @section Top-Level Definitions, or Defuns | |
6bf7aab6 | 127 | |
93da5dff RS |
128 | In Emacs, a major definition at the top level in the buffer is |
129 | called a @dfn{defun}. The name comes from Lisp, but in Emacs we use | |
130 | it for all languages. | |
6bf7aab6 | 131 | |
93da5dff RS |
132 | In most programming language modes, Emacs assumes that a defun is |
133 | any pair of parentheses (or braces, if the language uses braces this | |
134 | way) that starts at the left margin. For example, in C, the body of a | |
135 | function definition is normally a defun, because the open-brace that | |
136 | begins it is normally at the left margin. A variable's initializer | |
137 | can also count as a defun, if the open-brace that begins the | |
138 | initializer is at the left margin. | |
6bf7aab6 | 139 | |
93da5dff RS |
140 | However, some language modes provide their own code for recognizing |
141 | defuns in a way that suits the language syntax and conventions better. | |
6bf7aab6 | 142 | |
93da5dff RS |
143 | @menu |
144 | * Left Margin Paren:: An open-paren or similar opening delimiter | |
145 | starts a defun if it is at the left margin. | |
146 | * Moving by Defuns:: Commands to move over or mark a major definition. | |
147 | * Imenu:: Making buffer indexes as menus. | |
148 | * Which Function:: Which Function mode shows which function you are in. | |
149 | @end menu | |
6bf7aab6 | 150 | |
93da5dff RS |
151 | @node Left Margin Paren |
152 | @subsection Left Margin Convention | |
6bf7aab6 | 153 | |
93da5dff RS |
154 | @cindex open-parenthesis in leftmost column |
155 | @cindex ( in leftmost column | |
156 | In most major modes, Emacs assumes that any opening delimiter found | |
157 | at the left margin is the start of a top-level definition, or defun. | |
158 | Therefore, @strong{never put an opening delimiter at the left margin | |
159 | unless it should have that significance.} For instance, never put an | |
160 | open-parenthesis at the left margin in a Lisp file unless it is the | |
161 | start of a top-level list. Never put an open-brace or other opening | |
162 | delimiter at the beginning of a line of C code unless it is at top | |
163 | level. | |
164 | ||
165 | If you don't follow this convention, not only will you have trouble | |
166 | when you explicitly use the commands for motion by defuns; other | |
167 | features that use them will also give you trouble. This includes | |
168 | the indentation commands (@pxref{Program Indent}) and Font Lock | |
169 | mode (@pxref{Font Lock}). | |
170 | ||
171 | The most likely problem case is when you want an opening delimiter | |
172 | at the start of a line inside a string. To avoid trouble, put an | |
173 | escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some | |
174 | other Lisp dialects) before the opening delimiter. This will not | |
175 | affect the contents of the string, but will prevent that opening | |
176 | delimiter from starting a defun. Here's an example: | |
6bf7aab6 | 177 | |
93da5dff RS |
178 | @example |
179 | (insert "Foo: | |
180 | \(bar) | |
181 | ") | |
182 | @end example | |
6bf7aab6 | 183 | |
5b8fe684 RS |
184 | To help you catch violations of this convention, Font Lock mode |
185 | highlights confusing opening delimiters (those that ought to be | |
186 | quoted) in bold red. | |
187 | ||
93da5dff RS |
188 | In the earliest days, the original Emacs found defuns by moving |
189 | upward a level of parentheses or braces until there were no more | |
190 | levels to go up. This always required scanning all the way back to | |
191 | the beginning of the buffer, even for a small function. To speed up | |
192 | the operation, we changed Emacs to assume that any opening delimiter | |
193 | at the left margin is the start of a defun. This heuristic is nearly | |
194 | always right, and avoids the need to scan back to the beginning of the | |
195 | buffer. However, it mandates following the convention described | |
196 | above. | |
197 | ||
198 | @node Moving by Defuns | |
199 | @subsection Moving by Defuns | |
6bf7aab6 DL |
200 | @cindex defuns |
201 | ||
93da5dff RS |
202 | These commands move point or set up the region based on top-level |
203 | major definitions, also called @dfn{defuns}. | |
520c3f4c | 204 | |
6bf7aab6 DL |
205 | @table @kbd |
206 | @item C-M-a | |
207 | Move to beginning of current or preceding defun | |
208 | (@code{beginning-of-defun}). | |
209 | @item C-M-e | |
210 | Move to end of current or following defun (@code{end-of-defun}). | |
211 | @item C-M-h | |
212 | Put region around whole current or following defun (@code{mark-defun}). | |
213 | @end table | |
214 | ||
f772775c RS |
215 | @cindex move to beginning or end of function |
216 | @cindex function, move to beginning or end | |
217 | @kindex C-M-a | |
218 | @kindex C-M-e | |
219 | @kindex C-M-h | |
220 | @findex beginning-of-defun | |
221 | @findex end-of-defun | |
222 | @findex mark-defun | |
223 | The commands to move to the beginning and end of the current defun | |
224 | are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} | |
225 | (@code{end-of-defun}). If you repeat one of these commands, or use a | |
226 | positive numeric argument, each repetition moves to the next defun in | |
227 | the direction of motion. | |
228 | ||
229 | @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward | |
230 | @var{n} times to the next beginning of a defun. This is not exactly | |
231 | the same place that @kbd{C-M-e} with argument @var{n} would move to; | |
232 | the end of this defun is not usually exactly the same place as the | |
93da5dff RS |
233 | beginning of the following defun. (Whitespace, comments, and perhaps |
234 | declarations can separate them.) Likewise, @kbd{C-M-e} with a | |
235 | negative argument moves back to an end of a defun, which is not quite | |
236 | the same as @kbd{C-M-a} with a positive argument. | |
f772775c | 237 | |
4946337d | 238 | @kindex C-M-h @r{(C mode)} |
6bf7aab6 | 239 | @findex c-mark-function |
93da5dff RS |
240 | To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun}) |
241 | which puts point at the beginning and mark at the end of the current | |
5e6f9132 RS |
242 | defun. This is the easiest way to get ready to kill the defun in |
243 | order to move it to a different place in the file. If you use the | |
244 | command while point is between defuns, it uses the following defun. | |
93da5dff RS |
245 | |
246 | In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, | |
247 | which is almost the same as @code{mark-defun}; the difference is that | |
248 | it backs up over the argument declarations, function name and returned | |
e79c6b89 RS |
249 | data type so that the entire C function is inside the region. This is |
250 | an example of how major modes adjust the standard key bindings so that | |
251 | they do their standard jobs in a way better fitting a particular | |
252 | language. Other major modes may replace any or all of these key | |
253 | bindings for that purpose. | |
6bf7aab6 | 254 | |
93da5dff RS |
255 | @node Imenu |
256 | @subsection Imenu | |
e79c6b89 RS |
257 | @cindex index of buffer definitions |
258 | @cindex buffer definitions index | |
93da5dff RS |
259 | @cindex tags |
260 | ||
269b7745 | 261 | The Imenu facility offers a way to find the major definitions in |
5e6f9132 RS |
262 | a file by name. It is also useful in text formatter major modes, |
263 | where it treats each chapter, section, etc., as a definition. | |
e79c6b89 | 264 | (@xref{Tags}, for a more powerful feature that handles multiple files |
5e6f9132 | 265 | together.) |
93da5dff RS |
266 | |
267 | @findex imenu | |
5e6f9132 | 268 | If you type @kbd{M-x imenu}, it reads the name of a definition using |
e79c6b89 RS |
269 | the minibuffer, then moves point to that definition. You can use |
270 | completion to specify the name; the command always displays the whole | |
271 | list of valid names. | |
d2fab838 | 272 | |
5e6f9132 | 273 | @findex imenu-add-menubar-index |
d2fab838 | 274 | Alternatively, you can bind the command @code{imenu} to a mouse |
e79c6b89 RS |
275 | click. Then it displays mouse menus for you to select a definition |
276 | name. You can also add the buffer's index to the menu bar by calling | |
277 | @code{imenu-add-menubar-index}. If you want to have this menu bar | |
278 | item available for all buffers in a certain major mode, you can do | |
279 | this by adding @code{imenu-add-menubar-index} to its mode hook. But | |
280 | if you have done that, you will have to wait each time you visit a | |
281 | file in that mode, while Emacs finds all the definitions in that | |
282 | buffer. | |
93da5dff RS |
283 | |
284 | @vindex imenu-auto-rescan | |
285 | When you change the contents of a buffer, if you add or delete | |
e79c6b89 | 286 | definitions, you can update the buffer's index based on the |
d2fab838 | 287 | new contents by invoking the @samp{*Rescan*} item in the menu. |
dcace646 EZ |
288 | Rescanning happens automatically if you set @code{imenu-auto-rescan} to |
289 | a non-@code{nil} value. There is no need to rescan because of small | |
e79c6b89 | 290 | changes in the text. |
93da5dff RS |
291 | |
292 | @vindex imenu-sort-function | |
d2fab838 | 293 | You can customize the way the menus are sorted by setting the |
e79c6b89 | 294 | variable @code{imenu-sort-function}. By default, names are ordered as |
5e6f9132 RS |
295 | they occur in the buffer; if you want alphabetic sorting, use the |
296 | symbol @code{imenu--sort-by-name} as the value. You can also | |
297 | define your own comparison function by writing Lisp code. | |
93da5dff RS |
298 | |
299 | Imenu provides the information to guide Which Function mode | |
300 | @ifnottex | |
301 | (@pxref{Which Function}). | |
302 | @end ifnottex | |
303 | @iftex | |
304 | (see below). | |
305 | @end iftex | |
306 | The Speedbar can also use it (@pxref{Speedbar}). | |
307 | ||
308 | @node Which Function | |
309 | @subsection Which Function Mode | |
af056954 | 310 | @cindex current function name in mode line |
93da5dff RS |
311 | |
312 | Which Function mode is a minor mode that displays the current | |
313 | function name in the mode line, updating it as you move around in a | |
314 | buffer. | |
315 | ||
316 | @findex which-function-mode | |
317 | @vindex which-func-modes | |
318 | To enable (or disable) Which Function mode, use the command @kbd{M-x | |
319 | which-function-mode}. This command is global; it applies to all | |
e79c6b89 RS |
320 | buffers, both existing ones and those yet to be created. However, |
321 | it only takes effect in certain major modes, those listed in the value of | |
322 | @code{which-func-modes}. If the value is @code{t}, then Which | |
323 | Function mode applies to all major modes that know how to support | |
324 | it---in other words, all the major modes that support Imenu. | |
6bf7aab6 DL |
325 | |
326 | @node Program Indent | |
327 | @section Indentation for Programs | |
328 | @cindex indentation for programs | |
329 | ||
330 | The best way to keep a program properly indented is to use Emacs to | |
331 | reindent it as you change it. Emacs has commands to indent properly | |
332 | either a single line, a specified number of lines, or all of the lines | |
333 | inside a single parenthetical grouping. | |
334 | ||
335 | @menu | |
336 | * Basic Indent:: Indenting a single line. | |
337 | * Multi-line Indent:: Commands to reindent many lines at once. | |
338 | * Lisp Indent:: Specifying how each Lisp function should be indented. | |
339 | * C Indent:: Extra features for indenting C and related modes. | |
340 | * Custom C Indent:: Controlling indentation style for C and related modes. | |
341 | @end menu | |
342 | ||
d2fab838 | 343 | @cindex pretty-printer |
6bf7aab6 DL |
344 | Emacs also provides a Lisp pretty-printer in the library @code{pp}. |
345 | This program reformats a Lisp object with indentation chosen to look nice. | |
346 | ||
347 | @node Basic Indent | |
348 | @subsection Basic Program Indentation Commands | |
349 | ||
d2fab838 RS |
350 | The basic indentation commands indent a single line according to the |
351 | usual conventions of the language you are editing. | |
cf1c48d4 | 352 | |
6bf7aab6 DL |
353 | @table @kbd |
354 | @item @key{TAB} | |
355 | Adjust indentation of current line. | |
356 | @item C-j | |
357 | Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
d2fab838 | 358 | @item @key{LINEFEED} |
e79c6b89 | 359 | This key, if the keyboard has it, is another way to enter @kbd{C-j}. |
6bf7aab6 DL |
360 | @end table |
361 | ||
362 | @kindex TAB @r{(programming modes)} | |
4f7666dc RS |
363 | @findex c-indent-command |
364 | @findex indent-line-function | |
f772775c | 365 | @findex indent-for-tab-command |
6bf7aab6 DL |
366 | The basic indentation command is @key{TAB}, which gives the current line |
367 | the correct indentation as determined from the previous lines. The | |
cf1c48d4 RS |
368 | function that @key{TAB} runs depends on the major mode; it is |
369 | @code{indent-for-tab-command} | |
4f7666dc | 370 | in Lisp mode, @code{c-indent-command} in C mode, etc. These functions |
cf1c48d4 RS |
371 | understand the syntax and conventions of different languages, but they all do |
372 | conceptually the same job: @key{TAB} in any programming-language major mode | |
6bf7aab6 | 373 | inserts or deletes whitespace at the beginning of the current line, |
cf1c48d4 RS |
374 | independent of where point is in the line. If point was inside the |
375 | whitespace at the beginning of the line, @key{TAB} puts it at the end of | |
376 | that whitespace; otherwise, @key{TAB} keeps point fixed with respect to | |
6bf7aab6 DL |
377 | the characters around it. |
378 | ||
379 | Use @kbd{C-q @key{TAB}} to insert a tab at point. | |
380 | ||
381 | @kindex C-j | |
382 | @findex newline-and-indent | |
cf1c48d4 RS |
383 | When entering lines of new code, use @kbd{C-j} |
384 | (@code{newline-and-indent}), which is equivalent to a @key{RET} | |
385 | followed by a @key{TAB}. @kbd{C-j} at the end of a line creates a | |
386 | blank line and then gives it the appropriate indentation. | |
6bf7aab6 | 387 | |
f772775c RS |
388 | @key{TAB} indents lines that start within a parenthetical grouping |
389 | each under the preceding line (or the text after the parenthesis). | |
390 | Therefore, if you manually give one of these lines a nonstandard | |
391 | indentation, the lines below will tend to follow it. This behavior is | |
392 | convenient in cases where you have overridden the standard result of | |
393 | @key{TAB} because you find it unaesthetic for a particular line. | |
6bf7aab6 DL |
394 | |
395 | Remember that an open-parenthesis, open-brace or other opening delimiter | |
396 | at the left margin is assumed by Emacs (including the indentation routines) | |
397 | to be the start of a function. Therefore, you must never have an opening | |
398 | delimiter in column zero that is not the beginning of a function, not even | |
399 | inside a string. This restriction is vital for making the indentation | |
93da5dff RS |
400 | commands fast; you must simply accept it. @xref{Left Margin Paren}, |
401 | for more information on this. | |
6bf7aab6 | 402 | |
5151db0c EZ |
403 | Normally, lines are indented with tabs and spaces. If you want Emacs |
404 | to use spaces only, see @ref{Just Spaces}. | |
405 | ||
6bf7aab6 DL |
406 | @node Multi-line Indent |
407 | @subsection Indenting Several Lines | |
408 | ||
93da5dff RS |
409 | When you wish to reindent several lines of code which have been |
410 | altered or moved to a different level in the parenthesis structure, | |
411 | you have several commands available. | |
6bf7aab6 DL |
412 | |
413 | @table @kbd | |
414 | @item C-M-q | |
93da5dff | 415 | Reindent all the lines within one parenthetical grouping(@code{indent-sexp}). |
e79c6b89 RS |
416 | @item C-M-\ |
417 | Reindent all lines in the region (@code{indent-region}). | |
6bf7aab6 | 418 | @item C-u @key{TAB} |
93da5dff RS |
419 | Shift an entire parenthetical grouping rigidly sideways so that its |
420 | first line is properly indented. | |
5cc06e0b EZ |
421 | @item M-x indent-code-rigidly |
422 | Shift all the lines in the region rigidly sideways, but do not alter | |
423 | lines that start inside comments and strings. | |
6bf7aab6 DL |
424 | @end table |
425 | ||
426 | @kindex C-M-q | |
427 | @findex indent-sexp | |
93da5dff RS |
428 | You can reindent the contents of a single parenthetical grouping by |
429 | positioning point before the beginning of it and typing @kbd{C-M-q} | |
430 | (@code{indent-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also | |
431 | bound to other suitable commands in other modes). The indentation of | |
432 | the line where the grouping starts is not changed; therefore, this | |
433 | changes only the relative indentation within the grouping, not its | |
434 | overall indentation. To correct that as well, type @key{TAB} first. | |
6bf7aab6 | 435 | |
e79c6b89 RS |
436 | Another way to specify the range to be reindented is with the |
437 | region. The command @kbd{C-M-\} (@code{indent-region}) applies | |
438 | @key{TAB} to every line whose first character is between point and | |
439 | mark. | |
440 | ||
6bf7aab6 | 441 | @kindex C-u TAB |
93da5dff RS |
442 | If you like the relative indentation within a grouping, but not the |
443 | indentation of its first line, you can type @kbd{C-u @key{TAB}} to | |
24c7c69c RS |
444 | reindent the whole grouping as a rigid unit. (This works in Lisp |
445 | modes and C and related modes.) @key{TAB} with a numeric argument | |
446 | reindents the current line as usual, then reindents by the same amount | |
447 | all the lines in the parenthetical grouping starting on the current | |
448 | line. It is clever, though, and does not alter lines that start | |
449 | inside strings, or C preprocessor lines when in C mode. | |
6bf7aab6 | 450 | |
5cc06e0b | 451 | @findex indent-code-rigidly |
e79c6b89 RS |
452 | You can also perform this operation on the region, using the command |
453 | @kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the | |
454 | region sideways, like @code{indent-rigidly} does (@pxref{Indentation | |
455 | Commands}). It doesn't alter the indentation of lines that start | |
456 | inside a comment or a string, unless the region starts inside that | |
5cc06e0b | 457 | comment or string. |
6bf7aab6 DL |
458 | |
459 | @node Lisp Indent | |
460 | @subsection Customizing Lisp Indentation | |
461 | @cindex customizing Lisp indentation | |
462 | ||
463 | The indentation pattern for a Lisp expression can depend on the function | |
464 | called by the expression. For each Lisp function, you can choose among | |
465 | several predefined patterns of indentation, or define an arbitrary one with | |
466 | a Lisp program. | |
467 | ||
468 | The standard pattern of indentation is as follows: the second line of the | |
469 | expression is indented under the first argument, if that is on the same | |
470 | line as the beginning of the expression; otherwise, the second line is | |
471 | indented underneath the function name. Each following line is indented | |
472 | under the previous line whose nesting depth is the same. | |
473 | ||
474 | @vindex lisp-indent-offset | |
475 | If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides | |
476 | the usual indentation pattern for the second line of an expression, so that | |
477 | such lines are always indented @code{lisp-indent-offset} more columns than | |
478 | the containing list. | |
479 | ||
480 | @vindex lisp-body-indent | |
d2fab838 | 481 | Certain functions override the standard pattern. Functions whose |
269b7745 | 482 | names start with @code{def} treat the second lines as the start of |
d2fab838 RS |
483 | a @dfn{body}, by indenting the second line @code{lisp-body-indent} |
484 | additional columns beyond the open-parenthesis that starts the | |
485 | expression. | |
6bf7aab6 | 486 | |
b771b258 | 487 | @cindex @code{lisp-indent-function} property |
d2fab838 | 488 | You can override the standard pattern in various ways for individual |
6b61353c KH |
489 | functions, according to the @code{lisp-indent-function} property of |
490 | the function name. Normally you would use this for macro definitions | |
491 | and specify it using the @code{declare} construct (@pxref{Defining | |
492 | Macros,,, elisp, the Emacs Lisp Reference Manual}). | |
6bf7aab6 DL |
493 | |
494 | @node C Indent | |
495 | @subsection Commands for C Indentation | |
496 | ||
93da5dff | 497 | Here are special features for indentation in C mode and related modes: |
6bf7aab6 DL |
498 | |
499 | @table @code | |
500 | @item C-c C-q | |
501 | @kindex C-c C-q @r{(C mode)} | |
502 | @findex c-indent-defun | |
503 | Reindent the current top-level function definition or aggregate type | |
504 | declaration (@code{c-indent-defun}). | |
505 | ||
506 | @item C-M-q | |
507 | @kindex C-M-q @r{(C mode)} | |
508 | @findex c-indent-exp | |
509 | Reindent each line in the balanced expression that follows point | |
510 | (@code{c-indent-exp}). A prefix argument inhibits error checking and | |
511 | warning messages about invalid syntax. | |
512 | ||
513 | @item @key{TAB} | |
514 | @findex c-indent-command | |
515 | Reindent the current line, and/or in some cases insert a tab character | |
516 | (@code{c-indent-command}). | |
517 | ||
518 | If @code{c-tab-always-indent} is @code{t}, this command always reindents | |
519 | the current line and does nothing else. This is the default. | |
520 | ||
521 | If that variable is @code{nil}, this command reindents the current line | |
522 | only if point is at the left margin or in the line's indentation; | |
523 | otherwise, it inserts a tab (or the equivalent number of spaces, | |
524 | if @code{indent-tabs-mode} is @code{nil}). | |
525 | ||
526 | Any other value (not @code{nil} or @code{t}) means always reindent the | |
527 | line, and also insert a tab if within a comment, a string, or a | |
528 | preprocessor directive. | |
6bf7aab6 DL |
529 | @end table |
530 | ||
531 | To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This | |
532 | first selects the whole buffer as the region, then reindents that | |
533 | region. | |
534 | ||
535 | To reindent the current block, use @kbd{C-M-u C-M-q}. This moves | |
536 | to the front of the block and then reindents it all. | |
537 | ||
538 | @node Custom C Indent | |
539 | @subsection Customizing C Indentation | |
93da5dff | 540 | @cindex style (for indentation) |
6bf7aab6 DL |
541 | |
542 | C mode and related modes use a simple yet flexible mechanism for | |
543 | customizing indentation. The mechanism works in two steps: first it | |
544 | classifies the line syntactically according to its contents and context; | |
545 | second, it associates each kind of syntactic construct with an | |
93da5dff | 546 | indentation offset based on your selected @dfn{style}. |
6bf7aab6 | 547 | |
93da5dff RS |
548 | @table @kbd |
549 | @item M-x c-set-style @key{RET} @var{style} @key{RET} | |
550 | Select predefined indentation style @var{style}. | |
551 | @end table | |
6bf7aab6 | 552 | |
93da5dff RS |
553 | A style is a named collection of indentation customizations that can |
554 | be used in C mode and the related modes. Emacs comes with several | |
555 | predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, | |
556 | @code{stroustrup}, @code{linux}, @code{python}, @code{java}, | |
557 | @code{whitesmith}, @code{ellemtel}, @code{cc-mode}, and @code{user}. | |
558 | Some of these styles are primarily intended for one language, but any | |
559 | of them can be used with any of the languages supported by these | |
560 | modes. To find out what a style looks like, select it and reindent | |
561 | some code, e.g., by typing @key{C-M-q} at the start of a function | |
562 | definition. | |
6bf7aab6 | 563 | |
93da5dff RS |
564 | @findex c-set-style |
565 | To choose a style for the current buffer, use the command @kbd{M-x | |
566 | c-set-style}. Specify a style name as an argument (case is not | |
567 | significant). This command affects the current buffer only, and it | |
568 | affects only future invocations of the indentation commands; it does | |
e79c6b89 RS |
569 | not reindent the code in the buffer. To reindent the whole buffer in |
570 | the new style, you can type @kbd{C-x h C-M-\}. | |
6bf7aab6 | 571 | |
93da5dff RS |
572 | @vindex c-default-style |
573 | You can also set the variable @code{c-default-style} to specify the | |
574 | default style for various major modes. Its value should be an alist, | |
575 | in which each element specifies one major mode and which indentation | |
576 | style to use for it. For example, | |
6bf7aab6 DL |
577 | |
578 | @example | |
93da5dff RS |
579 | (setq c-default-style |
580 | '((java-mode . "java") (other . "gnu"))) | |
6bf7aab6 DL |
581 | @end example |
582 | ||
93da5dff RS |
583 | @noindent |
584 | specifies an explicit choice for Java mode, and the default @samp{gnu} | |
585 | style for the other C-like modes. This variable takes effect when you | |
e79c6b89 | 586 | select one of the C-like major modes; thus, if you specify a new |
93da5dff RS |
587 | default style for Java mode, you can make it take effect in an |
588 | existing Java mode buffer by typing @kbd{M-x java-mode} there. | |
6bf7aab6 | 589 | |
93da5dff RS |
590 | The @code{gnu} style specifies the formatting recommended by the GNU |
591 | Project for C; it is the default, so as to encourage use of our | |
592 | recommended style. | |
6bf7aab6 | 593 | |
0d103856 | 594 | @xref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for |
93da5dff RS |
595 | more information on customizing indentation for C and related modes, |
596 | including how to override parts of an existing style and how to define | |
597 | your own styles. | |
6bf7aab6 | 598 | |
93da5dff RS |
599 | @node Parentheses |
600 | @section Commands for Editing with Parentheses | |
6bf7aab6 | 601 | |
93da5dff RS |
602 | @findex check-parens |
603 | @cindex unbalanced parentheses and quotes | |
604 | This section describes the commands and features that take advantage | |
605 | of the parenthesis structure in a program, or help you keep it | |
606 | balanced. | |
6bf7aab6 | 607 | |
93da5dff RS |
608 | When talking about these facilities, the term ``parenthesis'' also |
609 | includes braces, brackets, or whatever delimiters are defined to match | |
e79c6b89 RS |
610 | in pairs. The major mode controls which delimiters are significant, |
611 | through the syntax table (@pxref{Syntax}). In Lisp, only parentheses | |
612 | count; in C, these commands apply to braces and brackets too. | |
6bf7aab6 | 613 | |
93da5dff RS |
614 | You can use @kbd{M-x check-parens} to find any unbalanced |
615 | parentheses and unbalanced string quotes in the buffer. | |
6bf7aab6 | 616 | |
93da5dff RS |
617 | @menu |
618 | * Expressions:: Expressions with balanced parentheses. | |
619 | * Moving by Parens:: Commands for moving up, down and across | |
620 | in the structure of parentheses. | |
621 | * Matching:: Insertion of a close-delimiter flashes matching open. | |
622 | @end menu | |
6bf7aab6 | 623 | |
93da5dff RS |
624 | @node Expressions |
625 | @subsection Expressions with Balanced Parentheses | |
6bf7aab6 | 626 | |
93da5dff RS |
627 | @cindex sexp |
628 | @cindex expression | |
629 | @cindex balanced expression | |
630 | These commands deal with balanced expressions, also called | |
631 | @dfn{sexps}@footnote{The word ``sexp'' is used to refer to an | |
632 | expression in Lisp.}. | |
6bf7aab6 | 633 | |
93da5dff RS |
634 | @table @kbd |
635 | @item C-M-f | |
636 | Move forward over a balanced expression (@code{forward-sexp}). | |
637 | @item C-M-b | |
638 | Move backward over a balanced expression(@code{backward-sexp}). | |
639 | @item C-M-k | |
640 | Kill balanced expression forward (@code{kill-sexp}). | |
93da5dff RS |
641 | @item C-M-t |
642 | Transpose expressions (@code{transpose-sexps}). | |
643 | @item C-M-@@ | |
6b61353c | 644 | @itemx C-M-@key{SPC} |
93da5dff RS |
645 | Put mark after following expression (@code{mark-sexp}). |
646 | @end table | |
6bf7aab6 | 647 | |
93da5dff RS |
648 | Each programming language major mode customizes the definition of |
649 | balanced expressions to suit that language. Balanced expressions | |
650 | typically include symbols, numbers, and string constants, as well as | |
e79c6b89 | 651 | any pair of matching delimiters and their contents. Some languages |
93da5dff RS |
652 | have obscure forms of expression syntax that nobody has bothered to |
653 | implement in Emacs. | |
6bf7aab6 | 654 | |
93da5dff | 655 | @cindex Control-Meta |
e79c6b89 RS |
656 | By convention, the keys for these commands are all Control-Meta |
657 | characters. They usually act on expressions just as the corresponding | |
658 | Meta characters act on words. For instance, the command @kbd{C-M-b} | |
659 | moves backward over a balanced expression, just as @kbd{M-b} moves | |
660 | back over a word. | |
6bf7aab6 | 661 | |
93da5dff RS |
662 | @kindex C-M-f |
663 | @kindex C-M-b | |
664 | @findex forward-sexp | |
665 | @findex backward-sexp | |
666 | To move forward over a balanced expression, use @kbd{C-M-f} | |
667 | (@code{forward-sexp}). If the first significant character after point | |
668 | is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or | |
669 | @samp{@{} in C), @kbd{C-M-f} moves past the matching closing | |
670 | delimiter. If the character begins a symbol, string, or number, | |
671 | @kbd{C-M-f} moves over that. | |
6bf7aab6 | 672 | |
93da5dff RS |
673 | The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a |
674 | balanced expression. The detailed rules are like those above for | |
675 | @kbd{C-M-f}, but with directions reversed. If there are prefix | |
676 | characters (single-quote, backquote and comma, in Lisp) preceding the | |
677 | expression, @kbd{C-M-b} moves back over them as well. The balanced | |
678 | expression commands move across comments as if they were whitespace, | |
679 | in most modes. | |
6bf7aab6 | 680 | |
93da5dff RS |
681 | @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the |
682 | specified number of times; with a negative argument, it moves in the | |
683 | opposite direction. | |
6bf7aab6 | 684 | |
93da5dff RS |
685 | @cindex killing expressions |
686 | @kindex C-M-k | |
687 | @findex kill-sexp | |
93da5dff | 688 | Killing a whole balanced expression can be done with @kbd{C-M-k} |
880b0421 RS |
689 | (@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} |
690 | would move over. | |
6bf7aab6 | 691 | |
93da5dff RS |
692 | @cindex transposition of expressions |
693 | @kindex C-M-t | |
694 | @findex transpose-sexps | |
695 | A somewhat random-sounding command which is nevertheless handy is | |
696 | @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous | |
697 | balanced expression across the next one. An argument serves as a | |
e79c6b89 RS |
698 | repeat count, and a negative argument drags the previous balanced |
699 | expression backwards across those before it (thus canceling out the | |
700 | effect of @kbd{C-M-t} with a positive argument). An argument of zero, | |
701 | rather than doing nothing, transposes the balanced expressions ending | |
702 | at or after point and the mark. | |
6bf7aab6 | 703 | |
93da5dff | 704 | @kindex C-M-@@ |
6b61353c | 705 | @kindex C-M-@key{SPC} |
93da5dff RS |
706 | @findex mark-sexp |
707 | To set the region around the next balanced expression in the buffer, | |
708 | use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place | |
709 | that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like | |
710 | @kbd{C-M-f}. In particular, a negative argument is useful for putting | |
711 | the mark at the beginning of the previous balanced expression. | |
6b61353c | 712 | The alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. |
93da5dff RS |
713 | |
714 | In languages that use infix operators, such as C, it is not possible | |
715 | to recognize all balanced expressions as such because there can be | |
716 | multiple possibilities at a given position. For example, C mode does | |
717 | not treat @samp{foo + bar} as a single expression, even though it | |
718 | @emph{is} one C expression; instead, it recognizes @samp{foo} as one | |
719 | expression and @samp{bar} as another, with the @samp{+} as punctuation | |
720 | between them. Both @samp{foo + bar} and @samp{foo} are legitimate | |
721 | choices for ``the expression following point'' when point is at the | |
e79c6b89 RS |
722 | @samp{f}, so the expression commands must perforce choose one or the |
723 | other to operate on. Note that @samp{(foo + bar)} is recognized as a | |
724 | single expression in C mode, because of the parentheses. | |
93da5dff RS |
725 | |
726 | @node Moving by Parens | |
727 | @subsection Moving in the Parenthesis Structure | |
728 | ||
729 | @cindex parenthetical groupings | |
730 | @cindex parentheses, moving across | |
731 | @cindex matching parenthesis and braces, moving to | |
732 | @cindex braces, moving across | |
733 | @cindex list commands | |
734 | The Emacs commands for handling parenthetical groupings see nothing | |
735 | except parentheses (or whatever characters must balance in the | |
736 | language you are working with), and the escape characters that might | |
737 | be used to quote those. They are mainly intended for editing | |
738 | programs, but can be useful for editing any text that has parentheses. | |
739 | They are sometimes called ``list'' commands because in Lisp these | |
740 | groupings are lists. | |
6bf7aab6 DL |
741 | |
742 | @table @kbd | |
93da5dff RS |
743 | @item C-M-n |
744 | Move forward over a parenthetical group (@code{forward-list}). | |
745 | @item C-M-p | |
746 | Move backward over a parenthetical group(@code{backward-list}). | |
747 | @item C-M-u | |
748 | Move up in parenthesis structure (@code{backward-up-list}). | |
749 | @item C-M-d | |
750 | Move down in parenthesis structure (@code{down-list}). | |
6bf7aab6 DL |
751 | @end table |
752 | ||
93da5dff RS |
753 | @kindex C-M-n |
754 | @kindex C-M-p | |
755 | @findex forward-list | |
756 | @findex backward-list | |
757 | The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and | |
758 | @kbd{C-M-p} (@code{backward-list}) move over one (or @var{n}) | |
759 | parenthetical groupings, skipping blithely over any amount of text | |
760 | that doesn't include meaningful parentheses (symbols, strings, etc.). | |
6bf7aab6 | 761 | |
93da5dff RS |
762 | @kindex C-M-u |
763 | @kindex C-M-d | |
764 | @findex backward-up-list | |
765 | @findex down-list | |
766 | @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the | |
767 | parenthesis structure. To move @emph{up} one (or @var{n}) levels, use | |
768 | @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up | |
769 | past one unmatched opening delimiter. A positive argument serves as a | |
770 | repeat count; a negative argument reverses the direction of motion, so | |
d2fab838 | 771 | that the command moves forward and up one or more levels. |
93da5dff RS |
772 | |
773 | To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} | |
774 | (@code{down-list}). In Lisp mode, where @samp{(} is the only opening | |
775 | delimiter, this is nearly the same as searching for a @samp{(}. An | |
776 | argument specifies the number of levels to go down. | |
6bf7aab6 DL |
777 | |
778 | @node Matching | |
93da5dff | 779 | @subsection Automatic Display Of Matching Parentheses |
6bf7aab6 DL |
780 | @cindex matching parentheses |
781 | @cindex parentheses, displaying matches | |
782 | ||
783 | The Emacs parenthesis-matching feature is designed to show | |
93da5dff RS |
784 | automatically how parentheses (and other matching delimiters) match in |
785 | the text. Whenever you type a self-inserting character that is a | |
786 | closing delimiter, the cursor moves momentarily to the location of the | |
787 | matching opening delimiter, provided that is on the screen. If it is | |
e79c6b89 RS |
788 | not on the screen, Emacs displays some of the text near it in the echo |
789 | area. Either way, you can tell which grouping you are closing off. | |
93da5dff RS |
790 | |
791 | If the opening delimiter and closing delimiter are mismatched---such | |
792 | as in @samp{[x)}---a warning message is displayed in the echo area. | |
6bf7aab6 DL |
793 | |
794 | @vindex blink-matching-paren | |
795 | @vindex blink-matching-paren-distance | |
796 | @vindex blink-matching-delay | |
797 | Three variables control parenthesis match display. | |
93da5dff RS |
798 | @code{blink-matching-paren} turns the feature on or off: @code{nil} |
799 | disables it, but the default is @code{t} to enable match display. | |
f772775c RS |
800 | |
801 | @code{blink-matching-delay} says how many seconds to leave the | |
93da5dff | 802 | cursor on the matching opening delimiter, before bringing it back to |
f772775c RS |
803 | the real location of point; the default is 1, but on some systems it |
804 | is useful to specify a fraction of a second. | |
805 | ||
806 | @code{blink-matching-paren-distance} specifies how many characters | |
807 | back to search to find the matching opening delimiter. If the match | |
8b6f4c0a | 808 | is not found in that distance, scanning stops, and nothing is displayed. |
93da5dff | 809 | This is to prevent the scan for the matching delimiter from wasting |
f772775c | 810 | lots of time when there is no match. The default is 25600. |
6bf7aab6 DL |
811 | |
812 | @cindex Show Paren mode | |
79f9f655 | 813 | @cindex highlighting matching parentheses |
6bf7aab6 | 814 | @findex show-paren-mode |
93da5dff RS |
815 | Show Paren mode provides a more powerful kind of automatic matching. |
816 | Whenever point is after a closing delimiter, that delimiter and its | |
817 | matching opening delimiter are both highlighted; otherwise, if point | |
818 | is before an opening delimiter, the matching closing delimiter is | |
819 | highlighted. (There is no need to highlight the opening delimiter in | |
820 | that case, because the cursor appears on top of that character.) Use | |
821 | the command @kbd{M-x show-paren-mode} to enable or disable this mode. | |
79f9f655 EZ |
822 | |
823 | By default, @code{show-paren-mode} uses colors to highlight the | |
824 | parentheses. However, if your display doesn't support colors, you can | |
825 | customize the faces @code{show-paren-match-face} and | |
826 | @code{show-paren-mismatch-face} to use other attributes, such as bold or | |
827 | underline. @xref{Face Customization}. | |
6bf7aab6 DL |
828 | |
829 | @node Comments | |
830 | @section Manipulating Comments | |
831 | @cindex comments | |
832 | ||
833 | Because comments are such an important part of programming, Emacs | |
8f50b630 RS |
834 | provides special commands for editing and inserting comments. It can |
835 | also do spell checking on comments with Flyspell Prog mode | |
836 | (@pxref{Spelling}). | |
6bf7aab6 DL |
837 | |
838 | @menu | |
93da5dff RS |
839 | * Comment Commands:: Inserting, killing, and indenting comments. |
840 | * Multi-Line Comments:: Commands for adding and editing multi-line comments. | |
841 | * Options for Comments::Customizing the comment features. | |
6bf7aab6 DL |
842 | @end menu |
843 | ||
844 | @node Comment Commands | |
845 | @subsection Comment Commands | |
6bf7aab6 | 846 | @cindex indentation for comments |
6bf7aab6 | 847 | |
9234c238 RS |
848 | The comment commands in this table insert, kill and align comments. |
849 | They are described in this section and following sections. | |
6bf7aab6 | 850 | |
6bf7aab6 DL |
851 | @table @kbd |
852 | @item M-; | |
9234c238 RS |
853 | Insert or realign comment on current line; alternatively, comment or |
854 | uncomment the region (@code{comment-dwim}). | |
855 | @item C-u M-; | |
856 | Kill comment on current line (@code{comment-kill}). | |
6bf7aab6 | 857 | @item C-x ; |
47c1b5f4 | 858 | Set comment column (@code{comment-set-column}). |
6bf7aab6 DL |
859 | @item C-M-j |
860 | Like @key{RET} followed by inserting and aligning a comment | |
47c1b5f4 | 861 | (@code{comment-indent-new-line}). |
6bf7aab6 DL |
862 | @item M-x comment-region |
863 | Add or remove comment delimiters on all the lines in the region. | |
864 | @end table | |
865 | ||
9234c238 RS |
866 | @kindex M-; |
867 | @findex comment-dwim | |
868 | The command to create or align a comment is @kbd{M-;} | |
869 | (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What | |
870 | I Mean''; it indicates that this command can be used for many | |
871 | different jobs relating to comments, depending on the situation where | |
872 | you use it. | |
873 | ||
874 | If there is no comment already on the line, @kbd{M-;} inserts a new | |
875 | comment, aligned at a specific column called the @dfn{comment column}. | |
876 | The new comment begins with the string Emacs thinks comments should | |
877 | start with (the value of @code{comment-start}; see below). Point is | |
878 | after that string, so you can insert the text of the comment right | |
879 | away. If the major mode has specified a string to terminate comments, | |
880 | @kbd{M-;} inserts that too, to keep the syntax valid. | |
881 | ||
882 | If the text of the line extends past the comment column, then the | |
883 | comment start string is indented to a suitable boundary (usually, at | |
884 | least one space is inserted). | |
885 | ||
886 | You can also use @kbd{M-;} to align an existing comment. If a line | |
887 | already contains the comment-start string, @kbd{M-;} reindents it to | |
888 | the conventional alignment and moves point after it. (Exception: | |
889 | comments starting in column 0 are not moved.) Even when an existing | |
890 | comment is properly aligned, @kbd{M-;} is still useful for moving | |
891 | directly to the start of the text inside the comment. | |
892 | ||
893 | @findex comment-kill | |
894 | @kindex C-u M-; | |
895 | @kbd{C-u M-;} kills any comment on the current line, along with the | |
896 | whitespace before it. To reinsert the comment on another line, move | |
897 | to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to | |
898 | realign it. | |
899 | ||
900 | Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} | |
901 | (@code{comment-dwim}) with a prefix argument. That command is | |
902 | programmed so that when it receives a prefix argument it calls | |
903 | @code{comment-kill}. However, @code{comment-kill} is a valid command | |
904 | in its own right, and you can bind it directly to a key if you wish. | |
905 | ||
906 | @kbd{M-;} does two other jobs when used with an active region in | |
907 | Transient Mark mode (@pxref{Transient Mark}). Then it either adds or | |
908 | removes comment delimiters on each line of the region. (If every line | |
909 | is a comment, it removes comment delimiters from each; otherwise, it | |
910 | adds comment delimiters to each.) If you are not using Transient Mark | |
911 | mode, then you should use the commands @code{comment-region} and | |
7ad1b919 | 912 | @code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}). |
9234c238 RS |
913 | A prefix argument used in these circumstances specifies how many |
914 | comment delimiters to add or how many to delete. | |
6bf7aab6 DL |
915 | |
916 | Some major modes have special rules for indenting certain kinds of | |
917 | comments in certain contexts. For example, in Lisp code, comments which | |
918 | start with two semicolons are indented as if they were lines of code, | |
919 | instead of at the comment column. Comments which start with three | |
920 | semicolons are supposed to start at the left margin. Emacs understands | |
921 | these conventions by indenting a double-semicolon comment using @key{TAB}, | |
922 | and by not changing the indentation of a triple-semicolon comment at all. | |
923 | ||
924 | @example | |
925 | ;; This function is just an example | |
926 | ;;; Here either two or three semicolons are appropriate. | |
927 | (defun foo (x) | |
928 | ;;; And now, the first part of the function: | |
929 | ;; The following line adds one. | |
930 | (1+ x)) ; This line adds one. | |
931 | @end example | |
932 | ||
933 | In C code, a comment preceded on its line by nothing but whitespace | |
934 | is indented like a line of code. | |
935 | ||
6bf7aab6 DL |
936 | @node Multi-Line Comments |
937 | @subsection Multiple Lines of Comments | |
938 | ||
939 | @kindex C-M-j | |
940 | @cindex blank lines in programs | |
47c1b5f4 | 941 | @findex comment-indent-new-line |
6bf7aab6 | 942 | If you are typing a comment and wish to continue it on another line, |
47c1b5f4 | 943 | you can use the command @kbd{C-M-j} (@code{comment-indent-new-line}). |
6bf7aab6 DL |
944 | This terminates the comment you are typing, creates a new blank line |
945 | afterward, and begins a new comment indented under the old one. When | |
946 | Auto Fill mode is on, going past the fill column while typing a comment | |
947 | causes the comment to be continued in just this fashion. If point is | |
948 | not at the end of the line when @kbd{C-M-j} is typed, the text on | |
949 | the rest of the line becomes part of the new comment line. | |
950 | ||
951 | @findex comment-region | |
952 | To turn existing lines into comment lines, use the @kbd{M-x | |
953 | comment-region} command. It adds comment delimiters to the lines that start | |
954 | in the region, thus commenting them out. With a negative argument, it | |
955 | does the opposite---it deletes comment delimiters from the lines in the | |
956 | region. | |
957 | ||
958 | With a positive argument, @code{comment-region} duplicates the last | |
959 | character of the comment start sequence it adds; the argument specifies | |
960 | how many copies of the character to insert. Thus, in Lisp mode, | |
961 | @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating | |
962 | the comment delimiter is a way of calling attention to the comment. It | |
963 | can also affect how the comment is indented. In Lisp, for proper | |
47c1b5f4 RS |
964 | indentation, you should use an argument of two or three, if between defuns; |
965 | if within a defun, it must be three. | |
6bf7aab6 | 966 | |
6bf7aab6 DL |
967 | @node Options for Comments |
968 | @subsection Options Controlling Comments | |
969 | ||
970 | @vindex comment-column | |
971 | @kindex C-x ; | |
47c1b5f4 | 972 | @findex comment-set-column |
6bf7aab6 DL |
973 | The comment column is stored in the variable @code{comment-column}. You |
974 | can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} | |
47c1b5f4 | 975 | (@code{comment-set-column}) sets the comment column to the column point is |
6bf7aab6 DL |
976 | at. @kbd{C-u C-x ;} sets the comment column to match the last comment |
977 | before point in the buffer, and then does a @kbd{M-;} to align the | |
9234c238 | 978 | current line's comment under the previous one. |
6bf7aab6 DL |
979 | |
980 | The variable @code{comment-column} is per-buffer: setting the variable | |
981 | in the normal fashion affects only the current buffer, but there is a | |
982 | default value which you can change with @code{setq-default}. | |
983 | @xref{Locals}. Many major modes initialize this variable for the | |
984 | current buffer. | |
985 | ||
986 | @vindex comment-start-skip | |
987 | The comment commands recognize comments based on the regular | |
988 | expression that is the value of the variable @code{comment-start-skip}. | |
989 | Make sure this regexp does not match the null string. It may match more | |
990 | than the comment starting delimiter in the strictest sense of the word; | |
47c1b5f4 RS |
991 | for example, in C mode the value of the variable is |
992 | @c This stops M-q from breaking the line inside that @code. | |
993 | @code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spaces | |
994 | after the @samp{/*} itself, and accepts C++ style comments also. | |
6bf7aab6 DL |
995 | (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in |
996 | the string, which is needed to deny the first star its special meaning | |
997 | in regexp syntax. @xref{Regexps}.) | |
998 | ||
999 | @vindex comment-start | |
1000 | @vindex comment-end | |
1001 | When a comment command makes a new comment, it inserts the value of | |
1002 | @code{comment-start} to begin it. The value of @code{comment-end} is | |
1003 | inserted after point, so that it will follow the text that you will insert | |
1004 | into the comment. In C mode, @code{comment-start} has the value | |
1005 | @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}. | |
1006 | ||
9234c238 RS |
1007 | @vindex comment-padding |
1008 | The variable @code{comment-padding} specifies how many spaces | |
1009 | @code{comment-region} should insert on each line between the | |
47c1b5f4 RS |
1010 | comment delimiter and the line's original text. The default is 1, |
1011 | to insert one space. | |
9234c238 | 1012 | |
6bf7aab6 DL |
1013 | @vindex comment-multi-line |
1014 | The variable @code{comment-multi-line} controls how @kbd{C-M-j} | |
1015 | (@code{indent-new-comment-line}) behaves when used inside a comment. If | |
1016 | @code{comment-multi-line} is @code{nil}, as it normally is, then the | |
1017 | comment on the starting line is terminated and a new comment is started | |
1018 | on the new following line. If @code{comment-multi-line} is not | |
1019 | @code{nil}, then the new following line is set up as part of the same | |
1020 | comment that was found on the starting line. This is done by not | |
1021 | inserting a terminator on the old line, and not inserting a starter on | |
1022 | the new line. In languages where multi-line comments work, the choice | |
1023 | of value for this variable is a matter of taste. | |
1024 | ||
4190ce5c | 1025 | @vindex comment-indent-function |
6bf7aab6 DL |
1026 | The variable @code{comment-indent-function} should contain a function |
1027 | that will be called to compute the indentation for a newly inserted | |
1028 | comment or for aligning an existing comment. It is set differently by | |
1029 | various major modes. The function is called with no arguments, but with | |
1030 | point at the beginning of the comment, or at the end of a line if a new | |
1031 | comment is to be inserted. It should return the column in which the | |
1032 | comment ought to start. For example, in Lisp mode, the indent hook | |
1033 | function bases its decision on how many semicolons begin an existing | |
1034 | comment, and on the code in the preceding lines. | |
1035 | ||
93da5dff RS |
1036 | @node Documentation |
1037 | @section Documentation Lookup | |
6bf7aab6 | 1038 | |
93da5dff RS |
1039 | Emacs provides several features you can use to look up the |
1040 | documentation of functions, variables and commands that you plan to | |
1041 | use in your program. | |
6bf7aab6 | 1042 | |
93da5dff RS |
1043 | @menu |
1044 | * Info Lookup:: Looking up library functions and commands | |
1045 | in Info files. | |
1046 | * Man Page:: Looking up man pages of library functions and commands. | |
1047 | * Lisp Doc:: Looking up Emacs Lisp functions, etc. | |
1048 | @end menu | |
6bf7aab6 | 1049 | |
93da5dff RS |
1050 | @node Info Lookup |
1051 | @subsection Info Documentation Lookup | |
85750656 | 1052 | |
93da5dff RS |
1053 | @findex info-lookup-symbol |
1054 | @findex info-lookup-file | |
1055 | @kindex C-h C-i | |
1056 | For C, Lisp, and other languages that have documentation in Info, | |
1057 | you can use @kbd{C-h C-i} (@code{info-lookup-symbol}) to view the Info | |
1058 | documentation for a symbol. You specify the symbol with the | |
1059 | minibuffer; the default is the symbol appearing in the buffer at | |
1060 | point. | |
6bf7aab6 | 1061 | |
93da5dff RS |
1062 | The major mode determines where to look for documentation for the |
1063 | symbol---which Info files to look in, and which indices to search. | |
1064 | You can also use @kbd{M-x info-lookup-file} to look for documentation | |
1065 | for a file name. | |
6bf7aab6 | 1066 | |
93da5dff RS |
1067 | This feature currently supports the modes Awk, Autoconf, Bison, C, |
1068 | Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo, | |
1069 | provided you have installed the relevant Info files, which are | |
1070 | typically available with the appropriate GNU package. | |
6bf7aab6 | 1071 | |
93da5dff RS |
1072 | @node Man Page |
1073 | @subsection Man Page Lookup | |
6bf7aab6 | 1074 | |
e79c6b89 RS |
1075 | @cindex manual page |
1076 | On Unix, the main form of on-line documentation was the @dfn{manual | |
1077 | page} or @dfn{man page}. In the GNU operating system, we hope to | |
1078 | replace man pages with better-organized manuals that you can browse | |
1079 | with Info (@pxref{Misc Help}). This process is not finished, so it is | |
1080 | still useful to read manual pages. | |
6bf7aab6 | 1081 | |
93da5dff | 1082 | @findex manual-entry |
e79c6b89 RS |
1083 | You can read the man page for an operating system command, library |
1084 | function, or system call, with the @kbd{M-x manual-entry} command. It | |
1085 | runs the @code{man} program to format the man page; if the system | |
1086 | permits, it runs @code{man} asynchronously, so that you can keep on | |
1087 | editing while the page is being formatted. (On MS-DOS and MS-Windows | |
1088 | 3, you cannot edit while Emacs waits for @code{man} to finish.) The | |
1089 | result goes in a buffer named @samp{*Man @var{topic}*}. These buffers | |
1090 | use a special major mode, Man mode, that facilitates scrolling and | |
1091 | jumping to other manual pages. For details, type @kbd{C-h m} while in | |
1092 | a man page buffer. | |
6bf7aab6 | 1093 | |
93da5dff | 1094 | @cindex sections of manual pages |
e79c6b89 RS |
1095 | Each man page belongs to one of ten or more @dfn{sections}, each |
1096 | named by a digit or by a digit and a letter. Sometimes there are | |
1097 | multiple man pages with the same name in different sections. To read | |
1098 | a man page from a specific section, type | |
93da5dff RS |
1099 | @samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} |
1100 | when @kbd{M-x manual-entry} prompts for the topic. For example, to | |
1101 | read the man page for the C library function @code{chmod} (as opposed | |
e79c6b89 RS |
1102 | to a command of the same name), type @kbd{M-x manual-entry @key{RET} |
1103 | chmod(2) @key{RET}} (@code{chmod} is a system call, so it is in | |
1104 | section @samp{2}). | |
6bf7aab6 | 1105 | |
08220274 | 1106 | @vindex Man-switches |
93da5dff | 1107 | If you do not specify a section, the results depend on how the |
08220274 | 1108 | @code{man} program works on your system. Some of them display only |
93da5dff RS |
1109 | the first man page they find. Others display all man pages that have |
1110 | the specified name, so you can move between them with the @kbd{M-n} | |
08220274 EZ |
1111 | and @kbd{M-p} keys@footnote{On some systems, the @code{man} program |
1112 | accepts a @samp{-a} command-line option which tells it to display all | |
1113 | the man pages for the specified topic. If you want this behavior, you | |
1114 | can add this option to the value of the variable @code{Man-switches}.}. | |
1115 | The mode line shows how many manual pages are present in the Man buffer. | |
6bf7aab6 | 1116 | |
93da5dff | 1117 | @vindex Man-fontify-manpage-flag |
e79c6b89 RS |
1118 | By default, Emacs highlights the text in man pages. For a long man |
1119 | page, highlighting can take substantial time. You can turn off | |
1120 | highlighting of man pages by setting the variable | |
1121 | @code{Man-fontify-manpage-flag} to @code{nil}. | |
6bf7aab6 | 1122 | |
93da5dff RS |
1123 | @findex Man-fontify-manpage |
1124 | If you insert the text of a man page into an Emacs buffer in some | |
1125 | other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to | |
1126 | perform the same conversions that @kbd{M-x manual-entry} does. | |
1127 | ||
1128 | @findex woman | |
1129 | @cindex manual pages, on MS-DOS/MS-Windows | |
1130 | An alternative way of reading manual pages is the @kbd{M-x woman} | |
1131 | command@footnote{The name of the command, @code{woman}, is an acronym | |
1132 | for ``w/o (without) man,'' since it doesn't use the @code{man} | |
1133 | program.}. Unlike @kbd{M-x man}, it does not run any external | |
1134 | programs to format and display the man pages; instead it does the job | |
1135 | in Emacs Lisp, so it works on systems such as MS-Windows, where the | |
d2fab838 RS |
1136 | @code{man} program (and the other programs it uses) are not generally |
1137 | available. | |
1138 | ||
1139 | @kbd{M-x woman} prompts for a name of a manual page, and provides | |
1140 | completion based on the list of manual pages that are installed on | |
1141 | your machine; the list of available manual pages is computed | |
1142 | automatically the first time you invoke @code{woman}. The word at | |
1143 | point in the current buffer is used to suggest the default for the | |
1144 | name the manual page. | |
93da5dff RS |
1145 | |
1146 | With a numeric argument, @kbd{M-x woman} recomputes the list of the | |
1147 | manual pages used for completion. This is useful if you add or delete | |
1148 | manual pages. | |
1149 | ||
1150 | If you type a name of a manual page and @kbd{M-x woman} finds that | |
1151 | several manual pages by the same name exist in different sections, it | |
1152 | pops up a window with possible candidates asking you to choose one of | |
1153 | them. | |
1154 | ||
1155 | @vindex woman-manpath | |
1156 | By default, @kbd{M-x woman} looks for manual pages in the | |
1157 | directories specified in the @code{MANPATH} environment variable. (If | |
1158 | @code{MANPATH} is not set, @code{woman} uses a suitable default value, | |
1159 | which can be customized.) More precisely, @code{woman} looks for | |
e79c6b89 | 1160 | subdirectories that match the shell wildcard pattern @file{man*} in each one |
93da5dff RS |
1161 | of these directories, and tries to find the manual pages in those |
1162 | subdirectories. When first invoked, @kbd{M-x woman} converts the | |
1163 | value of @code{MANPATH} to a list of directory names and stores that | |
1164 | list in the @code{woman-manpath} variable. Changing the value of this | |
1165 | variable is another way to control the list of directories used. | |
1166 | ||
1167 | @vindex woman-path | |
1168 | You can also augment the list of directories searched by | |
1169 | @code{woman} by setting the value of the @code{woman-path} variable. | |
1170 | This variable should hold a list of specific directories which | |
1171 | @code{woman} should search, in addition to those in | |
1172 | @code{woman-manpath}. Unlike @code{woman-manpath}, the directories in | |
1173 | @code{woman-path} are searched for the manual pages, not for | |
1174 | @file{man*} subdirectories. | |
1175 | ||
1176 | @findex woman-find-file | |
1177 | Occasionally, you might need to display manual pages that are not in | |
1178 | any of the directories listed by @code{woman-manpath} and | |
1179 | @code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a | |
1180 | name of a manual page file, with completion, and then formats and | |
1181 | displays that file like @kbd{M-x woman} does. | |
1182 | ||
1183 | @vindex woman-dired-keys | |
1184 | The first time you invoke @kbd{M-x woman}, it defines the Dired | |
1185 | @kbd{W} key to run the @code{woman-find-file} command on the current | |
1186 | line's file. You can disable this by setting the variable | |
1187 | @code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, | |
1188 | the Tar-mode @kbd{w} key is define to invoke @code{woman-find-file} on | |
1189 | the current line's archive member. | |
1190 | ||
1191 | For more information about setting up and using @kbd{M-x woman}, see | |
1192 | @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan | |
1193 | Manual}. | |
1194 | ||
1195 | @node Lisp Doc | |
1196 | @subsection Emacs Lisp Documentation Lookup | |
1197 | ||
1198 | As you edit Lisp code to be run in Emacs, you can use the commands | |
1199 | @kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} | |
1200 | (@code{describe-variable}) to view documentation of functions and | |
1201 | variables that you want to use. These commands use the minibuffer to | |
1202 | read the name of a function or variable to document, and display the | |
1203 | documentation in a window. Their default arguments are based on the | |
1204 | code in the neighborhood of point. For @kbd{C-h f}, the default is | |
1205 | the function called in the innermost list containing point. @kbd{C-h | |
1206 | v} uses the symbol name around or adjacent to point as its default. | |
1207 | ||
1208 | @cindex Eldoc mode | |
1209 | @findex eldoc-mode | |
1210 | A more automatic but less powerful method is Eldoc mode. This minor | |
1211 | mode constantly displays in the echo area the argument list for the | |
1212 | function being called at point. (In other words, it finds the | |
1213 | function call that point is contained in, and displays the argument | |
1214 | list of that function.) Eldoc mode applies in Emacs Lisp and Lisp | |
1215 | Interaction modes only. Use the command @kbd{M-x eldoc-mode} to | |
1216 | enable or disable this feature. | |
6bf7aab6 | 1217 | |
51ed0ea0 DL |
1218 | @node Hideshow |
1219 | @section Hideshow minor mode | |
1220 | ||
1221 | @findex hs-minor-mode | |
9234c238 | 1222 | Hideshow minor mode provides selective display of portions of a |
93da5dff RS |
1223 | program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} |
1224 | to enable or disable this mode, or add @code{hs-minor-mode} to the | |
1225 | mode hook for certain major modes in order to enable it automatically | |
1226 | for those modes. | |
51ed0ea0 | 1227 | |
9234c238 RS |
1228 | Just what constitutes a block depends on the major mode. In C mode |
1229 | or C++ mode, they are delimited by braces, while in Lisp mode and | |
1230 | similar modes they are delimited by parentheses. Multi-line comments | |
1231 | also count as blocks. | |
51ed0ea0 DL |
1232 | |
1233 | @findex hs-hide-all | |
1234 | @findex hs-hide-block | |
1235 | @findex hs-show-all | |
1236 | @findex hs-show-block | |
1237 | @findex hs-show-region | |
1238 | @findex hs-hide-level | |
1239 | @findex hs-minor-mode | |
6401dc86 EZ |
1240 | @kindex C-c @@ C-h |
1241 | @kindex C-c @@ C-s | |
1242 | @kindex C-c @@ C-M-h | |
1243 | @kindex C-c @@ C-M-s | |
1244 | @kindex C-c @@ C-r | |
1245 | @kindex C-c @@ C-l | |
9234c238 RS |
1246 | @kindex S-Mouse-2 |
1247 | @table @kbd | |
6401dc86 | 1248 | @item C-c @@ C-h |
9234c238 | 1249 | Hide the current block (@code{hs-hide-block}). |
6401dc86 | 1250 | @item C-c @@ C-s |
9234c238 | 1251 | Show the current block (@code{hs-show-block}). |
6401dc86 | 1252 | @item C-c @@ C-c |
9234c238 RS |
1253 | Either hide or show the current block (@code{hs-toggle-hiding}) |
1254 | @item S-Mouse-2 | |
1255 | Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}) | |
6401dc86 | 1256 | @item C-c @@ C-M-h |
9234c238 | 1257 | Hide all top-level blocks (@code{hs-hide-all}). |
6401dc86 | 1258 | @item C-c @@ C-M-s |
9234c238 | 1259 | Show everything in the buffer (@code{hs-show-all}). |
6401dc86 | 1260 | @item C-c @@ C-l |
9234c238 RS |
1261 | Hide all blocks @var{n} levels below this block |
1262 | (@code{hs-hide-level}). | |
1263 | @end table | |
51ed0ea0 DL |
1264 | |
1265 | @vindex hs-hide-comments-when-hiding-all | |
51ed0ea0 DL |
1266 | @vindex hs-isearch-open |
1267 | @vindex hs-special-modes-alist | |
9234c238 RS |
1268 | These user options exist for customizing Hideshow mode. |
1269 | ||
51ed0ea0 DL |
1270 | @table @code |
1271 | @item hs-hide-comments-when-hiding-all | |
9234c238 | 1272 | Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. |
d2fab838 | 1273 | |
51ed0ea0 DL |
1274 | @item hs-isearch-open |
1275 | Specifies what kind of hidden blocks to open in Isearch mode. | |
d2fab838 RS |
1276 | The value should be one of these four symbols. |
1277 | ||
1278 | @table @code | |
9198a323 RS |
1279 | @item code |
1280 | Open only code blocks. | |
d2fab838 RS |
1281 | @item comment |
1282 | Open only comments. | |
1283 | @item t | |
9198a323 | 1284 | Open both code blocks and comments. |
d2fab838 | 1285 | @item nil |
9198a323 | 1286 | Open neither code blocks nor comments. |
d2fab838 RS |
1287 | @end table |
1288 | ||
51ed0ea0 | 1289 | @item hs-special-modes-alist |
e79c6b89 | 1290 | A list of elements, each specifying how to initialize Hideshow |
d2fab838 RS |
1291 | variables for one major mode. See the variable's documentation string |
1292 | for more information. | |
51ed0ea0 DL |
1293 | @end table |
1294 | ||
93da5dff RS |
1295 | @node Symbol Completion |
1296 | @section Completion for Symbol Names | |
1297 | @cindex completion (symbol names) | |
3b8b8888 | 1298 | |
e79c6b89 RS |
1299 | In Emacs, completion is something you normally do in the minibuffer. |
1300 | But one kind of completion is available in all buffers: completion for | |
1301 | symbol names. | |
3b8b8888 | 1302 | |
93da5dff | 1303 | @kindex M-TAB |
e79c6b89 RS |
1304 | The character @kbd{M-@key{TAB}} runs a command to complete the |
1305 | partial symbol before point against the set of meaningful symbol | |
1306 | names. This command inserts at point any additional characters that | |
1307 | it can determine from the partial name. | |
6bf7aab6 | 1308 | |
e79c6b89 RS |
1309 | If the partial name in the buffer has multiple possible completions |
1310 | that differ in the very next character, so that it is impossible to | |
1311 | complete even one more character, @kbd{M-@key{TAB}} displays a list of | |
1312 | all possible completions in another window. | |
6bf7aab6 | 1313 | |
93da5dff RS |
1314 | @cindex tags-based completion |
1315 | @cindex Info index completion | |
1316 | @findex complete-symbol | |
1317 | In most programming language major modes, @kbd{M-@key{TAB}} runs the | |
1318 | command @code{complete-symbol}, which provides two kinds of completion. | |
1319 | Normally it does completion based on a tags table (@pxref{Tags}); with a | |
1320 | numeric argument (regardless of the value), it does completion based on | |
1321 | the names listed in the Info file indexes for your language. Thus, to | |
1322 | complete the name of a symbol defined in your own program, use | |
1323 | @kbd{M-@key{TAB}} with no argument; to complete the name of a standard | |
1324 | library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based | |
1325 | completion works only if there is an Info file for the standard library | |
1326 | functions of your language, and only if it is installed at your site. | |
6bf7aab6 | 1327 | |
93da5dff RS |
1328 | @cindex Lisp symbol completion |
1329 | @cindex completion (Lisp symbols) | |
1330 | @findex lisp-complete-symbol | |
1331 | In Emacs-Lisp mode, the name space for completion normally consists of | |
1332 | nontrivial symbols present in Emacs---those that have function | |
1333 | definitions, values or properties. However, if there is an | |
1334 | open-parenthesis immediately before the beginning of the partial symbol, | |
1335 | only symbols with function definitions are considered as completions. | |
1336 | The command which implements this is @code{lisp-complete-symbol}. | |
6bf7aab6 | 1337 | |
93da5dff RS |
1338 | In Text mode and related modes, @kbd{M-@key{TAB}} completes words |
1339 | based on the spell-checker's dictionary. @xref{Spelling}. | |
6bf7aab6 | 1340 | |
93da5dff RS |
1341 | @node Glasses |
1342 | @section Glasses minor mode | |
1343 | @cindex Glasses mode | |
1344 | @cindex identifiers, making long ones readable | |
1345 | @cindex StudlyCaps, making them readable | |
1346 | @findex glasses-mode | |
6bf7aab6 | 1347 | |
93da5dff | 1348 | Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} |
e79c6b89 RS |
1349 | readable by altering the way they display. It knows two different |
1350 | ways to do this: by displaying underscores between a lower-case letter | |
1351 | and the following capital letter, and by emboldening the capital | |
1352 | letters. It does not alter the buffer text, only the way they | |
1353 | display, so you can use it even on read-only buffers. You can use the | |
1354 | command @kbd{M-x glasses-mode} to enable or disable the mode in the | |
1355 | current buffer; you can also add @code{glasses-mode} to the mode hook | |
1356 | of the programming language major modes in which you normally want | |
177c0ea7 | 1357 | to use Glasses mode. |
6bf7aab6 | 1358 | |
93da5dff RS |
1359 | @node Misc for Programs |
1360 | @section Other Features Useful for Editing Programs | |
6bf7aab6 | 1361 | |
93da5dff | 1362 | A number of Emacs commands that aren't designed specifically for |
e79c6b89 | 1363 | editing programs are useful for that nonetheless. |
6bf7aab6 | 1364 | |
93da5dff RS |
1365 | The Emacs commands that operate on words, sentences and paragraphs |
1366 | are useful for editing code. Most symbols names contain words | |
1367 | (@pxref{Words}); sentences can be found in strings and comments | |
e79c6b89 | 1368 | (@pxref{Sentences}). Paragraphs in the strict sense can be found in |
93da5dff RS |
1369 | program code (in long comments), but the paragraph commands are useful |
1370 | in other places too, because programming language major modes define | |
1371 | paragraphs to begin and end at blank lines (@pxref{Paragraphs}). | |
1372 | Judicious use of blank lines to make the program clearer will also | |
1373 | provide useful chunks of text for the paragraph commands to work on. | |
1374 | Auto Fill mode, if enabled in a programming language major mode, | |
1375 | indents the new lines which it creates. | |
6bf7aab6 | 1376 | |
93da5dff RS |
1377 | The selective display feature is useful for looking at the overall |
1378 | structure of a function (@pxref{Selective Display}). This feature | |
1379 | hides the lines that are indented more than a specified amount. | |
1380 | Programming modes often support Outline minor mode (@pxref{Outline | |
1381 | Mode}). The Foldout package provides folding-editor features | |
1382 | (@pxref{Foldout}). | |
6bf7aab6 | 1383 | |
93da5dff RS |
1384 | The ``automatic typing'' features may be useful for writing programs. |
1385 | @xref{Top,,Autotyping, autotype, Autotyping}. | |
6bf7aab6 DL |
1386 | |
1387 | @node C Modes | |
1388 | @section C and Related Modes | |
1389 | @cindex C mode | |
1390 | @cindex Java mode | |
1391 | @cindex Pike mode | |
1392 | @cindex IDL mode | |
1393 | @cindex CORBA IDL mode | |
1394 | @cindex Objective C mode | |
1395 | @cindex C++ mode | |
1396 | @cindex mode, Java | |
1397 | @cindex mode, C | |
1398 | @cindex mode, Objective C | |
1399 | @cindex mode, CORBA IDL | |
1400 | @cindex mode, Pike | |
1401 | ||
9234c238 RS |
1402 | This section gives a brief description of the special features |
1403 | available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes. | |
6b61353c KH |
1404 | (These are called ``C mode and related modes.'') @xref{Top, , CC Mode, |
1405 | ccmode, CC Mode}, for a more extensive description of these modes | |
9234c238 | 1406 | and their special features. |
51ed0ea0 | 1407 | |
6bf7aab6 | 1408 | @menu |
93da5dff RS |
1409 | * Motion in C:: Commands to move by C statements, etc. |
1410 | * Electric C:: Colon and other chars can automatically reindent. | |
1411 | * Hungry Delete:: A more powerful DEL command. | |
1412 | * Other C Commands:: Filling comments, viewing expansion of macros, | |
1413 | and other neat features. | |
1414 | * Comments in C:: Options for customizing comment style. | |
6bf7aab6 DL |
1415 | @end menu |
1416 | ||
1417 | @node Motion in C | |
1418 | @subsection C Mode Motion Commands | |
1419 | ||
1420 | This section describes commands for moving point, in C mode and | |
1421 | related modes. | |
1422 | ||
1423 | @table @code | |
1424 | @item C-c C-u | |
1425 | @kindex C-c C-u @r{(C mode)} | |
1426 | @findex c-up-conditional | |
1427 | Move point back to the containing preprocessor conditional, leaving the | |
1428 | mark behind. A prefix argument acts as a repeat count. With a negative | |
1429 | argument, move point forward to the end of the containing | |
1430 | preprocessor conditional. When going backwards, @code{#elif} is treated | |
1431 | like @code{#else} followed by @code{#if}. When going forwards, | |
1432 | @code{#elif} is ignored.@refill | |
1433 | ||
1434 | @item C-c C-p | |
1435 | @kindex C-c C-p @r{(C mode)} | |
1436 | @findex c-backward-conditional | |
1437 | Move point back over a preprocessor conditional, leaving the mark | |
1438 | behind. A prefix argument acts as a repeat count. With a negative | |
1439 | argument, move forward. | |
1440 | ||
1441 | @item C-c C-n | |
1442 | @kindex C-c C-n @r{(C mode)} | |
1443 | @findex c-forward-conditional | |
1444 | Move point forward across a preprocessor conditional, leaving the mark | |
1445 | behind. A prefix argument acts as a repeat count. With a negative | |
1446 | argument, move backward. | |
1447 | ||
1448 | @item M-a | |
1449 | @kindex ESC a | |
1450 | @findex c-beginning-of-statement | |
1451 | Move point to the beginning of the innermost C statement | |
1452 | (@code{c-beginning-of-statement}). If point is already at the beginning | |
1453 | of a statement, move to the beginning of the preceding statement. With | |
1454 | prefix argument @var{n}, move back @var{n} @minus{} 1 statements. | |
1455 | ||
1456 | If point is within a string or comment, or next to a comment (only | |
1457 | whitespace between them), this command moves by sentences instead of | |
1458 | statements. | |
1459 | ||
1460 | When called from a program, this function takes three optional | |
1461 | arguments: the numeric prefix argument, a buffer position limit | |
1462 | (don't move back before that place), and a flag that controls whether | |
1463 | to do sentence motion when inside of a comment. | |
1464 | ||
1465 | @item M-e | |
1466 | @kindex ESC e | |
1467 | @findex c-end-of-statement | |
1468 | Move point to the end of the innermost C statement; like @kbd{M-a} | |
1469 | except that it moves in the other direction (@code{c-end-of-statement}). | |
1470 | ||
1471 | @item M-x c-backward-into-nomenclature | |
1472 | @findex c-backward-into-nomenclature | |
1473 | Move point backward to beginning of a C++ nomenclature section or word. | |
1474 | With prefix argument @var{n}, move @var{n} times. If @var{n} is | |
1475 | negative, move forward. C++ nomenclature means a symbol name in the | |
1476 | style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter | |
1477 | begins a section or word. | |
1478 | ||
1479 | In the GNU project, we recommend using underscores to separate words | |
1480 | within an identifier in C or C++, rather than using case distinctions. | |
1481 | ||
1482 | @item M-x c-forward-into-nomenclature | |
1483 | @findex c-forward-into-nomenclature | |
1484 | Move point forward to end of a C++ nomenclature section or word. | |
1485 | With prefix argument @var{n}, move @var{n} times. | |
1486 | @end table | |
1487 | ||
1488 | @node Electric C | |
1489 | @subsection Electric C Characters | |
1490 | ||
1491 | In C mode and related modes, certain printing characters are | |
1492 | ``electric''---in addition to inserting themselves, they also reindent | |
1493 | the current line and may insert newlines. This feature is controlled by | |
1494 | the variable @code{c-auto-newline}. The ``electric'' characters are | |
1495 | @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, | |
1496 | @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. | |
1497 | ||
1498 | Electric characters insert newlines only when the @dfn{auto-newline} | |
1499 | feature is enabled (indicated by @samp{/a} in the mode line after the | |
1500 | mode name). This feature is controlled by the variable | |
1501 | @code{c-auto-newline}. You can turn this feature on or off with the | |
1502 | command @kbd{C-c C-a}: | |
1503 | ||
1504 | @table @kbd | |
1505 | @item C-c C-a | |
1506 | @kindex C-c C-a @r{(C mode)} | |
1507 | @findex c-toggle-auto-state | |
1508 | Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a | |
1509 | prefix argument, this command turns the auto-newline feature on if the | |
1510 | argument is positive, and off if it is negative. | |
1511 | @end table | |
1512 | ||
1513 | The colon character is electric because that is appropriate for a | |
1514 | single colon. But when you want to insert a double colon in C++, the | |
1515 | electric behavior of colon is inconvenient. You can insert a double | |
1516 | colon with no reindentation or newlines by typing @kbd{C-c :}: | |
1517 | ||
1518 | @table @kbd | |
1519 | @item C-c : | |
da8acb6b | 1520 | @ifinfo |
c668cdd0 EZ |
1521 | @c This uses ``colon'' instead of a literal `:' because Info cannot |
1522 | @c cope with a `:' in a menu | |
1523 | @kindex C-c @key{colon} @r{(C mode)} | |
da8acb6b EZ |
1524 | @end ifinfo |
1525 | @ifnotinfo | |
1526 | @kindex C-c : @r{(C mode)} | |
1527 | @end ifnotinfo | |
6bf7aab6 DL |
1528 | @findex c-scope-operator |
1529 | Insert a double colon scope operator at point, without reindenting the | |
1530 | line or adding any newlines (@code{c-scope-operator}). | |
1531 | @end table | |
1532 | ||
1533 | The electric @kbd{#} key reindents the line if it appears to be the | |
1534 | beginning of a preprocessor directive. This happens when the value of | |
1535 | @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn | |
1536 | this feature off by setting @code{c-electric-pound-behavior} to | |
1537 | @code{nil}. | |
1538 | ||
1539 | The variable @code{c-hanging-braces-alist} controls the insertion of | |
1540 | newlines before and after inserted braces. It is an association list | |
1541 | with elements of the following form: @code{(@var{syntactic-symbol} | |
1542 | . @var{nl-list})}. Most of the syntactic symbols that appear in | |
1543 | @code{c-offsets-alist} are meaningful here as well. | |
1544 | ||
1545 | The list @var{nl-list} may contain either of the symbols | |
1546 | @code{before} or @code{after}, or both; or it may be @code{nil}. When a | |
1547 | brace is inserted, the syntactic context it defines is looked up in | |
1548 | @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used | |
1549 | to determine where newlines are inserted: either before the brace, | |
1550 | after, or both. If not found, the default is to insert a newline both | |
1551 | before and after braces. | |
1552 | ||
1553 | The variable @code{c-hanging-colons-alist} controls the insertion of | |
1554 | newlines before and after inserted colons. It is an association list | |
1555 | with elements of the following form: @code{(@var{syntactic-symbol} | |
1556 | . @var{nl-list})}. The list @var{nl-list} may contain either of the | |
1557 | symbols @code{before} or @code{after}, or both; or it may be @code{nil}. | |
1558 | ||
1559 | When a colon is inserted, the syntactic symbol it defines is looked | |
1560 | up in this list, and if found, the @var{nl-list} is used to determine | |
1561 | where newlines are inserted: either before the brace, after, or both. | |
1562 | If the syntactic symbol is not found in this list, no newlines are | |
1563 | inserted. | |
1564 | ||
1565 | Electric characters can also delete newlines automatically when the | |
1566 | auto-newline feature is enabled. This feature makes auto-newline more | |
1567 | acceptable, by deleting the newlines in the most common cases where you | |
1568 | do not want them. Emacs can recognize several cases in which deleting a | |
1569 | newline might be desirable; by setting the variable | |
1570 | @code{c-cleanup-list}, you can specify @emph{which} of these cases that | |
1571 | should happen. The variable's value is a list of symbols, each | |
1572 | describing one case for possible deletion of a newline. Here are the | |
1573 | meaningful symbols, and their meanings: | |
1574 | ||
1575 | @table @code | |
1576 | @item brace-catch-brace | |
1577 | Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the | |
1578 | entire construct on a single line. The clean-up occurs when you type | |
1579 | the @samp{@{}, if there is nothing between the braces aside from | |
1580 | @code{catch} and @var{condition}. | |
1581 | ||
1582 | @item brace-else-brace | |
1583 | Clean up @samp{@} else @{} constructs by placing the entire construct on | |
1584 | a single line. The clean-up occurs when you type the @samp{@{} after | |
1585 | the @code{else}, but only if there is nothing but white space between | |
1586 | the braces and the @code{else}. | |
1587 | ||
1588 | @item brace-elseif-brace | |
1589 | Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire | |
1590 | construct on a single line. The clean-up occurs when you type the | |
1591 | @samp{@{}, if there is nothing but white space between the @samp{@}} and | |
1592 | @samp{@{} aside from the keywords and the @code{if}-condition. | |
1593 | ||
1594 | @item empty-defun-braces | |
1595 | Clean up empty defun braces by placing the braces on the same | |
1596 | line. Clean-up occurs when you type the closing brace. | |
1597 | ||
1598 | @item defun-close-semi | |
1599 | Clean up the semicolon after a @code{struct} or similar type | |
1600 | declaration, by placing the semicolon on the same line as the closing | |
1601 | brace. Clean-up occurs when you type the semicolon. | |
1602 | ||
1603 | @item list-close-comma | |
1604 | Clean up commas following braces in array and aggregate | |
1605 | initializers. Clean-up occurs when you type the comma. | |
1606 | ||
1607 | @item scope-operator | |
1608 | Clean up double colons which may designate a C++ scope operator, by | |
1609 | placing the colons together. Clean-up occurs when you type the second | |
1610 | colon, but only when the two colons are separated by nothing but | |
1611 | whitespace. | |
1612 | @end table | |
1613 | ||
1614 | @node Hungry Delete | |
1615 | @subsection Hungry Delete Feature in C | |
1616 | ||
1617 | When the @dfn{hungry-delete} feature is enabled (indicated by | |
1618 | @samp{/h} or @samp{/ah} in the mode line after the mode name), a single | |
1619 | @key{DEL} command deletes all preceding whitespace, not just one space. | |
1620 | To turn this feature on or off, use @kbd{C-c C-d}: | |
1621 | ||
1622 | @table @kbd | |
1623 | @item C-c C-d | |
1624 | @kindex C-c C-d @r{(C mode)} | |
1625 | @findex c-toggle-hungry-state | |
1626 | Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a | |
1627 | prefix argument, this command turns the hungry-delete feature on if the | |
1628 | argument is positive, and off if it is negative. | |
1629 | ||
1630 | @item C-c C-t | |
1631 | @kindex C-c C-t @r{(C mode)} | |
1632 | @findex c-toggle-auto-hungry-state | |
1633 | Toggle the auto-newline and hungry-delete features, both at once | |
1634 | (@code{c-toggle-auto-hungry-state}). | |
1635 | @end table | |
1636 | ||
1637 | @vindex c-hungry-delete-key | |
1638 | The variable @code{c-hungry-delete-key} controls whether the | |
1639 | hungry-delete feature is enabled. | |
1640 | ||
1641 | @node Other C Commands | |
1642 | @subsection Other Commands for C Mode | |
1643 | ||
1644 | @table @kbd | |
1645 | @item C-M-h | |
6bf7aab6 DL |
1646 | Put mark at the end of a function definition, and put point at the |
1647 | beginning (@code{c-mark-function}). | |
1648 | ||
1649 | @item M-q | |
1650 | @kindex M-q @r{(C mode)} | |
1651 | @findex c-fill-paragraph | |
1652 | Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). | |
1653 | If any part of the current line is a comment or within a comment, this | |
1654 | command fills the comment or the paragraph of it that point is in, | |
1655 | preserving the comment indentation and comment delimiters. | |
1656 | ||
1657 | @item C-c C-e | |
1658 | @cindex macro expansion in C | |
1659 | @cindex expansion of C macros | |
1660 | @findex c-macro-expand | |
1661 | @kindex C-c C-e @r{(C mode)} | |
1662 | Run the C preprocessor on the text in the region, and show the result, | |
1663 | which includes the expansion of all the macro calls | |
1664 | (@code{c-macro-expand}). The buffer text before the region is also | |
1665 | included in preprocessing, for the sake of macros defined there, but the | |
1666 | output from this part isn't shown. | |
1667 | ||
1668 | When you are debugging C code that uses macros, sometimes it is hard to | |
1669 | figure out precisely how the macros expand. With this command, you | |
1670 | don't have to figure it out; you can see the expansions. | |
1671 | ||
1672 | @item C-c C-\ | |
1673 | @findex c-backslash-region | |
1674 | @kindex C-c C-\ @r{(C mode)} | |
1675 | Insert or align @samp{\} characters at the ends of the lines of the | |
1676 | region (@code{c-backslash-region}). This is useful after writing or | |
1677 | editing a C macro definition. | |
1678 | ||
1679 | If a line already ends in @samp{\}, this command adjusts the amount of | |
1680 | whitespace before it. Otherwise, it inserts a new @samp{\}. However, | |
1681 | the last line in the region is treated specially; no @samp{\} is | |
1682 | inserted on that line, and any @samp{\} there is deleted. | |
1683 | ||
1684 | @item M-x cpp-highlight-buffer | |
1685 | @cindex preprocessor highlighting | |
1686 | @findex cpp-highlight-buffer | |
1687 | Highlight parts of the text according to its preprocessor conditionals. | |
1688 | This command displays another buffer named @samp{*CPP Edit*}, which | |
1689 | serves as a graphic menu for selecting how to display particular kinds | |
1690 | of conditionals and their contents. After changing various settings, | |
1691 | click on @samp{[A]pply these settings} (or go to that buffer and type | |
1692 | @kbd{a}) to rehighlight the C mode buffer accordingly. | |
1693 | ||
1694 | @item C-c C-s | |
1695 | @findex c-show-syntactic-information | |
1696 | @kindex C-c C-s @r{(C mode)} | |
1697 | Display the syntactic information about the current source line | |
1698 | (@code{c-show-syntactic-information}). This is the information that | |
1699 | directs how the line is indented. | |
3b8b8888 DL |
1700 | |
1701 | @item M-x cwarn-mode | |
1702 | @itemx M-x global-cwarn-mode | |
1703 | @findex cwarn-mode | |
1704 | @findex global-cwarn-mode | |
1705 | @cindex CWarn mode | |
1706 | @cindex suspicious constructions in C, C++ | |
9234c238 | 1707 | CWarn minor mode highlights certain suspicious C and C++ constructions: |
3b8b8888 DL |
1708 | |
1709 | @itemize @bullet{} | |
1710 | @item | |
9234c238 | 1711 | Assignments inside expressions. |
3b8b8888 DL |
1712 | @item |
1713 | Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} | |
1714 | (except after a @samp{do @dots{} while} statement); | |
1715 | @item | |
1716 | C++ functions with reference parameters. | |
1717 | @end itemize | |
1718 | ||
1719 | @noindent | |
9234c238 RS |
1720 | You can enable the mode for one buffer with the command @kbd{M-x |
1721 | cwarn-mode}, or for all suitable buffers with the command @kbd{M-x | |
1722 | global-cwarn-mode} or by customizing the variable | |
1723 | @code{global-cwarn-mode}. You must also enable Font Lock mode to make | |
1724 | it work. | |
3b8b8888 DL |
1725 | |
1726 | @item M-x hide-ifdef-mode | |
1727 | @findex hide-ifdef-mode | |
1728 | @cindex Hide-ifdef mode | |
1729 | Hide-ifdef minor mode hides selected code within @samp{#if} and | |
9234c238 RS |
1730 | @samp{#ifdef} preprocessor blocks. See the documentation string of |
1731 | @code{hide-ifdef-mode} for more information. | |
1732 | ||
1733 | @item M-x ff-find-related-file | |
1734 | @cindex related files | |
1735 | @findex ff-find-related-file | |
1736 | @vindex ff-related-file-alist | |
1737 | Find a file ``related'' in a special way to the file visited by the | |
1738 | current buffer. Typically this will be the header file corresponding | |
1739 | to a C/C++ source file, or vice versa. The variable | |
1740 | @code{ff-related-file-alist} specifies how to compute related file | |
1741 | names. | |
6bf7aab6 DL |
1742 | @end table |
1743 | ||
1744 | @node Comments in C | |
1745 | @subsection Comments in C Modes | |
1746 | ||
1747 | C mode and related modes use a number of variables for controlling | |
1748 | comment format. | |
1749 | ||
1750 | @table @code | |
1751 | @item c-comment-only-line-offset | |
1752 | @vindex c-comment-only-line-offset | |
1753 | Extra offset for line which contains only the start of a comment. It | |
1754 | can be either an integer or a cons cell of the form | |
1755 | @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where | |
1756 | @var{non-anchored-offset} is the amount of offset given to | |
1757 | non-column-zero anchored comment-only lines, and @var{anchored-offset} | |
1758 | is the amount of offset to give column-zero anchored comment-only lines. | |
1759 | Just an integer as value is equivalent to @code{(@var{val} . 0)}. | |
1760 | ||
1761 | @item c-comment-start-regexp | |
1762 | @vindex c-comment-start-regexp | |
1763 | This buffer-local variable specifies how to recognize the start of a comment. | |
1764 | ||
1765 | @item c-hanging-comment-ender-p | |
1766 | @vindex c-hanging-comment-ender-p | |
1767 | If this variable is @code{nil}, @code{c-fill-paragraph} leaves the | |
1768 | comment terminator of a block comment on a line by itself. The default | |
1769 | value is @code{t}, which puts the comment-end delimiter @samp{*/} at the | |
1770 | end of the last line of the comment text. | |
1771 | ||
1772 | @item c-hanging-comment-starter-p | |
1773 | @vindex c-hanging-comment-starter-p | |
1774 | If this variable is @code{nil}, @code{c-fill-paragraph} leaves the | |
1775 | starting delimiter of a block comment on a line by itself. The default | |
1776 | value is @code{t}, which puts the comment-start delimiter @samp{/*} at | |
1777 | the beginning of the first line of the comment text. | |
1778 | @end table | |
1779 | ||
1780 | @node Fortran | |
1781 | @section Fortran Mode | |
1782 | @cindex Fortran mode | |
1783 | @cindex mode, Fortran | |
1784 | ||
1785 | Fortran mode provides special motion commands for Fortran statements and | |
1786 | subprograms, and indentation commands that understand Fortran conventions | |
1787 | of nesting, line numbers and continuation statements. Fortran mode has | |
1788 | its own Auto Fill mode that breaks long lines into proper Fortran | |
1789 | continuation lines. | |
1790 | ||
1791 | Special commands for comments are provided because Fortran comments | |
1792 | are unlike those of other languages. Built-in abbrevs optionally save | |
1793 | typing when you insert Fortran keywords. | |
1794 | ||
6bf7aab6 DL |
1795 | Use @kbd{M-x fortran-mode} to switch to this major mode. This command |
1796 | runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). | |
1797 | ||
4946337d | 1798 | @cindex Fortran77 and Fortran90 |
138a8f12 DL |
1799 | @findex f90-mode |
1800 | @findex fortran-mode | |
5fe3b9bc | 1801 | Fortran mode is meant for editing Fortran77 ``fixed format'' source |
9234c238 RS |
1802 | code. For editing the modern Fortran90 ``free format'' source code, |
1803 | use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for | |
1804 | files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode | |
1805 | for the extension @samp{.f90}. GNU Fortran supports both kinds of | |
1806 | format. | |
138a8f12 | 1807 | |
6bf7aab6 DL |
1808 | @menu |
1809 | * Motion: Fortran Motion. Moving point by statements or subprograms. | |
1810 | * Indent: Fortran Indent. Indentation commands for Fortran. | |
1811 | * Comments: Fortran Comments. Inserting and aligning comments. | |
1812 | * Autofill: Fortran Autofill. Auto fill minor mode for Fortran. | |
1813 | * Columns: Fortran Columns. Measuring columns for valid Fortran. | |
1814 | * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. | |
6bf7aab6 DL |
1815 | @end menu |
1816 | ||
1817 | @node Fortran Motion | |
1818 | @subsection Motion Commands | |
1819 | ||
9234c238 RS |
1820 | In addition to the normal commands for moving by and operating on |
1821 | ``defuns'' (Fortran subprograms---functions and subroutines), Fortran | |
1822 | mode provides special commands to move by statements. | |
6bf7aab6 | 1823 | |
9234c238 | 1824 | @table @kbd |
6bf7aab6 | 1825 | @kindex C-c C-n @r{(Fortran mode)} |
6bf7aab6 | 1826 | @findex fortran-next-statement |
6bf7aab6 DL |
1827 | @item C-c C-n |
1828 | Move to beginning of current or next statement | |
1829 | (@code{fortran-next-statement}). | |
9234c238 RS |
1830 | |
1831 | @kindex C-c C-p @r{(Fortran mode)} | |
1832 | @findex fortran-previous-statement | |
6bf7aab6 DL |
1833 | @item C-c C-p |
1834 | Move to beginning of current or previous statement | |
1835 | (@code{fortran-previous-statement}). | |
1836 | @end table | |
1837 | ||
1838 | @node Fortran Indent | |
1839 | @subsection Fortran Indentation | |
1840 | ||
1841 | Special commands and features are needed for indenting Fortran code in | |
1842 | order to make sure various syntactic entities (line numbers, comment line | |
1843 | indicators and continuation line flags) appear in the columns that are | |
1844 | required for standard Fortran. | |
1845 | ||
1846 | @menu | |
85750656 | 1847 | * Commands: ForIndent Commands. Commands for indenting and filling Fortran. |
6bf7aab6 DL |
1848 | * Contline: ForIndent Cont. How continuation lines indent. |
1849 | * Numbers: ForIndent Num. How line numbers auto-indent. | |
1850 | * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. | |
1851 | * Vars: ForIndent Vars. Variables controlling Fortran indent style. | |
1852 | @end menu | |
1853 | ||
1854 | @node ForIndent Commands | |
9234c238 | 1855 | @subsubsection Fortran Indentation and Filling Commands |
6bf7aab6 DL |
1856 | |
1857 | @table @kbd | |
6bf7aab6 | 1858 | @item C-M-j |
85750656 DL |
1859 | Break the current line and set up a continuation line |
1860 | (@code{fortran-split-line}). | |
6bf7aab6 | 1861 | @item M-^ |
85750656 | 1862 | Join this line to the previous line (@code{fortran-join-line}). |
6bf7aab6 DL |
1863 | @item C-M-q |
1864 | Indent all the lines of the subprogram point is in | |
1865 | (@code{fortran-indent-subprogram}). | |
85750656 DL |
1866 | @item M-q |
1867 | Fill a comment block or statement. | |
6bf7aab6 DL |
1868 | @end table |
1869 | ||
6bf7aab6 DL |
1870 | @kindex C-M-q @r{(Fortran mode)} |
1871 | @findex fortran-indent-subprogram | |
1872 | The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command | |
1873 | to reindent all the lines of the Fortran subprogram (function or | |
1874 | subroutine) containing point. | |
1875 | ||
1876 | @kindex C-M-j @r{(Fortran mode)} | |
1877 | @findex fortran-split-line | |
1878 | The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits | |
1879 | a line in the appropriate fashion for Fortran. In a non-comment line, | |
1880 | the second half becomes a continuation line and is indented | |
1881 | accordingly. In a comment line, both halves become separate comment | |
1882 | lines. | |
1883 | ||
1884 | @kindex M-^ @r{(Fortran mode)} | |
138a8f12 DL |
1885 | @kindex C-c C-d @r{(Fortran mode)} |
1886 | @findex fortran-join-line | |
85750656 DL |
1887 | @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, |
1888 | which joins a continuation line back to the previous line, roughly as | |
1889 | the inverse of @code{fortran-split-line}. The point must be on a | |
138a8f12 DL |
1890 | continuation line when this command is invoked. |
1891 | ||
85750656 | 1892 | @kindex M-q @r{(Fortran mode)} |
9234c238 RS |
1893 | @kbd{M-q} in Fortran mode fills the comment block or statement that |
1894 | point is in. This removes any excess statement continuations. | |
85750656 | 1895 | |
6bf7aab6 DL |
1896 | @node ForIndent Cont |
1897 | @subsubsection Continuation Lines | |
1898 | @cindex Fortran continuation lines | |
1899 | ||
1900 | @vindex fortran-continuation-string | |
1901 | Most modern Fortran compilers allow two ways of writing continuation | |
1902 | lines. If the first non-space character on a line is in column 5, then | |
1903 | that line is a continuation of the previous line. We call this | |
1904 | @dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The | |
1905 | variable @code{fortran-continuation-string} specifies what character to | |
1906 | put on column 5. A line that starts with a tab character followed by | |
1907 | any digit except @samp{0} is also a continuation line. We call this | |
1908 | style of continuation @dfn{tab format}. | |
1909 | ||
1910 | @vindex indent-tabs-mode @r{(Fortran mode)} | |
1911 | Fortran mode can make either style of continuation line, but you | |
1912 | must specify which one you prefer. The value of the variable | |
1913 | @code{indent-tabs-mode} controls the choice: @code{nil} for fixed | |
1914 | format, and non-@code{nil} for tab format. You can tell which style | |
1915 | is presently in effect by the presence or absence of the string | |
1916 | @samp{Tab} in the mode line. | |
1917 | ||
1918 | If the text on a line starts with the conventional Fortran | |
1919 | continuation marker @samp{$}, or if it begins with any non-whitespace | |
1920 | character in column 5, Fortran mode treats it as a continuation line. | |
1921 | When you indent a continuation line with @key{TAB}, it converts the line | |
1922 | to the current continuation style. When you split a Fortran statement | |
1923 | with @kbd{C-M-j}, the continuation marker on the newline is created | |
1924 | according to the continuation style. | |
1925 | ||
1926 | The setting of continuation style affects several other aspects of | |
1927 | editing in Fortran mode. In fixed format mode, the minimum column | |
1928 | number for the body of a statement is 6. Lines inside of Fortran | |
1929 | blocks that are indented to larger column numbers always use only the | |
1930 | space character for whitespace. In tab format mode, the minimum | |
1931 | column number for the statement body is 8, and the whitespace before | |
1932 | column 8 must always consist of one tab character. | |
1933 | ||
1934 | @vindex fortran-tab-mode-default | |
1935 | @vindex fortran-analyze-depth | |
1936 | When you enter Fortran mode for an existing file, it tries to deduce the | |
1937 | proper continuation style automatically from the file contents. The first | |
1938 | line that begins with either a tab character or six spaces determines the | |
1939 | choice. The variable @code{fortran-analyze-depth} specifies how many lines | |
1940 | to consider (at the beginning of the file); if none of those lines | |
1941 | indicates a style, then the variable @code{fortran-tab-mode-default} | |
1942 | specifies the style. If it is @code{nil}, that specifies fixed format, and | |
1943 | non-@code{nil} specifies tab format. | |
1944 | ||
1945 | @node ForIndent Num | |
1946 | @subsubsection Line Numbers | |
1947 | ||
1948 | If a number is the first non-whitespace in the line, Fortran | |
1949 | indentation assumes it is a line number and moves it to columns 0 | |
1950 | through 4. (Columns always count from 0 in GNU Emacs.) | |
1951 | ||
1952 | @vindex fortran-line-number-indent | |
1953 | Line numbers of four digits or less are normally indented one space. | |
1954 | The variable @code{fortran-line-number-indent} controls this; it | |
1955 | specifies the maximum indentation a line number can have. Line numbers | |
1956 | are indented to right-justify them to end in column 4 unless that would | |
1957 | require more than this maximum indentation. The default value of the | |
1958 | variable is 1. | |
1959 | ||
1960 | @vindex fortran-electric-line-number | |
1961 | Simply inserting a line number is enough to indent it according to | |
1962 | these rules. As each digit is inserted, the indentation is recomputed. | |
1963 | To turn off this feature, set the variable | |
1964 | @code{fortran-electric-line-number} to @code{nil}. Then inserting line | |
1965 | numbers is like inserting anything else. | |
1966 | ||
1967 | @node ForIndent Conv | |
1968 | @subsubsection Syntactic Conventions | |
1969 | ||
1970 | Fortran mode assumes that you follow certain conventions that simplify | |
1971 | the task of understanding a Fortran program well enough to indent it | |
1972 | properly: | |
1973 | ||
1974 | @itemize @bullet | |
1975 | @item | |
1976 | Two nested @samp{do} loops never share a @samp{continue} statement. | |
1977 | ||
1978 | @item | |
1979 | Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} | |
1980 | and others are written without embedded whitespace or line breaks. | |
1981 | ||
1982 | Fortran compilers generally ignore whitespace outside of string | |
1983 | constants, but Fortran mode does not recognize these keywords if they | |
1984 | are not contiguous. Constructs such as @samp{else if} or @samp{end do} | |
1985 | are acceptable, but the second word should be on the same line as the | |
1986 | first and not on a continuation line. | |
1987 | @end itemize | |
1988 | ||
1989 | @noindent | |
1990 | If you fail to follow these conventions, the indentation commands may | |
1991 | indent some lines unaesthetically. However, a correct Fortran program | |
1992 | retains its meaning when reindented even if the conventions are not | |
1993 | followed. | |
1994 | ||
1995 | @node ForIndent Vars | |
1996 | @subsubsection Variables for Fortran Indentation | |
1997 | ||
1998 | @vindex fortran-do-indent | |
1999 | @vindex fortran-if-indent | |
2000 | @vindex fortran-structure-indent | |
2001 | @vindex fortran-continuation-indent | |
2002 | @vindex fortran-check-all-num@dots{} | |
2003 | @vindex fortran-minimum-statement-indent@dots{} | |
2004 | Several additional variables control how Fortran indentation works: | |
2005 | ||
2006 | @table @code | |
2007 | @item fortran-do-indent | |
2008 | Extra indentation within each level of @samp{do} statement (default 3). | |
2009 | ||
2010 | @item fortran-if-indent | |
2011 | Extra indentation within each level of @samp{if} statement (default 3). | |
2012 | This value is also used for extra indentation within each level of the | |
2013 | Fortran 90 @samp{where} statement. | |
2014 | ||
2015 | @item fortran-structure-indent | |
2016 | Extra indentation within each level of @samp{structure}, @samp{union}, or | |
2017 | @samp{map} statements (default 3). | |
2018 | ||
2019 | @item fortran-continuation-indent | |
2020 | Extra indentation for bodies of continuation lines (default 5). | |
2021 | ||
2022 | @item fortran-check-all-num-for-matching-do | |
2023 | If this is @code{nil}, indentation assumes that each @samp{do} statement | |
2024 | ends on a @samp{continue} statement. Therefore, when computing | |
2025 | indentation for a statement other than @samp{continue}, it can save time | |
2026 | by not checking for a @samp{do} statement ending there. If this is | |
2027 | non-@code{nil}, indenting any numbered statement must check for a | |
2028 | @samp{do} that ends there. The default is @code{nil}. | |
2029 | ||
2030 | @item fortran-blink-matching-if | |
2031 | If this is @code{t}, indenting an @samp{endif} statement moves the | |
2032 | cursor momentarily to the matching @samp{if} statement to show where it | |
2033 | is. The default is @code{nil}. | |
2034 | ||
2035 | @item fortran-minimum-statement-indent-fixed | |
2036 | Minimum indentation for fortran statements when using fixed format | |
2037 | continuation line style. Statement bodies are never indented less than | |
2038 | this much. The default is 6. | |
2039 | ||
2040 | @item fortran-minimum-statement-indent-tab | |
2041 | Minimum indentation for fortran statements for tab format continuation line | |
2042 | style. Statement bodies are never indented less than this much. The | |
2043 | default is 8. | |
2044 | @end table | |
2045 | ||
2046 | @node Fortran Comments | |
2047 | @subsection Fortran Comments | |
2048 | ||
2049 | The usual Emacs comment commands assume that a comment can follow a line | |
2050 | of code. In Fortran, the standard comment syntax requires an entire line | |
2051 | to be just a comment. Therefore, Fortran mode replaces the standard Emacs | |
2052 | comment commands and defines some new variables. | |
2053 | ||
85750656 DL |
2054 | Fortran mode can also handle the Fortran90 comment syntax where comments |
2055 | start with @samp{!} and can follow other text. Because only some Fortran77 | |
6bf7aab6 DL |
2056 | compilers accept this syntax, Fortran mode will not insert such comments |
2057 | unless you have said in advance to do so. To do this, set the variable | |
2058 | @code{comment-start} to @samp{"!"} (@pxref{Variables}). | |
2059 | ||
2060 | @table @kbd | |
2061 | @item M-; | |
2062 | Align comment or insert new comment (@code{fortran-comment-indent}). | |
2063 | ||
2064 | @item C-x ; | |
2065 | Applies to nonstandard @samp{!} comments only. | |
2066 | ||
2067 | @item C-c ; | |
2068 | Turn all lines of the region into comments, or (with argument) turn them back | |
2069 | into real code (@code{fortran-comment-region}). | |
2070 | @end table | |
2071 | ||
2072 | @kbd{M-;} in Fortran mode is redefined as the command | |
2073 | @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this | |
2074 | recognizes any kind of existing comment and aligns its text appropriately; | |
2075 | if there is no existing comment, a comment is inserted and aligned. But | |
2076 | inserting and aligning comments are not the same in Fortran mode as in | |
2077 | other modes. | |
2078 | ||
2079 | When a new comment must be inserted, if the current line is blank, a | |
2080 | full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} | |
2081 | comment is inserted if you have said you want to use them. Otherwise a | |
2082 | full-line comment is inserted on a new line before the current line. | |
2083 | ||
2084 | Nonstandard @samp{!} comments are aligned like comments in other | |
2085 | languages, but full-line comments are different. In a standard full-line | |
2086 | comment, the comment delimiter itself must always appear in column zero. | |
2087 | What can be aligned is the text within the comment. You can choose from | |
2088 | three styles of alignment by setting the variable | |
2089 | @code{fortran-comment-indent-style} to one of these values: | |
2090 | ||
2091 | @vindex fortran-comment-indent-style | |
2092 | @vindex fortran-comment-line-extra-indent | |
2093 | @table @code | |
2094 | @item fixed | |
2095 | Align the text at a fixed column, which is the sum of | |
2096 | @code{fortran-comment-line-extra-indent} and the minimum statement | |
2097 | indentation. This is the default. | |
2098 | ||
2099 | The minimum statement indentation is | |
2100 | @code{fortran-minimum-statement-indent-fixed} for fixed format | |
2101 | continuation line style and @code{fortran-minimum-statement-indent-tab} | |
2102 | for tab format style. | |
2103 | ||
2104 | @item relative | |
2105 | Align the text as if it were a line of code, but with an additional | |
2106 | @code{fortran-comment-line-extra-indent} columns of indentation. | |
2107 | ||
2108 | @item nil | |
2109 | Don't move text in full-line comments automatically at all. | |
2110 | @end table | |
2111 | ||
2112 | @vindex fortran-comment-indent-char | |
2113 | In addition, you can specify the character to be used to indent within | |
2114 | full-line comments by setting the variable | |
2115 | @code{fortran-comment-indent-char} to the single-character string you want | |
2116 | to use. | |
2d588beb GM |
2117 | |
2118 | @vindex fortran-directive-re | |
2119 | Compiler directive lines, or preprocessor lines, have much the same | |
2120 | appearance as comment lines. It is important, though, that such lines | |
2121 | never be indented at all, no matter what the value of | |
2122 | @code{fortran-comment-indent-style}. The variable | |
2123 | @code{fortran-directive-re} is a regular expression that specifies which | |
2124 | lines are directives. Matching lines are never indented, and receive | |
2125 | distinctive font-locking. | |
6bf7aab6 DL |
2126 | |
2127 | @vindex comment-line-start | |
2128 | @vindex comment-line-start-skip | |
2129 | Fortran mode introduces two variables @code{comment-line-start} and | |
2130 | @code{comment-line-start-skip}, which play for full-line comments the same | |
2131 | roles played by @code{comment-start} and @code{comment-start-skip} for | |
2132 | ordinary text-following comments. Normally these are set properly by | |
2133 | Fortran mode, so you do not need to change them. | |
2134 | ||
2135 | The normal Emacs comment command @kbd{C-x ;} has not been redefined. If | |
2136 | you use @samp{!} comments, this command can be used with them. Otherwise | |
2137 | it is useless in Fortran mode. | |
2138 | ||
2139 | @kindex C-c ; @r{(Fortran mode)} | |
2140 | @findex fortran-comment-region | |
2141 | @vindex fortran-comment-region | |
2142 | The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the | |
2143 | lines of the region into comments by inserting the string @samp{C$$$} at | |
2144 | the front of each one. With a numeric argument, it turns the region | |
2145 | back into live code by deleting @samp{C$$$} from the front of each line | |
2146 | in it. The string used for these comments can be controlled by setting | |
2147 | the variable @code{fortran-comment-region}. Note that here we have an | |
2148 | example of a command and a variable with the same name; these two uses | |
2149 | of the name never conflict because in Lisp and in Emacs it is always | |
2150 | clear from the context which one is meant. | |
2151 | ||
2152 | @node Fortran Autofill | |
2153 | @subsection Fortran Auto Fill Mode | |
2154 | ||
2155 | Fortran Auto Fill mode is a minor mode which automatically splits | |
2156 | Fortran statements as you insert them when they become too wide. | |
2157 | Splitting a statement involves making continuation lines using | |
2158 | @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This | |
2159 | splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and | |
2160 | also in the Fortran indentation commands. | |
2161 | ||
2162 | @findex fortran-auto-fill-mode | |
2163 | @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it | |
2164 | was off, or off if it was on. This command works the same as @kbd{M-x | |
2165 | auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A | |
2166 | positive numeric argument turns Fortran Auto Fill mode on, and a | |
2167 | negative argument turns it off. You can see when Fortran Auto Fill mode | |
2168 | is in effect by the presence of the word @samp{Fill} in the mode line, | |
2169 | inside the parentheses. Fortran Auto Fill mode is a minor mode, turned | |
2170 | on or off for each buffer individually. @xref{Minor Modes}. | |
2171 | ||
2172 | @vindex fortran-break-before-delimiters | |
2173 | Fortran Auto Fill mode breaks lines at spaces or delimiters when the | |
2174 | lines get longer than the desired width (the value of @code{fill-column}). | |
2175 | The delimiters that Fortran Auto Fill mode may break at are @samp{,}, | |
2176 | @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}. | |
2177 | The line break comes after the delimiter if the variable | |
2178 | @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by | |
2179 | default), the break comes before the delimiter. | |
2180 | ||
2181 | By default, Fortran Auto Fill mode is not enabled. If you want this | |
2182 | feature turned on permanently, add a hook function to | |
2183 | @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}. | |
2184 | @xref{Hooks}. | |
2185 | ||
2186 | @node Fortran Columns | |
2187 | @subsection Checking Columns in Fortran | |
2188 | ||
2189 | @table @kbd | |
2190 | @item C-c C-r | |
2191 | Display a ``column ruler'' momentarily above the current line | |
2192 | (@code{fortran-column-ruler}). | |
2193 | @item C-c C-w | |
2194 | Split the current window horizontally temporarily so that it is 72 | |
9234c238 RS |
2195 | columns wide (@code{fortran-window-create-momentarily}). This may |
2196 | help you avoid making lines longer than the 72-character limit that | |
2197 | some Fortran compilers impose. | |
2198 | @item C-u C-c C-w | |
2199 | Split the current window horizontally so that it is 72 columns wide | |
2200 | (@code{fortran-window-create}). You can then continue editing. | |
2201 | @item M-x fortran-strip-sequence-nos | |
2202 | Delete all text in column 72 and beyond. | |
6bf7aab6 DL |
2203 | @end table |
2204 | ||
2205 | @kindex C-c C-r @r{(Fortran mode)} | |
2206 | @findex fortran-column-ruler | |
6bf7aab6 DL |
2207 | The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column |
2208 | ruler momentarily above the current line. The comment ruler is two lines | |
2209 | of text that show you the locations of columns with special significance in | |
2210 | Fortran programs. Square brackets show the limits of the columns for line | |
2211 | numbers, and curly brackets show the limits of the columns for the | |
2212 | statement body. Column numbers appear above them. | |
2213 | ||
2214 | Note that the column numbers count from zero, as always in GNU Emacs. | |
2215 | As a result, the numbers may be one less than those you are familiar | |
2216 | with; but the positions they indicate in the line are standard for | |
2217 | Fortran. | |
2218 | ||
9234c238 RS |
2219 | @vindex fortran-column-ruler-fixed |
2220 | @vindex fortran-column-ruler-tabs | |
79214ddf | 2221 | The text used to display the column ruler depends on the value of |
6bf7aab6 DL |
2222 | the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is |
2223 | @code{nil}, then the value of the variable | |
2224 | @code{fortran-column-ruler-fixed} is used as the column ruler. | |
2225 | Otherwise, the variable @code{fortran-column-ruler-tab} is displayed. | |
2226 | By changing these variables, you can change the column ruler display. | |
2227 | ||
9234c238 RS |
2228 | @kindex C-c C-w @r{(Fortran mode)} |
2229 | @findex fortran-window-create-momentarily | |
2230 | @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily | |
2231 | splits the current window horizontally, making a window 72 columns | |
2232 | wide, so you can see which lines that is too long. Type a space to | |
2233 | restore the normal width. | |
2234 | ||
138a8f12 | 2235 | @kindex C-u C-c C-w @r{(Fortran mode)} |
6bf7aab6 | 2236 | @findex fortran-window-create |
9234c238 RS |
2237 | You can also split the window horizontally and continue editing with |
2238 | the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x | |
2239 | fortran-window-create}). By editing in this window you can | |
2240 | immediately see when you make a line too wide to be correct Fortran. | |
6bf7aab6 | 2241 | |
9234c238 RS |
2242 | @findex fortran-strip-sequence-nos |
2243 | The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in | |
2244 | column 72 and beyond, on all lines in the current buffer. This is the | |
2245 | easiest way to get rid of old sequence numbers. | |
138a8f12 | 2246 | |
6bf7aab6 DL |
2247 | @node Fortran Abbrev |
2248 | @subsection Fortran Keyword Abbrevs | |
2249 | ||
2250 | Fortran mode provides many built-in abbrevs for common keywords and | |
2251 | declarations. These are the same sort of abbrev that you can define | |
2252 | yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. | |
2253 | ||
2254 | The built-in abbrevs are unusual in one way: they all start with a | |
2255 | semicolon. You cannot normally use semicolon in an abbrev, but Fortran | |
2256 | mode makes this possible by changing the syntax of semicolon to ``word | |
2257 | constituent.'' | |
2258 | ||
2259 | For example, one built-in Fortran abbrev is @samp{;c} for | |
2260 | @samp{continue}. If you insert @samp{;c} and then insert a punctuation | |
2261 | character such as a space or a newline, the @samp{;c} expands automatically | |
2262 | to @samp{continue}, provided Abbrev mode is enabled.@refill | |
2263 | ||
2264 | Type @samp{;?} or @samp{;C-h} to display a list of all the built-in | |
2265 | Fortran abbrevs and what they stand for. | |
2266 | ||
6bf7aab6 DL |
2267 | @node Asm Mode |
2268 | @section Asm Mode | |
2269 | ||
2270 | @cindex Asm mode | |
9234c238 | 2271 | @cindex assembler mode |
6bf7aab6 DL |
2272 | Asm mode is a major mode for editing files of assembler code. It |
2273 | defines these commands: | |
2274 | ||
2275 | @table @kbd | |
2276 | @item @key{TAB} | |
2277 | @code{tab-to-tab-stop}. | |
2278 | @item C-j | |
2279 | Insert a newline and then indent using @code{tab-to-tab-stop}. | |
2280 | @item : | |
2281 | Insert a colon and then remove the indentation from before the label | |
2282 | preceding colon. Then do @code{tab-to-tab-stop}. | |
2283 | @item ; | |
2284 | Insert or align a comment. | |
2285 | @end table | |
2286 | ||
2287 | The variable @code{asm-comment-char} specifies which character | |
2288 | starts comments in assembler syntax. | |
6b61353c KH |
2289 | |
2290 | @ignore | |
2291 | arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 | |
2292 | @end ignore |