Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
acaf905b | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 |
324a4f6a | 3 | @c Free Software Foundation, Inc. |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Programs, Building, Text, Top | |
6 | @chapter Editing Programs | |
7 | @cindex Lisp editing | |
8 | @cindex C editing | |
9 | @cindex program editing | |
10 | ||
ec7ae032 CY |
11 | This chapter describes Emacs features for facilitating editing |
12 | programs. Some of these features can: | |
6bf7aab6 DL |
13 | |
14 | @itemize @bullet | |
15 | @item | |
93da5dff | 16 | Find or move over top-level definitions (@pxref{Defuns}). |
6bf7aab6 | 17 | @item |
93da5dff RS |
18 | Apply the usual indentation conventions of the language |
19 | (@pxref{Program Indent}). | |
6bf7aab6 | 20 | @item |
93da5dff | 21 | Balance parentheses (@pxref{Parentheses}). |
cf1c48d4 | 22 | @item |
ea118de1 SE |
23 | Insert, kill or align comments (@pxref{Comments}). |
24 | @item | |
cf1c48d4 | 25 | Highlight program syntax (@pxref{Font Lock}). |
6bf7aab6 DL |
26 | @end itemize |
27 | ||
6bf7aab6 DL |
28 | @menu |
29 | * Program Modes:: Major modes for editing programs. | |
93da5dff RS |
30 | * Defuns:: Commands to operate on major top-level parts |
31 | of a program. | |
6bf7aab6 | 32 | * Program Indent:: Adjusting indentation to show the nesting. |
93da5dff | 33 | * Parentheses:: Commands that operate on parentheses. |
8838673e | 34 | * Comments:: Inserting, killing, and aligning comments. |
93da5dff | 35 | * Documentation:: Getting documentation of functions you plan to call. |
51ed0ea0 | 36 | * Hideshow:: Displaying blocks selectively. |
93da5dff | 37 | * Symbol Completion:: Completion on symbol names of your program or language. |
3b8b8888 | 38 | * Glasses:: Making identifiersLikeThis more readable. |
a42dbee1 | 39 | * Semantic:: Suite of editing tools based on source code parsing. |
93da5dff | 40 | * Misc for Programs:: Other Emacs features useful for editing programs. |
47d42d81 AM |
41 | * C Modes:: Special commands of C, C++, Objective-C, Java, |
42 | IDL, Pike and AWK modes. | |
51ed0ea0 | 43 | * Asm Mode:: Asm mode and its special features. |
b23ef7a5 EZ |
44 | @ifnottex |
45 | * Fortran:: Fortran mode and its special features. | |
46 | @end ifnottex | |
6bf7aab6 DL |
47 | @end menu |
48 | ||
49 | @node Program Modes | |
50 | @section Major Modes for Programming Languages | |
6bf7aab6 | 51 | @cindex modes for programming languages |
cf1c48d4 | 52 | |
ec7ae032 CY |
53 | Emacs has specialized major modes (@pxref{Major Modes}) for many |
54 | programming languages. A programming language mode typically | |
cf1c48d4 RS |
55 | specifies the syntax of expressions, the customary rules for |
56 | indentation, how to do syntax highlighting for the language, and how | |
ec7ae032 CY |
57 | to find the beginning or end of a function definition. It often has |
58 | features for compiling and debugging programs as well. The major mode | |
59 | for each language is named after the language; for instance, the major | |
60 | mode for the C programming language is @code{c-mode}. | |
cf1c48d4 | 61 | |
6bf7aab6 DL |
62 | @cindex Perl mode |
63 | @cindex Icon mode | |
6bf7aab6 DL |
64 | @cindex Makefile mode |
65 | @cindex Tcl mode | |
66 | @cindex CPerl mode | |
138a8f12 DL |
67 | @cindex DSSSL mode |
68 | @cindex Octave mode | |
69 | @cindex Metafont mode | |
70 | @cindex Modula2 mode | |
71 | @cindex Prolog mode | |
7b703414 | 72 | @cindex Python mode |
e37d4360 | 73 | @cindex Ruby mode |
138a8f12 DL |
74 | @cindex Simula mode |
75 | @cindex VHDL mode | |
76 | @cindex M4 mode | |
77 | @cindex Shell-script mode | |
3b8b8888 DL |
78 | @cindex Delphi mode |
79 | @cindex PostScript mode | |
8758a7da RS |
80 | @cindex Conf mode |
81 | @cindex DNS mode | |
71785b7a | 82 | @cindex Javascript mode |
ec7ae032 CY |
83 | Emacs has programming language modes for Lisp, Scheme, the |
84 | Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi, | |
85 | Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont | |
86 | (@TeX{}'s companion for font creation), Modula2, Objective-C, Octave, | |
87 | Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and | |
88 | VHDL. An alternative mode for Perl is called CPerl mode. Modes are | |
89 | also available for the scripting languages of the common GNU and Unix | |
90 | shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for | |
91 | makefiles, DNS master files, and various sorts of configuration files. | |
92 | ||
93 | Ideally, Emacs should have a major mode for each programming | |
94 | language that you might want to edit. If it doesn't have a mode for | |
95 | your favorite language, the mode might be implemented in a package not | |
96 | distributed with Emacs (@pxref{Packages}); or you can contribute one. | |
6bf7aab6 DL |
97 | |
98 | @kindex DEL @r{(programming modes)} | |
4f7666dc | 99 | @findex c-electric-backspace |
ec7ae032 | 100 | @findex backward-delete-char-untabify |
93da5dff | 101 | In most programming languages, indentation should vary from line to |
ec7ae032 CY |
102 | line to illustrate the structure of the program. Therefore, in most |
103 | programming language modes, typing @key{TAB} updates the indentation | |
104 | of the current line (@pxref{Program Indent}). Furthermore, @key{DEL} | |
105 | is usually bound to @code{backward-delete-char-untabify}, which | |
106 | deletes backward treating each tab as if it were the equivalent number | |
107 | of spaces, so that you can delete one column of indentation without | |
108 | worrying whether the whitespace consists of spaces or tabs. | |
b23ef7a5 | 109 | |
6bf7aab6 DL |
110 | @cindex mode hook |
111 | @vindex c-mode-hook | |
112 | @vindex lisp-mode-hook | |
113 | @vindex emacs-lisp-mode-hook | |
114 | @vindex lisp-interaction-mode-hook | |
115 | @vindex scheme-mode-hook | |
ec7ae032 CY |
116 | Entering a programming language mode runs the custom Lisp functions |
117 | specified in the hook variable @code{prog-mode-hook}, followed by | |
118 | those specified in the mode's own mode hook (@pxref{Major Modes}). | |
119 | For instance, entering C mode runs the hooks @code{prog-mode-hook} and | |
120 | @code{c-mode-hook}. @xref{Hooks}, for information about hooks. | |
121 | ||
122 | @ifinfo | |
123 | Separate manuals are available for the modes for Ada (@pxref{Top,, | |
124 | Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba | |
125 | IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE | |
126 | (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). | |
127 | @end ifinfo | |
128 | @ifnotinfo | |
129 | The Emacs distribution contains Info manuals for the major modes for | |
130 | Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For | |
131 | Fortran mode, see the ``Fortran'' section in the Info version of the | |
132 | Emacs manual, which is not included in this printed version. | |
133 | @end ifnotinfo | |
6bf7aab6 | 134 | |
93da5dff RS |
135 | @node Defuns |
136 | @section Top-Level Definitions, or Defuns | |
6bf7aab6 | 137 | |
e722aa81 CY |
138 | In Emacs, a major definition at the top level in the buffer, such as |
139 | a function, is called a @dfn{defun}. The name comes from Lisp, but in | |
140 | Emacs we use it for all languages. | |
6bf7aab6 | 141 | |
93da5dff RS |
142 | @menu |
143 | * Left Margin Paren:: An open-paren or similar opening delimiter | |
144 | starts a defun if it is at the left margin. | |
145 | * Moving by Defuns:: Commands to move over or mark a major definition. | |
146 | * Imenu:: Making buffer indexes as menus. | |
147 | * Which Function:: Which Function mode shows which function you are in. | |
148 | @end menu | |
6bf7aab6 | 149 | |
93da5dff RS |
150 | @node Left Margin Paren |
151 | @subsection Left Margin Convention | |
6bf7aab6 | 152 | |
93da5dff RS |
153 | @cindex open-parenthesis in leftmost column |
154 | @cindex ( in leftmost column | |
e722aa81 CY |
155 | Many programming-language modes assume by default that any opening |
156 | delimiter found at the left margin is the start of a top-level | |
157 | definition, or defun. Therefore, @strong{don't put an opening | |
158 | delimiter at the left margin unless it should have that significance}. | |
159 | For instance, never put an open-parenthesis at the left margin in a | |
160 | Lisp file unless it is the start of a top-level list. | |
161 | ||
162 | The convention speeds up many Emacs operations, which would | |
163 | otherwise have to scan back to the beginning of the buffer to analyze | |
164 | the syntax of the code. | |
93da5dff RS |
165 | |
166 | If you don't follow this convention, not only will you have trouble | |
167 | when you explicitly use the commands for motion by defuns; other | |
e722aa81 CY |
168 | features that use them will also give you trouble. This includes the |
169 | indentation commands (@pxref{Program Indent}) and Font Lock mode | |
170 | (@pxref{Font Lock}). | |
93da5dff RS |
171 | |
172 | The most likely problem case is when you want an opening delimiter | |
173 | at the start of a line inside a string. To avoid trouble, put an | |
aca2cfd2 AM |
174 | escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some |
175 | other Lisp dialects) before the opening delimiter. This will not | |
176 | affect the contents of the string, but will prevent that opening | |
177 | delimiter from starting a defun. Here's an example: | |
6bf7aab6 | 178 | |
93da5dff RS |
179 | @example |
180 | (insert "Foo: | |
181 | \(bar) | |
182 | ") | |
183 | @end example | |
6bf7aab6 | 184 | |
5b8fe684 RS |
185 | To help you catch violations of this convention, Font Lock mode |
186 | highlights confusing opening delimiters (those that ought to be | |
187 | quoted) in bold red. | |
188 | ||
e722aa81 CY |
189 | If you need to override this convention, you can do so by setting |
190 | this user option: | |
aca2cfd2 AM |
191 | |
192 | @defvar open-paren-in-column-0-is-defun-start | |
193 | If this user option is set to @code{t} (the default), opening | |
194 | parentheses or braces at column zero always start defuns. When it's | |
195 | @code{nil}, defuns are found by searching for parens or braces at the | |
196 | outermost level. | |
197 | @end defvar | |
198 | ||
e722aa81 CY |
199 | Usually, you should leave this option at its default value of |
200 | @code{t}. If your buffer contains parentheses or braces in column | |
201 | zero which don't start defuns, and it is somehow impractical to remove | |
202 | these parentheses or braces, it might be helpful to set the option to | |
203 | @code{nil}. Be aware that this might make scrolling and display in | |
204 | large buffers quite sluggish. Furthermore, the parentheses and braces | |
205 | must be correctly matched throughout the buffer for it to work | |
206 | properly. | |
93da5dff RS |
207 | |
208 | @node Moving by Defuns | |
209 | @subsection Moving by Defuns | |
6bf7aab6 DL |
210 | @cindex defuns |
211 | ||
93da5dff RS |
212 | These commands move point or set up the region based on top-level |
213 | major definitions, also called @dfn{defuns}. | |
520c3f4c | 214 | |
6bf7aab6 DL |
215 | @table @kbd |
216 | @item C-M-a | |
217 | Move to beginning of current or preceding defun | |
218 | (@code{beginning-of-defun}). | |
219 | @item C-M-e | |
220 | Move to end of current or following defun (@code{end-of-defun}). | |
221 | @item C-M-h | |
222 | Put region around whole current or following defun (@code{mark-defun}). | |
223 | @end table | |
224 | ||
f772775c RS |
225 | @cindex move to beginning or end of function |
226 | @cindex function, move to beginning or end | |
227 | @kindex C-M-a | |
228 | @kindex C-M-e | |
229 | @kindex C-M-h | |
230 | @findex beginning-of-defun | |
231 | @findex end-of-defun | |
232 | @findex mark-defun | |
233 | The commands to move to the beginning and end of the current defun | |
234 | are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} | |
235 | (@code{end-of-defun}). If you repeat one of these commands, or use a | |
236 | positive numeric argument, each repetition moves to the next defun in | |
237 | the direction of motion. | |
238 | ||
239 | @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward | |
240 | @var{n} times to the next beginning of a defun. This is not exactly | |
241 | the same place that @kbd{C-M-e} with argument @var{n} would move to; | |
242 | the end of this defun is not usually exactly the same place as the | |
93da5dff RS |
243 | beginning of the following defun. (Whitespace, comments, and perhaps |
244 | declarations can separate them.) Likewise, @kbd{C-M-e} with a | |
245 | negative argument moves back to an end of a defun, which is not quite | |
246 | the same as @kbd{C-M-a} with a positive argument. | |
f772775c | 247 | |
4946337d | 248 | @kindex C-M-h @r{(C mode)} |
6bf7aab6 | 249 | @findex c-mark-function |
25716538 CY |
250 | To operate on the current defun, use @kbd{C-M-h} |
251 | (@code{mark-defun}), which sets the mark at the end of the current | |
252 | defun and puts point at its beginning. @xref{Marking Objects}. This | |
253 | is the easiest way to get ready to kill the defun in order to move it | |
254 | to a different place in the file. If you use the command while point | |
255 | is between defuns, it uses the following defun. If you use the | |
256 | command while the mark is already active, it sets the mark but does | |
257 | not move point; furthermore, each successive use of @kbd{C-M-h} | |
258 | extends the end of the region to include one more defun. | |
93da5dff RS |
259 | |
260 | In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, | |
261 | which is almost the same as @code{mark-defun}; the difference is that | |
262 | it backs up over the argument declarations, function name and returned | |
e79c6b89 RS |
263 | data type so that the entire C function is inside the region. This is |
264 | an example of how major modes adjust the standard key bindings so that | |
265 | they do their standard jobs in a way better fitting a particular | |
266 | language. Other major modes may replace any or all of these key | |
267 | bindings for that purpose. | |
6bf7aab6 | 268 | |
93da5dff RS |
269 | @node Imenu |
270 | @subsection Imenu | |
e79c6b89 RS |
271 | @cindex index of buffer definitions |
272 | @cindex buffer definitions index | |
93da5dff | 273 | |
269b7745 | 274 | The Imenu facility offers a way to find the major definitions in |
5e6f9132 RS |
275 | a file by name. It is also useful in text formatter major modes, |
276 | where it treats each chapter, section, etc., as a definition. | |
e79c6b89 | 277 | (@xref{Tags}, for a more powerful feature that handles multiple files |
5e6f9132 | 278 | together.) |
93da5dff RS |
279 | |
280 | @findex imenu | |
5e6f9132 | 281 | If you type @kbd{M-x imenu}, it reads the name of a definition using |
e79c6b89 RS |
282 | the minibuffer, then moves point to that definition. You can use |
283 | completion to specify the name; the command always displays the whole | |
284 | list of valid names. | |
d2fab838 | 285 | |
5e6f9132 | 286 | @findex imenu-add-menubar-index |
d2fab838 | 287 | Alternatively, you can bind the command @code{imenu} to a mouse |
e79c6b89 RS |
288 | click. Then it displays mouse menus for you to select a definition |
289 | name. You can also add the buffer's index to the menu bar by calling | |
290 | @code{imenu-add-menubar-index}. If you want to have this menu bar | |
291 | item available for all buffers in a certain major mode, you can do | |
292 | this by adding @code{imenu-add-menubar-index} to its mode hook. But | |
dfec8297 RS |
293 | if you have done that, you will have to wait a little while each time |
294 | you visit a file in that mode, while Emacs finds all the definitions | |
295 | in that buffer. | |
93da5dff RS |
296 | |
297 | @vindex imenu-auto-rescan | |
298 | When you change the contents of a buffer, if you add or delete | |
e79c6b89 | 299 | definitions, you can update the buffer's index based on the |
d2fab838 | 300 | new contents by invoking the @samp{*Rescan*} item in the menu. |
dcace646 EZ |
301 | Rescanning happens automatically if you set @code{imenu-auto-rescan} to |
302 | a non-@code{nil} value. There is no need to rescan because of small | |
e79c6b89 | 303 | changes in the text. |
93da5dff RS |
304 | |
305 | @vindex imenu-sort-function | |
d2fab838 | 306 | You can customize the way the menus are sorted by setting the |
e79c6b89 | 307 | variable @code{imenu-sort-function}. By default, names are ordered as |
5e6f9132 RS |
308 | they occur in the buffer; if you want alphabetic sorting, use the |
309 | symbol @code{imenu--sort-by-name} as the value. You can also | |
310 | define your own comparison function by writing Lisp code. | |
93da5dff RS |
311 | |
312 | Imenu provides the information to guide Which Function mode | |
313 | @ifnottex | |
314 | (@pxref{Which Function}). | |
315 | @end ifnottex | |
316 | @iftex | |
317 | (see below). | |
318 | @end iftex | |
319 | The Speedbar can also use it (@pxref{Speedbar}). | |
320 | ||
321 | @node Which Function | |
322 | @subsection Which Function Mode | |
af056954 | 323 | @cindex current function name in mode line |
93da5dff | 324 | |
ec7ae032 CY |
325 | Which Function mode is a global minor mode (@pxref{Minor Modes}) |
326 | which displays the current function name in the mode line, updating it | |
327 | as you move around in a buffer. | |
93da5dff RS |
328 | |
329 | @findex which-function-mode | |
330 | @vindex which-func-modes | |
df7593dd | 331 | To either enable or disable Which Function mode, use the command |
ec7ae032 CY |
332 | @kbd{M-x which-function-mode}. Although Which Function mode is a |
333 | global minor mode, it takes effect only in certain major modes: those | |
334 | listed in the variable @code{which-func-modes}. If the value of | |
335 | @code{which-func-modes} is @code{t} rather than a list of modes, then | |
336 | Which Function mode applies to all major modes that know how to | |
337 | support it---in other words, all the major modes that support Imenu. | |
6bf7aab6 DL |
338 | |
339 | @node Program Indent | |
340 | @section Indentation for Programs | |
341 | @cindex indentation for programs | |
342 | ||
343 | The best way to keep a program properly indented is to use Emacs to | |
e722aa81 CY |
344 | reindent it as you change it. Emacs has commands to indent either a |
345 | single line, a specified number of lines, or all of the lines inside a | |
346 | single parenthetical grouping. | |
6bf7aab6 | 347 | |
ec7ae032 CY |
348 | @xref{Indentation}, for general information about indentation. This |
349 | section describes indentation features specific to programming | |
350 | language modes. | |
351 | ||
6bf7aab6 | 352 | @menu |
8838673e | 353 | * Basic Indent:: Indenting a single line. |
6bf7aab6 | 354 | * Multi-line Indent:: Commands to reindent many lines at once. |
8838673e GM |
355 | * Lisp Indent:: Specifying how each Lisp function should be indented. |
356 | * C Indent:: Extra features for indenting C and related modes. | |
357 | * Custom C Indent:: Controlling indentation style for C and related modes. | |
6bf7aab6 DL |
358 | @end menu |
359 | ||
d2fab838 | 360 | @cindex pretty-printer |
ec7ae032 CY |
361 | Emacs also provides a Lisp pretty-printer in the @code{pp} package, |
362 | which reformats Lisp objects with nice-looking indentation. | |
6bf7aab6 DL |
363 | |
364 | @node Basic Indent | |
365 | @subsection Basic Program Indentation Commands | |
366 | ||
6bf7aab6 DL |
367 | @table @kbd |
368 | @item @key{TAB} | |
ec7ae032 | 369 | Adjust indentation of current line (@code{indent-for-tab-command}). |
6bf7aab6 | 370 | @item C-j |
bb63d706 RS |
371 | Insert a newline, then adjust indentation of following line |
372 | (@code{newline-and-indent}). | |
6bf7aab6 DL |
373 | @end table |
374 | ||
375 | @kindex TAB @r{(programming modes)} | |
4f7666dc RS |
376 | @findex c-indent-command |
377 | @findex indent-line-function | |
f772775c | 378 | @findex indent-for-tab-command |
ec7ae032 CY |
379 | The basic indentation command is @key{TAB} |
380 | (@code{indent-for-tab-command}), which was documented in | |
381 | @ref{Indentation}. In programming language modes, @key{TAB} indents | |
382 | the current line, based on the indentation and syntactic content of | |
383 | the preceding lines; if the region is active, @key{TAB} indents each | |
384 | line within the region, not just the current line. | |
6bf7aab6 | 385 | |
6d262977 | 386 | @kindex C-j @r{(indenting source code)} |
6bf7aab6 | 387 | @findex newline-and-indent |
ec7ae032 CY |
388 | The command @kbd{C-j} (@code{newline-and-indent}), which was |
389 | documented in @ref{Indentation Commands}, does the same as @key{RET} | |
390 | followed by @key{TAB}: it inserts a new line, then adjusts the line's | |
391 | indentation. | |
392 | ||
393 | When indenting a line that starts within a parenthetical grouping, | |
394 | Emacs usually places the start of the line under the preceding line | |
395 | within the group, or under the text after the parenthesis. If you | |
396 | manually give one of these lines a nonstandard indentation (e.g.@: for | |
397 | aesthetic purposes), the lines below will follow it. | |
398 | ||
399 | The indentation commands for most programming language modes assume | |
400 | that a open-parenthesis, open-brace or other opening delimiter at the | |
401 | left margin is the start of a function. If the code you are editing | |
402 | violates this assumption---even if the delimiters occur in strings or | |
403 | comments---you must set @code{open-paren-in-column-0-is-defun-start} | |
404 | to @code{nil} for indentation to work properly. @xref{Left Margin | |
e722aa81 | 405 | Paren}. |
6bf7aab6 DL |
406 | |
407 | @node Multi-line Indent | |
408 | @subsection Indenting Several Lines | |
409 | ||
e722aa81 CY |
410 | Sometimes, you may want to reindent several lines of code at a time. |
411 | One way to do this is to use the mark; when the mark is active and the | |
ec7ae032 CY |
412 | region is non-empty, @key{TAB} indents every line in the region. |
413 | Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents | |
414 | every line in the region, whether or not the mark is active | |
415 | (@pxref{Indentation Commands}). | |
416 | ||
417 | In addition, Emacs provides the following commands for indenting | |
418 | large chunks of code: | |
6bf7aab6 DL |
419 | |
420 | @table @kbd | |
421 | @item C-M-q | |
e722aa81 | 422 | Reindent all the lines within one parenthetical grouping. |
6bf7aab6 | 423 | @item C-u @key{TAB} |
93da5dff RS |
424 | Shift an entire parenthetical grouping rigidly sideways so that its |
425 | first line is properly indented. | |
5cc06e0b EZ |
426 | @item M-x indent-code-rigidly |
427 | Shift all the lines in the region rigidly sideways, but do not alter | |
428 | lines that start inside comments and strings. | |
6bf7aab6 DL |
429 | @end table |
430 | ||
431 | @kindex C-M-q | |
6daf3e15 | 432 | @findex indent-pp-sexp |
e722aa81 CY |
433 | To reindent the contents of a single parenthetical grouping, |
434 | position point before the beginning of the grouping and type | |
435 | @kbd{C-M-q}. This changes the relative indentation within the | |
ec7ae032 | 436 | grouping, without affecting its overall indentation (i.e.@: the |
e722aa81 CY |
437 | indentation of the line where the grouping starts). The function that |
438 | @kbd{C-M-q} runs depends on the major mode; it is | |
439 | @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, | |
440 | etc. To correct the overall indentation as well, type @key{TAB} | |
441 | first. | |
442 | ||
6bf7aab6 | 443 | @kindex C-u TAB |
e722aa81 CY |
444 | If you like the relative indentation within a grouping but not the |
445 | indentation of its first line, move point to that first line and type | |
446 | @kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, | |
447 | @key{TAB} with a numeric argument reindents the current line as usual, | |
448 | then reindents by the same amount all the lines in the parenthetical | |
449 | grouping starting on the current line. It is clever, though, and does | |
450 | not alter lines that start inside strings. Neither does it alter C | |
451 | preprocessor lines when in C mode, but it does reindent any | |
452 | continuation lines that may be attached to them. | |
6bf7aab6 | 453 | |
5cc06e0b | 454 | @findex indent-code-rigidly |
e722aa81 CY |
455 | The command @kbd{M-x indent-code-rigidly} rigidly shifts all the |
456 | lines in the region sideways, like @code{indent-rigidly} does | |
457 | (@pxref{Indentation Commands}). It doesn't alter the indentation of | |
458 | lines that start inside a string, unless the region also starts inside | |
459 | that string. The prefix arg specifies the number of columns to | |
460 | indent. | |
6bf7aab6 DL |
461 | |
462 | @node Lisp Indent | |
463 | @subsection Customizing Lisp Indentation | |
464 | @cindex customizing Lisp indentation | |
465 | ||
466 | The indentation pattern for a Lisp expression can depend on the function | |
467 | called by the expression. For each Lisp function, you can choose among | |
468 | several predefined patterns of indentation, or define an arbitrary one with | |
469 | a Lisp program. | |
470 | ||
471 | The standard pattern of indentation is as follows: the second line of the | |
472 | expression is indented under the first argument, if that is on the same | |
473 | line as the beginning of the expression; otherwise, the second line is | |
474 | indented underneath the function name. Each following line is indented | |
475 | under the previous line whose nesting depth is the same. | |
476 | ||
477 | @vindex lisp-indent-offset | |
478 | If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides | |
479 | the usual indentation pattern for the second line of an expression, so that | |
480 | such lines are always indented @code{lisp-indent-offset} more columns than | |
481 | the containing list. | |
482 | ||
483 | @vindex lisp-body-indent | |
d2fab838 | 484 | Certain functions override the standard pattern. Functions whose |
269b7745 | 485 | names start with @code{def} treat the second lines as the start of |
d2fab838 RS |
486 | a @dfn{body}, by indenting the second line @code{lisp-body-indent} |
487 | additional columns beyond the open-parenthesis that starts the | |
488 | expression. | |
6bf7aab6 | 489 | |
b771b258 | 490 | @cindex @code{lisp-indent-function} property |
d2fab838 | 491 | You can override the standard pattern in various ways for individual |
690a6d08 | 492 | functions, according to the @code{lisp-indent-function} property of |
ec7ae032 CY |
493 | the function name. This is normally done for macro definitions, using |
494 | the @code{declare} construct. @xref{Defining Macros,,, elisp, the | |
495 | Emacs Lisp Reference Manual}. | |
6bf7aab6 DL |
496 | |
497 | @node C Indent | |
498 | @subsection Commands for C Indentation | |
499 | ||
93da5dff | 500 | Here are special features for indentation in C mode and related modes: |
6bf7aab6 DL |
501 | |
502 | @table @code | |
503 | @item C-c C-q | |
504 | @kindex C-c C-q @r{(C mode)} | |
505 | @findex c-indent-defun | |
506 | Reindent the current top-level function definition or aggregate type | |
507 | declaration (@code{c-indent-defun}). | |
508 | ||
509 | @item C-M-q | |
510 | @kindex C-M-q @r{(C mode)} | |
511 | @findex c-indent-exp | |
512 | Reindent each line in the balanced expression that follows point | |
7ae8ad94 RS |
513 | (@code{c-indent-exp}). A prefix argument inhibits warning messages |
514 | about invalid syntax. | |
6bf7aab6 DL |
515 | |
516 | @item @key{TAB} | |
517 | @findex c-indent-command | |
518 | Reindent the current line, and/or in some cases insert a tab character | |
519 | (@code{c-indent-command}). | |
520 | ||
7ae8ad94 | 521 | @vindex c-tab-always-indent |
6bf7aab6 DL |
522 | If @code{c-tab-always-indent} is @code{t}, this command always reindents |
523 | the current line and does nothing else. This is the default. | |
524 | ||
525 | If that variable is @code{nil}, this command reindents the current line | |
526 | only if point is at the left margin or in the line's indentation; | |
527 | otherwise, it inserts a tab (or the equivalent number of spaces, | |
528 | if @code{indent-tabs-mode} is @code{nil}). | |
529 | ||
530 | Any other value (not @code{nil} or @code{t}) means always reindent the | |
7ae8ad94 | 531 | line, and also insert a tab if within a comment or a string. |
6bf7aab6 DL |
532 | @end table |
533 | ||
534 | To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This | |
535 | first selects the whole buffer as the region, then reindents that | |
536 | region. | |
537 | ||
538 | To reindent the current block, use @kbd{C-M-u C-M-q}. This moves | |
539 | to the front of the block and then reindents it all. | |
540 | ||
541 | @node Custom C Indent | |
542 | @subsection Customizing C Indentation | |
93da5dff | 543 | @cindex style (for indentation) |
6bf7aab6 | 544 | |
7ae8ad94 RS |
545 | C mode and related modes use a flexible mechanism for customizing |
546 | indentation. C mode indents a source line in two steps: first it | |
547 | classifies the line syntactically according to its contents and | |
548 | context; second, it determines the indentation offset associated by | |
549 | your selected @dfn{style} with the syntactic construct and adds this | |
550 | onto the indentation of the @dfn{anchor statement}. | |
6bf7aab6 | 551 | |
93da5dff | 552 | @table @kbd |
7ae8ad94 RS |
553 | @item C-c . @key{RET} @var{style} @key{RET} |
554 | Select a predefined style @var{style} (@code{c-set-style}). | |
93da5dff | 555 | @end table |
6bf7aab6 | 556 | |
108262a0 AM |
557 | A @dfn{style} is a named collection of customizations that can be |
558 | used in C mode and the related modes. @ref{Styles,,, ccmode, The CC | |
559 | Mode Manual}, for a complete description. Emacs comes with several | |
93da5dff RS |
560 | predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, |
561 | @code{stroustrup}, @code{linux}, @code{python}, @code{java}, | |
108262a0 AM |
562 | @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these |
563 | styles are primarily intended for one language, but any of them can be | |
564 | used with any of the languages supported by these modes. To find out | |
565 | what a style looks like, select it and reindent some code, e.g., by | |
566 | typing @key{C-M-q} at the start of a function definition. | |
6bf7aab6 | 567 | |
7ae8ad94 | 568 | @kindex C-c . @r{(C mode)} |
93da5dff | 569 | @findex c-set-style |
dfec8297 RS |
570 | To choose a style for the current buffer, use the command @w{@kbd{C-c |
571 | .}}. Specify a style name as an argument (case is not significant). | |
7ae8ad94 RS |
572 | This command affects the current buffer only, and it affects only |
573 | future invocations of the indentation commands; it does not reindent | |
108262a0 AM |
574 | the code already in the buffer. To reindent the whole buffer in the |
575 | new style, you can type @kbd{C-x h C-M-\}. | |
6bf7aab6 | 576 | |
93da5dff RS |
577 | @vindex c-default-style |
578 | You can also set the variable @code{c-default-style} to specify the | |
7ae8ad94 RS |
579 | default style for various major modes. Its value should be either the |
580 | style's name (a string) or an alist, in which each element specifies | |
581 | one major mode and which indentation style to use for it. For | |
582 | example, | |
6bf7aab6 DL |
583 | |
584 | @example | |
93da5dff | 585 | (setq c-default-style |
ae742cb5 CY |
586 | '((java-mode . "java") |
587 | (awk-mode . "awk") | |
588 | (other . "gnu"))) | |
6bf7aab6 DL |
589 | @end example |
590 | ||
93da5dff | 591 | @noindent |
108262a0 AM |
592 | specifies explicit choices for Java and AWK modes, and the default |
593 | @samp{gnu} style for the other C-like modes. (These settings are | |
594 | actually the defaults.) This variable takes effect when you select | |
595 | one of the C-like major modes; thus, if you specify a new default | |
596 | style for Java mode, you can make it take effect in an existing Java | |
597 | mode buffer by typing @kbd{M-x java-mode} there. | |
6bf7aab6 | 598 | |
93da5dff RS |
599 | The @code{gnu} style specifies the formatting recommended by the GNU |
600 | Project for C; it is the default, so as to encourage use of our | |
601 | recommended style. | |
6bf7aab6 | 602 | |
108262a0 AM |
603 | @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and |
604 | @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more | |
605 | information on customizing indentation for C and related modes, | |
93da5dff RS |
606 | including how to override parts of an existing style and how to define |
607 | your own styles. | |
6bf7aab6 | 608 | |
d3098e1e CY |
609 | @findex c-guess |
610 | @findex c-guess-install | |
611 | As an alternative to specifying a style, you can tell Emacs to guess | |
612 | a style by typing @kbd{M-x c-guess} in a sample code buffer. You can | |
613 | then apply the guessed style to other buffers with @kbd{M-x | |
47d42d81 | 614 | c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode |
d3098e1e | 615 | Manual}, for details. |
47d42d81 | 616 | |
93da5dff RS |
617 | @node Parentheses |
618 | @section Commands for Editing with Parentheses | |
6bf7aab6 | 619 | |
93da5dff RS |
620 | @findex check-parens |
621 | @cindex unbalanced parentheses and quotes | |
622 | This section describes the commands and features that take advantage | |
623 | of the parenthesis structure in a program, or help you keep it | |
624 | balanced. | |
6bf7aab6 | 625 | |
93da5dff RS |
626 | When talking about these facilities, the term ``parenthesis'' also |
627 | includes braces, brackets, or whatever delimiters are defined to match | |
e79c6b89 | 628 | in pairs. The major mode controls which delimiters are significant, |
6cfd0fa2 CY |
629 | through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp, |
630 | The Emacs Lisp Reference Manual}). In Lisp, only parentheses count; | |
631 | in C, these commands apply to braces and brackets too. | |
6bf7aab6 | 632 | |
93da5dff RS |
633 | You can use @kbd{M-x check-parens} to find any unbalanced |
634 | parentheses and unbalanced string quotes in the buffer. | |
6bf7aab6 | 635 | |
93da5dff RS |
636 | @menu |
637 | * Expressions:: Expressions with balanced parentheses. | |
638 | * Moving by Parens:: Commands for moving up, down and across | |
639 | in the structure of parentheses. | |
8838673e | 640 | * Matching:: Insertion of a close-delimiter flashes matching open. |
93da5dff | 641 | @end menu |
6bf7aab6 | 642 | |
93da5dff RS |
643 | @node Expressions |
644 | @subsection Expressions with Balanced Parentheses | |
6bf7aab6 | 645 | |
93da5dff RS |
646 | @cindex sexp |
647 | @cindex expression | |
648 | @cindex balanced expression | |
ec7ae032 CY |
649 | Each programming language mode has its own definition of a |
650 | @dfn{balanced expression}. Balanced expressions typically include | |
651 | individual symbols, numbers, and string constants, as well as pieces | |
652 | of code enclosed in a matching pair of delimiters. The following | |
653 | commands deal with balanced expressions (in Emacs, such expressions | |
654 | are referred to internally as @dfn{sexps}@footnote{The word ``sexp'' | |
655 | is used to refer to an expression in Lisp.}). | |
6bf7aab6 | 656 | |
93da5dff RS |
657 | @table @kbd |
658 | @item C-M-f | |
659 | Move forward over a balanced expression (@code{forward-sexp}). | |
660 | @item C-M-b | |
ea118de1 | 661 | Move backward over a balanced expression (@code{backward-sexp}). |
93da5dff RS |
662 | @item C-M-k |
663 | Kill balanced expression forward (@code{kill-sexp}). | |
93da5dff RS |
664 | @item C-M-t |
665 | Transpose expressions (@code{transpose-sexps}). | |
666 | @item C-M-@@ | |
649d1cbe | 667 | @itemx C-M-@key{SPC} |
93da5dff RS |
668 | Put mark after following expression (@code{mark-sexp}). |
669 | @end table | |
6bf7aab6 | 670 | |
93da5dff RS |
671 | @kindex C-M-f |
672 | @kindex C-M-b | |
673 | @findex forward-sexp | |
674 | @findex backward-sexp | |
675 | To move forward over a balanced expression, use @kbd{C-M-f} | |
676 | (@code{forward-sexp}). If the first significant character after point | |
ec7ae032 CY |
677 | is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C), |
678 | this command moves past the matching closing delimiter. If the | |
679 | character begins a symbol, string, or number, the command moves over | |
680 | that. | |
6bf7aab6 | 681 | |
93da5dff | 682 | The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a |
ec7ae032 CY |
683 | balanced expression---like @kbd{C-M-f}, but in the reverse direction. |
684 | If the expression is preceded by any prefix characters (single-quote, | |
685 | backquote and comma, in Lisp), the command moves back over them as | |
686 | well. | |
687 | ||
688 | @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation | |
689 | the specified number of times; with a negative argument means to move | |
690 | in the opposite direction. In most modes, these two commands move | |
691 | across comments as if they were whitespace. Note that their keys, | |
692 | @kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b}, | |
693 | which move by characters (@pxref{Moving Point}), and @kbd{M-f} and | |
694 | @kbd{M-b}, which move by words (@pxref{Words}). | |
6bf7aab6 | 695 | |
93da5dff RS |
696 | @cindex killing expressions |
697 | @kindex C-M-k | |
698 | @findex kill-sexp | |
ec7ae032 CY |
699 | To kill a whole balanced expression, type @kbd{C-M-k} |
700 | (@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move | |
701 | over. | |
6bf7aab6 | 702 | |
93da5dff RS |
703 | @cindex transposition of expressions |
704 | @kindex C-M-t | |
705 | @findex transpose-sexps | |
ec7ae032 CY |
706 | @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the |
707 | previous balanced expression and the next one. It is analogous to the | |
708 | @kbd{C-t} command, which transposes characters (@pxref{Transpose}). | |
709 | An argument to @kbd{C-M-t} serves as a repeat count, moving the | |
710 | previous expression over that many following ones. A negative | |
711 | argument moves the previous balanced expression backwards across those | |
712 | before it. An argument of zero, rather than doing nothing, transposes | |
713 | the balanced expressions ending at or after point and the mark. | |
6bf7aab6 | 714 | |
93da5dff | 715 | @kindex C-M-@@ |
649d1cbe | 716 | @kindex C-M-@key{SPC} |
93da5dff | 717 | @findex mark-sexp |
ec7ae032 CY |
718 | To operate on balanced expressions with a command which acts on the |
719 | region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the | |
720 | mark where @kbd{C-M-f} would move to. While the mark is active, each | |
721 | successive call to this command extends the region by shifting the | |
722 | mark by one expression. Positive or negative numeric arguments move | |
723 | the mark forward or backward by the specified number of expressions. | |
724 | The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}. | |
725 | @xref{Marking Objects}, for more information about this and related | |
726 | commands. | |
93da5dff RS |
727 | |
728 | In languages that use infix operators, such as C, it is not possible | |
ec7ae032 CY |
729 | to recognize all balanced expressions because there can be multiple |
730 | possibilities at a given position. For example, C mode does not treat | |
731 | @samp{foo + bar} as a single expression, even though it @emph{is} one | |
732 | C expression; instead, it recognizes @samp{foo} as one expression and | |
733 | @samp{bar} as another, with the @samp{+} as punctuation between them. | |
734 | However, C mode recognizes @samp{(foo + bar)} as a single expression, | |
735 | because of the parentheses. | |
93da5dff RS |
736 | |
737 | @node Moving by Parens | |
738 | @subsection Moving in the Parenthesis Structure | |
739 | ||
740 | @cindex parenthetical groupings | |
741 | @cindex parentheses, moving across | |
742 | @cindex matching parenthesis and braces, moving to | |
743 | @cindex braces, moving across | |
744 | @cindex list commands | |
3fbb05ff | 745 | |
ec7ae032 CY |
746 | The following commands move over groupings delimited by parentheses |
747 | (or whatever else serves as delimiters in the language you are working | |
748 | with). They ignore strings and comments, including any parentheses | |
749 | within them, and also ignore parentheses that are ``quoted'' with an | |
750 | escape character. These commands are mainly intended for editing | |
751 | programs, but can be useful for editing any text containing | |
752 | parentheses. They are referred to internally as ``list'' commands | |
753 | because in Lisp these groupings are lists. | |
6bf7aab6 | 754 | |
ec7ae032 CY |
755 | These commands assume that the starting point is not inside a string |
756 | or a comment. If you invoke them from inside a string or comment, the | |
757 | results are unreliable. | |
3fbb05ff | 758 | |
6bf7aab6 | 759 | @table @kbd |
93da5dff RS |
760 | @item C-M-n |
761 | Move forward over a parenthetical group (@code{forward-list}). | |
762 | @item C-M-p | |
ea118de1 | 763 | Move backward over a parenthetical group (@code{backward-list}). |
93da5dff RS |
764 | @item C-M-u |
765 | Move up in parenthesis structure (@code{backward-up-list}). | |
766 | @item C-M-d | |
767 | Move down in parenthesis structure (@code{down-list}). | |
6bf7aab6 DL |
768 | @end table |
769 | ||
93da5dff RS |
770 | @kindex C-M-n |
771 | @kindex C-M-p | |
772 | @findex forward-list | |
773 | @findex backward-list | |
774 | The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and | |
3fbb05ff AM |
775 | @kbd{C-M-p} (@code{backward-list}) move forward or backward over one |
776 | (or @var{n}) parenthetical groupings. | |
6bf7aab6 | 777 | |
93da5dff | 778 | @kindex C-M-u |
93da5dff | 779 | @findex backward-up-list |
93da5dff RS |
780 | @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the |
781 | parenthesis structure. To move @emph{up} one (or @var{n}) levels, use | |
782 | @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up | |
783 | past one unmatched opening delimiter. A positive argument serves as a | |
784 | repeat count; a negative argument reverses the direction of motion, so | |
d2fab838 | 785 | that the command moves forward and up one or more levels. |
93da5dff | 786 | |
dfec8297 RS |
787 | @kindex C-M-d |
788 | @findex down-list | |
93da5dff RS |
789 | To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} |
790 | (@code{down-list}). In Lisp mode, where @samp{(} is the only opening | |
791 | delimiter, this is nearly the same as searching for a @samp{(}. An | |
792 | argument specifies the number of levels to go down. | |
6bf7aab6 DL |
793 | |
794 | @node Matching | |
ec7ae032 | 795 | @subsection Matching Parentheses |
6bf7aab6 DL |
796 | @cindex matching parentheses |
797 | @cindex parentheses, displaying matches | |
798 | ||
ec7ae032 CY |
799 | Emacs has a number of @dfn{parenthesis matching} features, which |
800 | make it easy to see how and whether parentheses (or other delimiters) | |
801 | match up. | |
802 | ||
803 | Whenever you type a self-inserting character that is a closing | |
804 | delimiter, the cursor moves momentarily to the location of the | |
93da5dff | 805 | matching opening delimiter, provided that is on the screen. If it is |
e79c6b89 RS |
806 | not on the screen, Emacs displays some of the text near it in the echo |
807 | area. Either way, you can tell which grouping you are closing off. | |
ec7ae032 | 808 | If the opening delimiter and closing delimiter are mismatched---such |
93da5dff | 809 | as in @samp{[x)}---a warning message is displayed in the echo area. |
6bf7aab6 DL |
810 | |
811 | @vindex blink-matching-paren | |
812 | @vindex blink-matching-paren-distance | |
813 | @vindex blink-matching-delay | |
ec7ae032 | 814 | Three variables control the display of matching parentheses: |
054af0fd | 815 | |
ec7ae032 CY |
816 | @itemize @bullet |
817 | @item | |
818 | @code{blink-matching-paren} turns the feature on or off: @code{nil} | |
819 | disables it, but the default is @code{t} to enable it. | |
f772775c | 820 | |
ec7ae032 CY |
821 | @item |
822 | @code{blink-matching-delay} says how many seconds to leave the cursor | |
823 | on the matching opening delimiter, before bringing it back to the real | |
824 | location of point. This may be an integer or floating-point number; | |
825 | the default is 1. | |
f772775c | 826 | |
ec7ae032 CY |
827 | @item |
828 | @code{blink-matching-paren-distance} specifies how many characters | |
f772775c | 829 | back to search to find the matching opening delimiter. If the match |
ec7ae032 CY |
830 | is not found in that distance, Emacs stops scanning and nothing is |
831 | displayed. The default is 102400. | |
832 | @end itemize | |
6bf7aab6 DL |
833 | |
834 | @cindex Show Paren mode | |
79f9f655 | 835 | @cindex highlighting matching parentheses |
6bf7aab6 | 836 | @findex show-paren-mode |
ec7ae032 CY |
837 | Show Paren mode, a global minor mode, provides a more powerful kind |
838 | of automatic matching. Whenever point is before an opening delimiter | |
839 | or after a closing delimiter, both that delimiter and its opposite | |
840 | delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x | |
841 | show-paren-mode}. | |
842 | ||
843 | @cindex Electric Pair mode | |
844 | @cindex inserting matching parentheses | |
845 | @findex electric-pair-mode | |
846 | Electric Pair mode, a global minor mode, provides a way to easily | |
847 | insert matching delimiters. Whenever you insert an opening delimiter, | |
848 | the matching closing delimiter is automatically inserted as well, | |
849 | leaving point between the two. To toggle Electric Pair mode, type | |
850 | @kbd{M-x electric-pair-mode}. | |
6bf7aab6 DL |
851 | |
852 | @node Comments | |
853 | @section Manipulating Comments | |
854 | @cindex comments | |
855 | ||
856 | Because comments are such an important part of programming, Emacs | |
8f50b630 RS |
857 | provides special commands for editing and inserting comments. It can |
858 | also do spell checking on comments with Flyspell Prog mode | |
859 | (@pxref{Spelling}). | |
6bf7aab6 | 860 | |
ebf10822 CY |
861 | Some major modes have special rules for indenting different kinds of |
862 | comments. For example, in Lisp code, comments starting with two | |
863 | semicolons are indented as if they were lines of code, while those | |
864 | starting with three semicolons are supposed to be aligned to the left | |
865 | margin and are often used for sectioning purposes. Emacs understand | |
866 | these conventions; for instance, typing @key{TAB} on a comment line | |
867 | will indent the comment to the appropriate position. | |
868 | ||
869 | @example | |
870 | ;; This function is just an example. | |
871 | ;;; Here either two or three semicolons are appropriate. | |
872 | (defun foo (x) | |
873 | ;;; And now, the first part of the function: | |
874 | ;; The following line adds one. | |
875 | (1+ x)) ; This line adds one. | |
876 | @end example | |
877 | ||
6bf7aab6 | 878 | @menu |
5b31640c | 879 | * Comment Commands:: Inserting, killing, and aligning comments. |
93da5dff RS |
880 | * Multi-Line Comments:: Commands for adding and editing multi-line comments. |
881 | * Options for Comments::Customizing the comment features. | |
6bf7aab6 DL |
882 | @end menu |
883 | ||
884 | @node Comment Commands | |
885 | @subsection Comment Commands | |
6bf7aab6 | 886 | @cindex indentation for comments |
5b31640c | 887 | @cindex alignment for comments |
6bf7aab6 | 888 | |
ebf10822 | 889 | The following commands operate on comments: |
6bf7aab6 | 890 | |
7ae8ad94 RS |
891 | @table @asis |
892 | @item @kbd{M-;} | |
ebf10822 CY |
893 | Insert or realign comment on current line; if the region is active, |
894 | comment or uncomment the region instead (@code{comment-dwim}). | |
7ae8ad94 | 895 | @item @kbd{C-u M-;} |
9234c238 | 896 | Kill comment on current line (@code{comment-kill}). |
7ae8ad94 | 897 | @item @kbd{C-x ;} |
47c1b5f4 | 898 | Set comment column (@code{comment-set-column}). |
7ae8ad94 RS |
899 | @item @kbd{C-M-j} |
900 | @itemx @kbd{M-j} | |
6bf7aab6 | 901 | Like @key{RET} followed by inserting and aligning a comment |
108262a0 | 902 | (@code{comment-indent-new-line}). @xref{Multi-Line Comments}. |
7ae8ad94 RS |
903 | @item @kbd{M-x comment-region} |
904 | @itemx @kbd{C-c C-c} (in C-like modes) | |
ebf10822 | 905 | Add comment delimiters to all the lines in the region. |
6bf7aab6 DL |
906 | @end table |
907 | ||
9234c238 RS |
908 | @kindex M-; |
909 | @findex comment-dwim | |
910 | The command to create or align a comment is @kbd{M-;} | |
911 | (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What | |
912 | I Mean''; it indicates that this command can be used for many | |
913 | different jobs relating to comments, depending on the situation where | |
914 | you use it. | |
915 | ||
ebf10822 CY |
916 | When a region is active (@pxref{Mark}), @kbd{M-;} either adds |
917 | comment delimiters to the region, or removes them. If every line in | |
918 | the region is already a comment, it ``uncomments'' each of those lines | |
919 | by removing their comment delimiters. Otherwise, it adds comment | |
920 | delimiters to enclose the text in the region. | |
921 | ||
922 | If you supply a prefix argument to @kbd{M-;} when a region is | |
923 | active, that specifies the number of comment delimiters to add or | |
924 | delete. A positive argument @var{n} adds @var{n} delimiters, while a | |
925 | negative argument @var{-n} removes @var{n} delimiters. | |
926 | ||
927 | If the region is not active, and there is no existing comment on the | |
928 | current line, @kbd{M-;} adds a new comment to the current line. If | |
929 | the line is blank (i.e.@: empty or containing only whitespace | |
930 | characters), the comment is indented to the same position where | |
931 | @key{TAB} would indent to (@pxref{Basic Indent}). If the line is | |
932 | non-blank, the comment is placed after the last non-whitespace | |
933 | character on the line; normally, Emacs tries putting it at the column | |
934 | specified by the variable @code{comment-column} (@pxref{Options for | |
935 | Comments}), but if the line already extends past that column, it puts | |
936 | the comment at some suitable position, usually separated from the | |
937 | non-comment text by at least one space. In each case, Emacs places | |
938 | point after the comment's starting delimiter, so that you can start | |
939 | typing the comment text right away. | |
9234c238 RS |
940 | |
941 | You can also use @kbd{M-;} to align an existing comment. If a line | |
5b31640c | 942 | already contains the comment-start string, @kbd{M-;} realigns it to |
ebf10822 CY |
943 | the conventional alignment and moves point after the comment's |
944 | starting delimiter. As an exception, comments starting in column 0 | |
945 | are not moved. Even when an existing comment is properly aligned, | |
946 | @kbd{M-;} is still useful for moving directly to the start of the | |
947 | comment text. | |
9234c238 RS |
948 | |
949 | @findex comment-kill | |
950 | @kindex C-u M-; | |
ebf10822 CY |
951 | @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any |
952 | comment on the current line, along with the whitespace before it. | |
953 | Since the comment is saved to the kill ring, you can reinsert it on | |
954 | another line by moving to the end of that line, doing @kbd{C-y}, and | |
01ec1eed | 955 | then @kbd{M-;} to realign the comment. You can achieve the same |
ebf10822 CY |
956 | effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill} |
957 | (@code{comment-dwim} actually calls @code{comment-kill} as a | |
958 | subroutine when it is given a prefix argument). | |
6bf7aab6 | 959 | |
ebf10822 CY |
960 | @kindex C-c C-c (C mode) |
961 | @findex comment-region | |
962 | @findex uncomment-region | |
963 | The command @kbd{M-x comment-region} is equivalent to calling | |
964 | @kbd{M-;} on an active region, except that it always acts on the | |
965 | region, even if the mark is inactive. In C mode and related modes, | |
966 | this command is bound to @kbd{C-c C-c}. The command @kbd{M-x | |
967 | uncomment-region} uncomments each line in the region; a numeric prefix | |
968 | argument specifies the number of comment delimiters to remove | |
969 | (negative arguments specify the number of comment to delimiters to | |
970 | add). | |
6bf7aab6 | 971 | |
e722aa81 CY |
972 | For C-like modes, you can configure the exact effect of @kbd{M-;} by |
973 | setting the variables @code{c-indent-comment-alist} and | |
108262a0 AM |
974 | @code{c-indent-comments-syntactically-p}. For example, on a line |
975 | ending in a closing brace, @kbd{M-;} puts the comment one space after | |
976 | the brace rather than at @code{comment-column}. For full details see | |
e722aa81 | 977 | @ref{Comment Commands,,, ccmode, The CC Mode Manual}. |
6bf7aab6 | 978 | |
6bf7aab6 DL |
979 | @node Multi-Line Comments |
980 | @subsection Multiple Lines of Comments | |
981 | ||
982 | @kindex C-M-j | |
7ae8ad94 | 983 | @kindex M-j |
6bf7aab6 | 984 | @cindex blank lines in programs |
47c1b5f4 | 985 | @findex comment-indent-new-line |
ebf10822 CY |
986 | @vindex comment-multi-line |
987 | If you are typing a comment and wish to continue it to another line, | |
988 | type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This | |
989 | breaks the current line, and inserts the necessary comment delimiters | |
990 | and indentation to continue the comment. | |
991 | ||
992 | For languages with closing comment delimiters (e.g.@: @samp{*/} in | |
993 | C), the exact behavior of @kbd{M-j} depends on the value of the | |
994 | variable @code{comment-multi-line}. If the value is @code{nil}, the | |
995 | command closes the comment on the old line and starts a new comment on | |
996 | the new line. Otherwise, it opens a new line within the current | |
997 | comment delimiters. | |
998 | ||
999 | When Auto Fill mode is on, going past the fill column while typing a | |
1000 | comment also continues the comment, in the same way as an explicit | |
1001 | invocation of @kbd{M-j}. | |
1002 | ||
1003 | To turn existing lines into comment lines, use @kbd{M-;} with the | |
1004 | region active, or use @kbd{M-x comment-region} | |
1005 | @ifinfo | |
1006 | (@pxref{Comment Commands}). | |
1007 | @end ifinfo | |
1008 | @ifnotinfo | |
1009 | as described in the preceding section. | |
1010 | @end ifnotinfo | |
6bf7aab6 | 1011 | |
108262a0 AM |
1012 | You can configure C Mode such that when you type a @samp{/} at the |
1013 | start of a line in a multi-line block comment, this closes the | |
1014 | comment. Enable the @code{comment-close-slash} clean-up for this. | |
1015 | @xref{Clean-ups,,, ccmode, The CC Mode Manual}. | |
1016 | ||
6bf7aab6 DL |
1017 | @node Options for Comments |
1018 | @subsection Options Controlling Comments | |
1019 | ||
1020 | @vindex comment-column | |
1021 | @kindex C-x ; | |
47c1b5f4 | 1022 | @findex comment-set-column |
ebf10822 CY |
1023 | As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command |
1024 | adds a comment to a line, it tries to place the comment at the column | |
1025 | specified by the buffer-local variable @code{comment-column}. You can | |
1026 | set either the local value or the default value of this buffer-local | |
1027 | variable in the usual way (@pxref{Locals}). Alternatively, you can | |
1028 | type @kbd{C-x ;} (@code{comment-set-column}) to set the value of | |
1029 | @code{comment-column} in the current buffer to the column where point | |
1030 | is currently located. @kbd{C-u C-x ;} sets the comment column to | |
1031 | match the last comment before point in the buffer, and then does a | |
1032 | @kbd{M-;} to align the current line's comment under the previous one. | |
6bf7aab6 DL |
1033 | |
1034 | @vindex comment-start-skip | |
1035 | The comment commands recognize comments based on the regular | |
1036 | expression that is the value of the variable @code{comment-start-skip}. | |
1037 | Make sure this regexp does not match the null string. It may match more | |
1038 | than the comment starting delimiter in the strictest sense of the word; | |
47c1b5f4 RS |
1039 | for example, in C mode the value of the variable is |
1040 | @c This stops M-q from breaking the line inside that @code. | |
ebf10822 CY |
1041 | @code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and |
1042 | spaces after the @samp{/*} itself, and accepts C++ style comments | |
1043 | also. (Note that @samp{\\} is needed in Lisp syntax to include a | |
1044 | @samp{\} in the string, which is needed to deny the first star its | |
1045 | special meaning in regexp syntax. @xref{Regexp Backslash}.) | |
6bf7aab6 DL |
1046 | |
1047 | @vindex comment-start | |
1048 | @vindex comment-end | |
1049 | When a comment command makes a new comment, it inserts the value of | |
ebf10822 CY |
1050 | @code{comment-start} as an opening comment delimiter. It also inserts |
1051 | the value of @code{comment-end} after point, as a closing comment | |
1052 | delimiter. For example, in Lisp mode, @code{comment-start} is | |
1053 | @samp{";"} and @code{comment-end} is @code{""} (the empty string). In | |
1054 | C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is | |
1055 | @code{" */"}. | |
6bf7aab6 | 1056 | |
9234c238 | 1057 | @vindex comment-padding |
ebf10822 CY |
1058 | The variable @code{comment-padding} specifies a string that the |
1059 | commenting commands should insert between the comment delimiter(s) and | |
1060 | the comment text. The default, @samp{" "}, specifies a single space. | |
1061 | Alternatively, the value can be a number, which specifies that number | |
1062 | of spaces, or @code{nil}, which means no spaces at all. | |
1063 | ||
1064 | The variable @code{comment-multi-line} controls how @kbd{M-j} and | |
1065 | Auto Fill mode continue comments over multiple lines. | |
1066 | @xref{Multi-Line Comments}. | |
6bf7aab6 | 1067 | |
4190ce5c | 1068 | @vindex comment-indent-function |
6bf7aab6 | 1069 | The variable @code{comment-indent-function} should contain a function |
5b31640c | 1070 | that will be called to compute the alignment for a newly inserted |
6bf7aab6 DL |
1071 | comment or for aligning an existing comment. It is set differently by |
1072 | various major modes. The function is called with no arguments, but with | |
1073 | point at the beginning of the comment, or at the end of a line if a new | |
1074 | comment is to be inserted. It should return the column in which the | |
1075 | comment ought to start. For example, in Lisp mode, the indent hook | |
1076 | function bases its decision on how many semicolons begin an existing | |
1077 | comment, and on the code in the preceding lines. | |
1078 | ||
93da5dff RS |
1079 | @node Documentation |
1080 | @section Documentation Lookup | |
6bf7aab6 | 1081 | |
93da5dff RS |
1082 | Emacs provides several features you can use to look up the |
1083 | documentation of functions, variables and commands that you plan to | |
1084 | use in your program. | |
6bf7aab6 | 1085 | |
93da5dff | 1086 | @menu |
2d2f6581 | 1087 | * Info Lookup:: Looking up library functions and commands in Info files. |
93da5dff RS |
1088 | * Man Page:: Looking up man pages of library functions and commands. |
1089 | * Lisp Doc:: Looking up Emacs Lisp functions, etc. | |
1090 | @end menu | |
6bf7aab6 | 1091 | |
93da5dff RS |
1092 | @node Info Lookup |
1093 | @subsection Info Documentation Lookup | |
85750656 | 1094 | |
93da5dff RS |
1095 | @findex info-lookup-symbol |
1096 | @findex info-lookup-file | |
d2f9ea87 | 1097 | @kindex C-h S |
e722aa81 CY |
1098 | For major modes that apply to languages which have documentation in |
1099 | Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the | |
1100 | Info documentation for a symbol used in the program. You specify the | |
1101 | symbol with the minibuffer; the default is the symbol appearing in the | |
1102 | buffer at point. For example, in C mode this looks for the symbol in | |
1103 | the C Library Manual. The command only works if the appropriate | |
1104 | manual's Info files are installed. | |
6bf7aab6 | 1105 | |
93da5dff RS |
1106 | The major mode determines where to look for documentation for the |
1107 | symbol---which Info files to look in, and which indices to search. | |
1108 | You can also use @kbd{M-x info-lookup-file} to look for documentation | |
1109 | for a file name. | |
6bf7aab6 | 1110 | |
dfec8297 | 1111 | If you use @kbd{C-h S} in a major mode that does not support it, |
16152b76 | 1112 | it asks you to specify the ``symbol help mode''. You should enter |
dfec8297 RS |
1113 | a command such as @code{c-mode} that would select a major |
1114 | mode which @kbd{C-h S} does support. | |
6bf7aab6 | 1115 | |
93da5dff RS |
1116 | @node Man Page |
1117 | @subsection Man Page Lookup | |
6bf7aab6 | 1118 | |
2a185919 | 1119 | @cindex man page |
e79c6b89 | 1120 | On Unix, the main form of on-line documentation was the @dfn{manual |
dfec8297 | 1121 | page} or @dfn{man page}. In the GNU operating system, we aim to |
e79c6b89 RS |
1122 | replace man pages with better-organized manuals that you can browse |
1123 | with Info (@pxref{Misc Help}). This process is not finished, so it is | |
1124 | still useful to read manual pages. | |
6bf7aab6 | 1125 | |
93da5dff | 1126 | @findex manual-entry |
e79c6b89 | 1127 | You can read the man page for an operating system command, library |
2a185919 CY |
1128 | function, or system call, with the @kbd{M-x man} command. This |
1129 | prompts for a topic, with completion (@pxref{Completion}), and runs | |
1130 | the @command{man} program to format the corresponding man page. If | |
1131 | the system permits, it runs @command{man} asynchronously, so that you | |
1132 | can keep on editing while the page is being formatted. The result | |
1c64e6ed | 1133 | goes in a buffer named @file{*Man @var{topic}*}. These buffers use a |
2a185919 CY |
1134 | special major mode, Man mode, that facilitates scrolling and jumping |
1135 | to other manual pages. For details, type @kbd{C-h m} while in a Man | |
1136 | mode buffer. | |
6bf7aab6 | 1137 | |
93da5dff | 1138 | @cindex sections of manual pages |
e79c6b89 | 1139 | Each man page belongs to one of ten or more @dfn{sections}, each |
2a185919 CY |
1140 | named by a digit or by a digit and a letter. Sometimes there are man |
1141 | pages with the same name in different sections. To read a man page | |
1142 | from a specific section, type @samp{@var{topic}(@var{section})} or | |
1143 | @samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts | |
1144 | for the topic. For example, the man page for the C library function | |
1145 | @code{chmod} is in section 2, but there is a shell command of the same | |
1146 | name, whose man page is in section 1; to view the former, type | |
1147 | @kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}. | |
6bf7aab6 | 1148 | |
08220274 | 1149 | @vindex Man-switches |
2a185919 CY |
1150 | @kindex M-n @r{(Man mode)} |
1151 | @kindex M-p @r{(Man mode)} | |
1152 | If you do not specify a section, @kbd{M-x man} normally displays | |
1153 | only the first man page found. On some systems, the @code{man} | |
1154 | program accepts a @samp{-a} command-line option, which tells it to | |
1155 | display all the man pages for the specified topic. To make use of | |
1156 | this, change the value of the variable @code{Man-switches} to | |
1157 | @samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and | |
1158 | @kbd{M-p} to switch between man pages in different sections. The mode | |
1159 | line shows how many manual pages are available. | |
93da5dff RS |
1160 | |
1161 | @findex woman | |
1162 | @cindex manual pages, on MS-DOS/MS-Windows | |
1163 | An alternative way of reading manual pages is the @kbd{M-x woman} | |
2a185919 CY |
1164 | command. Unlike @kbd{M-x man}, it does not run any external programs |
1165 | to format and display the man pages; the formatting is done by Emacs, | |
1166 | so it works on systems such as MS-Windows where the @command{man} | |
1167 | program may be unavailable. It prompts for a man page, and displays | |
1c64e6ed | 1168 | it in a buffer named @file{*WoMan @var{section} @var{topic}}. |
2a185919 CY |
1169 | |
1170 | @kbd{M-x woman} computes the completion list for manpages the first | |
1171 | time you invoke the command. With a numeric argument, it recomputes | |
1172 | this list; this is useful if you add or delete manual pages. | |
93da5dff RS |
1173 | |
1174 | If you type a name of a manual page and @kbd{M-x woman} finds that | |
1175 | several manual pages by the same name exist in different sections, it | |
1176 | pops up a window with possible candidates asking you to choose one of | |
1177 | them. | |
1178 | ||
93da5dff | 1179 | For more information about setting up and using @kbd{M-x woman}, see |
ec7ae032 CY |
1180 | @ifinfo |
1181 | @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The | |
1182 | WoMan Manual}. | |
1183 | @end ifinfo | |
1184 | @ifnotinfo | |
1185 | the WoMan Info manual, which is distributed with Emacs. | |
1186 | @end ifnotinfo | |
93da5dff RS |
1187 | |
1188 | @node Lisp Doc | |
1189 | @subsection Emacs Lisp Documentation Lookup | |
1190 | ||
2a185919 CY |
1191 | When editing Emacs Lisp code, you can use the commands @kbd{C-h f} |
1192 | (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) | |
1193 | to view the built-in documentation for the Lisp functions and | |
1194 | variables that you want to use. @xref{Name Help}. | |
93da5dff RS |
1195 | |
1196 | @cindex Eldoc mode | |
1197 | @findex eldoc-mode | |
2a185919 CY |
1198 | Eldoc is a buffer-local minor mode that helps with looking up Lisp |
1199 | documention. When it is enabled, the echo area displays some useful | |
1200 | information whenever there is a Lisp function or variable at point; | |
1201 | for a function, it shows the argument list, and for a variable it | |
1202 | shows the first line of the variable's documentation string. To | |
1203 | toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used | |
1204 | with the Emacs Lisp and Lisp Interaction major modes. | |
6bf7aab6 | 1205 | |
51ed0ea0 DL |
1206 | @node Hideshow |
1207 | @section Hideshow minor mode | |
2a185919 CY |
1208 | @cindex Hideshow mode |
1209 | @cindex mode, Hideshow | |
51ed0ea0 DL |
1210 | |
1211 | @findex hs-minor-mode | |
2a185919 CY |
1212 | Hideshow mode is a buffer-local minor mode that allows you to |
1213 | selectively display portions of a program, which are referred to as | |
1214 | @dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode | |
1215 | (@pxref{Minor Modes}). | |
1216 | ||
1217 | When you use Hideshow mode to hide a block, the block disappears | |
1218 | from the screen, to be replaced by an ellipsis (three periods in a | |
1219 | row). Just what constitutes a block depends on the major mode. In C | |
1220 | mode and related modes, blocks are delimited by braces, while in Lisp | |
1221 | mode they are delimited by parentheses. Multi-line comments also | |
1222 | count as blocks. | |
51ed0ea0 | 1223 | |
2a185919 | 1224 | Hideshow mode provides the following commands: |
51ed0ea0 DL |
1225 | |
1226 | @findex hs-hide-all | |
1227 | @findex hs-hide-block | |
1228 | @findex hs-show-all | |
1229 | @findex hs-show-block | |
1230 | @findex hs-show-region | |
1231 | @findex hs-hide-level | |
1232 | @findex hs-minor-mode | |
6401dc86 EZ |
1233 | @kindex C-c @@ C-h |
1234 | @kindex C-c @@ C-s | |
1235 | @kindex C-c @@ C-M-h | |
1236 | @kindex C-c @@ C-M-s | |
1237 | @kindex C-c @@ C-r | |
1238 | @kindex C-c @@ C-l | |
9234c238 RS |
1239 | @kindex S-Mouse-2 |
1240 | @table @kbd | |
6401dc86 | 1241 | @item C-c @@ C-h |
9234c238 | 1242 | Hide the current block (@code{hs-hide-block}). |
6401dc86 | 1243 | @item C-c @@ C-s |
9234c238 | 1244 | Show the current block (@code{hs-show-block}). |
6401dc86 | 1245 | @item C-c @@ C-c |
ea118de1 | 1246 | Either hide or show the current block (@code{hs-toggle-hiding}). |
9234c238 | 1247 | @item S-Mouse-2 |
2a185919 | 1248 | Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}). |
6401dc86 | 1249 | @item C-c @@ C-M-h |
9234c238 | 1250 | Hide all top-level blocks (@code{hs-hide-all}). |
6401dc86 | 1251 | @item C-c @@ C-M-s |
2a185919 | 1252 | Show all blocks in the buffer (@code{hs-show-all}). |
6401dc86 | 1253 | @item C-c @@ C-l |
9234c238 RS |
1254 | Hide all blocks @var{n} levels below this block |
1255 | (@code{hs-hide-level}). | |
1256 | @end table | |
51ed0ea0 DL |
1257 | |
1258 | @vindex hs-hide-comments-when-hiding-all | |
51ed0ea0 DL |
1259 | @vindex hs-isearch-open |
1260 | @vindex hs-special-modes-alist | |
2a185919 | 1261 | These variables can be used to customize Hideshow mode: |
9234c238 | 1262 | |
51ed0ea0 DL |
1263 | @table @code |
1264 | @item hs-hide-comments-when-hiding-all | |
2a185919 CY |
1265 | If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides |
1266 | comments too. | |
d2fab838 | 1267 | |
51ed0ea0 | 1268 | @item hs-isearch-open |
2a185919 CY |
1269 | This variable specifies the conditions under which incremental search |
1270 | should unhide a hidden block when matching text occurs within the | |
1271 | block. Its value should be either @code{code} (unhide only code | |
1272 | blocks), @code{comment} (unhide only comments), @code{t} (unhide both | |
1273 | code blocks and comments), or @code{nil} (unhide neither code blocks | |
1274 | nor comments). The default value is @code{code}. | |
51ed0ea0 DL |
1275 | @end table |
1276 | ||
93da5dff RS |
1277 | @node Symbol Completion |
1278 | @section Completion for Symbol Names | |
1279 | @cindex completion (symbol names) | |
3b8b8888 | 1280 | |
2a185919 CY |
1281 | Completion is normally done in the minibuffer (@pxref{Completion}), |
1282 | but you can also complete symbol names in ordinary Emacs buffers. | |
3b8b8888 | 1283 | |
93da5dff | 1284 | @kindex M-TAB |
2a185919 CY |
1285 | @kindex C-M-i |
1286 | In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}} | |
1287 | to complete the partial symbol before point. On graphical displays, | |
1288 | the @kbd{M-@key{TAB}} key is usually reserved by the window manager | |
1289 | for switching graphical windows, so you should type @kbd{C-M-i} or | |
1290 | @kbd{@key{ESC} @key{TAB}} instead. | |
6bf7aab6 | 1291 | |
93da5dff | 1292 | @cindex tags-based completion |
3d992aa0 | 1293 | @findex completion-at-point |
93da5dff RS |
1294 | @cindex Lisp symbol completion |
1295 | @cindex completion (Lisp symbols) | |
3d992aa0 CY |
1296 | In most programming language modes, @kbd{C-M-i} (or |
1297 | @kbd{M-@key{TAB}}) invokes the command @code{completion-at-point}, | |
1298 | which generates its completion list in a flexible way. If Semantic | |
1299 | mode is enabled, it tries to use the Semantic parser data for | |
1300 | completion (@pxref{Semantic}). If Semantic mode is not enabled or | |
1301 | fails at performing completion, it tries to complete using the | |
1302 | selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it | |
1303 | performs completion using the function, variable, or property names | |
1304 | defined in the current Emacs session. | |
2a185919 CY |
1305 | |
1306 | In all other respects, in-buffer symbol completion behaves like | |
1307 | minibuffer completion. For instance, if Emacs cannot complete to a | |
1308 | unique symbol, it displays a list of completion alternatives in | |
1309 | another window. @xref{Completion}. | |
6bf7aab6 | 1310 | |
93da5dff RS |
1311 | In Text mode and related modes, @kbd{M-@key{TAB}} completes words |
1312 | based on the spell-checker's dictionary. @xref{Spelling}. | |
6bf7aab6 | 1313 | |
93da5dff RS |
1314 | @node Glasses |
1315 | @section Glasses minor mode | |
1316 | @cindex Glasses mode | |
2a185919 CY |
1317 | @cindex camel case |
1318 | @findex mode, Glasses | |
1319 | ||
1320 | Glasses mode is a buffer-local minor mode that makes it easier to | |
1321 | read mixed-case (or ``CamelCase'') symbols like | |
1322 | @samp{unReadableSymbol}, by altering how they are displayed. By | |
1323 | default, it displays extra underscores between each lower-case letter | |
1324 | and the following capital letter. This does not alter the buffer | |
1325 | text, only how it is displayed. | |
1326 | ||
1327 | To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor | |
1328 | Modes}). When Glasses mode is enabled, the minor mode indicator | |
1329 | @samp{o^o} appears in the mode line. For more information about | |
1330 | Glasses mode, type @kbd{C-h P glasses @key{RET}}. | |
6bf7aab6 | 1331 | |
a42dbee1 CY |
1332 | @node Semantic |
1333 | @section Semantic | |
1334 | @cindex Semantic package | |
1335 | ||
1336 | Semantic is a package that provides language-aware editing commands | |
1337 | based on @code{source code parsers}. This section provides a brief | |
ec7ae032 | 1338 | description of Semantic; for full details, |
a42dbee1 | 1339 | @ifnottex |
ec7ae032 | 1340 | see @ref{Top, Semantic,, semantic, Semantic}. |
a42dbee1 CY |
1341 | @end ifnottex |
1342 | @iftex | |
ec7ae032 | 1343 | see the Semantic Info manual, which is distributed with Emacs. |
a42dbee1 CY |
1344 | @end iftex |
1345 | ||
2a185919 CY |
1346 | Most of the ``language aware'' features in Emacs, such as Font Lock |
1347 | mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular | |
a42dbee1 CY |
1348 | expressions and syntax tables.} that usually give good results but are |
1349 | never completely exact. In contrast, the parsers used by Semantic | |
1350 | have an exact understanding of programming language syntax. This | |
1351 | allows Semantic to provide search, navigation, and completion commands | |
1352 | that are powerful and precise. | |
1353 | ||
b09d01da CY |
1354 | @cindex Semantic mode |
1355 | @cindex mode, Semantic | |
a42dbee1 CY |
1356 | To begin using Semantic, type @kbd{M-x semantic-mode} or click on |
1357 | the menu item named @samp{Source Code Parsers (Semantic)} in the | |
1358 | @samp{Tools} menu. This enables Semantic mode, a global minor mode. | |
1359 | ||
1360 | When Semantic mode is enabled, Emacs automatically attempts to | |
1361 | parses each file you visit. Currently, Semantic understands C, C++, | |
1362 | Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer, | |
1363 | the following commands are available: | |
1364 | ||
1365 | @table @kbd | |
1366 | @item C-c , j | |
1367 | @kindex C-c , j | |
1368 | Prompt for the name of a function defined in the current file, and | |
1369 | move point there (@code{semantic-complete-jump-local}). | |
1370 | ||
1371 | @item C-c , J | |
1372 | @kindex C-c , J | |
1373 | Prompt for the name of a function defined in any file Emacs has | |
1374 | parsed, and move point there (@code{semantic-complete-jump}). | |
1375 | ||
1376 | @item C-c , @key{SPC} | |
1377 | @kindex C-c , @key{SPC} | |
1378 | Display a list of possible completions for the symbol at point | |
1379 | (@code{semantic-complete-analyze-inline}). This also activates a set | |
e7a3ff06 | 1380 | of special key bindings for choosing a completion: @key{RET} accepts |
a42dbee1 CY |
1381 | the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible |
1382 | completions, @key{TAB} completes as far as possible and then cycles, | |
1383 | and @kbd{C-g} or any other key aborts completion. | |
1384 | ||
1385 | @item C-c , l | |
1386 | @kindex C-c , l | |
1387 | Display a list of the possible completions of the symbol at point, in | |
1388 | another window (@code{semantic-analyze-possible-completions}). | |
1389 | @end table | |
1390 | ||
1391 | @noindent | |
1392 | In addition to the above commands, the Semantic package provides a | |
1393 | variety of other ways to make use of parser information. For | |
1394 | instance, you can use it to display a list of completions when Emacs | |
1395 | is idle. | |
1396 | @ifnottex | |
1397 | @xref{Top, Semantic,, semantic, Semantic}, for details. | |
1398 | @end ifnottex | |
1399 | ||
93da5dff RS |
1400 | @node Misc for Programs |
1401 | @section Other Features Useful for Editing Programs | |
6bf7aab6 | 1402 | |
2a185919 CY |
1403 | Some Emacs commands that aren't designed specifically for editing |
1404 | programs are useful for that nonetheless. | |
6bf7aab6 | 1405 | |
93da5dff RS |
1406 | The Emacs commands that operate on words, sentences and paragraphs |
1407 | are useful for editing code. Most symbols names contain words | |
2a185919 CY |
1408 | (@pxref{Words}), while sentences can be found in strings and comments |
1409 | (@pxref{Sentences}). As for paragraphs, they are defined in most | |
1410 | programming language modes to begin and end at blank lines | |
1411 | (@pxref{Paragraphs}). Therefore, judicious use of blank lines to make | |
1412 | the program clearer will also provide useful chunks of text for the | |
1413 | paragraph commands to work on. Auto Fill mode, if enabled in a | |
1414 | programming language major mode, indents the new lines which it | |
1415 | creates. | |
1416 | ||
0aca1292 GM |
1417 | @findex electric-layout-mode |
1418 | Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global | |
1419 | minor mode that automatically inserts newlines when you type certain | |
1420 | characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript | |
1421 | mode. | |
1422 | ||
2a185919 CY |
1423 | Apart from Hideshow mode (@pxref{Hideshow}), another way to |
1424 | selectively display parts of a program is to use the selective display | |
1425 | feature (@pxref{Selective Display}). Programming modes often also | |
1426 | support Outline minor mode (@pxref{Outline Mode}), which can be used | |
1427 | with the Foldout package (@pxref{Foldout}). | |
6bf7aab6 | 1428 | |
ec7ae032 | 1429 | @ifinfo |
93da5dff RS |
1430 | The ``automatic typing'' features may be useful for writing programs. |
1431 | @xref{Top,,Autotyping, autotype, Autotyping}. | |
ec7ae032 | 1432 | @end ifinfo |
6bf7aab6 DL |
1433 | |
1434 | @node C Modes | |
1435 | @section C and Related Modes | |
1436 | @cindex C mode | |
1437 | @cindex Java mode | |
1438 | @cindex Pike mode | |
1439 | @cindex IDL mode | |
1440 | @cindex CORBA IDL mode | |
1441 | @cindex Objective C mode | |
1442 | @cindex C++ mode | |
7ae8ad94 | 1443 | @cindex AWK mode |
6bf7aab6 DL |
1444 | @cindex mode, Java |
1445 | @cindex mode, C | |
7ae8ad94 | 1446 | @cindex mode, C++ |
6bf7aab6 DL |
1447 | @cindex mode, Objective C |
1448 | @cindex mode, CORBA IDL | |
1449 | @cindex mode, Pike | |
7ae8ad94 | 1450 | @cindex mode, AWK |
6bf7aab6 | 1451 | |
9234c238 | 1452 | This section gives a brief description of the special features |
7ae8ad94 | 1453 | available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. |
16152b76 | 1454 | (These are called ``C mode and related modes''.) |
ec7ae032 CY |
1455 | @ifinfo |
1456 | @xref{Top,, CC Mode, ccmode, CC Mode}, for more details. | |
1457 | @end ifinfo | |
1458 | @ifnotinfo | |
1459 | For more details, see the CC mode Info manual, which is distributed | |
1460 | with Emacs. | |
1461 | @end ifnotinfo | |
51ed0ea0 | 1462 | |
6bf7aab6 | 1463 | @menu |
7ae8ad94 RS |
1464 | * Motion in C:: Commands to move by C statements, etc. |
1465 | * Electric C:: Colon and other chars can automatically reindent. | |
1466 | * Hungry Delete:: A more powerful DEL command. | |
1467 | * Other C Commands:: Filling comments, viewing expansion of macros, | |
1468 | and other neat features. | |
6bf7aab6 DL |
1469 | @end menu |
1470 | ||
1471 | @node Motion in C | |
1472 | @subsection C Mode Motion Commands | |
1473 | ||
1474 | This section describes commands for moving point, in C mode and | |
1475 | related modes. | |
1476 | ||
1477 | @table @code | |
47d42d81 AM |
1478 | @item C-M-a |
1479 | @itemx C-M-e | |
7ae8ad94 RS |
1480 | @findex c-beginning-of-defun |
1481 | @findex c-end-of-defun | |
1482 | Move point to the beginning or end of the current function or | |
47d42d81 AM |
1483 | top-level definition. In languages with enclosing scopes (such as |
1484 | C++'s classes) the @dfn{current function} is the immediate one, | |
1485 | possibly inside a scope. Otherwise it is the one defined by the least | |
7ae8ad94 | 1486 | enclosing braces. (By contrast, @code{beginning-of-defun} and |
47d42d81 AM |
1487 | @code{end-of-defun} search for braces in column zero.) @xref{Moving |
1488 | by Defuns}. | |
7ae8ad94 | 1489 | |
6bf7aab6 DL |
1490 | @item C-c C-u |
1491 | @kindex C-c C-u @r{(C mode)} | |
1492 | @findex c-up-conditional | |
1493 | Move point back to the containing preprocessor conditional, leaving the | |
1494 | mark behind. A prefix argument acts as a repeat count. With a negative | |
1495 | argument, move point forward to the end of the containing | |
7ae8ad94 RS |
1496 | preprocessor conditional. |
1497 | ||
1498 | @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so | |
1499 | the function will stop at a @samp{#elif} when going backward, but not | |
1500 | when going forward. | |
6bf7aab6 DL |
1501 | |
1502 | @item C-c C-p | |
1503 | @kindex C-c C-p @r{(C mode)} | |
1504 | @findex c-backward-conditional | |
1505 | Move point back over a preprocessor conditional, leaving the mark | |
1506 | behind. A prefix argument acts as a repeat count. With a negative | |
1507 | argument, move forward. | |
1508 | ||
1509 | @item C-c C-n | |
1510 | @kindex C-c C-n @r{(C mode)} | |
1511 | @findex c-forward-conditional | |
1512 | Move point forward across a preprocessor conditional, leaving the mark | |
1513 | behind. A prefix argument acts as a repeat count. With a negative | |
1514 | argument, move backward. | |
1515 | ||
1516 | @item M-a | |
7ae8ad94 | 1517 | @kindex M-a (C mode) |
6bf7aab6 DL |
1518 | @findex c-beginning-of-statement |
1519 | Move point to the beginning of the innermost C statement | |
1520 | (@code{c-beginning-of-statement}). If point is already at the beginning | |
1521 | of a statement, move to the beginning of the preceding statement. With | |
1522 | prefix argument @var{n}, move back @var{n} @minus{} 1 statements. | |
1523 | ||
7ae8ad94 RS |
1524 | In comments or in strings which span more than one line, this command |
1525 | moves by sentences instead of statements. | |
6bf7aab6 DL |
1526 | |
1527 | @item M-e | |
7ae8ad94 | 1528 | @kindex M-e (C mode) |
6bf7aab6 | 1529 | @findex c-end-of-statement |
7ae8ad94 RS |
1530 | Move point to the end of the innermost C statement or sentence; like |
1531 | @kbd{M-a} except that it moves in the other direction | |
1532 | (@code{c-end-of-statement}). | |
6bf7aab6 DL |
1533 | @end table |
1534 | ||
1535 | @node Electric C | |
1536 | @subsection Electric C Characters | |
1537 | ||
1538 | In C mode and related modes, certain printing characters are | |
108262a0 AM |
1539 | @dfn{electric}---in addition to inserting themselves, they also |
1540 | reindent the current line, and optionally also insert newlines. The | |
64e207c0 RS |
1541 | ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, |
1542 | @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and | |
f5eb910a | 1543 | @kbd{)}. |
108262a0 AM |
1544 | |
1545 | You might find electric indentation inconvenient if you are editing | |
1546 | chaotically indented code. If you are new to CC Mode, you might find | |
1547 | it disconcerting. You can toggle electric action with the command | |
1548 | @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line | |
1549 | after the mode name: | |
6bf7aab6 | 1550 | |
108262a0 AM |
1551 | @table @kbd |
1552 | @item C-c C-l | |
1553 | @kindex C-c C-l @r{(C mode)} | |
1554 | @findex c-toggle-electric-state | |
1555 | Toggle electric action (@code{c-toggle-electric-state}). With a | |
1556 | prefix argument, this command enables electric action if the argument | |
1557 | is positive, disables it if it is negative. | |
1558 | @end table | |
1559 | ||
1560 | Electric characters insert newlines only when, in addition to the | |
1561 | electric state, the @dfn{auto-newline} feature is enabled (indicated | |
1562 | by @samp{/la} in the mode line after the mode name). You can turn | |
1563 | this feature on or off with the command @kbd{C-c C-a}: | |
6bf7aab6 DL |
1564 | |
1565 | @table @kbd | |
1566 | @item C-c C-a | |
1567 | @kindex C-c C-a @r{(C mode)} | |
108262a0 AM |
1568 | @findex c-toggle-auto-newline |
1569 | Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a | |
6bf7aab6 DL |
1570 | prefix argument, this command turns the auto-newline feature on if the |
1571 | argument is positive, and off if it is negative. | |
1572 | @end table | |
1573 | ||
f5eb910a RS |
1574 | Usually the CC Mode style configures the exact circumstances in |
1575 | which Emacs inserts auto-newlines. You can also configure this | |
1576 | directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. | |
6bf7aab6 DL |
1577 | |
1578 | @node Hungry Delete | |
1579 | @subsection Hungry Delete Feature in C | |
7ae8ad94 | 1580 | @cindex hungry deletion (C Mode) |
6bf7aab6 | 1581 | |
108262a0 AM |
1582 | If you want to delete an entire block of whitespace at point, you |
1583 | can use @dfn{hungry deletion}. This deletes all the contiguous | |
1584 | whitespace either before point or after point in a single operation. | |
1585 | @dfn{Whitespace} here includes tabs and newlines, but not comments or | |
1586 | preprocessor commands. | |
6bf7aab6 DL |
1587 | |
1588 | @table @kbd | |
69d271a7 AM |
1589 | @item C-c C-@key{DEL} |
1590 | @itemx C-c @key{DEL} | |
aca2cfd2 | 1591 | @findex c-hungry-delete-backwards |
69d271a7 AM |
1592 | @kindex C-c C-@key{DEL} (C Mode) |
1593 | @kindex C-c @key{DEL} (C Mode) | |
aca2cfd2 | 1594 | @code{c-hungry-delete-backwards}---Delete the entire block of whitespace |
108262a0 AM |
1595 | preceding point. |
1596 | ||
6bf7aab6 | 1597 | @item C-c C-d |
69d271a7 AM |
1598 | @itemx C-c C-@key{DELETE} |
1599 | @itemx C-c @key{DELETE} | |
108262a0 AM |
1600 | @findex c-hungry-delete-forward |
1601 | @kindex C-c C-d (C Mode) | |
69d271a7 AM |
1602 | @kindex C-c C-@key{DELETE} (C Mode) |
1603 | @kindex C-c @key{DELETE} (C Mode) | |
108262a0 AM |
1604 | @code{c-hungry-delete-forward}---Delete the entire block of whitespace |
1605 | following point. | |
1606 | @end table | |
1607 | ||
1608 | As an alternative to the above commands, you can enable @dfn{hungry | |
1609 | delete mode}. When this feature is enabled (indicated by @samp{/h} in | |
d884be12 RS |
1610 | the mode line after the mode name), a single @key{DEL} deletes all |
1611 | preceding whitespace, not just one space, and a single @kbd{C-c C-d} | |
1612 | (but @emph{not} plain @key{DELETE}) deletes all following whitespace. | |
6bf7aab6 | 1613 | |
108262a0 AM |
1614 | @table @kbd |
1615 | @item M-x c-toggle-hungry-state | |
1616 | @findex c-toggle-hungry-state | |
1617 | Toggle the hungry-delete feature | |
1618 | (@code{c-toggle-hungry-state})@footnote{This command had the binding | |
1619 | @kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now | |
1620 | bound to @code{c-hungry-delete-forward}.}. With a prefix argument, | |
1621 | this command turns the hungry-delete feature on if the argument is | |
1622 | positive, and off if it is negative. | |
6bf7aab6 DL |
1623 | @end table |
1624 | ||
1625 | @vindex c-hungry-delete-key | |
1626 | The variable @code{c-hungry-delete-key} controls whether the | |
1627 | hungry-delete feature is enabled. | |
1628 | ||
1629 | @node Other C Commands | |
1630 | @subsection Other Commands for C Mode | |
1631 | ||
1632 | @table @kbd | |
108262a0 | 1633 | @item C-c C-w |
aaef4f91 MH |
1634 | @itemx M-x subword-mode |
1635 | @findex subword-mode | |
f5eb910a | 1636 | Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word |
8a75579f | 1637 | commands recognize upper case letters in |
f5eb910a RS |
1638 | @samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by |
1639 | the flag @samp{/w} on the mode line after the mode name | |
aaef4f91 | 1640 | (e.g. @samp{C/law}). You can even use @kbd{M-x subword-mode} in |
f5eb910a | 1641 | non-CC Mode buffers. |
108262a0 | 1642 | |
dfec8297 RS |
1643 | In the GNU project, we recommend using underscores to separate words |
1644 | within an identifier in C or C++, rather than using case distinctions. | |
1645 | ||
7ae8ad94 RS |
1646 | @item M-x c-context-line-break |
1647 | @findex c-context-line-break | |
1648 | This command inserts a line break and indents the new line in a manner | |
1649 | appropriate to the context. In normal code, it does the work of | |
1650 | @kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it | |
1651 | additionally inserts a @samp{\} at the line break, and within comments | |
1652 | it's like @kbd{M-j} (@code{c-indent-new-comment-line}). | |
1653 | ||
1654 | @code{c-context-line-break} isn't bound to a key by default, but it | |
1655 | needs a binding to be useful. The following code will bind it to | |
108262a0 AM |
1656 | @kbd{C-j}. We use @code{c-initialization-hook} here to make sure |
1657 | the keymap is loaded before we try to change it. | |
1658 | ||
444246ca | 1659 | @smallexample |
108262a0 AM |
1660 | (defun my-bind-clb () |
1661 | (define-key c-mode-base-map "\C-j" 'c-context-line-break)) | |
1662 | (add-hook 'c-initialization-hook 'my-bind-clb) | |
444246ca | 1663 | @end smallexample |
7ae8ad94 | 1664 | |
6bf7aab6 | 1665 | @item C-M-h |
6bf7aab6 DL |
1666 | Put mark at the end of a function definition, and put point at the |
1667 | beginning (@code{c-mark-function}). | |
1668 | ||
1669 | @item M-q | |
1670 | @kindex M-q @r{(C mode)} | |
1671 | @findex c-fill-paragraph | |
1672 | Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). | |
1673 | If any part of the current line is a comment or within a comment, this | |
1674 | command fills the comment or the paragraph of it that point is in, | |
1675 | preserving the comment indentation and comment delimiters. | |
1676 | ||
1677 | @item C-c C-e | |
1678 | @cindex macro expansion in C | |
1679 | @cindex expansion of C macros | |
1680 | @findex c-macro-expand | |
1681 | @kindex C-c C-e @r{(C mode)} | |
1682 | Run the C preprocessor on the text in the region, and show the result, | |
1683 | which includes the expansion of all the macro calls | |
1684 | (@code{c-macro-expand}). The buffer text before the region is also | |
1685 | included in preprocessing, for the sake of macros defined there, but the | |
1686 | output from this part isn't shown. | |
1687 | ||
1688 | When you are debugging C code that uses macros, sometimes it is hard to | |
1689 | figure out precisely how the macros expand. With this command, you | |
1690 | don't have to figure it out; you can see the expansions. | |
1691 | ||
1692 | @item C-c C-\ | |
1693 | @findex c-backslash-region | |
1694 | @kindex C-c C-\ @r{(C mode)} | |
1695 | Insert or align @samp{\} characters at the ends of the lines of the | |
1696 | region (@code{c-backslash-region}). This is useful after writing or | |
1697 | editing a C macro definition. | |
1698 | ||
1699 | If a line already ends in @samp{\}, this command adjusts the amount of | |
1700 | whitespace before it. Otherwise, it inserts a new @samp{\}. However, | |
1701 | the last line in the region is treated specially; no @samp{\} is | |
1702 | inserted on that line, and any @samp{\} there is deleted. | |
1703 | ||
1704 | @item M-x cpp-highlight-buffer | |
1705 | @cindex preprocessor highlighting | |
1706 | @findex cpp-highlight-buffer | |
1707 | Highlight parts of the text according to its preprocessor conditionals. | |
1c64e6ed | 1708 | This command displays another buffer named @file{*CPP Edit*}, which |
6bf7aab6 DL |
1709 | serves as a graphic menu for selecting how to display particular kinds |
1710 | of conditionals and their contents. After changing various settings, | |
1711 | click on @samp{[A]pply these settings} (or go to that buffer and type | |
1712 | @kbd{a}) to rehighlight the C mode buffer accordingly. | |
1713 | ||
1714 | @item C-c C-s | |
1715 | @findex c-show-syntactic-information | |
1716 | @kindex C-c C-s @r{(C mode)} | |
1717 | Display the syntactic information about the current source line | |
054af0fd SE |
1718 | (@code{c-show-syntactic-information}). This information directs how |
1719 | the line is indented. | |
3b8b8888 DL |
1720 | |
1721 | @item M-x cwarn-mode | |
1722 | @itemx M-x global-cwarn-mode | |
1723 | @findex cwarn-mode | |
1724 | @findex global-cwarn-mode | |
7ae8ad94 | 1725 | @vindex global-cwarn-mode |
3b8b8888 DL |
1726 | @cindex CWarn mode |
1727 | @cindex suspicious constructions in C, C++ | |
9234c238 | 1728 | CWarn minor mode highlights certain suspicious C and C++ constructions: |
3b8b8888 DL |
1729 | |
1730 | @itemize @bullet{} | |
1731 | @item | |
9234c238 | 1732 | Assignments inside expressions. |
3b8b8888 DL |
1733 | @item |
1734 | Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} | |
1735 | (except after a @samp{do @dots{} while} statement); | |
1736 | @item | |
1737 | C++ functions with reference parameters. | |
1738 | @end itemize | |
1739 | ||
1740 | @noindent | |
9234c238 RS |
1741 | You can enable the mode for one buffer with the command @kbd{M-x |
1742 | cwarn-mode}, or for all suitable buffers with the command @kbd{M-x | |
1743 | global-cwarn-mode} or by customizing the variable | |
1744 | @code{global-cwarn-mode}. You must also enable Font Lock mode to make | |
1745 | it work. | |
3b8b8888 DL |
1746 | |
1747 | @item M-x hide-ifdef-mode | |
1748 | @findex hide-ifdef-mode | |
1749 | @cindex Hide-ifdef mode | |
8474de5b | 1750 | @vindex hide-ifdef-shadow |
3b8b8888 | 1751 | Hide-ifdef minor mode hides selected code within @samp{#if} and |
8474de5b CY |
1752 | @samp{#ifdef} preprocessor blocks. If you change the variable |
1753 | @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode | |
1754 | ``shadows'' preprocessor blocks by displaying them with a less | |
1755 | prominent face, instead of hiding them entirely. See the | |
1756 | documentation string of @code{hide-ifdef-mode} for more information. | |
9234c238 RS |
1757 | |
1758 | @item M-x ff-find-related-file | |
1759 | @cindex related files | |
1760 | @findex ff-find-related-file | |
1761 | @vindex ff-related-file-alist | |
1762 | Find a file ``related'' in a special way to the file visited by the | |
1763 | current buffer. Typically this will be the header file corresponding | |
1764 | to a C/C++ source file, or vice versa. The variable | |
1765 | @code{ff-related-file-alist} specifies how to compute related file | |
1766 | names. | |
6bf7aab6 DL |
1767 | @end table |
1768 | ||
6bf7aab6 DL |
1769 | @node Asm Mode |
1770 | @section Asm Mode | |
1771 | ||
1772 | @cindex Asm mode | |
9234c238 | 1773 | @cindex assembler mode |
6bf7aab6 DL |
1774 | Asm mode is a major mode for editing files of assembler code. It |
1775 | defines these commands: | |
1776 | ||
1777 | @table @kbd | |
1778 | @item @key{TAB} | |
1779 | @code{tab-to-tab-stop}. | |
1780 | @item C-j | |
1781 | Insert a newline and then indent using @code{tab-to-tab-stop}. | |
1782 | @item : | |
1783 | Insert a colon and then remove the indentation from before the label | |
1784 | preceding colon. Then do @code{tab-to-tab-stop}. | |
1785 | @item ; | |
1786 | Insert or align a comment. | |
1787 | @end table | |
1788 | ||
1789 | The variable @code{asm-comment-char} specifies which character | |
1790 | starts comments in assembler syntax. | |
ab5796a9 | 1791 | |
b23ef7a5 EZ |
1792 | @ifnottex |
1793 | @include fortran-xtra.texi | |
1794 | @end ifnottex |