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