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