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