Mercurial > emacs
annotate man/programs.texi @ 38081:fecdcc18b027
(tar-header-block-summarize): Add help-echo to mouse-highlighted text.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sun, 17 Jun 2001 11:23:58 +0000 |
parents | 3382f3158d21 |
children | c8bf8c704581 |
rev | line source |
---|---|
25829 | 1 @c This is part of the Emacs manual. |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
2 @c Copyright (C) 1985,86,87,93,94,95,97,99,2000 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 | |
10 Emacs has many commands designed to understand the syntax of programming | |
38051
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
11 languages such as Lisp and C. These commands can: |
25829 | 12 |
13 @itemize @bullet | |
14 @item | |
15 Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}). | |
16 @item | |
17 Move over or mark top-level expressions---@dfn{defuns}, in Lisp; | |
18 functions, in C (@pxref{Defuns}). | |
19 @item | |
20 Show how parentheses balance (@pxref{Matching}). | |
21 @item | |
22 Insert, kill or align comments (@pxref{Comments}). | |
23 @item | |
24 Follow the usual indentation conventions of the language | |
25 (@pxref{Program Indent}). | |
26 @end itemize | |
27 | |
38051
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
28 Emacs commands that operate on words, sentences and paragraphs are |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
29 very useful in editing code even though their canonical application is |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
30 for editing human language text. Most symbols contain words |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
31 (@pxref{Words}); sentences can be found in strings and comments |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
32 (@pxref{Sentences}). Paragraphs per se don't exist in code, but the |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
33 paragraph commands are useful anyway, because programming language major |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
34 modes define paragraphs to begin and end at blank lines |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
35 (@pxref{Paragraphs}). Judicious use of blank lines to make the program |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
36 clearer will also provide useful chunks of text for the paragraph |
3382f3158d21
Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents:
38018
diff
changeset
|
37 commands to work on. |
25829 | 38 |
39 The selective display feature is useful for looking at the overall | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
40 structure of a function (@pxref{Selective Display}). This feature |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
41 hides the lines that are indented more than a specified amount. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
42 Programming modes often support Outline minor mode (@pxref{Outline |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
43 Mode}). The Foldout package provides folding-editor features |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
44 (@pxref{Foldout}). |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
45 |
36185 | 46 The ``automatic typing'' features may be useful for writing programs. |
37868
ac2238e335f8
Fix some xrefs to other manuals.
Richard M. Stallman <rms@gnu.org>
parents:
36786
diff
changeset
|
47 @xref{Top,,Autotyping, autotype, Autotyping}. |
25829 | 48 |
49 @menu | |
50 * Program Modes:: Major modes for editing programs. | |
51 * Lists:: Expressions with balanced parentheses. | |
52 * List Commands:: The commands for working with list and sexps. | |
53 * Defuns:: Each program is made up of separate functions. | |
54 There are editing commands to operate on them. | |
55 * Program Indent:: Adjusting indentation to show the nesting. | |
56 * Matching:: Insertion of a close-delimiter flashes matching open. | |
57 * Comments:: Inserting, killing, and aligning comments. | |
58 * Balanced Editing:: Inserting two matching parentheses at once, etc. | |
59 * Symbol Completion:: Completion on symbol names of your program or language. | |
60 * Which Function:: Which Function mode shows which function you are in. | |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
61 * Hideshow:: Displaying blocks selectively. |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
62 * Glasses:: Making identifiersLikeThis more readable. |
25829 | 63 * Documentation:: Getting documentation of functions you plan to call. |
64 * Change Log:: Maintaining a change history for your program. | |
30793 | 65 * Authors:: Maintaining an @file{AUTHORS} file. |
25829 | 66 * Tags:: Go direct to any function in your program in one |
67 command. Tags remembers which file it is in. | |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
68 * Imenu:: Making buffer indexes as menus. |
25829 | 69 * Emerge:: A convenient way of merging two versions of a program. |
26264 | 70 * C Modes:: Special commands of C, C++, Objective-C, |
25829 | 71 Java, and Pike modes. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
72 * Fortran:: Fortran mode and its special features. |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
73 * Asm Mode:: Asm mode and its special features. |
25829 | 74 @end menu |
75 | |
76 @node Program Modes | |
77 @section Major Modes for Programming Languages | |
78 | |
79 @cindex modes for programming languages | |
80 @cindex Perl mode | |
81 @cindex Icon mode | |
82 @cindex Awk mode | |
83 @cindex Makefile mode | |
84 @cindex Tcl mode | |
85 @cindex CPerl mode | |
26106 | 86 @cindex DSSSL mode |
87 @cindex Octave mode | |
88 @cindex Metafont mode | |
89 @cindex Modula2 mode | |
90 @cindex Prolog mode | |
91 @cindex Simula mode | |
92 @cindex VHDL mode | |
93 @cindex M4 mode | |
94 @cindex Shell-script mode | |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
95 @cindex Delphi mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
96 @cindex PostScript mode |
25829 | 97 Emacs also has major modes for the programming languages Lisp, Scheme |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
98 (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada, |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
99 Awk, C, C++, Delphi (Object Pascal), Fortran (free and fixed format), |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
100 Icon, IDLWAVE, |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
101 Java, Metafont (@TeX{}'s companion for font creation), Modula2, |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
102 Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula, |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
103 VHDL, CORBA IDL, and Tcl. |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
104 There is also a major mode for makefiles, called Makefile |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
105 mode. An alternative mode for Perl is called CPerl mode. Modes |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
106 are available for scripts for the common Unix shells, VMS DCL and |
36185 | 107 MS-DOS/MS-Windows @samp{BAT} files. In a similar fashion to programming |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
108 languages, modes are provided for editing various sorts of configuration |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
109 files. |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
110 |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
111 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
112 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
113 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
114 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). |
25829 | 115 |
116 Ideally, a major mode should be implemented for each programming | |
117 language that you might want to edit with Emacs; but often the mode for | |
118 one language can serve for other syntactically similar languages. The | |
119 language modes that exist are those that someone decided to take the | |
120 trouble to write. | |
121 | |
122 There are several forms of Lisp mode, which differ in the way they | |
123 interface to Lisp execution. @xref{Executing Lisp}. | |
124 | |
125 Each of the programming language major modes defines the @key{TAB} key | |
126 to run an indentation function that knows the indentation conventions of | |
127 that language and updates the current line's indentation accordingly. | |
37978
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
128 For example, in C mode @key{TAB} is bound to @code{c-indent-command}. |
25829 | 129 @kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB}; |
130 thus, it too indents in a mode-specific fashion. | |
131 | |
132 @kindex DEL @r{(programming modes)} | |
37978
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
133 @findex c-electric-backspace |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
134 In most programming languages, indentation is likely to vary from |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
135 line to line. So the major modes for those languages rebind @key{DEL} |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
136 to treat a tab as if it were the equivalent number of spaces (using |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
137 the command @code{c-electric-backspace}). This makes it possible to |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
138 rub out indentation one column at a time without worrying whether it |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
139 is made up of spaces or tabs. Use @kbd{C-b C-d} to delete a tab |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
140 character before point, in these modes. |
25829 | 141 |
142 Programming language modes define paragraphs to be separated only by | |
143 blank lines, so that the paragraph commands remain useful. Auto Fill mode, | |
144 if enabled in a programming language major mode, indents the new lines | |
145 which it creates. | |
146 | |
147 @cindex mode hook | |
148 @vindex c-mode-hook | |
149 @vindex lisp-mode-hook | |
150 @vindex emacs-lisp-mode-hook | |
151 @vindex lisp-interaction-mode-hook | |
152 @vindex scheme-mode-hook | |
153 Turning on a major mode runs a normal hook called the @dfn{mode hook}, | |
154 which is the value of a Lisp variable. Each major mode has a mode hook, | |
155 and the hook's name is always made from the mode command's name by | |
156 adding @samp{-hook}. For example, turning on C mode runs the hook | |
157 @code{c-mode-hook}, while turning on Lisp mode runs the hook | |
158 @code{lisp-mode-hook}. @xref{Hooks}. | |
159 | |
160 @node Lists | |
161 @section Lists and Sexps | |
162 | |
163 @cindex Control-Meta | |
164 By convention, Emacs keys for dealing with balanced expressions are | |
165 usually Control-Meta characters. They tend to be analogous in | |
166 function to their Control and Meta equivalents. These commands are | |
167 usually thought of as pertaining to expressions in programming | |
168 languages, but can be useful with any language in which some sort of | |
169 parentheses exist (including human languages). | |
170 | |
171 @cindex list | |
172 @cindex sexp | |
173 @cindex expression | |
174 These commands fall into two classes. Some deal only with @dfn{lists} | |
175 (parenthetical groupings). They see nothing except parentheses, brackets, | |
176 braces (whichever ones must balance in the language you are working with), | |
177 and escape characters that might be used to quote those. | |
178 | |
36185 | 179 The other commands deal with expressions or @dfn{sexps}. The word ``sexp'' |
25829 | 180 is derived from @dfn{s-expression}, the ancient term for an expression in |
36185 | 181 Lisp. But in Emacs, the notion of ``sexp'' is not limited to Lisp. It |
25829 | 182 refers to an expression in whatever language your program is written in. |
183 Each programming language has its own major mode, which customizes the | |
184 syntax tables so that expressions in that language count as sexps. | |
185 | |
186 Sexps typically include symbols, numbers, and string constants, as well | |
187 as anything contained in parentheses, brackets or braces. | |
188 | |
189 In languages that use prefix and infix operators, such as C, it is not | |
190 possible for all expressions to be sexps. For example, C mode does not | |
191 recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression; | |
192 it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the | |
193 @samp{+} as punctuation between them. This is a fundamental ambiguity: | |
194 both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to | |
195 move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a | |
196 single sexp in C mode. | |
197 | |
198 Some languages have obscure forms of expression syntax that nobody | |
199 has bothered to make Emacs understand properly. | |
200 | |
201 @node List Commands | |
202 @section List And Sexp Commands | |
203 | |
204 @c doublewidecommands | |
205 @table @kbd | |
206 @item C-M-f | |
207 Move forward over a sexp (@code{forward-sexp}). | |
208 @item C-M-b | |
209 Move backward over a sexp (@code{backward-sexp}). | |
210 @item C-M-k | |
211 Kill sexp forward (@code{kill-sexp}). | |
212 @item C-M-@key{DEL} | |
213 Kill sexp backward (@code{backward-kill-sexp}). | |
214 @item C-M-u | |
215 Move up and backward in list structure (@code{backward-up-list}). | |
216 @item C-M-d | |
217 Move down and forward in list structure (@code{down-list}). | |
218 @item C-M-n | |
219 Move forward over a list (@code{forward-list}). | |
220 @item C-M-p | |
221 Move backward over a list (@code{backward-list}). | |
222 @item C-M-t | |
223 Transpose expressions (@code{transpose-sexps}). | |
224 @item C-M-@@ | |
225 Put mark after following expression (@code{mark-sexp}). | |
226 @end table | |
227 | |
34821
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
228 @cindex parentheses, moving across |
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
229 @cindex matching parenthesis and braces, moving to |
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
230 @cindex braces, moving across |
25829 | 231 @kindex C-M-f |
232 @kindex C-M-b | |
233 @findex forward-sexp | |
234 @findex backward-sexp | |
235 To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If | |
236 the first significant character after point is an opening delimiter | |
237 (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f} | |
238 moves past the matching closing delimiter. If the character begins a | |
239 symbol, string, or number, @kbd{C-M-f} moves over that. | |
240 | |
241 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a | |
242 sexp. The detailed rules are like those above for @kbd{C-M-f}, but with | |
243 directions reversed. If there are any prefix characters (single-quote, | |
244 backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back | |
245 over them as well. The sexp commands move across comments as if they | |
246 were whitespace in most modes. | |
247 | |
248 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the | |
249 specified number of times; with a negative argument, it moves in the | |
250 opposite direction. | |
251 | |
34821
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
252 @cindex deleting parenthesized expressions |
25829 | 253 @kindex C-M-k |
254 @findex kill-sexp | |
255 @kindex C-M-DEL | |
256 @findex backward-kill-sexp | |
257 Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp}) | |
258 or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills | |
259 the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}} | |
260 kills the characters that @kbd{C-M-b} would move over. | |
261 | |
262 @kindex C-M-n | |
263 @kindex C-M-p | |
264 @findex forward-list | |
265 @findex backward-list | |
266 The @dfn{list commands} move over lists, as the sexp commands do, but skip | |
267 blithely over any number of other kinds of sexps (symbols, strings, etc.). | |
268 They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p} | |
269 (@code{backward-list}). The main reason they are useful is that they | |
270 usually ignore comments (since the comments usually do not contain any | |
271 lists).@refill | |
272 | |
273 @kindex C-M-u | |
274 @kindex C-M-d | |
275 @findex backward-up-list | |
276 @findex down-list | |
277 @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when | |
278 that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u} | |
279 (@code{backward-up-list}). | |
280 @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A | |
281 positive argument serves as a repeat count; a negative argument reverses | |
282 direction of motion and also requests repetition, so it moves forward and | |
283 up one or more levels.@refill | |
284 | |
285 To move @emph{down} in list structure, use @kbd{C-M-d} | |
286 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening | |
287 delimiter, this is nearly the same as searching for a @samp{(}. An | |
288 argument specifies the number of levels of parentheses to go down. | |
289 | |
34821
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
290 @cindex transposition of parenthesized expressions |
25829 | 291 @kindex C-M-t |
292 @findex transpose-sexps | |
293 A somewhat random-sounding command which is nevertheless handy is | |
294 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp | |
295 across the next one. An argument serves as a repeat count, and a | |
296 negative argument drags backwards (thus canceling out the effect of | |
297 @kbd{C-M-t} with a positive argument). An argument of zero, rather than | |
298 doing nothing, transposes the sexps ending after point and the mark. | |
299 | |
300 @kindex C-M-@@ | |
301 @findex mark-sexp | |
302 To set the region around the next sexp in the buffer, use @kbd{C-M-@@} | |
303 (@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f} | |
304 would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In | |
305 particular, a negative argument is useful for putting the mark at the | |
306 beginning of the previous sexp. | |
307 | |
308 The list and sexp commands' understanding of syntax is completely | |
309 controlled by the syntax table. Any character can, for example, be | |
310 declared to be an opening delimiter and act like an open parenthesis. | |
311 @xref{Syntax}. | |
312 | |
313 @node Defuns | |
314 @section Defuns | |
315 @cindex defuns | |
316 | |
317 In Emacs, a parenthetical grouping at the top level in the buffer is | |
318 called a @dfn{defun}. The name derives from the fact that most top-level | |
319 lists in a Lisp file are instances of the special form @code{defun}, but | |
320 any top-level parenthetical grouping counts as a defun in Emacs parlance | |
321 regardless of what its contents are, and regardless of the programming | |
322 language in use. For example, in C, the body of a function definition is a | |
323 defun. | |
324 | |
325 @c doublewidecommands | |
326 @table @kbd | |
327 @item C-M-a | |
328 Move to beginning of current or preceding defun | |
329 (@code{beginning-of-defun}). | |
330 @item C-M-e | |
331 Move to end of current or following defun (@code{end-of-defun}). | |
332 @item C-M-h | |
333 Put region around whole current or following defun (@code{mark-defun}). | |
334 @end table | |
335 | |
34821
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
336 @cindex move to beginning or end of function |
1d7bee7283ac
Move the cindex about moving to matching paren into the "List Commands"
Eli Zaretskii <eliz@gnu.org>
parents:
34254
diff
changeset
|
337 @cindex function, move to beginning or end |
25829 | 338 @kindex C-M-a |
339 @kindex C-M-e | |
340 @kindex C-M-h | |
341 @findex beginning-of-defun | |
342 @findex end-of-defun | |
343 @findex mark-defun | |
344 The commands to move to the beginning and end of the current defun are | |
345 @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}). | |
346 | |
36263
11db0318031d
Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents:
36198
diff
changeset
|
347 @kindex C-M-h @r{(C mode)} |
25829 | 348 @findex c-mark-function |
349 If you wish to operate on the current defun, use @kbd{C-M-h} | |
350 (@code{mark-defun}) which puts point at the beginning and mark at the end | |
351 of the current or next defun. For example, this is the easiest way to get | |
352 ready to move the defun to a different place in the text. In C mode, | |
353 @kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the | |
354 same as @code{mark-defun}; the difference is that it backs up over the | |
355 argument declarations, function name and returned data type so that the | |
356 entire C function is inside the region. @xref{Marking Objects}. | |
357 | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
358 @cindex open-parenthesis in leftmost column |
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
359 @cindex ( in leftmost column |
25829 | 360 Emacs assumes that any open-parenthesis found in the leftmost column |
361 is the start of a defun. Therefore, @strong{never put an | |
362 open-parenthesis at the left margin in a Lisp file unless it is the | |
363 start of a top-level list. Never put an open-brace or other opening | |
364 delimiter at the beginning of a line of C code unless it starts the body | |
365 of a function.} The most likely problem case is when you want an | |
366 opening delimiter at the start of a line inside a string. To avoid | |
367 trouble, put an escape character (@samp{\}, in C and Emacs Lisp, | |
368 @samp{/} in some other Lisp dialects) before the opening delimiter. It | |
369 will not affect the contents of the string. | |
370 | |
371 In the remotest past, the original Emacs found defuns by moving upward a | |
372 level of parentheses until there were no more levels to go up. This always | |
373 required scanning all the way back to the beginning of the buffer, even for | |
374 a small function. To speed up the operation, Emacs was changed to assume | |
375 that any @samp{(} (or other character assigned the syntactic class of | |
376 opening-delimiter) at the left margin is the start of a defun. This | |
377 heuristic is nearly always right and avoids the costly scan; however, | |
378 it mandates the convention described above. | |
379 | |
380 @node Program Indent | |
381 @section Indentation for Programs | |
382 @cindex indentation for programs | |
383 | |
384 The best way to keep a program properly indented is to use Emacs to | |
385 reindent it as you change it. Emacs has commands to indent properly | |
386 either a single line, a specified number of lines, or all of the lines | |
387 inside a single parenthetical grouping. | |
388 | |
389 @menu | |
390 * Basic Indent:: Indenting a single line. | |
391 * Multi-line Indent:: Commands to reindent many lines at once. | |
392 * Lisp Indent:: Specifying how each Lisp function should be indented. | |
393 * C Indent:: Extra features for indenting C and related modes. | |
394 * Custom C Indent:: Controlling indentation style for C and related modes. | |
395 @end menu | |
396 | |
397 Emacs also provides a Lisp pretty-printer in the library @code{pp}. | |
398 This program reformats a Lisp object with indentation chosen to look nice. | |
399 | |
400 @node Basic Indent | |
401 @subsection Basic Program Indentation Commands | |
402 | |
403 @c WideCommands | |
404 @table @kbd | |
405 @item @key{TAB} | |
406 Adjust indentation of current line. | |
407 @item C-j | |
408 Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
409 @end table | |
410 | |
411 @kindex TAB @r{(programming modes)} | |
37978
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
412 @findex c-indent-command |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
413 @findex indent-line-function |
25829 | 414 The basic indentation command is @key{TAB}, which gives the current line |
415 the correct indentation as determined from the previous lines. The | |
37978
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
416 function that @key{TAB} runs depends on the major mode; it is @code{indent-for-tab-command} |
c41356c953a0
Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents:
37868
diff
changeset
|
417 in Lisp mode, @code{c-indent-command} in C mode, etc. These functions |
25829 | 418 understand different syntaxes for different languages, but they all do |
419 about the same thing. @key{TAB} in any programming-language major mode | |
420 inserts or deletes whitespace at the beginning of the current line, | |
421 independent of where point is in the line. If point is inside the | |
422 whitespace at the beginning of the line, @key{TAB} leaves it at the end of | |
423 that whitespace; otherwise, @key{TAB} leaves point fixed with respect to | |
424 the characters around it. | |
425 | |
426 Use @kbd{C-q @key{TAB}} to insert a tab at point. | |
427 | |
428 @kindex C-j | |
429 @findex newline-and-indent | |
430 When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}), | |
431 which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates | |
432 a blank line and then gives it the appropriate indentation. | |
433 | |
434 @key{TAB} indents the second and following lines of the body of a | |
435 parenthetical grouping each under the preceding one; therefore, if you | |
436 alter one line's indentation to be nonstandard, the lines below will | |
437 tend to follow it. This behavior is convenient in cases where you have | |
438 overridden the standard result of @key{TAB} because you find it | |
439 unaesthetic for a particular line. | |
440 | |
441 Remember that an open-parenthesis, open-brace or other opening delimiter | |
442 at the left margin is assumed by Emacs (including the indentation routines) | |
443 to be the start of a function. Therefore, you must never have an opening | |
444 delimiter in column zero that is not the beginning of a function, not even | |
445 inside a string. This restriction is vital for making the indentation | |
446 commands fast; you must simply accept it. @xref{Defuns}, for more | |
447 information on this. | |
448 | |
38009
b6036155d1ca
(Basic Indent): Add a cross-reference to description of indent-tabs-mode.
Eli Zaretskii <eliz@gnu.org>
parents:
37997
diff
changeset
|
449 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>
parents:
37997
diff
changeset
|
450 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>
parents:
37997
diff
changeset
|
451 |
25829 | 452 @node Multi-line Indent |
453 @subsection Indenting Several Lines | |
454 | |
455 When you wish to reindent several lines of code which have been altered | |
456 or moved to a different level in the list structure, you have several | |
457 commands available. | |
458 | |
459 @table @kbd | |
460 @item C-M-q | |
461 Reindent all the lines within one list (@code{indent-sexp}). | |
462 @item C-u @key{TAB} | |
463 Shift an entire list rigidly sideways so that its first line | |
464 is properly indented. | |
465 @item C-M-\ | |
466 Reindent all lines in the region (@code{indent-region}). | |
467 @end table | |
468 | |
469 @kindex C-M-q | |
470 @findex indent-sexp | |
471 You can reindent the contents of a single list by positioning point | |
472 before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in | |
473 Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable | |
474 commands in other modes). The indentation of the line the sexp starts on | |
475 is not changed; therefore, only the relative indentation within the list, | |
476 and not its position, is changed. To correct the position as well, type a | |
477 @key{TAB} before the @kbd{C-M-q}. | |
478 | |
479 @kindex C-u TAB | |
480 If the relative indentation within a list is correct but the | |
481 indentation of its first line is not, go to that line and type @kbd{C-u | |
482 @key{TAB}}. @key{TAB} with a numeric argument reindents the current | |
483 line as usual, then reindents by the same amount all the lines in the | |
484 grouping starting on the current line. In other words, it reindents the | |
485 whole grouping rigidly as a unit. It is clever, though, and does not | |
486 alter lines that start inside strings, or C preprocessor lines when in C | |
487 mode. | |
488 | |
489 Another way to specify the range to be reindented is with the region. | |
490 The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to | |
491 every line whose first character is between point and mark. | |
492 | |
493 @node Lisp Indent | |
494 @subsection Customizing Lisp Indentation | |
495 @cindex customizing Lisp indentation | |
496 | |
497 The indentation pattern for a Lisp expression can depend on the function | |
498 called by the expression. For each Lisp function, you can choose among | |
499 several predefined patterns of indentation, or define an arbitrary one with | |
500 a Lisp program. | |
501 | |
502 The standard pattern of indentation is as follows: the second line of the | |
503 expression is indented under the first argument, if that is on the same | |
504 line as the beginning of the expression; otherwise, the second line is | |
505 indented underneath the function name. Each following line is indented | |
506 under the previous line whose nesting depth is the same. | |
507 | |
508 @vindex lisp-indent-offset | |
509 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides | |
510 the usual indentation pattern for the second line of an expression, so that | |
511 such lines are always indented @code{lisp-indent-offset} more columns than | |
512 the containing list. | |
513 | |
514 @vindex lisp-body-indent | |
515 The standard pattern is overridden for certain functions. Functions | |
516 whose names start with @code{def} always indent the second line by | |
517 @code{lisp-body-indent} extra columns beyond the open-parenthesis | |
518 starting the expression. | |
519 | |
520 The standard pattern can be overridden in various ways for individual | |
521 functions, according to the @code{lisp-indent-function} property of the | |
522 function name. There are four possibilities for this property: | |
523 | |
524 @table @asis | |
525 @item @code{nil} | |
526 This is the same as no property; the standard indentation pattern is used. | |
527 @item @code{defun} | |
528 The pattern used for function names that start with @code{def} is used for | |
529 this function also. | |
530 @item a number, @var{number} | |
531 The first @var{number} arguments of the function are | |
532 @dfn{distinguished} arguments; the rest are considered the @dfn{body} | |
533 of the expression. A line in the expression is indented according to | |
534 whether the first argument on it is distinguished or not. If the | |
535 argument is part of the body, the line is indented @code{lisp-body-indent} | |
536 more columns than the open-parenthesis starting the containing | |
537 expression. If the argument is distinguished and is either the first | |
538 or second argument, it is indented @emph{twice} that many extra columns. | |
539 If the argument is distinguished and not the first or second argument, | |
540 the standard pattern is followed for that line. | |
541 @item a symbol, @var{symbol} | |
542 @var{symbol} should be a function name; that function is called to | |
543 calculate the indentation of a line within this expression. The | |
544 function receives two arguments: | |
545 @table @asis | |
546 @item @var{state} | |
547 The value returned by @code{parse-partial-sexp} (a Lisp primitive for | |
548 indentation and nesting computation) when it parses up to the | |
549 beginning of this line. | |
550 @item @var{pos} | |
551 The position at which the line being indented begins. | |
552 @end table | |
553 @noindent | |
554 It should return either a number, which is the number of columns of | |
555 indentation for that line, or a list whose car is such a number. The | |
556 difference between returning a number and returning a list is that a | |
557 number says that all following lines at the same nesting level should | |
558 be indented just like this one; a list says that following lines might | |
559 call for different indentations. This makes a difference when the | |
560 indentation is being computed by @kbd{C-M-q}; if the value is a | |
561 number, @kbd{C-M-q} need not recalculate indentation for the following | |
562 lines until the end of the list. | |
563 @end table | |
564 | |
565 @node C Indent | |
566 @subsection Commands for C Indentation | |
567 | |
568 Here are the commands for indentation in C mode and related modes: | |
569 | |
570 @table @code | |
571 @item C-c C-q | |
572 @kindex C-c C-q @r{(C mode)} | |
573 @findex c-indent-defun | |
574 Reindent the current top-level function definition or aggregate type | |
575 declaration (@code{c-indent-defun}). | |
576 | |
577 @item C-M-q | |
578 @kindex C-M-q @r{(C mode)} | |
579 @findex c-indent-exp | |
580 Reindent each line in the balanced expression that follows point | |
581 (@code{c-indent-exp}). A prefix argument inhibits error checking and | |
582 warning messages about invalid syntax. | |
583 | |
584 @item @key{TAB} | |
585 @findex c-indent-command | |
586 Reindent the current line, and/or in some cases insert a tab character | |
587 (@code{c-indent-command}). | |
588 | |
589 If @code{c-tab-always-indent} is @code{t}, this command always reindents | |
590 the current line and does nothing else. This is the default. | |
591 | |
592 If that variable is @code{nil}, this command reindents the current line | |
593 only if point is at the left margin or in the line's indentation; | |
594 otherwise, it inserts a tab (or the equivalent number of spaces, | |
595 if @code{indent-tabs-mode} is @code{nil}). | |
596 | |
597 Any other value (not @code{nil} or @code{t}) means always reindent the | |
598 line, and also insert a tab if within a comment, a string, or a | |
599 preprocessor directive. | |
600 | |
601 @item C-u @key{TAB} | |
602 Reindent the current line according to its syntax; also rigidly reindent | |
603 any other lines of the expression that starts on the current line. | |
604 @xref{Multi-line Indent}. | |
605 @end table | |
606 | |
607 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This | |
608 first selects the whole buffer as the region, then reindents that | |
609 region. | |
610 | |
611 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves | |
612 to the front of the block and then reindents it all. | |
613 | |
614 @node Custom C Indent | |
615 @subsection Customizing C Indentation | |
616 | |
617 C mode and related modes use a simple yet flexible mechanism for | |
618 customizing indentation. The mechanism works in two steps: first it | |
619 classifies the line syntactically according to its contents and context; | |
620 second, it associates each kind of syntactic construct with an | |
621 indentation offset which you can customize. | |
622 | |
623 @menu | |
624 * Syntactic Analysis:: | |
625 * Indentation Calculation:: | |
626 * Changing Indent Style:: | |
627 * Syntactic Symbols:: | |
628 * Variables for C Indent:: | |
629 * C Indent Styles:: | |
630 @end menu | |
631 | |
632 @node Syntactic Analysis | |
633 @subsubsection Step 1---Syntactic Analysis | |
634 @cindex syntactic analysis | |
635 | |
636 In the first step, the C indentation mechanism looks at the line | |
637 before the one you are currently indenting and determines the syntactic | |
638 components of the construct on that line. It builds a list of these | |
639 syntactic components, each of which contains a @dfn{syntactic symbol} | |
640 and sometimes also a buffer position. Some syntactic symbols describe | |
641 grammatical elements, for example @code{statement} and | |
642 @code{substatement}; others describe locations amidst grammatical | |
643 elements, for example @code{class-open} and @code{knr-argdecl}. | |
644 | |
645 Conceptually, a line of C code is always indented relative to the | |
646 indentation of some line higher up in the buffer. This is represented | |
647 by the buffer positions in the syntactic component list. | |
648 | |
649 Here is an example. Suppose we have the following code in a C++ mode | |
650 buffer (the line numbers don't actually appear in the buffer): | |
651 | |
652 @example | |
653 1: void swap (int& a, int& b) | |
654 2: @{ | |
655 3: int tmp = a; | |
656 4: a = b; | |
657 5: b = tmp; | |
658 6: @} | |
659 @end example | |
660 | |
661 If you type @kbd{C-c C-s} (which runs the command | |
662 @code{c-show-syntactic-information}) on line 4, it shows the result of | |
663 the indentation mechanism for that line: | |
664 | |
665 @example | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
666 syntactic analysis: ((statement . 32)) |
25829 | 667 @end example |
668 | |
669 This indicates that the line is a statement and it is indented | |
670 relative to buffer position 32, which happens to be the @samp{i} in | |
671 @code{int} on line 3. If you move the cursor to line 3 and type | |
672 @kbd{C-c C-s}, it displays this: | |
673 | |
674 @example | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
675 syntactic analysis: ((defun-block-intro . 28)) |
25829 | 676 @end example |
677 | |
678 This indicates that the @code{int} line is the first statement in a | |
679 block, and is indented relative to buffer position 28, which is the | |
680 brace just after the function header. | |
681 | |
682 @noindent | |
683 Here is another example: | |
684 | |
685 @example | |
686 1: int add (int val, int incr, int doit) | |
687 2: @{ | |
688 3: if (doit) | |
689 4: @{ | |
690 5: return (val + incr); | |
691 6: @} | |
692 7: return (val); | |
693 8: @} | |
694 @end example | |
695 | |
696 @noindent | |
697 Typing @kbd{C-c C-s} on line 4 displays this: | |
698 | |
699 @example | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
700 syntactic analysis: ((substatement-open . 43)) |
25829 | 701 @end example |
702 | |
703 This says that the brace @emph{opens} a substatement block. By the | |
704 way, a @dfn{substatement} indicates the line after an @code{if}, | |
705 @code{else}, @code{while}, @code{do}, @code{switch}, @code{for}, | |
706 @code{try}, @code{catch}, @code{finally}, or @code{synchronized} | |
707 statement. | |
708 | |
709 @cindex syntactic component | |
710 @cindex syntactic symbol | |
711 @vindex c-syntactic-context | |
712 Within the C indentation commands, after a line has been analyzed | |
713 syntactically for indentation, the variable @code{c-syntactic-context} | |
714 contains a list that describes the results. Each element in this list | |
715 is a @dfn{syntactic component}: a cons cell containing a syntactic | |
716 symbol and (optionally) its corresponding buffer position. There may be | |
717 several elements in a component list; typically only one element has a | |
718 buffer position. | |
719 | |
720 @node Indentation Calculation | |
721 @subsubsection Step 2---Indentation Calculation | |
722 @cindex Indentation Calculation | |
723 | |
724 The C indentation mechanism calculates the indentation for the current | |
725 line using the list of syntactic components, @code{c-syntactic-context}, | |
726 derived from syntactic analysis. Each component is a cons cell that | |
727 contains a syntactic symbol and may also contain a buffer position. | |
728 | |
729 Each component contributes to the final total indentation of the line | |
730 in two ways. First, the syntactic symbol identifies an element of | |
731 @code{c-offsets-alist}, which is an association list mapping syntactic | |
732 symbols into indentation offsets. Each syntactic symbol's offset adds | |
733 to the total indentation. Second, if the component includes a buffer | |
734 position, the column number of that position adds to the indentation. | |
735 All these offsets and column numbers, added together, give the total | |
736 indentation. | |
737 | |
738 The following examples demonstrate the workings of the C indentation | |
739 mechanism: | |
740 | |
741 @example | |
742 1: void swap (int& a, int& b) | |
743 2: @{ | |
744 3: int tmp = a; | |
745 4: a = b; | |
746 5: b = tmp; | |
747 6: @} | |
748 @end example | |
749 | |
750 Suppose that point is on line 3 and you type @key{TAB} to reindent the | |
751 line. As explained above (@pxref{Syntactic Analysis}), the syntactic | |
752 component list for that line is: | |
753 | |
754 @example | |
755 ((defun-block-intro . 28)) | |
756 @end example | |
757 | |
758 In this case, the indentation calculation first looks up | |
759 @code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose | |
760 that it finds the integer 2; it adds this to the running total | |
761 (initialized to zero), yielding a updated total indentation of 2 spaces. | |
762 | |
763 The next step is to find the column number of buffer position 28. | |
764 Since the brace at buffer position 28 is in column zero, this adds 0 to | |
765 the running total. Since this line has only one syntactic component, | |
766 the total indentation for the line is 2 spaces. | |
767 | |
768 @example | |
769 1: int add (int val, int incr, int doit) | |
770 2: @{ | |
771 3: if (doit) | |
772 4: @{ | |
773 5: return(val + incr); | |
774 6: @} | |
775 7: return(val); | |
776 8: @} | |
777 @end example | |
778 | |
779 If you type @key{TAB} on line 4, the same process is performed, but | |
780 with different data. The syntactic component list for this line is: | |
781 | |
782 @example | |
783 ((substatement-open . 43)) | |
784 @end example | |
785 | |
786 Here, the indentation calculation's first job is to look up the | |
787 symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume | |
788 that the offset for this symbol is 2. At this point the running total | |
789 is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43, | |
790 which is the @samp{i} in @code{if} on line 3. This character is in | |
791 column 2 on that line. Adding this yields a total indentation of 4 | |
792 spaces. | |
793 | |
794 @vindex c-strict-syntax-p | |
795 If a syntactic symbol in the analysis of a line does not appear in | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
796 @code{c-offsets-alist}, it is ignored. |
25829 | 797 |
798 @node Changing Indent Style | |
799 @subsubsection Changing Indentation Style | |
800 | |
801 There are two ways to customize the indentation style for the C-like | |
802 modes. First, you can select one of several predefined styles, each of | |
803 which specifies offsets for all the syntactic symbols. For more | |
804 flexibility, you can customize the handling of individual syntactic | |
805 symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic | |
806 symbols. | |
807 | |
808 @table @kbd | |
809 @item M-x c-set-style @key{RET} @var{style} @key{RET} | |
810 Select predefined indentation style @var{style}. Type @kbd{?} when | |
811 entering @var{style} to see a list of supported styles; to find out what | |
812 a style looks like, select it and reindent some C code. | |
813 | |
814 @item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET} | |
815 Set the indentation offset for syntactic symbol @var{symbol} | |
816 (@code{c-set-offset}). The second argument @var{offset} specifies the | |
817 new indentation offset. | |
818 @end table | |
819 | |
820 The @code{c-offsets-alist} variable controls the amount of | |
821 indentation to give to each syntactic symbol. Its value is an | |
822 association list, and each element of the list has the form | |
823 @code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets | |
824 for various syntactic symbols, you can customize indentation in fine | |
825 detail. To change this alist, use @code{c-set-offset} (see below). | |
826 | |
827 Each offset value in @code{c-offsets-alist} can be an integer, a | |
828 function or variable name, a list, or one of the following symbols: @code{+}, | |
829 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative | |
830 multiples of the variable @code{c-basic-offset}. Thus, if you want to | |
831 change the levels of indentation to be 3 spaces instead of 2 spaces, set | |
832 @code{c-basic-offset} to 3. | |
833 | |
834 Using a function as the offset value provides the ultimate flexibility | |
835 in customizing indentation. The function is called with a single | |
836 argument containing the @code{cons} of the syntactic symbol and | |
837 the buffer position, if any. The function should return an integer | |
838 offset. | |
26264 | 839 |
25829 | 840 If the offset value is a list, its elements are processed according |
841 to the rules above until a non-@code{nil} value is found. That value is | |
842 then added to the total indentation in the normal manner. The primary | |
843 use for this is to combine the results of several functions. | |
844 | |
845 @kindex C-c C-o @r{(C mode)} | |
846 @findex c-set-offset | |
847 The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to | |
848 set offsets, both interactively or in your @file{~/.emacs} file. First | |
849 specify the syntactic symbol, then the offset you want. @xref{Syntactic | |
850 Symbols}, for a list of valid syntactic symbols and their meanings. | |
851 | |
852 @node Syntactic Symbols | |
853 @subsubsection Syntactic Symbols | |
854 | |
855 Here is a table of valid syntactic symbols for indentation in C and | |
856 related modes, with their syntactic meanings. Normally, most of these | |
857 symbols are assigned offsets in @code{c-offsets-alist}. | |
858 | |
859 @table @code | |
860 @item string | |
861 Inside a multi-line string. | |
862 | |
863 @item c | |
864 Inside a multi-line C style block comment. | |
865 | |
866 @item defun-open | |
867 On a brace that opens a function definition. | |
868 | |
869 @item defun-close | |
870 On a brace that closes a function definition. | |
871 | |
872 @item defun-block-intro | |
873 In the first line in a top-level defun. | |
874 | |
875 @item class-open | |
876 On a brace that opens a class definition. | |
877 | |
878 @item class-close | |
879 On a brace that closes a class definition. | |
880 | |
881 @item inline-open | |
882 On a brace that opens an in-class inline method. | |
883 | |
884 @item inline-close | |
885 On a brace that closes an in-class inline method. | |
886 | |
887 @item extern-lang-open | |
888 On a brace that opens an external language block. | |
889 | |
890 @item extern-lang-close | |
891 On a brace that closes an external language block. | |
892 | |
893 @item func-decl-cont | |
894 The region between a function definition's argument list and the defun | |
895 opening brace (excluding K&R function definitions). In C, you cannot | |
896 put anything but whitespace and comments between them; in C++ and Java, | |
897 @code{throws} declarations and other things can appear in this context. | |
898 | |
899 @item knr-argdecl-intro | |
900 On the first line of a K&R C argument declaration. | |
901 | |
902 @item knr-argdecl | |
903 In one of the subsequent lines in a K&R C argument declaration. | |
904 | |
905 @item topmost-intro | |
906 On the first line in a topmost construct definition. | |
907 | |
908 @item topmost-intro-cont | |
909 On the topmost definition continuation lines. | |
910 | |
911 @item member-init-intro | |
912 On the first line in a member initialization list. | |
913 | |
914 @item member-init-cont | |
915 On one of the subsequent member initialization list lines. | |
916 | |
917 @item inher-intro | |
918 On the first line of a multiple inheritance list. | |
919 | |
920 @item inher-cont | |
921 On one of the subsequent multiple inheritance lines. | |
922 | |
923 @item block-open | |
924 On a statement block open brace. | |
925 | |
926 @item block-close | |
927 On a statement block close brace. | |
928 | |
929 @item brace-list-open | |
930 On the opening brace of an @code{enum} or @code{static} array list. | |
931 | |
932 @item brace-list-close | |
933 On the closing brace of an @code{enum} or @code{static} array list. | |
934 | |
935 @item brace-list-intro | |
936 On the first line in an @code{enum} or @code{static} array list. | |
937 | |
938 @item brace-list-entry | |
939 On one of the subsequent lines in an @code{enum} or @code{static} array | |
940 list. | |
941 | |
942 @item brace-entry-open | |
943 On one of the subsequent lines in an @code{enum} or @code{static} array | |
944 list, when the line begins with an open brace. | |
945 | |
946 @item statement | |
947 On an ordinary statement. | |
948 | |
949 @item statement-cont | |
950 On a continuation line of a statement. | |
951 | |
952 @item statement-block-intro | |
953 On the first line in a new statement block. | |
954 | |
955 @item statement-case-intro | |
956 On the first line in a @code{case} ``block.'' | |
957 | |
958 @item statement-case-open | |
959 On the first line in a @code{case} block starting with brace. | |
960 | |
961 @item inexpr-statement | |
962 On a statement block inside an expression. This is used for a GNU | |
963 extension to the C language, and for Pike special functions that take a | |
964 statement block as an argument. | |
965 | |
966 @item inexpr-class | |
967 On a class definition inside an expression. This is used for anonymous | |
968 classes and anonymous array initializers in Java. | |
969 | |
970 @item substatement | |
971 On the first line after an @code{if}, @code{while}, @code{for}, | |
972 @code{do}, or @code{else}. | |
973 | |
974 @item substatement-open | |
975 On the brace that opens a substatement block. | |
976 | |
977 @item case-label | |
978 On a @code{case} or @code{default} label. | |
979 | |
980 @item access-label | |
981 On a C++ @code{private}, @code{protected}, or @code{public} access label. | |
982 | |
983 @item label | |
984 On any ordinary label. | |
985 | |
986 @item do-while-closure | |
987 On the @code{while} that ends a @code{do}-@code{while} construct. | |
988 | |
989 @item else-clause | |
990 On the @code{else} of an @code{if}-@code{else} construct. | |
991 | |
992 @item catch-clause | |
993 On the @code{catch} and @code{finally} lines in | |
994 @code{try}@dots{}@code{catch} constructs in C++ and Java. | |
995 | |
996 @item comment-intro | |
997 On a line containing only a comment introduction. | |
998 | |
999 @item arglist-intro | |
1000 On the first line in an argument list. | |
1001 | |
1002 @item arglist-cont | |
1003 On one of the subsequent argument list lines when no arguments follow on | |
1004 the same line as the arglist opening parenthesis. | |
1005 | |
1006 @item arglist-cont-nonempty | |
1007 On one of the subsequent argument list lines when at least one argument | |
1008 follows on the same line as the arglist opening parenthesis. | |
1009 | |
1010 @item arglist-close | |
1011 On the closing parenthesis of an argument list. | |
1012 | |
1013 @item stream-op | |
1014 On one of the lines continuing a stream operator construct. | |
1015 | |
1016 @item inclass | |
1017 On a construct that is nested inside a class definition. The | |
1018 indentation is relative to the open brace of the class definition. | |
1019 | |
1020 @item inextern-lang | |
1021 On a construct that is nested inside an external language block. | |
1022 | |
1023 @item inexpr-statement | |
1024 On the first line of statement block inside an expression. This is used | |
1025 for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}. | |
1026 It is also used for the special functions that takes a statement block | |
1027 as an argument in Pike. | |
1028 | |
1029 @item inexpr-class | |
1030 On the first line of a class definition inside an expression. This is | |
1031 used for anonymous classes and anonymous array initializers in Java. | |
1032 | |
1033 @item cpp-macro | |
1034 On the start of a cpp macro. | |
1035 | |
1036 @item friend | |
1037 On a C++ @code{friend} declaration. | |
1038 | |
1039 @item objc-method-intro | |
1040 On the first line of an Objective-C method definition. | |
1041 | |
1042 @item objc-method-args-cont | |
1043 On one of the lines continuing an Objective-C method definition. | |
1044 | |
1045 @item objc-method-call-cont | |
1046 On one of the lines continuing an Objective-C method call. | |
1047 | |
1048 @item inlambda | |
1049 Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only | |
1050 used in Pike. | |
1051 | |
1052 @item lambda-intro-cont | |
1053 On a line continuing the header of a lambda function, between the | |
1054 @code{lambda} keyword and the function body. Only used in Pike. | |
1055 @end table | |
1056 | |
1057 @node Variables for C Indent | |
1058 @subsubsection Variables for C Indentation | |
1059 | |
1060 This section describes additional variables which control the | |
1061 indentation behavior of C mode and related mode. | |
1062 | |
1063 @table @code | |
1064 @item c-offsets-alist | |
1065 @vindex c-offsets-alist | |
1066 Association list of syntactic symbols and their indentation offsets. | |
1067 You should not set this directly, only with @code{c-set-offset}. | |
1068 @xref{Changing Indent Style}, for details. | |
1069 | |
1070 @item c-style-alist | |
1071 @vindex c-style-alist | |
1072 Variable for defining indentation styles; see below. | |
1073 | |
1074 @item c-basic-offset | |
1075 @vindex c-basic-offset | |
1076 Amount of basic offset used by @code{+} and @code{-} symbols in | |
26264 | 1077 @code{c-offsets-alist}.@refill |
25829 | 1078 |
1079 @item c-special-indent-hook | |
1080 @vindex c-special-indent-hook | |
1081 Hook for user-defined special indentation adjustments. This hook is | |
1082 called after a line is indented by C mode and related modes. | |
1083 @end table | |
1084 | |
1085 The variable @code{c-style-alist} specifies the predefined indentation | |
1086 styles. Each element has form @code{(@var{name} | |
1087 @var{variable-setting}@dots{})}, where @var{name} is the name of the | |
1088 style. Each @var{variable-setting} has the form @code{(@var{variable} | |
1089 . @var{value})}; @var{variable} is one of the customization variables | |
1090 used by C mode, and @var{value} is the value for that variable when | |
1091 using the selected style. | |
1092 | |
1093 When @var{variable} is @code{c-offsets-alist}, that is a special case: | |
1094 @var{value} is appended to the front of the value of @code{c-offsets-alist} | |
1095 instead of replacing that value outright. Therefore, it is not necessary | |
1096 for @var{value} to specify each and every syntactic symbol---only those | |
1097 for which the style differs from the default. | |
1098 | |
1099 The indentation of lines containing only comments is also affected by | |
1100 the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}). | |
1101 | |
1102 @node C Indent Styles | |
1103 @subsubsection C Indentation Styles | |
1104 @cindex c indentation styles | |
1105 | |
1106 A @dfn{C style} is a collection of indentation style customizations. | |
1107 Emacs comes with several predefined indentation styles for C and related | |
1108 modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup}, | |
1109 @code{linux}, @code{python}, @code{java}, @code{whitesmith}, | |
28627
1f6ba3e73fe9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28391
diff
changeset
|
1110 @code{ellemtel}, @code{cc-mode}, and @code{user}. |
25829 | 1111 |
1112 @findex c-set-style | |
1113 @vindex c-default-style | |
1114 To choose the style you want, use the command @kbd{M-x c-set-style}. | |
1115 Specify a style name as an argument (case is not significant in C style | |
1116 names). The chosen style only affects newly visited buffers, not those | |
1117 you are already editing. You can also set the variable | |
1118 @code{c-default-style} to specify the style for various major modes. | |
1119 Its value should be an alist, in which each element specifies one major | |
1120 mode and which indentation style to use for it. For example, | |
1121 | |
1122 @example | |
1123 (setq c-default-style | |
1124 '((java-mode . "java") (other . "gnu"))) | |
1125 @end example | |
1126 | |
1127 @noindent | |
1128 specifies an explicit choice for Java mode, and the default @samp{gnu} | |
1129 style for the other C-like modes. | |
1130 | |
28627
1f6ba3e73fe9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28391
diff
changeset
|
1131 The style @code{gnu} defines the formatting recommend by the GNU |
1f6ba3e73fe9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28391
diff
changeset
|
1132 Project; it is the default, so as to encourage the indentation we |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1133 recommend. However, if you make changes in variables such as |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1134 @code{c-basic-offset} and @code{c-offsets-alist} in your |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1135 @file{~/.emacs} file, your changes override the what @code{gnu} style |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1136 says. |
28627
1f6ba3e73fe9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28391
diff
changeset
|
1137 |
25829 | 1138 @findex c-add-style |
1139 To define a new C indentation style, call the function | |
1140 @code{c-add-style}: | |
1141 | |
1142 @example | |
1143 (c-add-style @var{name} @var{values} @var{use-now}) | |
1144 @end example | |
1145 | |
1146 @noindent | |
1147 Here @var{name} is the name of the new style (a string), and | |
1148 @var{values} is an alist whose elements have the form | |
1149 @code{(@var{variable} . @var{value})}. The variables you specify should | |
1150 be among those documented in @ref{Variables for C Indent}. | |
1151 | |
28627
1f6ba3e73fe9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28391
diff
changeset
|
1152 If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new |
1f6ba3e73fe9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28391
diff
changeset
|
1153 style after defining it. |
25829 | 1154 |
1155 @node Matching | |
1156 @section Automatic Display Of Matching Parentheses | |
1157 @cindex matching parentheses | |
1158 @cindex parentheses, displaying matches | |
1159 | |
1160 The Emacs parenthesis-matching feature is designed to show | |
1161 automatically how parentheses match in the text. Whenever you type a | |
1162 self-inserting character that is a closing delimiter, the cursor moves | |
1163 momentarily to the location of the matching opening delimiter, provided | |
1164 that is on the screen. If it is not on the screen, some text near it is | |
1165 displayed in the echo area. Either way, you can tell what grouping is | |
1166 being closed off. | |
1167 | |
1168 In Lisp, automatic matching applies only to parentheses. In C, it | |
1169 applies to braces and brackets too. Emacs knows which characters to regard | |
1170 as matching delimiters based on the syntax table, which is set by the major | |
1171 mode. @xref{Syntax}. | |
1172 | |
1173 If the opening delimiter and closing delimiter are mismatched---such as | |
1174 in @samp{[x)}---a warning message is displayed in the echo area. The | |
1175 correct matches are specified in the syntax table. | |
1176 | |
1177 @vindex blink-matching-paren | |
1178 @vindex blink-matching-paren-distance | |
1179 @vindex blink-matching-delay | |
1180 Three variables control parenthesis match display. | |
1181 @code{blink-matching-paren} turns the feature on or off; @code{nil} | |
1182 turns it off, but the default is @code{t} to turn match display on. | |
1183 @code{blink-matching-delay} says how many seconds to wait; the default | |
1184 is 1, but on some systems it is useful to specify a fraction of a | |
1185 second. @code{blink-matching-paren-distance} specifies how many | |
1186 characters back to search to find the matching opening delimiter. If | |
1187 the match is not found in that far, scanning stops, and nothing is | |
1188 displayed. This is to prevent scanning for the matching delimiter from | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1189 wasting lots of time when there is no match. The default is 25600. |
25829 | 1190 |
1191 @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>
parents:
31188
diff
changeset
|
1192 @cindex highlighting matching parentheses |
25829 | 1193 @findex show-paren-mode |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1194 Show Paren mode provides a more powerful kind of automatic |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1195 parenthesis matching. Whenever point is after a close parenthesis, |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1196 the close parenthesis and its matching open parenthesis are both |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1197 highlighted; otherwise, if point is before an open parenthesis, the |
34122
c42bb7d4437b
Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents:
31188
diff
changeset
|
1198 matching close parenthesis is highlighted. (There is no need to |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1199 highlight the open parenthesis after point because the cursor appears |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1200 on top of that character.) Use the command @kbd{M-x show-paren-mode} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1201 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>
parents:
31188
diff
changeset
|
1202 |
c42bb7d4437b
Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents:
31188
diff
changeset
|
1203 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>
parents:
31188
diff
changeset
|
1204 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>
parents:
31188
diff
changeset
|
1205 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>
parents:
31188
diff
changeset
|
1206 @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>
parents:
31188
diff
changeset
|
1207 underline. @xref{Face Customization}. |
25829 | 1208 |
1209 @node Comments | |
1210 @section Manipulating Comments | |
1211 @cindex comments | |
1212 | |
1213 Because comments are such an important part of programming, Emacs | |
1214 provides special commands for editing and inserting comments. | |
1215 | |
1216 @menu | |
1217 * Comment Commands:: | |
1218 * Multi-Line Comments:: | |
1219 * Options for Comments:: | |
1220 @end menu | |
1221 | |
1222 @node Comment Commands | |
1223 @subsection Comment Commands | |
1224 @cindex indentation for comments | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1225 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1226 The comment commands in this table insert, kill and align comments. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1227 They are described in this section and following sections. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1228 |
25829 | 1229 @table @kbd |
1230 @item M-; | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1231 Insert or realign comment on current line; alternatively, comment or |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1232 uncomment the region (@code{comment-dwim}). |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1233 @item C-u M-; |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1234 Kill comment on current line (@code{comment-kill}). |
25829 | 1235 @item C-x ; |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1236 Set comment column (@code{comment-set-column}). |
25829 | 1237 @item C-M-j |
1238 Like @key{RET} followed by inserting and aligning a comment | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1239 (@code{comment-indent-new-line}). |
25829 | 1240 @item M-x comment-region |
1241 Add or remove comment delimiters on all the lines in the region. | |
1242 @end table | |
1243 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1244 @kindex M-; |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1245 @findex comment-dwim |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1246 The command to create or align a comment is @kbd{M-;} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1247 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1248 I Mean''; it indicates that this command can be used for many |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1249 different jobs relating to comments, depending on the situation where |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1250 you use it. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1251 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1252 If there is no comment already on the line, @kbd{M-;} inserts a new |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1253 comment, aligned at a specific column called the @dfn{comment column}. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1254 The new comment begins with the string Emacs thinks comments should |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1255 start with (the value of @code{comment-start}; see below). Point is |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1256 after that string, so you can insert the text of the comment right |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1257 away. If the major mode has specified a string to terminate comments, |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1258 @kbd{M-;} inserts that too, to keep the syntax valid. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1259 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1260 If the text of the line extends past the comment column, then the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1261 comment start string is indented to a suitable boundary (usually, at |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1262 least one space is inserted). |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1263 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1264 You can also use @kbd{M-;} to align an existing comment. If a line |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1265 already contains the comment-start string, @kbd{M-;} reindents it to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1266 the conventional alignment and moves point after it. (Exception: |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1267 comments starting in column 0 are not moved.) Even when an existing |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1268 comment is properly aligned, @kbd{M-;} is still useful for moving |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1269 directly to the start of the text inside the comment. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1270 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1271 @findex comment-kill |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1272 @kindex C-u M-; |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1273 @kbd{C-u M-;} kills any comment on the current line, along with the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1274 whitespace before it. To reinsert the comment on another line, move |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1275 to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1276 realign it. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1277 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1278 Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1279 (@code{comment-dwim}) with a prefix argument. That command is |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1280 programmed so that when it receives a prefix argument it calls |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1281 @code{comment-kill}. However, @code{comment-kill} is a valid command |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1282 in its own right, and you can bind it directly to a key if you wish. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1283 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1284 @kbd{M-;} does two other jobs when used with an active region in |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1285 Transient Mark mode (@pxref{Transient Mark}). Then it either adds or |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1286 removes comment delimiters on each line of the region. (If every line |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1287 is a comment, it removes comment delimiters from each; otherwise, it |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1288 adds comment delimiters to each.) If you are not using Transient Mark |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1289 mode, then you should use the commands @code{comment-region} and |
36198 | 1290 @code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}). |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1291 A prefix argument used in these circumstances specifies how many |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1292 comment delimiters to add or how many to delete. |
25829 | 1293 |
1294 Some major modes have special rules for indenting certain kinds of | |
1295 comments in certain contexts. For example, in Lisp code, comments which | |
1296 start with two semicolons are indented as if they were lines of code, | |
1297 instead of at the comment column. Comments which start with three | |
1298 semicolons are supposed to start at the left margin. Emacs understands | |
1299 these conventions by indenting a double-semicolon comment using @key{TAB}, | |
1300 and by not changing the indentation of a triple-semicolon comment at all. | |
1301 | |
1302 @example | |
1303 ;; This function is just an example | |
1304 ;;; Here either two or three semicolons are appropriate. | |
1305 (defun foo (x) | |
1306 ;;; And now, the first part of the function: | |
1307 ;; The following line adds one. | |
1308 (1+ x)) ; This line adds one. | |
1309 @end example | |
1310 | |
1311 In C code, a comment preceded on its line by nothing but whitespace | |
1312 is indented like a line of code. | |
1313 | |
1314 @node Multi-Line Comments | |
1315 @subsection Multiple Lines of Comments | |
1316 | |
1317 @kindex C-M-j | |
1318 @cindex blank lines in programs | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1319 @findex comment-indent-new-line |
25829 | 1320 If you are typing a comment and wish to continue it on another line, |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1321 you can use the command @kbd{C-M-j} (@code{comment-indent-new-line}). |
25829 | 1322 This terminates the comment you are typing, creates a new blank line |
1323 afterward, and begins a new comment indented under the old one. When | |
1324 Auto Fill mode is on, going past the fill column while typing a comment | |
1325 causes the comment to be continued in just this fashion. If point is | |
1326 not at the end of the line when @kbd{C-M-j} is typed, the text on | |
1327 the rest of the line becomes part of the new comment line. | |
1328 | |
1329 @findex comment-region | |
1330 To turn existing lines into comment lines, use the @kbd{M-x | |
1331 comment-region} command. It adds comment delimiters to the lines that start | |
1332 in the region, thus commenting them out. With a negative argument, it | |
1333 does the opposite---it deletes comment delimiters from the lines in the | |
1334 region. | |
1335 | |
1336 With a positive argument, @code{comment-region} duplicates the last | |
1337 character of the comment start sequence it adds; the argument specifies | |
1338 how many copies of the character to insert. Thus, in Lisp mode, | |
1339 @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating | |
1340 the comment delimiter is a way of calling attention to the comment. It | |
1341 can also affect how the comment is indented. In Lisp, for proper | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1342 indentation, you should use an argument of two or three, if between defuns; |
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1343 if within a defun, it must be three. |
25829 | 1344 |
1345 @node Options for Comments | |
1346 @subsection Options Controlling Comments | |
1347 | |
1348 @vindex comment-column | |
1349 @kindex C-x ; | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1350 @findex comment-set-column |
25829 | 1351 The comment column is stored in the variable @code{comment-column}. You |
1352 can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1353 (@code{comment-set-column}) sets the comment column to the column point is |
25829 | 1354 at. @kbd{C-u C-x ;} sets the comment column to match the last comment |
1355 before point in the buffer, and then does a @kbd{M-;} to align the | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1356 current line's comment under the previous one. |
25829 | 1357 |
1358 The variable @code{comment-column} is per-buffer: setting the variable | |
1359 in the normal fashion affects only the current buffer, but there is a | |
1360 default value which you can change with @code{setq-default}. | |
1361 @xref{Locals}. Many major modes initialize this variable for the | |
1362 current buffer. | |
1363 | |
1364 @vindex comment-start-skip | |
1365 The comment commands recognize comments based on the regular | |
1366 expression that is the value of the variable @code{comment-start-skip}. | |
1367 Make sure this regexp does not match the null string. It may match more | |
1368 than the comment starting delimiter in the strictest sense of the word; | |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1369 for example, in C mode the value of the variable is |
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1370 @c This stops M-q from breaking the line inside that @code. |
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1371 @code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spaces |
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1372 after the @samp{/*} itself, and accepts C++ style comments also. |
25829 | 1373 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in |
1374 the string, which is needed to deny the first star its special meaning | |
1375 in regexp syntax. @xref{Regexps}.) | |
1376 | |
1377 @vindex comment-start | |
1378 @vindex comment-end | |
1379 When a comment command makes a new comment, it inserts the value of | |
1380 @code{comment-start} to begin it. The value of @code{comment-end} is | |
1381 inserted after point, so that it will follow the text that you will insert | |
1382 into the comment. In C mode, @code{comment-start} has the value | |
1383 @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}. | |
1384 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1385 @vindex comment-padding |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1386 The variable @code{comment-padding} specifies how many spaces |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1387 @code{comment-region} should insert on each line between the |
38018
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1388 comment delimiter and the line's original text. The default is 1, |
f802bdff6c2c
Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents:
38009
diff
changeset
|
1389 to insert one space. |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1390 |
25829 | 1391 @vindex comment-multi-line |
1392 The variable @code{comment-multi-line} controls how @kbd{C-M-j} | |
1393 (@code{indent-new-comment-line}) behaves when used inside a comment. If | |
1394 @code{comment-multi-line} is @code{nil}, as it normally is, then the | |
1395 comment on the starting line is terminated and a new comment is started | |
1396 on the new following line. If @code{comment-multi-line} is not | |
1397 @code{nil}, then the new following line is set up as part of the same | |
1398 comment that was found on the starting line. This is done by not | |
1399 inserting a terminator on the old line, and not inserting a starter on | |
1400 the new line. In languages where multi-line comments work, the choice | |
1401 of value for this variable is a matter of taste. | |
1402 | |
1403 @vindex comment-indent-function | |
1404 The variable @code{comment-indent-function} should contain a function | |
1405 that will be called to compute the indentation for a newly inserted | |
1406 comment or for aligning an existing comment. It is set differently by | |
1407 various major modes. The function is called with no arguments, but with | |
1408 point at the beginning of the comment, or at the end of a line if a new | |
1409 comment is to be inserted. It should return the column in which the | |
1410 comment ought to start. For example, in Lisp mode, the indent hook | |
1411 function bases its decision on how many semicolons begin an existing | |
1412 comment, and on the code in the preceding lines. | |
1413 | |
1414 @node Balanced Editing | |
1415 @section Editing Without Unbalanced Parentheses | |
1416 | |
1417 @table @kbd | |
1418 @item M-( | |
1419 Put parentheses around next sexp(s) (@code{insert-parentheses}). | |
1420 @item M-) | |
1421 Move past next close parenthesis and reindent | |
1422 (@code{move-past-close-and-reindent}). | |
1423 @end table | |
1424 | |
1425 @kindex M-( | |
1426 @kindex M-) | |
1427 @findex insert-parentheses | |
1428 @findex move-past-close-and-reindent | |
1429 The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)} | |
1430 (@code{move-past-close-and-reindent}) are designed to facilitate a style | |
1431 of editing which keeps parentheses balanced at all times. @kbd{M-(} | |
1432 inserts a pair of parentheses, either together as in @samp{()}, or, if | |
1433 given an argument, around the next several sexps. It leaves point after | |
1434 the open parenthesis. The command @kbd{M-)} moves past the close | |
1435 parenthesis, deleting any indentation preceding it, and indenting with | |
1436 @kbd{C-j} after it. | |
1437 | |
1438 For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-( | |
1439 F O O}, which has the same effect except for leaving the cursor before | |
1440 the close parenthesis. | |
1441 | |
1442 @vindex parens-require-spaces | |
1443 @kbd{M-(} may insert a space before the open parenthesis, depending on | |
1444 the syntax class of the preceding character. Set | |
1445 @code{parens-require-spaces} to @code{nil} value if you wish to inhibit | |
1446 this. | |
1447 | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
1448 @findex check-parens |
31035
64a11267ce9a
check-parens can also find unbalanced quotes in strings.
Eli Zaretskii <eliz@gnu.org>
parents:
31033
diff
changeset
|
1449 @cindex unbalanced parentheses and quotes |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1450 You can use @kbd{M-x check-parens} to find any unbalanced |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1451 parentheses and unbalanced string quotes in a buffer. |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
1452 |
25829 | 1453 @node Symbol Completion |
1454 @section Completion for Symbol Names | |
1455 @cindex completion (symbol names) | |
1456 | |
1457 Usually completion happens in the minibuffer. But one kind of completion | |
1458 is available in all buffers: completion for symbol names. | |
1459 | |
1460 @kindex M-TAB | |
1461 The character @kbd{M-@key{TAB}} runs a command to complete the partial | |
1462 symbol before point against the set of meaningful symbol names. Any | |
1463 additional characters determined by the partial name are inserted at | |
1464 point. | |
1465 | |
1466 If the partial name in the buffer has more than one possible completion | |
1467 and they have no additional characters in common, a list of all possible | |
1468 completions is displayed in another window. | |
1469 | |
36263
11db0318031d
Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents:
36198
diff
changeset
|
1470 @cindex tags-based completion |
25829 | 1471 @cindex Info index completion |
1472 @findex complete-symbol | |
1473 In most programming language major modes, @kbd{M-@key{TAB}} runs the | |
1474 command @code{complete-symbol}, which provides two kinds of completion. | |
1475 Normally it does completion based on a tags table (@pxref{Tags}); with a | |
1476 numeric argument (regardless of the value), it does completion based on | |
1477 the names listed in the Info file indexes for your language. Thus, to | |
1478 complete the name of a symbol defined in your own program, use | |
1479 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard | |
1480 library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based | |
1481 completion works only if there is an Info file for the standard library | |
1482 functions of your language, and only if it is installed at your site. | |
1483 | |
1484 @cindex Lisp symbol completion | |
36263
11db0318031d
Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents:
36198
diff
changeset
|
1485 @cindex completion (Lisp symbols) |
25829 | 1486 @findex lisp-complete-symbol |
1487 In Emacs-Lisp mode, the name space for completion normally consists of | |
1488 nontrivial symbols present in Emacs---those that have function | |
1489 definitions, values or properties. However, if there is an | |
1490 open-parenthesis immediately before the beginning of the partial symbol, | |
1491 only symbols with function definitions are considered as completions. | |
1492 The command which implements this is @code{lisp-complete-symbol}. | |
1493 | |
1494 In Text mode and related modes, @kbd{M-@key{TAB}} completes words | |
1495 based on the spell-checker's dictionary. @xref{Spelling}. | |
1496 | |
1497 @node Which Function | |
1498 @section Which Function Mode | |
1499 | |
1500 Which Function mode is a minor mode that displays the current function | |
1501 name in the mode line, as you move around in a buffer. | |
1502 | |
1503 @findex which-function-mode | |
1504 @vindex which-func-modes | |
1505 To enable (or disable) Which Function mode, use the command @kbd{M-x | |
1506 which-function-mode}. This command is global; it applies to all | |
1507 buffers, both existing ones and those yet to be created. However, this | |
1508 only affects certain major modes, those listed in the value of | |
1509 @code{which-func-modes}. (If the value is @code{t}, then Which Function | |
1510 mode applies to all major modes that know how to support it---which are | |
1511 the major modes that support Imenu.) | |
1512 | |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1513 @node Hideshow |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1514 @section Hideshow minor mode |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1515 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1516 @findex hs-minor-mode |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1517 Hideshow minor mode provides selective display of portions of a |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1518 file, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1519 enable or disable this mode, or add @code{hs-minor-mode} to the mode |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1520 hook for certain major modes in order to enable it automatically for |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1521 those modes. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1522 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1523 Just what constitutes a block depends on the major mode. In C mode |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1524 or C++ mode, they are delimited by braces, while in Lisp mode and |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1525 similar modes they are delimited by parentheses. Multi-line comments |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1526 also count as blocks. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1527 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1528 @findex hs-hide-all |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1529 @findex hs-hide-block |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1530 @findex hs-show-all |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1531 @findex hs-show-block |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1532 @findex hs-show-region |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1533 @findex hs-hide-level |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1534 @findex hs-minor-mode |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1535 @kindex C-c @@ C-h |
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1536 @kindex C-c @@ C-s |
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1537 @kindex C-c @@ C-M-h |
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1538 @kindex C-c @@ C-M-s |
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1539 @kindex C-c @@ C-r |
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1540 @kindex C-c @@ C-l |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1541 @kindex S-Mouse-2 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1542 @table @kbd |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1543 @item C-c @@ C-h |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1544 Hide the current block (@code{hs-hide-block}). |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1545 @item C-c @@ C-s |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1546 Show the current block (@code{hs-show-block}). |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1547 @item C-c @@ C-c |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1548 Either hide or show the current block (@code{hs-toggle-hiding}) |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1549 @item S-Mouse-2 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1550 Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}) |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1551 @item C-c @@ C-M-h |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1552 Hide all top-level blocks (@code{hs-hide-all}). |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1553 @item C-c @@ C-M-s |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1554 Show everything in the buffer (@code{hs-show-all}). |
37997
c329103798cc
(Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents:
37978
diff
changeset
|
1555 @item C-c @@ C-l |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1556 Hide all blocks @var{n} levels below this block |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1557 (@code{hs-hide-level}). |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1558 @end table |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1559 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1560 @vindex hs-hide-comments-when-hiding-all |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1561 @vindex hs-show-hidden-short-form |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1562 @vindex hs-isearch-open |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1563 @vindex hs-special-modes-alist |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1564 These user options exist for customizing Hideshow mode. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1565 |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1566 @table @code |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1567 @item hs-hide-comments-when-hiding-all |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1568 Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1569 @item hs-show-hidden-short-form |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1570 Non-@code{nil} says to omit the last line in a form (saving screen |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1571 space). |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1572 @item hs-isearch-open |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1573 Specifies what kind of hidden blocks to open in Isearch mode. |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1574 @item hs-special-modes-alist |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1575 Specifies |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1576 Initializes Hideshow variables for different modes. |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1577 @end table |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1578 |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1579 @node Glasses |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1580 @section Glasses minor mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1581 @cindex Glasses mode |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1582 @cindex identifiers, making long ones readable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1583 @cindex StudlyCaps, making them readable |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1584 @findex glasses-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1585 |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1586 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1587 readable by altering the display. It can do this in two different |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1588 ways: by displaying underscores between an lower-case letter and the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1589 following capital letter, or by emboldening the capital letters. It |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1590 does not alter the buffer text, only the way they display, so you can |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1591 use it even on read-only buffers. You can use the command @kbd{M-x |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1592 glasses-mode} to enable or disable the mode; you can also add |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1593 @code{glasses-mode} to the mode hook of appropriate programming |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1594 language major modes. |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1595 |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1596 @node Documentation |
25829 | 1597 @section Documentation Commands |
1598 | |
1599 As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f} | |
1600 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can | |
1601 be used to print documentation of functions and variables that you want to | |
1602 call. These commands use the minibuffer to read the name of a function or | |
1603 variable to document, and display the documentation in a window. | |
1604 | |
1605 For extra convenience, these commands provide default arguments based on | |
1606 the code in the neighborhood of point. @kbd{C-h f} sets the default to the | |
1607 function called in the innermost list containing point. @kbd{C-h v} uses | |
1608 the symbol name around or adjacent to point as its default. | |
1609 | |
1610 @cindex Eldoc mode | |
1611 @findex eldoc-mode | |
1612 For Emacs Lisp code, you can also use Eldoc mode. This minor mode | |
1613 constantly displays in the echo area the argument list for the function | |
1614 being called at point. (In other words, it finds the function call that | |
1615 point is contained in, and displays the argument list of that function.) | |
1616 Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use | |
1617 the command @kbd{M-x eldoc-mode} to enable or disable this feature. | |
1618 | |
1619 @findex info-lookup-symbol | |
1620 @findex info-lookup-file | |
1621 @kindex C-h C-i | |
1622 For C, Lisp, and other languages, you can use @kbd{C-h C-i} | |
1623 (@code{info-lookup-symbol}) to view the Info documentation for a symbol. | |
1624 You specify the symbol with the minibuffer; by default, it uses the | |
1625 symbol that appears in the buffer at point. The major mode determines | |
1626 where to look for documentation for the symbol---which Info files and | |
1627 which indices. You can also use @kbd{M-x info-lookup-file} to look for | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1628 documentation for a file name. Currently this supports the following |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1629 modes: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4, |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1630 Makefile, Octave, Perl, Scheme and Texinfo, provided you have installed |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1631 the relevant Info files, which are typically available with the appropriate GNU |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
1632 package. |
25829 | 1633 |
1634 @findex manual-entry | |
28838
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1635 @cindex manual pages |
25829 | 1636 You can read the ``man page'' for an operating system command, library |
1637 function, or system call, with the @kbd{M-x manual-entry} command. It | |
1638 runs the @code{man} program to format the man page, and runs it | |
1639 asynchronously if your system permits, so that you can keep on editing | |
1640 while the page is being formatted. (MS-DOS and MS-Windows 3 do not | |
1641 permit asynchronous subprocesses, so on these systems you cannot edit | |
1642 while Emacs waits for @code{man} to exit.) The result goes in a buffer | |
1643 named @samp{*Man @var{topic}*}. These buffers use a special major mode, | |
1644 Man mode, that facilitates scrolling and examining other manual pages. | |
1645 For details, type @kbd{C-h m} while in a man page buffer. | |
1646 | |
29840
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1647 @cindex sections of manual pages |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1648 Man pages are classified into @dfn{sections}; sometimes there are |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1649 man pages with the same name in different sections. To read a man |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1650 page from a specific section, type @samp{@var{topic}(@var{section})} or |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1651 @samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1652 for the topic. For example, to read the man page for the C library |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1653 function @code{chmod} (as opposed to a command by the same name), type |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1654 @kbd{M-x manual-entry @key{RET} chmod(2v) @key{RET}} (assuming |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1655 @code{chmod} is in section @samp{2v}). |
29840
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1656 |
29854
ca9f6085d33b
(Documentation): Describe how man pages with
Eli Zaretskii <eliz@gnu.org>
parents:
29840
diff
changeset
|
1657 If you do not specify a section, the results depend on how the |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1658 @code{man} command works on your system. Some of them display only |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1659 the first man page they find. Others display all man pages that have |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1660 the specified name, so you can page between them with the @kbd{M-n} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1661 and @kbd{M-p} keys. The mode line shows how many manual pages are |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1662 available in the Man buffer. |
29854
ca9f6085d33b
(Documentation): Describe how man pages with
Eli Zaretskii <eliz@gnu.org>
parents:
29840
diff
changeset
|
1663 |
25829 | 1664 @vindex Man-fontify-manpage-flag |
1665 For a long man page, setting the faces properly can take substantial | |
1666 time. By default, Emacs uses faces in man pages if Emacs can display | |
1667 different fonts or colors. You can turn off use of faces in man pages | |
1668 by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}. | |
1669 | |
1670 @findex Man-fontify-manpage | |
1671 If you insert the text of a man page into an Emacs buffer in some | |
1672 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to | |
1673 perform the same conversions that @kbd{M-x manual-entry} does. | |
1674 | |
28838
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1675 @findex woman |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1676 @cindex manual pages, on MS-DOS/MS-Windows |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1677 An alternative way of reading manual pages is the @kbd{M-x woman} |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1678 command@footnote{The name of the command, @code{woman}, is an acronym |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1679 for ``w/o (without) man,'' since it doesn't use the @code{man} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1680 program.}. Unlike @kbd{M-x man}, it does not run any external |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1681 programs to format and display the man pages; instead it does the job |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1682 in Emacs Lisp, so it works on systems such as MS-Windows, where the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1683 @code{man} program and other the programs it needs are not readily |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1684 available. @kbd{M-x woman} prompts for a name of a manual page, and |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1685 provides completion based on the list of manual pages that are |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1686 installed on your machine; the list of available manual pages is |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1687 computed automatically the first time you invoke @code{woman}. The |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1688 word at point in the current buffer is used to suggest the default |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1689 name of the manual page. |
28838
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1690 |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1691 With a numeric argument, @kbd{M-x woman} recomputes the list of the |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1692 manual pages used for completion. This is useful if you add or delete |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1693 manual pages. |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1694 |
29840
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1695 If you type a name of a manual page and @kbd{M-x woman} finds that |
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1696 several manual pages by the same name exist in different sections, it |
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1697 pops up a window with possible candidates asking you to choose one of |
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1698 them. |
53f07097269e
(Documentation Commands): Explain how to get a man page from
Eli Zaretskii <eliz@gnu.org>
parents:
29107
diff
changeset
|
1699 |
28838
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1700 @vindex woman-manpath |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1701 By default, @kbd{M-x woman} looks up the manual pages in directories |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1702 listed by the @code{MANPATH} environment variable. (If @code{MANPATH} |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1703 is not set, @code{woman} uses a suitable default value, which can be |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1704 customized.) More precisely, @code{woman} looks for subdirectories that |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1705 match the shell wildcard @file{man*} in each one of these directories, |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1706 and tries to find the manual pages in those subdirectories. When first |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1707 invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1708 of directory names and stores that list in the @code{woman-manpath} |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1709 variable. By changing the value of this variable, you can customize the |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1710 list of directories where @code{woman} looks for manual pages. |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1711 |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1712 @vindex woman-path |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1713 In addition, you can augment the list of directories searched by |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1714 @code{woman} by setting the value of the @code{woman-path} variable. |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1715 This variable should hold a list of specific directories which |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1716 @code{woman} should search, in addition to those in |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1717 @code{woman-manpath}. Unlike @code{woman-manpath}, the directories in |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1718 @code{woman-path} are searched for the manual pages, not for @file{man*} |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1719 subdirectories. |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1720 |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1721 @findex woman-find-file |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1722 Occasionally, you might need to display manual pages that are not in |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1723 any of the directories listed by @code{woman-manpath} and |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1724 @code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1725 name of a manual page file, with completion, and then formats and |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1726 displays that file like @kbd{M-x woman} does. |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1727 |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1728 @vindex woman-dired-keys |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1729 First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W} |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1730 key to run the @code{woman-find-file} command on the current line's |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1731 file. You can disable this by setting the variable |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1732 @code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1733 Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1734 line's archive member. |
e3d33a77c205
(Documentation): Document woman.el features.
Eli Zaretskii <eliz@gnu.org>
parents:
28627
diff
changeset
|
1735 |
30668
9c402b90b24d
(Documentation): Add an xref to woman's own manual.
Eli Zaretskii <eliz@gnu.org>
parents:
30049
diff
changeset
|
1736 For more information about setting up and using @kbd{M-x woman}, see |
9c402b90b24d
(Documentation): Add an xref to woman's own manual.
Eli Zaretskii <eliz@gnu.org>
parents:
30049
diff
changeset
|
1737 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan |
9c402b90b24d
(Documentation): Add an xref to woman's own manual.
Eli Zaretskii <eliz@gnu.org>
parents:
30049
diff
changeset
|
1738 Manual}. |
9c402b90b24d
(Documentation): Add an xref to woman's own manual.
Eli Zaretskii <eliz@gnu.org>
parents:
30049
diff
changeset
|
1739 |
25829 | 1740 Eventually the GNU project hopes to replace most man pages with |
1741 better-organized manuals that you can browse with Info. @xref{Misc | |
1742 Help}. Since this process is only partially completed, it is still | |
1743 useful to read manual pages. | |
1744 | |
1745 @node Change Log | |
1746 @section Change Logs | |
1747 | |
1748 @cindex change log | |
1749 @kindex C-x 4 a | |
1750 @findex add-change-log-entry-other-window | |
1751 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log | |
1752 file for the file you are editing | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1753 (@code{add-change-log-entry-other-window}). If that file is actually |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1754 a backup file, it makes an entry appropriate for the file's |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1755 parent---that is useful for making log entries for functions that |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1756 have been deleted in the current version. |
25829 | 1757 |
1758 A change log file contains a chronological record of when and why you | |
1759 have changed a program, consisting of a sequence of entries describing | |
1760 individual changes. Normally it is kept in a file called | |
1761 @file{ChangeLog} in the same directory as the file you are editing, or | |
1762 one of its parent directories. A single @file{ChangeLog} file can | |
1763 record changes for all the files in its directory and all its | |
1764 subdirectories. | |
1765 | |
1766 A change log entry starts with a header line that contains your name, | |
1767 your email address (taken from the variable @code{user-mail-address}), | |
1768 and the current date and time. Aside from these header lines, every | |
1769 line in the change log starts with a space or a tab. The bulk of the | |
1770 entry consists of @dfn{items}, each of which starts with a line starting | |
1771 with whitespace and a star. Here are two entries, both dated in May | |
1772 1993, each with two items: | |
1773 | |
1774 @iftex | |
1775 @medbreak | |
1776 @end iftex | |
1777 @smallexample | |
1778 1993-05-25 Richard Stallman <rms@@gnu.org> | |
1779 | |
1780 * man.el: Rename symbols `man-*' to `Man-*'. | |
1781 (manual-entry): Make prompt string clearer. | |
1782 | |
1783 * simple.el (blink-matching-paren-distance): | |
1784 Change default to 12,000. | |
1785 | |
1786 1993-05-24 Richard Stallman <rms@@gnu.org> | |
1787 | |
1788 * vc.el (minor-mode-map-alist): Don't use it if it's void. | |
1789 (vc-cancel-version): Doc fix. | |
1790 @end smallexample | |
1791 | |
1792 One entry can describe several changes; each change should have its | |
1793 own item. Normally there should be a blank line between items. When | |
1794 items are related (parts of the same change, in different places), group | |
1795 them by leaving no blank line between them. The second entry above | |
1796 contains two items grouped in this way. | |
1797 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1798 @kbd{C-x 4 a} visits the change log file and creates a new entry |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1799 unless the most recent entry is for today's date and your name. It |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1800 also creates a new item for the current file. For many languages, it |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1801 can even guess the name of the function or other object that was |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1802 changed. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1803 |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
1804 @vindex add-log-keep-changes-together |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1805 When the option @code{add-log-keep-changes-together} is |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1806 non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1807 rather than starting a new entry. |
25829 | 1808 |
31052
b05772d7c2ad
Document change-log-version-info-enabled and
Eli Zaretskii <eliz@gnu.org>
parents:
31035
diff
changeset
|
1809 @vindex change-log-version-info-enabled |
b05772d7c2ad
Document change-log-version-info-enabled and
Eli Zaretskii <eliz@gnu.org>
parents:
31035
diff
changeset
|
1810 @vindex change-log-version-number-regexp-list |
b05772d7c2ad
Document change-log-version-info-enabled and
Eli Zaretskii <eliz@gnu.org>
parents:
31035
diff
changeset
|
1811 @cindex file version in change log entries |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1812 If the value of the variable @code{change-log-version-info-enabled} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1813 is non-@code{nil}, @kbd{C-x 4 a} ads the file's version number to the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1814 change log entry. It finds the version number by searching the first |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1815 ten percent of the file, using regular expressions from the variable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1816 @code{change-log-version-number-regexp-list}. |
31052
b05772d7c2ad
Document change-log-version-info-enabled and
Eli Zaretskii <eliz@gnu.org>
parents:
31035
diff
changeset
|
1817 |
25829 | 1818 @cindex Change Log mode |
1819 @findex change-log-mode | |
1820 The change log file is visited in Change Log mode. In this major | |
1821 mode, each bunch of grouped items counts as one paragraph, and each | |
1822 entry is considered a page. This facilitates editing the entries. | |
1823 @kbd{C-j} and auto-fill indent each new line like the previous line; | |
1824 this is convenient for entering the contents of an entry. | |
1825 | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
1826 @findex change-log-merge |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1827 You can use the command @kbd{M-x change-log-merge} to merge other |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1828 log files into a buffer in Change Log Mode, preserving the date |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1829 ordering of entries. |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
1830 |
30850
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1831 @findex change-log-redate |
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1832 @cindex converting change log date style |
30968
2dfd4d6a9043
Remove redundant description of change-log-redate.
Eli Zaretskii <eliz@gnu.org>
parents:
30850
diff
changeset
|
1833 Versions of Emacs before 20.1 used a different format for the time of |
2dfd4d6a9043
Remove redundant description of change-log-redate.
Eli Zaretskii <eliz@gnu.org>
parents:
30850
diff
changeset
|
1834 the change log entry: |
30850
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1835 |
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1836 @smallexample |
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1837 Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org> |
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1838 @end smallexample |
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1839 |
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1840 @noindent |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1841 The @kbd{M-x change-log-redate} command converts all the old-style |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1842 date entries in the change log file visited in the current buffer to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1843 the new format, to make the file uniform in style. This is handy when |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1844 entries are contributed by many different people, some of whom use old |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1845 versions of Emacs. |
30850
befd90253848
Document the new change-log-redate command.
Eli Zaretskii <eliz@gnu.org>
parents:
30810
diff
changeset
|
1846 |
25829 | 1847 Version control systems are another way to keep track of changes in your |
1848 program and keep a change log. @xref{Log Buffer}. | |
1849 | |
30793 | 1850 @node Authors |
1851 @section @file{AUTHORS} files | |
1852 @cindex @file{AUTHORS} file | |
1853 | |
1854 Programs which have many contributors usually include a file named | |
1855 @file{AUTHORS} in their distribution, which lists the individual | |
1856 contributions. Emacs has a special command for maintaining the | |
1857 @file{AUTHORS} file that is part of the Emacs distribution. | |
1858 | |
1859 @findex authors | |
1860 The @kbd{M-x authors} command prompts for the name of the root of the | |
1861 Emacs source directory. It then scans @file{ChageLog} files and Lisp | |
1862 source files under that directory for information about authors of | |
1863 individual packages and people who made changes in source files, and | |
1864 puts the information it gleans into a buffer named @samp{*Authors*}. | |
1865 You can then edit the contents of that buffer and merge it with the | |
1866 exisiting @file{AUTHORS} file. | |
1867 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1868 Do not assume that this command finds all the contributors; don't |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1869 assume that a person not listed in the output was not a contributor. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1870 If you merged in someone's contribution and did not put his name |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1871 in the change log, he won't show up in @kbd{M-x authors} either. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1872 |
25829 | 1873 @node Tags |
1874 @section Tags Tables | |
1875 @cindex tags table | |
1876 | |
1877 A @dfn{tags table} is a description of how a multi-file program is | |
1878 broken up into files. It lists the names of the component files and the | |
1879 names and positions of the functions (or other named subunits) in each | |
1880 file. Grouping the related files makes it possible to search or replace | |
1881 through all the files with one command. Recording the function names | |
1882 and positions makes possible the @kbd{M-.} command which finds the | |
1883 definition of a function by looking up which of the files it is in. | |
1884 | |
1885 Tags tables are stored in files called @dfn{tags table files}. The | |
1886 conventional name for a tags table file is @file{TAGS}. | |
1887 | |
1888 Each entry in the tags table records the name of one tag, the name of the | |
1889 file that the tag is defined in (implicitly), and the position in that file | |
1890 of the tag's definition. | |
1891 | |
1892 Just what names from the described files are recorded in the tags table | |
1893 depends on the programming language of the described file. They | |
36737
71af0a08c2cc
Mention that file names are tags.
Francesco Potortì <pot@gnu.org>
parents:
36263
diff
changeset
|
1894 normally include all file names, functions and subroutines, and may |
71af0a08c2cc
Mention that file names are tags.
Francesco Potortì <pot@gnu.org>
parents:
36263
diff
changeset
|
1895 also include global variables, data types, and anything else |
71af0a08c2cc
Mention that file names are tags.
Francesco Potortì <pot@gnu.org>
parents:
36263
diff
changeset
|
1896 convenient. Each name recorded is called a @dfn{tag}. |
25829 | 1897 |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1898 @cindex C++ class browser, tags |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1899 @cindex tags, C++ |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1900 @cindex class browser, C++ |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1901 @cindex Ebrowse |
37868
ac2238e335f8
Fix some xrefs to other manuals.
Richard M. Stallman <rms@gnu.org>
parents:
36786
diff
changeset
|
1902 See also the Ebrowse facility, which is tailored for C++. |
ac2238e335f8
Fix some xrefs to other manuals.
Richard M. Stallman <rms@gnu.org>
parents:
36786
diff
changeset
|
1903 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}. |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
1904 |
25829 | 1905 @menu |
26264 | 1906 * Tag Syntax:: Tag syntax for various types of code and text files. |
25829 | 1907 * Create Tags Table:: Creating a tags table with @code{etags}. |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
1908 * Etags Regexps:: Create arbitrary tags using regular expressions. |
25829 | 1909 * Select Tags Table:: How to visit a tags table. |
26264 | 1910 * Find Tag:: Commands to find the definition of a specific tag. |
25829 | 1911 * Tags Search:: Using a tags table for searching and replacing. |
1912 * List Tags:: Listing and finding tags defined in a file. | |
1913 @end menu | |
1914 | |
1915 @node Tag Syntax | |
1916 @subsection Source File Tag Syntax | |
1917 | |
1918 Here is how tag syntax is defined for the most popular languages: | |
1919 | |
1920 @itemize @bullet | |
1921 @item | |
1922 In C code, any C function or typedef is a tag, and so are definitions of | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1923 @code{struct}, @code{union} and @code{enum}. |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
1924 @code{#define} macro definitions and @code{enum} constants are also |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
1925 tags, unless you specify @samp{--no-defines} when making the tags table. |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
1926 Similarly, global variables are tags, unless you specify |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
1927 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines} |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
1928 can make the tags table file much smaller. |
25829 | 1929 |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1930 You can tag function declarations and external variables in addition |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1931 to function definitions by giving the @samp{--declarations} option to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1932 @code{etags}. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1933 |
25829 | 1934 @item |
1935 In C++ code, in addition to all the tag constructs of C code, member | |
1936 functions are also recognized, and optionally member variables if you | |
1937 use the @samp{--members} option. Tags for variables and functions in | |
1938 classes are named @samp{@var{class}::@var{variable}} and | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1939 @samp{@var{class}::@var{function}}. @code{operator} definitions have |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1940 tag names like @samp{operator+}. |
25829 | 1941 |
1942 @item | |
1943 In Java code, tags include all the constructs recognized in C++, plus | |
26264 | 1944 the @code{interface}, @code{extends} and @code{implements} constructs. |
1945 Tags for variables and functions in classes are named | |
1946 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. | |
25829 | 1947 |
1948 @item | |
1949 In La@TeX{} text, the argument of any of the commands @code{\chapter}, | |
1950 @code{\section}, @code{\subsection}, @code{\subsubsection}, | |
1951 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, | |
1952 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a | |
1953 tag.@refill | |
1954 | |
1955 Other commands can make tags as well, if you specify them in the | |
29107 | 1956 environment variable @env{TEXTAGS} before invoking @code{etags}. The |
25829 | 1957 value of this environment variable should be a colon-separated list of |
1958 command names. For example, | |
1959 | |
1960 @example | |
1961 TEXTAGS="def:newcommand:newenvironment" | |
1962 export TEXTAGS | |
1963 @end example | |
1964 | |
1965 @noindent | |
1966 specifies (using Bourne shell syntax) that the commands @samp{\def}, | |
1967 @samp{\newcommand} and @samp{\newenvironment} also define tags. | |
1968 | |
1969 @item | |
1970 In Lisp code, any function defined with @code{defun}, any variable | |
1971 defined with @code{defvar} or @code{defconst}, and in general the first | |
1972 argument of any expression that starts with @samp{(def} in column zero, is | |
1973 a tag. | |
1974 | |
1975 @item | |
1976 In Scheme code, tags include anything defined with @code{def} or with a | |
1977 construct whose name starts with @samp{def}. They also include variables | |
1978 set with @code{set!} at top level in the file. | |
1979 @end itemize | |
1980 | |
1981 Several other languages are also supported: | |
1982 | |
1983 @itemize @bullet | |
26264 | 1984 |
1985 @item | |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
1986 In Ada code, functions, procedures, packages, tasks, and types are |
35298
f5b916018b7e
Added instructions for use of Ada tags.
Francesco Potortì <pot@gnu.org>
parents:
35297
diff
changeset
|
1987 tags. Use the @samp{--packages-only} option to create tags for |
f5b916018b7e
Added instructions for use of Ada tags.
Francesco Potortì <pot@gnu.org>
parents:
35297
diff
changeset
|
1988 packages only. |
f5b916018b7e
Added instructions for use of Ada tags.
Francesco Potortì <pot@gnu.org>
parents:
35297
diff
changeset
|
1989 |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1990 In Ada, the same name can be used for different kinds of entity |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1991 (e.g.@:, for a procedure and for a function). Also, for things like |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1992 packages, procedures and functions, there is the spec (i.e.@: the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1993 interface) and the body (i.e.@: the implementation). To make it |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1994 easier to pick the definition you want, Ada tag name have suffixes |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1995 indicating the type of entity: |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1996 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1997 @table @samp |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1998 @item /b |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
1999 package body. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2000 @item /f |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2001 function. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2002 @item /k |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2003 task. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2004 @item /p |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2005 procedure. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2006 @item /s |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2007 package spec. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2008 @item /t |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2009 type. |
35298
f5b916018b7e
Added instructions for use of Ada tags.
Francesco Potortì <pot@gnu.org>
parents:
35297
diff
changeset
|
2010 @end table |
f5b916018b7e
Added instructions for use of Ada tags.
Francesco Potortì <pot@gnu.org>
parents:
35297
diff
changeset
|
2011 |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2012 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2013 directly to the body of the package @code{bidule}, while @kbd{M-x |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2014 find-tag @key{RET} bidule @key{RET}} will just search for any tag |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2015 @code{bidule}. |
26264 | 2016 |
25829 | 2017 @item |
2018 In assembler code, labels appearing at the beginning of a line, | |
2019 followed by a colon, are tags. | |
2020 | |
2021 @item | |
2022 In Bison or Yacc input files, each rule defines as a tag the nonterminal | |
2023 it constructs. The portions of the file that contain C code are parsed | |
2024 as C code. | |
2025 | |
2026 @item | |
2027 In Cobol code, tags are paragraph names; that is, any word starting in | |
2028 column 8 and followed by a period. | |
2029 | |
2030 @item | |
2031 In Erlang code, the tags are the functions, records, and macros defined | |
2032 in the file. | |
2033 | |
2034 @item | |
2035 In Fortran code, functions, subroutines and blockdata are tags. | |
2036 | |
2037 @item | |
35297
e268b7b500f0
Changes for makefile support in etags.
Francesco Potortì <pot@gnu.org>
parents:
35059
diff
changeset
|
2038 In makefiles, targets are tags. |
e268b7b500f0
Changes for makefile support in etags.
Francesco Potortì <pot@gnu.org>
parents:
35059
diff
changeset
|
2039 |
e268b7b500f0
Changes for makefile support in etags.
Francesco Potortì <pot@gnu.org>
parents:
35059
diff
changeset
|
2040 @item |
25829 | 2041 In Objective C code, tags include Objective C definitions for classes, |
2042 class categories, methods, and protocols. | |
2043 | |
2044 @item | |
2045 In Pascal code, the tags are the functions and procedures defined in | |
2046 the file. | |
2047 | |
2048 @item | |
26264 | 2049 In Perl code, the tags are the procedures defined by the @code{sub}, |
2050 @code{my} and @code{local} keywords. Use @samp{--globals} if you want | |
2051 to tag global variables. | |
25829 | 2052 |
2053 @item | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
2054 In PostScript code, the tags are the functions. |
25829 | 2055 |
2056 @item | |
2057 In Prolog code, a tag name appears at the left margin. | |
2058 | |
26264 | 2059 @item |
2060 In Python code, @code{def} or @code{class} at the beginning of a line | |
2061 generate a tag. | |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2062 @end itemize |
26264 | 2063 |
26462 | 2064 You can also generate tags based on regexp matching (@pxref{Etags |
26264 | 2065 Regexps}) to handle other formats and languages. |
25829 | 2066 |
2067 @node Create Tags Table | |
2068 @subsection Creating Tags Tables | |
2069 @cindex @code{etags} program | |
2070 | |
2071 The @code{etags} program is used to create a tags table file. It knows | |
2072 the syntax of several languages, as described in | |
2073 @iftex | |
2074 the previous section. | |
2075 @end iftex | |
2076 @ifinfo | |
2077 @ref{Tag Syntax}. | |
2078 @end ifinfo | |
2079 Here is how to run @code{etags}: | |
2080 | |
2081 @example | |
2082 etags @var{inputfiles}@dots{} | |
2083 @end example | |
2084 | |
2085 @noindent | |
26264 | 2086 The @code{etags} program reads the specified files, and writes a tags |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2087 table named @file{TAGS} in the current working directory. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2088 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2089 If the specified files don't exist, @code{etags} looks for |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2090 compressed versions of them and uncompresses them to read them. Under |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2091 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2092 if it is given @samp{mycode.c} on the command line and @file{mycode.c} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2093 does not exist. |
26264 | 2094 |
2095 @code{etags} recognizes the language used in an input file based on | |
2096 its file name and contents. You can specify the language with the | |
25829 | 2097 @samp{--language=@var{name}} option, described below. |
2098 | |
2099 If the tags table data become outdated due to changes in the files | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2100 described in the table, the way to update the tags table is the same |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2101 way it was made in the first place. But it is not necessary to do |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2102 this very often. |
25829 | 2103 |
2104 If the tags table fails to record a tag, or records it for the wrong | |
2105 file, then Emacs cannot possibly find its definition. However, if the | |
2106 position recorded in the tags table becomes a little bit wrong (due to | |
2107 some editing in the file that the tag definition is in), the only | |
2108 consequence is a slight delay in finding the tag. Even if the stored | |
2109 position is very wrong, Emacs will still find the tag, but it must | |
2110 search the entire file for it. | |
2111 | |
2112 So you should update a tags table when you define new tags that you want | |
2113 to have listed, or when you move tag definitions from one file to another, | |
2114 or when changes become substantial. Normally there is no need to update | |
2115 the tags table after each edit, or even every day. | |
2116 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2117 One tags table can virtually include another. Specify the included |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2118 tags file name with the @samp{--include=@var{file}} option when |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2119 creating the file that is to include it. The latter file then acts as |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2120 if it covered all the source files specified in the included file, as |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2121 well as the files it directly contains. |
25829 | 2122 |
2123 If you specify the source files with relative file names when you run | |
2124 @code{etags}, the tags file will contain file names relative to the | |
2125 directory where the tags file was initially written. This way, you can | |
2126 move an entire directory tree containing both the tags file and the | |
2127 source files, and the tags file will still refer correctly to the source | |
2128 files. | |
2129 | |
2130 If you specify absolute file names as arguments to @code{etags}, then | |
2131 the tags file will contain absolute file names. This way, the tags file | |
2132 will still refer to the same files even if you move it, as long as the | |
2133 source files remain in the same place. Absolute file names start with | |
2134 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. | |
2135 | |
2136 When you want to make a tags table from a great number of files, you | |
2137 may have problems listing them on the command line, because some systems | |
2138 have a limit on its length. The simplest way to circumvent this limit | |
2139 is to tell @code{etags} to read the file names from its standard input, | |
2140 by typing a dash in place of the file names, like this: | |
2141 | |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2142 @smallexample |
25829 | 2143 find . -name "*.[chCH]" -print | etags - |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2144 @end smallexample |
25829 | 2145 |
2146 Use the option @samp{--language=@var{name}} to specify the language | |
2147 explicitly. You can intermix these options with file names; each one | |
2148 applies to the file names that follow it. Specify | |
2149 @samp{--language=auto} to tell @code{etags} to resume guessing the | |
2150 language from the file names and file contents. Specify | |
2151 @samp{--language=none} to turn off language-specific processing | |
26264 | 2152 entirely; then @code{etags} recognizes tags by regexp matching alone |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2153 (@pxref{Etags Regexps}). |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2154 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2155 @samp{etags --help} prints the list of the languages @code{etags} |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2156 knows, and the file name rules for guessing the language. It also prints |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2157 a list of all the available @code{etags} options, together with a short |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2158 explanation. |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2159 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2160 @node Etags Regexps |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2161 @subsection Etags Regexps |
25829 | 2162 |
2163 The @samp{--regex} option provides a general way of recognizing tags | |
2164 based on regexp matching. You can freely intermix it with file names. | |
2165 Each @samp{--regex} option adds to the preceding ones, and applies only | |
2166 to the following files. The syntax is: | |
2167 | |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2168 @smallexample |
25829 | 2169 --regex=/@var{tagregexp}[/@var{nameregexp}]/ |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2170 @end smallexample |
26264 | 2171 |
25829 | 2172 @noindent |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2173 where @var{tagregexp} is used to match the lines to tag. It is always |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2174 anchored, that is, it behaves as if preceded by @samp{^}. If you want |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2175 to account for indentation, just match any initial number of blanks by |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2176 beginning your regular expression with @samp{[ \t]*}. In the regular |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2177 expressions, @samp{\} quotes the next character, and @samp{\t} stands |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2178 for the tab character. Note that @code{etags} does not handle the other |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2179 C escape sequences for special characters. |
25829 | 2180 |
2181 @cindex interval operator (in regexps) | |
2182 The syntax of regular expressions in @code{etags} is the same as in | |
2183 Emacs, augmented with the @dfn{interval operator}, which works as in | |
2184 @code{grep} and @code{ed}. The syntax of an interval operator is | |
2185 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding | |
2186 expression at least @var{m} times and up to @var{n} times. | |
2187 | |
2188 You should not match more characters with @var{tagregexp} than that | |
2189 needed to recognize what you want to tag. If the match is such that | |
26106 | 2190 more characters than needed are unavoidably matched by @var{tagregexp} |
2191 (as will usually be the case), you should add a @var{nameregexp}, to | |
2192 pick out just the tag. This will enable Emacs to find tags more | |
2193 accurately and to do completion on tag names more reliably. You can | |
2194 find some examples below. | |
2195 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2196 The option @samp{--ignore-case-regex} (or @samp{-c}) works like |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2197 @samp{--regex}, except that matching ignores case. This is |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2198 appropriate for certain programming languages. |
25829 | 2199 |
2200 The @samp{-R} option deletes all the regexps defined with | |
2201 @samp{--regex} options. It applies to the file names following it, as | |
2202 you can see from the following example: | |
2203 | |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2204 @smallexample |
25829 | 2205 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \ |
2206 bar.ber -R --lang=lisp los.er | |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2207 @end smallexample |
25829 | 2208 |
2209 @noindent | |
2210 Here @code{etags} chooses the parsing language for @file{voo.doo} and | |
2211 @file{bar.ber} according to their contents. @code{etags} also uses | |
2212 @var{reg1} to recognize additional tags in @file{voo.doo}, and both | |
2213 @var{reg1} and @var{reg2} to recognize additional tags in | |
2214 @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp | |
2215 matching, to recognize tags in @file{los.er}. | |
2216 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2217 You can specify a regular expression for a particular language, by |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2218 writing @samp{@{lang@}} in front of it. Then @code{etags} will use |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2219 the regular expression only for files of that language. (@samp{etags |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2220 --help} prints the list of languages recognised by @code{etags}.) The |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2221 following example tags the @code{DEFVAR} macros in the Emacs source |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2222 files, for the C language only: |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2223 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2224 @smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2225 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2226 @end smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2227 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2228 @noindent |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2229 This feature is particularly useful when you store a list of regular |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2230 expressions in a file. The following option syntax instructs |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2231 @code{etags} to read two files of regular expressions. The regular |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2232 expressions contained in the second file are matched without regard to |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2233 case. |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2234 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2235 @smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2236 --regex=@@first-file --ignore-case-regex=@@second-file |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2237 @end smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2238 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2239 @noindent |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2240 A regex file contains one regular expressions per line. Empty lines, |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2241 and lines beginning with space or tab are ignored. When the first |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2242 character in a line is @samp{@@}, @code{etags} assumes that the rest |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2243 of the line is the name of a file of regular expressions; thus, one |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2244 such file can include another file. All the other lines are taken to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2245 be regular expressions. If the first non-whitespace text on the line |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2246 is @samp{--}, that line is a comment. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2247 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2248 For example, one can create a file called @samp{emacs.tags} with the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2249 following contents: |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2250 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2251 @smallexample |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2252 -- This is for GNU Emacs C source files |
26289
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2253 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2254 @end smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2255 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2256 @noindent |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2257 and then use it like this: |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2258 |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2259 @smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2260 etags --regex=@@emacs.tags *.[ch] */*.[ch] |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2261 @end smallexample |
6651db4a4b1f
Document regexp changes in etags.
Francesco Potortì <pot@gnu.org>
parents:
26264
diff
changeset
|
2262 |
25829 | 2263 Here are some more examples. The regexps are quoted to protect them |
2264 from shell interpretation. | |
2265 | |
2266 @itemize @bullet | |
2267 | |
2268 @item | |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2269 Tag Octave files: |
25829 | 2270 |
2271 @smallexample | |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2272 etags --language=none \ |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2273 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2274 --regex='/###key \(.*\)/\1/' \ |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2275 --regex='/[ \t]*global[ \t].*/' \ |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2276 *.m |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2277 @end smallexample |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2278 |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2279 @noindent |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2280 Note that tags are not generated for scripts, so that you have to add |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2281 a line by yourself of the form @samp{###key @var{scriptname}} if you |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2282 want to jump to it. |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2283 |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2284 @item |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2285 Tag Tcl files: |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2286 |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2287 @smallexample |
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2288 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl |
25829 | 2289 @end smallexample |
2290 | |
2291 @item | |
26292
81cd0c225dd9
Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents:
26289
diff
changeset
|
2292 Tag VHDL files: |
25829 | 2293 |
2294 @smallexample | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2295 etags --language=none \ |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2296 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2297 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2298 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' |
25829 | 2299 @end smallexample |
2300 @end itemize | |
2301 | |
2302 @node Select Tags Table | |
2303 @subsection Selecting a Tags Table | |
2304 | |
2305 @vindex tags-file-name | |
2306 @findex visit-tags-table | |
2307 Emacs has at any time one @dfn{selected} tags table, and all the commands | |
2308 for working with tags tables use the selected one. To select a tags table, | |
2309 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an | |
2310 argument. The name @file{TAGS} in the default directory is used as the | |
2311 default file name. | |
2312 | |
2313 All this command does is store the file name in the variable | |
2314 @code{tags-file-name}. Emacs does not actually read in the tags table | |
2315 contents until you try to use them. Setting this variable yourself is just | |
2316 as good as using @code{visit-tags-table}. The variable's initial value is | |
2317 @code{nil}; that value tells all the commands for working with tags tables | |
2318 that they must ask for a tags table file name to use. | |
2319 | |
2320 Using @code{visit-tags-table} when a tags table is already loaded | |
2321 gives you a choice: you can add the new tags table to the current list | |
2322 of tags tables, or start a new list. The tags commands use all the tags | |
2323 tables in the current list. If you start a new list, the new tags table | |
2324 is used @emph{instead} of others. If you add the new table to the | |
2325 current list, it is used @emph{as well as} the others. When the tags | |
2326 commands scan the list of tags tables, they don't always start at the | |
2327 beginning of the list; they start with the first tags table (if any) | |
2328 that describes the current file, proceed from there to the end of the | |
2329 list, and then scan from the beginning of the list until they have | |
2330 covered all the tables in the list. | |
2331 | |
2332 @vindex tags-table-list | |
2333 You can specify a precise list of tags tables by setting the variable | |
2334 @code{tags-table-list} to a list of strings, like this: | |
2335 | |
2336 @c keep this on two lines for formatting in smallbook | |
2337 @example | |
2338 @group | |
2339 (setq tags-table-list | |
2340 '("~/emacs" "/usr/local/lib/emacs/src")) | |
2341 @end group | |
2342 @end example | |
2343 | |
2344 @noindent | |
2345 This tells the tags commands to look at the @file{TAGS} files in your | |
2346 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} | |
2347 directory. The order depends on which file you are in and which tags | |
2348 table mentions that file, as explained above. | |
2349 | |
2350 Do not set both @code{tags-file-name} and @code{tags-table-list}. | |
2351 | |
2352 @node Find Tag | |
2353 @subsection Finding a Tag | |
2354 | |
2355 The most important thing that a tags table enables you to do is to find | |
2356 the definition of a specific tag. | |
2357 | |
2358 @table @kbd | |
2359 @item M-.@: @var{tag} @key{RET} | |
2360 Find first definition of @var{tag} (@code{find-tag}). | |
2361 @item C-u M-. | |
2362 Find next alternate definition of last tag specified. | |
2363 @item C-u - M-. | |
2364 Go back to previous tag found. | |
2365 @item C-M-. @var{pattern} @key{RET} | |
2366 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). | |
2367 @item C-u C-M-. | |
2368 Find the next tag whose name matches the last pattern used. | |
2369 @item C-x 4 .@: @var{tag} @key{RET} | |
2370 Find first definition of @var{tag}, but display it in another window | |
2371 (@code{find-tag-other-window}). | |
2372 @item C-x 5 .@: @var{tag} @key{RET} | |
2373 Find first definition of @var{tag}, and create a new frame to select the | |
2374 buffer (@code{find-tag-other-frame}). | |
2375 @item M-* | |
2376 Pop back to where you previously invoked @kbd{M-.} and friends. | |
2377 @end table | |
2378 | |
2379 @kindex M-. | |
2380 @findex find-tag | |
2381 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of | |
2382 a specified tag. It searches through the tags table for that tag, as a | |
2383 string, and then uses the tags table info to determine the file that the | |
2384 definition is in and the approximate character position in the file of | |
2385 the definition. Then @code{find-tag} visits that file, moves point to | |
2386 the approximate character position, and searches ever-increasing | |
2387 distances away to find the tag definition. | |
2388 | |
2389 If an empty argument is given (just type @key{RET}), the sexp in the | |
2390 buffer before or around point is used as the @var{tag} argument. | |
2391 @xref{Lists}, for info on sexps. | |
2392 | |
2393 You don't need to give @kbd{M-.} the full name of the tag; a part | |
2394 will do. This is because @kbd{M-.} finds tags in the table which | |
2395 contain @var{tag} as a substring. However, it prefers an exact match | |
2396 to a substring match. To find other tags that match the same | |
2397 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u | |
2398 M-.}; this does not read a tag name, but continues searching the tags | |
2399 table's text for another tag containing the same substring last used. | |
2400 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier | |
2401 alternative to @kbd{C-u M-.}. | |
2402 | |
2403 @kindex C-x 4 . | |
2404 @findex find-tag-other-window | |
2405 @kindex C-x 5 . | |
2406 @findex find-tag-other-frame | |
2407 Like most commands that can switch buffers, @code{find-tag} has a | |
2408 variant that displays the new buffer in another window, and one that | |
2409 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes | |
2410 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .}, | |
2411 which invokes @code{find-tag-other-frame}. | |
2412 | |
2413 To move back to places you've found tags recently, use @kbd{C-u - | |
2414 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This | |
2415 command can take you to another buffer. @kbd{C-x 4 .} with a negative | |
2416 argument finds the previous tag location in another window. | |
2417 | |
2418 @kindex M-* | |
2419 @findex pop-tag-mark | |
2420 @vindex find-tag-marker-ring-length | |
2421 As well as going back to places you've found tags recently, you can go | |
2422 back to places @emph{from where} you found them. Use @kbd{M-*}, which | |
2423 invokes the command @code{pop-tag-mark}, for this. Typically you would | |
2424 find and study the definition of something with @kbd{M-.} and then | |
2425 return to where you were with @kbd{M-*}. | |
2426 | |
2427 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to | |
2428 a depth determined by the variable @code{find-tag-marker-ring-length}. | |
2429 | |
2430 @findex find-tag-regexp | |
2431 @kindex C-M-. | |
2432 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that | |
2433 match a specified regular expression. It is just like @kbd{M-.} except | |
2434 that it does regexp matching instead of substring matching. | |
2435 | |
2436 @node Tags Search | |
2437 @subsection Searching and Replacing with Tags Tables | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2438 @cindex search and replace in multiple files |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2439 @cindex multiple-file search and replace |
25829 | 2440 |
2441 The commands in this section visit and search all the files listed in the | |
2442 selected tags table, one by one. For these commands, the tags table serves | |
2443 only to specify a sequence of files to search. | |
2444 | |
2445 @table @kbd | |
2446 @item M-x tags-search @key{RET} @var{regexp} @key{RET} | |
2447 Search for @var{regexp} through the files in the selected tags | |
2448 table. | |
2449 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} | |
2450 Perform a @code{query-replace-regexp} on each file in the selected tags table. | |
2451 @item M-, | |
2452 Restart one of the commands above, from the current location of point | |
2453 (@code{tags-loop-continue}). | |
2454 @end table | |
2455 | |
2456 @findex tags-search | |
2457 @kbd{M-x tags-search} reads a regexp using the minibuffer, then | |
2458 searches for matches in all the files in the selected tags table, one | |
2459 file at a time. It displays the name of the file being searched so you | |
2460 can follow its progress. As soon as it finds an occurrence, | |
2461 @code{tags-search} returns. | |
2462 | |
2463 @kindex M-, | |
2464 @findex tags-loop-continue | |
2465 Having found one match, you probably want to find all the rest. To find | |
2466 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the | |
2467 @code{tags-search}. This searches the rest of the current buffer, followed | |
2468 by the remaining files of the tags table.@refill | |
2469 | |
2470 @findex tags-query-replace | |
2471 @kbd{M-x tags-query-replace} performs a single | |
2472 @code{query-replace-regexp} through all the files in the tags table. It | |
2473 reads a regexp to search for and a string to replace with, just like | |
2474 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x | |
2475 tags-search}, but repeatedly, processing matches according to your | |
2476 input. @xref{Replace}, for more information on query replace. | |
2477 | |
31065
357e242b7f87
Document tags-case-fold-search, tags-apropos-verbose and tags-tag-face.
Eli Zaretskii <eliz@gnu.org>
parents:
31052
diff
changeset
|
2478 @vindex tags-case-fold-search |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2479 @cindex case-sensitivity and tags search |
31065
357e242b7f87
Document tags-case-fold-search, tags-apropos-verbose and tags-tag-face.
Eli Zaretskii <eliz@gnu.org>
parents:
31052
diff
changeset
|
2480 You can control the case-sensitivity of tags search commands by |
357e242b7f87
Document tags-case-fold-search, tags-apropos-verbose and tags-tag-face.
Eli Zaretskii <eliz@gnu.org>
parents:
31052
diff
changeset
|
2481 customizing the value of the variable @code{tags-case-fold-search}. The |
357e242b7f87
Document tags-case-fold-search, tags-apropos-verbose and tags-tag-face.
Eli Zaretskii <eliz@gnu.org>
parents:
31052
diff
changeset
|
2482 default is to use the same setting as the value of |
357e242b7f87
Document tags-case-fold-search, tags-apropos-verbose and tags-tag-face.
Eli Zaretskii <eliz@gnu.org>
parents:
31052
diff
changeset
|
2483 @code{case-fold-search} (@pxref{Search Case}). |
357e242b7f87
Document tags-case-fold-search, tags-apropos-verbose and tags-tag-face.
Eli Zaretskii <eliz@gnu.org>
parents:
31052
diff
changeset
|
2484 |
25829 | 2485 It is possible to get through all the files in the tags table with a |
2486 single invocation of @kbd{M-x tags-query-replace}. But often it is | |
2487 useful to exit temporarily, which you can do with any input event that | |
2488 has no special query replace meaning. You can resume the query replace | |
2489 subsequently by typing @kbd{M-,}; this command resumes the last tags | |
2490 search or replace command that you did. | |
2491 | |
2492 The commands in this section carry out much broader searches than the | |
2493 @code{find-tag} family. The @code{find-tag} commands search only for | |
2494 definitions of tags that match your substring or regexp. The commands | |
2495 @code{tags-search} and @code{tags-query-replace} find every occurrence | |
2496 of the regexp, as ordinary search commands and replace commands do in | |
2497 the current buffer. | |
2498 | |
2499 These commands create buffers only temporarily for the files that they | |
2500 have to search (those which are not already visited in Emacs buffers). | |
2501 Buffers in which no match is found are quickly killed; the others | |
2502 continue to exist. | |
2503 | |
2504 It may have struck you that @code{tags-search} is a lot like | |
2505 @code{grep}. You can also run @code{grep} itself as an inferior of | |
2506 Emacs and have Emacs show you the matching lines one by one. This works | |
2507 much like running a compilation; finding the source locations of the | |
2508 @code{grep} matches works like finding the compilation errors. | |
2509 @xref{Compilation}. | |
26264 | 2510 |
25829 | 2511 @node List Tags |
2512 @subsection Tags Table Inquiries | |
2513 | |
2514 @table @kbd | |
2515 @item M-x list-tags @key{RET} @var{file} @key{RET} | |
2516 Display a list of the tags defined in the program file @var{file}. | |
2517 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET} | |
2518 Display a list of all tags matching @var{regexp}. | |
2519 @end table | |
2520 | |
2521 @findex list-tags | |
2522 @kbd{M-x list-tags} reads the name of one of the files described by | |
2523 the selected tags table, and displays a list of all the tags defined in | |
2524 that file. The ``file name'' argument is really just a string to | |
2525 compare against the file names recorded in the tags table; it is read as | |
2526 a string rather than as a file name. Therefore, completion and | |
2527 defaulting are not available, and you must enter the file name the same | |
2528 way it appears in the tags table. Do not include a directory as part of | |
2529 the file name unless the file name recorded in the tags table includes a | |
2530 directory. | |
2531 | |
2532 @findex tags-apropos | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2533 @vindex tags-apropos-verbose |
25829 | 2534 @kbd{M-x tags-apropos} is like @code{apropos} for tags |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2535 (@pxref{Apropos}). It finds all the tags in the selected tags table |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2536 whose entries match @var{regexp}, and displays them. If the variable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2537 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2538 of the tags files together with the tag names. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2539 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2540 @vindex tags-tag-face |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
2541 @vindex tags-apropos-additional-actions |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2542 You can customize the appearance of the output with the face |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2543 @code{tags-tag-face}. You can display additional output with @kbd{M-x |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2544 tags-apropos} by customizing the variable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2545 @code{tags-apropos-additional-actions}---see its documentation for |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2546 details. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2547 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2548 You can also use the collection of tag names to complete a symbol |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2549 name in the buffer. @xref{Symbol Completion}. |
25829 | 2550 |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2551 @node Imenu |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2552 @section Imenu |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2553 @cindex indexes of buffer contents |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2554 @cindex buffer content indexes |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2555 @cindex tags |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2556 |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2557 The Imenu facility is another way to find definitions or sections |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2558 in a file. It is similar in spirit to Tags, but operates on a single |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2559 buffer only, and works entirely within Emacs with no need for a separate |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2560 tags table. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2561 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2562 @findex imenu |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2563 @findex imenu-add-menu-bar-index |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2564 If you type @kbd{M-x imenu}, it reads the name of a section or |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2565 definition in the current buffer, then goes to that section or |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2566 definition. You can use completion to specify the name, and a |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2567 complete list of possible names is always displayed. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2568 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2569 Alternatively you can bind the command @code{imenu} to a mouse |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2570 click. Then it displays mouse menus for you to select the section or |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2571 definition you want. You can also add the buffer's index to the menu |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2572 bar by calling @code{imenu-add-menu-bar-index}. If you want to have |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2573 this menu bar item available for all buffers in a certain major mode, |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2574 you can do this by adding @code{imenu-add-menu-bar-index} to its mode |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2575 hook. But then you will have to wait for the buffer to be searched |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2576 for sections and definitions, each time you visit a file which uses |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2577 that mode. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2578 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2579 @vindex imenu-auto-rescan |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2580 When you change the contents of a buffer, if you add or delete |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2581 definitions or sections, you can update the buffer's index to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2582 correspond to the new contents by invoking the @samp{*Rescan*} item in |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2583 the menu. Rescanning happens automatically if |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2584 @code{imenu-auto-rescan} is non-@code{nil}. There is no need to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2585 rescan because of small changes in the text. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2586 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2587 @vindex imenu-sort-function |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2588 You can customize the way the menus are sorted via the variable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2589 @code{imenu-sort-function}. By default names are ordered as they |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2590 occur in the buffer; alphabetic sorting is provided as an alternative. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2591 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2592 Imenu provides the information to guide Which Function mode |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2593 (@pxref{Which Function}). The Speedbar can also use it |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2594 (@pxref{Speedbar}). |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2595 |
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
2596 @node Emerge, C Modes, Imenu, Programs |
25829 | 2597 @section Merging Files with Emerge |
2598 @cindex Emerge | |
2599 @cindex merging files | |
2600 | |
2601 It's not unusual for programmers to get their signals crossed and modify | |
2602 the same program in two different directions. To recover from this | |
2603 confusion, you need to merge the two versions. Emerge makes this | |
2604 easier. See also @ref{Comparing Files}, for commands to compare | |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
2605 in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}. |
25829 | 2606 |
2607 @menu | |
2608 * Overview of Emerge:: How to start Emerge. Basic concepts. | |
2609 * Submodes of Emerge:: Fast mode vs. Edit mode. | |
2610 Skip Prefers mode and Auto Advance mode. | |
2611 * State of Difference:: You do the merge by specifying state A or B | |
2612 for each difference. | |
2613 * Merge Commands:: Commands for selecting a difference, | |
2614 changing states of differences, etc. | |
2615 * Exiting Emerge:: What to do when you've finished the merge. | |
2616 * Combining in Emerge:: How to keep both alternatives for a difference. | |
2617 * Fine Points of Emerge:: Misc. | |
2618 @end menu | |
2619 | |
2620 @node Overview of Emerge | |
2621 @subsection Overview of Emerge | |
2622 | |
2623 To start Emerge, run one of these four commands: | |
2624 | |
2625 @table @kbd | |
2626 @item M-x emerge-files | |
2627 @findex emerge-files | |
2628 Merge two specified files. | |
2629 | |
2630 @item M-x emerge-files-with-ancestor | |
2631 @findex emerge-files-with-ancestor | |
2632 Merge two specified files, with reference to a common ancestor. | |
2633 | |
2634 @item M-x emerge-buffers | |
2635 @findex emerge-buffers | |
2636 Merge two buffers. | |
2637 | |
2638 @item M-x emerge-buffers-with-ancestor | |
2639 @findex emerge-buffers-with-ancestor | |
2640 Merge two buffers with reference to a common ancestor in a third | |
2641 buffer. | |
2642 @end table | |
2643 | |
2644 @cindex merge buffer (Emerge) | |
2645 @cindex A and B buffers (Emerge) | |
2646 The Emerge commands compare two files or buffers, and display the | |
2647 comparison in three buffers: one for each input text (the @dfn{A buffer} | |
2648 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging | |
2649 takes place. The merge buffer shows the full merged text, not just the | |
2650 differences. Wherever the two input texts differ, you can choose which | |
2651 one of them to include in the merge buffer. | |
2652 | |
2653 The Emerge commands that take input from existing buffers use only the | |
2654 accessible portions of those buffers, if they are narrowed | |
2655 (@pxref{Narrowing}). | |
2656 | |
2657 If a common ancestor version is available, from which the two texts to | |
2658 be merged were both derived, Emerge can use it to guess which | |
2659 alternative is right. Wherever one current version agrees with the | |
2660 ancestor, Emerge presumes that the other current version is a deliberate | |
2661 change which should be kept in the merged version. Use the | |
2662 @samp{with-ancestor} commands if you want to specify a common ancestor | |
2663 text. These commands read three file or buffer names---variant A, | |
2664 variant B, and the common ancestor. | |
2665 | |
2666 After the comparison is done and the buffers are prepared, the | |
2667 interactive merging starts. You control the merging by typing special | |
2668 @dfn{merge commands} in the merge buffer. The merge buffer shows you a | |
2669 full merged text, not just differences. For each run of differences | |
2670 between the input texts, you can choose which one of them to keep, or | |
2671 edit them both together. | |
2672 | |
2673 The merge buffer uses a special major mode, Emerge mode, with commands | |
2674 for making these choices. But you can also edit the buffer with | |
2675 ordinary Emacs commands. | |
2676 | |
2677 At any given time, the attention of Emerge is focused on one | |
2678 particular difference, called the @dfn{selected} difference. This | |
2679 difference is marked off in the three buffers like this: | |
2680 | |
2681 @example | |
2682 vvvvvvvvvvvvvvvvvvvv | |
2683 @var{text that differs} | |
2684 ^^^^^^^^^^^^^^^^^^^^ | |
2685 @end example | |
2686 | |
2687 @noindent | |
2688 Emerge numbers all the differences sequentially and the mode | |
2689 line always shows the number of the selected difference. | |
2690 | |
2691 Normally, the merge buffer starts out with the A version of the text. | |
2692 But when the A version of a difference agrees with the common ancestor, | |
2693 then the B version is initially preferred for that difference. | |
2694 | |
2695 Emerge leaves the merged text in the merge buffer when you exit. At | |
2696 that point, you can save it in a file with @kbd{C-x C-w}. If you give a | |
2697 numeric argument to @code{emerge-files} or | |
2698 @code{emerge-files-with-ancestor}, it reads the name of the output file | |
2699 using the minibuffer. (This is the last file name those commands read.) | |
2700 Then exiting from Emerge saves the merged text in the output file. | |
2701 | |
2702 Normally, Emerge commands save the output buffer in its file when you | |
2703 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not | |
2704 save the output buffer, but you can save it yourself if you wish. | |
2705 | |
2706 @node Submodes of Emerge | |
2707 @subsection Submodes of Emerge | |
2708 | |
2709 You can choose between two modes for giving merge commands: Fast mode | |
2710 and Edit mode. In Fast mode, basic merge commands are single | |
2711 characters, but ordinary Emacs commands are disabled. This is | |
2712 convenient if you use only merge commands. In Edit mode, all merge | |
2713 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs | |
2714 commands are also available. This allows editing the merge buffer, but | |
2715 slows down Emerge operations. | |
2716 | |
2717 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to | |
2718 Fast mode. The mode line indicates Edit and Fast modes with @samp{E} | |
2719 and @samp{F}. | |
2720 | |
2721 Emerge has two additional submodes that affect how particular merge | |
2722 commands work: Auto Advance mode and Skip Prefers mode. | |
2723 | |
2724 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands | |
2725 advance to the next difference. This lets you go through the merge | |
2726 faster as long as you simply choose one of the alternatives from the | |
2727 input. The mode line indicates Auto Advance mode with @samp{A}. | |
2728 | |
2729 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands | |
2730 skip over differences in states prefer-A and prefer-B (@pxref{State of | |
2731 Difference}). Thus you see only differences for which neither version | |
2732 is presumed ``correct.'' The mode line indicates Skip Prefers mode with | |
2733 @samp{S}. | |
2734 | |
2735 @findex emerge-auto-advance-mode | |
2736 @findex emerge-skip-prefers-mode | |
2737 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or | |
2738 clear Auto Advance mode. Use @kbd{s s} | |
2739 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. | |
2740 These commands turn on the mode with a positive argument, turns it off | |
2741 with a negative or zero argument, and toggle the mode with no argument. | |
2742 | |
2743 @node State of Difference | |
2744 @subsection State of a Difference | |
2745 | |
2746 In the merge buffer, a difference is marked with lines of @samp{v} and | |
2747 @samp{^} characters. Each difference has one of these seven states: | |
2748 | |
2749 @table @asis | |
2750 @item A | |
2751 The difference is showing the A version. The @kbd{a} command always | |
2752 produces this state; the mode line indicates it with @samp{A}. | |
2753 | |
2754 @item B | |
2755 The difference is showing the B version. The @kbd{b} command always | |
2756 produces this state; the mode line indicates it with @samp{B}. | |
2757 | |
2758 @item default-A | |
2759 @itemx default-B | |
2760 The difference is showing the A or the B state by default, because you | |
2761 haven't made a choice. All differences start in the default-A state | |
2762 (and thus the merge buffer is a copy of the A buffer), except those for | |
2763 which one alternative is ``preferred'' (see below). | |
2764 | |
2765 When you select a difference, its state changes from default-A or | |
2766 default-B to plain A or B. Thus, the selected difference never has | |
2767 state default-A or default-B, and these states are never displayed in | |
2768 the mode line. | |
2769 | |
2770 The command @kbd{d a} chooses default-A as the default state, and @kbd{d | |
2771 b} chooses default-B. This chosen default applies to all differences | |
2772 which you haven't ever selected and for which no alternative is preferred. | |
2773 If you are moving through the merge sequentially, the differences you | |
2774 haven't selected are those following the selected one. Thus, while | |
2775 moving sequentially, you can effectively make the A version the default | |
2776 for some sections of the merge buffer and the B version the default for | |
2777 others by using @kbd{d a} and @kbd{d b} between sections. | |
2778 | |
2779 @item prefer-A | |
2780 @itemx prefer-B | |
2781 The difference is showing the A or B state because it is | |
2782 @dfn{preferred}. This means that you haven't made an explicit choice, | |
2783 but one alternative seems likely to be right because the other | |
2784 alternative agrees with the common ancestor. Thus, where the A buffer | |
2785 agrees with the common ancestor, the B version is preferred, because | |
2786 chances are it is the one that was actually changed. | |
2787 | |
2788 These two states are displayed in the mode line as @samp{A*} and @samp{B*}. | |
2789 | |
2790 @item combined | |
2791 The difference is showing a combination of the A and B states, as a | |
2792 result of the @kbd{x c} or @kbd{x C} commands. | |
2793 | |
2794 Once a difference is in this state, the @kbd{a} and @kbd{b} commands | |
2795 don't do anything to it unless you give them a numeric argument. | |
2796 | |
2797 The mode line displays this state as @samp{comb}. | |
2798 @end table | |
2799 | |
2800 @node Merge Commands | |
2801 @subsection Merge Commands | |
2802 | |
2803 Here are the Merge commands for Fast mode; in Edit mode, precede them | |
2804 with @kbd{C-c C-c}: | |
2805 | |
2806 @table @kbd | |
2807 @item p | |
2808 Select the previous difference. | |
2809 | |
2810 @item n | |
2811 Select the next difference. | |
2812 | |
2813 @item a | |
2814 Choose the A version of this difference. | |
2815 | |
2816 @item b | |
2817 Choose the B version of this difference. | |
2818 | |
2819 @item C-u @var{n} j | |
2820 Select difference number @var{n}. | |
2821 | |
2822 @item . | |
2823 Select the difference containing point. You can use this command in the | |
2824 merge buffer or in the A or B buffer. | |
2825 | |
2826 @item q | |
2827 Quit---finish the merge. | |
2828 | |
2829 @item C-] | |
2830 Abort---exit merging and do not save the output. | |
2831 | |
2832 @item f | |
2833 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) | |
2834 | |
2835 @item e | |
2836 Go into Edit mode. | |
2837 | |
2838 @item l | |
2839 Recenter (like @kbd{C-l}) all three windows. | |
2840 | |
26264 | 2841 @item - |
25829 | 2842 Specify part of a prefix numeric argument. |
2843 | |
2844 @item @var{digit} | |
2845 Also specify part of a prefix numeric argument. | |
2846 | |
2847 @item d a | |
2848 Choose the A version as the default from here down in | |
2849 the merge buffer. | |
2850 | |
2851 @item d b | |
2852 Choose the B version as the default from here down in | |
2853 the merge buffer. | |
2854 | |
2855 @item c a | |
2856 Copy the A version of this difference into the kill ring. | |
2857 | |
2858 @item c b | |
2859 Copy the B version of this difference into the kill ring. | |
2860 | |
2861 @item i a | |
2862 Insert the A version of this difference at point. | |
2863 | |
2864 @item i b | |
2865 Insert the B version of this difference at point. | |
2866 | |
2867 @item m | |
2868 Put point and mark around the difference. | |
2869 | |
2870 @item ^ | |
2871 Scroll all three windows down (like @kbd{M-v}). | |
2872 | |
2873 @item v | |
2874 Scroll all three windows up (like @kbd{C-v}). | |
2875 | |
2876 @item < | |
2877 Scroll all three windows left (like @kbd{C-x <}). | |
2878 | |
2879 @item > | |
2880 Scroll all three windows right (like @kbd{C-x >}). | |
2881 | |
2882 @item | | |
2883 Reset horizontal scroll on all three windows. | |
2884 | |
2885 @item x 1 | |
2886 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it | |
2887 to full size.) | |
2888 | |
2889 @item x c | |
2890 Combine the two versions of this difference (@pxref{Combining in | |
2891 Emerge}). | |
2892 | |
2893 @item x f | |
2894 Show the names of the files/buffers Emerge is operating on, in a Help | |
2895 window. (Use @kbd{C-u l} to restore windows.) | |
2896 | |
2897 @item x j | |
2898 Join this difference with the following one. | |
2899 (@kbd{C-u x j} joins this difference with the previous one.) | |
2900 | |
2901 @item x s | |
2902 Split this difference into two differences. Before you use this | |
2903 command, position point in each of the three buffers at the place where | |
2904 you want to split the difference. | |
2905 | |
2906 @item x t | |
2907 Trim identical lines off the top and bottom of the difference. | |
2908 Such lines occur when the A and B versions are | |
2909 identical but differ from the ancestor version. | |
2910 @end table | |
2911 | |
2912 @node Exiting Emerge | |
2913 @subsection Exiting Emerge | |
2914 | |
2915 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing | |
2916 the results into the output file if you specified one. It restores the | |
2917 A and B buffers to their proper contents, or kills them if they were | |
2918 created by Emerge and you haven't changed them. It also disables the | |
2919 Emerge commands in the merge buffer, since executing them later could | |
2920 damage the contents of the various buffers. | |
2921 | |
2922 @kbd{C-]} aborts the merge. This means exiting without writing the | |
2923 output file. If you didn't specify an output file, then there is no | |
2924 real difference between aborting and finishing the merge. | |
2925 | |
2926 If the Emerge command was called from another Lisp program, then its | |
2927 return value is @code{t} for successful completion, or @code{nil} if you | |
2928 abort. | |
2929 | |
2930 @node Combining in Emerge | |
2931 @subsection Combining the Two Versions | |
2932 | |
2933 Sometimes you want to keep @emph{both} alternatives for a particular | |
2934 difference. To do this, use @kbd{x c}, which edits the merge buffer | |
2935 like this: | |
2936 | |
2937 @example | |
2938 @group | |
2939 #ifdef NEW | |
2940 @var{version from A buffer} | |
2941 #else /* not NEW */ | |
2942 @var{version from B buffer} | |
2943 #endif /* not NEW */ | |
2944 @end group | |
2945 @end example | |
2946 | |
2947 @noindent | |
2948 @vindex emerge-combine-versions-template | |
2949 While this example shows C preprocessor conditionals delimiting the two | |
2950 alternative versions, you can specify the strings to use by setting | |
2951 the variable @code{emerge-combine-versions-template} to a string of your | |
2952 choice. In the string, @samp{%a} says where to put version A, and | |
2953 @samp{%b} says where to put version B. The default setting, which | |
2954 produces the results shown above, looks like this: | |
2955 | |
2956 @example | |
2957 @group | |
2958 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" | |
2959 @end group | |
2960 @end example | |
2961 | |
2962 @node Fine Points of Emerge | |
2963 @subsection Fine Points of Emerge | |
2964 | |
2965 During the merge, you mustn't try to edit the A and B buffers yourself. | |
2966 Emerge modifies them temporarily, but ultimately puts them back the way | |
2967 they were. | |
2968 | |
2969 You can have any number of merges going at once---just don't use any one | |
2970 buffer as input to more than one merge at once, since the temporary | |
2971 changes made in these buffers would get in each other's way. | |
2972 | |
2973 Starting Emerge can take a long time because it needs to compare the | |
2974 files fully. Emacs can't do anything else until @code{diff} finishes. | |
2975 Perhaps in the future someone will change Emerge to do the comparison in | |
2976 the background when the input files are large---then you could keep on | |
2977 doing other things with Emacs until Emerge is ready to accept | |
2978 commands. | |
2979 | |
2980 @vindex emerge-startup-hook | |
2981 After setting up the merge, Emerge runs the hook | |
2982 @code{emerge-startup-hook} (@pxref{Hooks}). | |
2983 | |
2984 @node C Modes | |
2985 @section C and Related Modes | |
2986 @cindex C mode | |
2987 @cindex Java mode | |
2988 @cindex Pike mode | |
2989 @cindex IDL mode | |
2990 @cindex CORBA IDL mode | |
2991 @cindex Objective C mode | |
2992 @cindex C++ mode | |
2993 @cindex mode, Java | |
2994 @cindex mode, C | |
2995 @cindex mode, Objective C | |
2996 @cindex mode, CORBA IDL | |
2997 @cindex mode, Pike | |
2998 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
2999 This section gives a brief description of the special features |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3000 available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3001 (These are called ``C mode and related modes.'') @xref{Top, CC Mode, |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3002 ccmode, , CC Mode}, for a more extensive description of these modes |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3003 and their special features. |
28329
6e740f27f255
(Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents:
27221
diff
changeset
|
3004 |
25829 | 3005 @menu |
3006 * Motion in C:: | |
3007 * Electric C:: | |
3008 * Hungry Delete:: | |
3009 * Other C Commands:: | |
3010 * Comments in C:: | |
3011 @end menu | |
3012 | |
3013 @node Motion in C | |
3014 @subsection C Mode Motion Commands | |
3015 | |
3016 This section describes commands for moving point, in C mode and | |
3017 related modes. | |
3018 | |
3019 @table @code | |
3020 @item C-c C-u | |
3021 @kindex C-c C-u @r{(C mode)} | |
3022 @findex c-up-conditional | |
3023 Move point back to the containing preprocessor conditional, leaving the | |
3024 mark behind. A prefix argument acts as a repeat count. With a negative | |
3025 argument, move point forward to the end of the containing | |
3026 preprocessor conditional. When going backwards, @code{#elif} is treated | |
3027 like @code{#else} followed by @code{#if}. When going forwards, | |
3028 @code{#elif} is ignored.@refill | |
3029 | |
3030 @item C-c C-p | |
3031 @kindex C-c C-p @r{(C mode)} | |
3032 @findex c-backward-conditional | |
3033 Move point back over a preprocessor conditional, leaving the mark | |
3034 behind. A prefix argument acts as a repeat count. With a negative | |
3035 argument, move forward. | |
3036 | |
3037 @item C-c C-n | |
3038 @kindex C-c C-n @r{(C mode)} | |
3039 @findex c-forward-conditional | |
3040 Move point forward across a preprocessor conditional, leaving the mark | |
3041 behind. A prefix argument acts as a repeat count. With a negative | |
3042 argument, move backward. | |
3043 | |
3044 @item M-a | |
3045 @kindex ESC a | |
3046 @findex c-beginning-of-statement | |
3047 Move point to the beginning of the innermost C statement | |
3048 (@code{c-beginning-of-statement}). If point is already at the beginning | |
3049 of a statement, move to the beginning of the preceding statement. With | |
3050 prefix argument @var{n}, move back @var{n} @minus{} 1 statements. | |
3051 | |
3052 If point is within a string or comment, or next to a comment (only | |
3053 whitespace between them), this command moves by sentences instead of | |
3054 statements. | |
3055 | |
3056 When called from a program, this function takes three optional | |
3057 arguments: the numeric prefix argument, a buffer position limit | |
3058 (don't move back before that place), and a flag that controls whether | |
3059 to do sentence motion when inside of a comment. | |
3060 | |
3061 @item M-e | |
3062 @kindex ESC e | |
3063 @findex c-end-of-statement | |
3064 Move point to the end of the innermost C statement; like @kbd{M-a} | |
3065 except that it moves in the other direction (@code{c-end-of-statement}). | |
3066 | |
3067 @item M-x c-backward-into-nomenclature | |
3068 @findex c-backward-into-nomenclature | |
3069 Move point backward to beginning of a C++ nomenclature section or word. | |
3070 With prefix argument @var{n}, move @var{n} times. If @var{n} is | |
3071 negative, move forward. C++ nomenclature means a symbol name in the | |
3072 style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter | |
3073 begins a section or word. | |
3074 | |
3075 In the GNU project, we recommend using underscores to separate words | |
3076 within an identifier in C or C++, rather than using case distinctions. | |
3077 | |
3078 @item M-x c-forward-into-nomenclature | |
3079 @findex c-forward-into-nomenclature | |
3080 Move point forward to end of a C++ nomenclature section or word. | |
3081 With prefix argument @var{n}, move @var{n} times. | |
3082 @end table | |
3083 | |
3084 @node Electric C | |
3085 @subsection Electric C Characters | |
3086 | |
3087 In C mode and related modes, certain printing characters are | |
3088 ``electric''---in addition to inserting themselves, they also reindent | |
3089 the current line and may insert newlines. This feature is controlled by | |
3090 the variable @code{c-auto-newline}. The ``electric'' characters are | |
3091 @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, | |
3092 @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. | |
3093 | |
3094 Electric characters insert newlines only when the @dfn{auto-newline} | |
3095 feature is enabled (indicated by @samp{/a} in the mode line after the | |
3096 mode name). This feature is controlled by the variable | |
3097 @code{c-auto-newline}. You can turn this feature on or off with the | |
3098 command @kbd{C-c C-a}: | |
3099 | |
3100 @table @kbd | |
3101 @item C-c C-a | |
3102 @kindex C-c C-a @r{(C mode)} | |
3103 @findex c-toggle-auto-state | |
3104 Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a | |
3105 prefix argument, this command turns the auto-newline feature on if the | |
3106 argument is positive, and off if it is negative. | |
3107 @end table | |
3108 | |
3109 The colon character is electric because that is appropriate for a | |
3110 single colon. But when you want to insert a double colon in C++, the | |
3111 electric behavior of colon is inconvenient. You can insert a double | |
3112 colon with no reindentation or newlines by typing @kbd{C-c :}: | |
3113 | |
3114 @table @kbd | |
3115 @item C-c : | |
3116 @kindex C-c : @r{(C mode)} | |
3117 @findex c-scope-operator | |
3118 Insert a double colon scope operator at point, without reindenting the | |
3119 line or adding any newlines (@code{c-scope-operator}). | |
3120 @end table | |
3121 | |
3122 The electric @kbd{#} key reindents the line if it appears to be the | |
3123 beginning of a preprocessor directive. This happens when the value of | |
3124 @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn | |
3125 this feature off by setting @code{c-electric-pound-behavior} to | |
3126 @code{nil}. | |
3127 | |
3128 The variable @code{c-hanging-braces-alist} controls the insertion of | |
3129 newlines before and after inserted braces. It is an association list | |
3130 with elements of the following form: @code{(@var{syntactic-symbol} | |
3131 . @var{nl-list})}. Most of the syntactic symbols that appear in | |
3132 @code{c-offsets-alist} are meaningful here as well. | |
3133 | |
3134 The list @var{nl-list} may contain either of the symbols | |
3135 @code{before} or @code{after}, or both; or it may be @code{nil}. When a | |
3136 brace is inserted, the syntactic context it defines is looked up in | |
3137 @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used | |
3138 to determine where newlines are inserted: either before the brace, | |
3139 after, or both. If not found, the default is to insert a newline both | |
3140 before and after braces. | |
3141 | |
3142 The variable @code{c-hanging-colons-alist} controls the insertion of | |
3143 newlines before and after inserted colons. It is an association list | |
3144 with elements of the following form: @code{(@var{syntactic-symbol} | |
3145 . @var{nl-list})}. The list @var{nl-list} may contain either of the | |
3146 symbols @code{before} or @code{after}, or both; or it may be @code{nil}. | |
3147 | |
3148 When a colon is inserted, the syntactic symbol it defines is looked | |
3149 up in this list, and if found, the @var{nl-list} is used to determine | |
3150 where newlines are inserted: either before the brace, after, or both. | |
3151 If the syntactic symbol is not found in this list, no newlines are | |
3152 inserted. | |
3153 | |
3154 Electric characters can also delete newlines automatically when the | |
3155 auto-newline feature is enabled. This feature makes auto-newline more | |
3156 acceptable, by deleting the newlines in the most common cases where you | |
3157 do not want them. Emacs can recognize several cases in which deleting a | |
3158 newline might be desirable; by setting the variable | |
3159 @code{c-cleanup-list}, you can specify @emph{which} of these cases that | |
3160 should happen. The variable's value is a list of symbols, each | |
3161 describing one case for possible deletion of a newline. Here are the | |
3162 meaningful symbols, and their meanings: | |
3163 | |
3164 @table @code | |
3165 @item brace-catch-brace | |
3166 Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the | |
3167 entire construct on a single line. The clean-up occurs when you type | |
3168 the @samp{@{}, if there is nothing between the braces aside from | |
3169 @code{catch} and @var{condition}. | |
3170 | |
3171 @item brace-else-brace | |
3172 Clean up @samp{@} else @{} constructs by placing the entire construct on | |
3173 a single line. The clean-up occurs when you type the @samp{@{} after | |
3174 the @code{else}, but only if there is nothing but white space between | |
3175 the braces and the @code{else}. | |
3176 | |
3177 @item brace-elseif-brace | |
3178 Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire | |
3179 construct on a single line. The clean-up occurs when you type the | |
3180 @samp{@{}, if there is nothing but white space between the @samp{@}} and | |
3181 @samp{@{} aside from the keywords and the @code{if}-condition. | |
3182 | |
3183 @item empty-defun-braces | |
3184 Clean up empty defun braces by placing the braces on the same | |
3185 line. Clean-up occurs when you type the closing brace. | |
3186 | |
3187 @item defun-close-semi | |
3188 Clean up the semicolon after a @code{struct} or similar type | |
3189 declaration, by placing the semicolon on the same line as the closing | |
3190 brace. Clean-up occurs when you type the semicolon. | |
3191 | |
3192 @item list-close-comma | |
3193 Clean up commas following braces in array and aggregate | |
3194 initializers. Clean-up occurs when you type the comma. | |
3195 | |
3196 @item scope-operator | |
3197 Clean up double colons which may designate a C++ scope operator, by | |
3198 placing the colons together. Clean-up occurs when you type the second | |
3199 colon, but only when the two colons are separated by nothing but | |
3200 whitespace. | |
3201 @end table | |
3202 | |
3203 @node Hungry Delete | |
3204 @subsection Hungry Delete Feature in C | |
3205 | |
3206 When the @dfn{hungry-delete} feature is enabled (indicated by | |
3207 @samp{/h} or @samp{/ah} in the mode line after the mode name), a single | |
3208 @key{DEL} command deletes all preceding whitespace, not just one space. | |
3209 To turn this feature on or off, use @kbd{C-c C-d}: | |
3210 | |
3211 @table @kbd | |
3212 @item C-c C-d | |
3213 @kindex C-c C-d @r{(C mode)} | |
3214 @findex c-toggle-hungry-state | |
3215 Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a | |
3216 prefix argument, this command turns the hungry-delete feature on if the | |
3217 argument is positive, and off if it is negative. | |
3218 | |
3219 @item C-c C-t | |
3220 @kindex C-c C-t @r{(C mode)} | |
3221 @findex c-toggle-auto-hungry-state | |
3222 Toggle the auto-newline and hungry-delete features, both at once | |
3223 (@code{c-toggle-auto-hungry-state}). | |
3224 @end table | |
3225 | |
3226 @vindex c-hungry-delete-key | |
3227 The variable @code{c-hungry-delete-key} controls whether the | |
3228 hungry-delete feature is enabled. | |
3229 | |
3230 @node Other C Commands | |
3231 @subsection Other Commands for C Mode | |
3232 | |
3233 @table @kbd | |
3234 @item C-M-h | |
3235 Put mark at the end of a function definition, and put point at the | |
3236 beginning (@code{c-mark-function}). | |
3237 | |
3238 @item M-q | |
3239 @kindex M-q @r{(C mode)} | |
3240 @findex c-fill-paragraph | |
3241 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). | |
3242 If any part of the current line is a comment or within a comment, this | |
3243 command fills the comment or the paragraph of it that point is in, | |
3244 preserving the comment indentation and comment delimiters. | |
3245 | |
3246 @item C-c C-e | |
3247 @cindex macro expansion in C | |
3248 @cindex expansion of C macros | |
3249 @findex c-macro-expand | |
3250 @kindex C-c C-e @r{(C mode)} | |
3251 Run the C preprocessor on the text in the region, and show the result, | |
3252 which includes the expansion of all the macro calls | |
3253 (@code{c-macro-expand}). The buffer text before the region is also | |
3254 included in preprocessing, for the sake of macros defined there, but the | |
3255 output from this part isn't shown. | |
3256 | |
3257 When you are debugging C code that uses macros, sometimes it is hard to | |
3258 figure out precisely how the macros expand. With this command, you | |
3259 don't have to figure it out; you can see the expansions. | |
3260 | |
3261 @item C-c C-\ | |
3262 @findex c-backslash-region | |
3263 @kindex C-c C-\ @r{(C mode)} | |
3264 Insert or align @samp{\} characters at the ends of the lines of the | |
3265 region (@code{c-backslash-region}). This is useful after writing or | |
3266 editing a C macro definition. | |
3267 | |
3268 If a line already ends in @samp{\}, this command adjusts the amount of | |
3269 whitespace before it. Otherwise, it inserts a new @samp{\}. However, | |
3270 the last line in the region is treated specially; no @samp{\} is | |
3271 inserted on that line, and any @samp{\} there is deleted. | |
3272 | |
3273 @item M-x cpp-highlight-buffer | |
3274 @cindex preprocessor highlighting | |
3275 @findex cpp-highlight-buffer | |
3276 Highlight parts of the text according to its preprocessor conditionals. | |
3277 This command displays another buffer named @samp{*CPP Edit*}, which | |
3278 serves as a graphic menu for selecting how to display particular kinds | |
3279 of conditionals and their contents. After changing various settings, | |
3280 click on @samp{[A]pply these settings} (or go to that buffer and type | |
3281 @kbd{a}) to rehighlight the C mode buffer accordingly. | |
3282 | |
3283 @item C-c C-s | |
3284 @findex c-show-syntactic-information | |
3285 @kindex C-c C-s @r{(C mode)} | |
3286 Display the syntactic information about the current source line | |
3287 (@code{c-show-syntactic-information}). This is the information that | |
3288 directs how the line is indented. | |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3289 |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3290 @item M-x cwarn-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3291 @itemx M-x global-cwarn-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3292 @findex cwarn-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3293 @findex global-cwarn-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3294 @cindex CWarn mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3295 @cindex suspicious constructions in C, C++ |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3296 CWarn minor mode highlights certain suspicious C and C++ constructions: |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3297 |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3298 @itemize @bullet{} |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3299 @item |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3300 Assignments inside expressions. |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3301 @item |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3302 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3303 (except after a @samp{do @dots{} while} statement); |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3304 @item |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3305 C++ functions with reference parameters. |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3306 @end itemize |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3307 |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3308 @noindent |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3309 You can enable the mode for one buffer with the command @kbd{M-x |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3310 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3311 global-cwarn-mode} or by customizing the variable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3312 @code{global-cwarn-mode}. You must also enable Font Lock mode to make |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3313 it work. |
30810
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3314 |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3315 @item M-x hide-ifdef-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3316 @findex hide-ifdef-mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3317 @cindex Hide-ifdef mode |
6c6b0162bae2
Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents:
30793
diff
changeset
|
3318 Hide-ifdef minor mode hides selected code within @samp{#if} and |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3319 @samp{#ifdef} preprocessor blocks. See the documentation string of |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3320 @code{hide-ifdef-mode} for more information. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3321 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3322 @item M-x ff-find-related-file |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3323 @cindex related files |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3324 @findex ff-find-related-file |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3325 @vindex ff-related-file-alist |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3326 Find a file ``related'' in a special way to the file visited by the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3327 current buffer. Typically this will be the header file corresponding |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3328 to a C/C++ source file, or vice versa. The variable |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3329 @code{ff-related-file-alist} specifies how to compute related file |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3330 names. |
25829 | 3331 @end table |
3332 | |
3333 @node Comments in C | |
3334 @subsection Comments in C Modes | |
3335 | |
3336 C mode and related modes use a number of variables for controlling | |
3337 comment format. | |
3338 | |
3339 @table @code | |
3340 @item c-comment-only-line-offset | |
3341 @vindex c-comment-only-line-offset | |
3342 Extra offset for line which contains only the start of a comment. It | |
3343 can be either an integer or a cons cell of the form | |
3344 @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where | |
3345 @var{non-anchored-offset} is the amount of offset given to | |
3346 non-column-zero anchored comment-only lines, and @var{anchored-offset} | |
3347 is the amount of offset to give column-zero anchored comment-only lines. | |
3348 Just an integer as value is equivalent to @code{(@var{val} . 0)}. | |
3349 | |
3350 @item c-comment-start-regexp | |
3351 @vindex c-comment-start-regexp | |
3352 This buffer-local variable specifies how to recognize the start of a comment. | |
3353 | |
3354 @item c-hanging-comment-ender-p | |
3355 @vindex c-hanging-comment-ender-p | |
3356 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the | |
3357 comment terminator of a block comment on a line by itself. The default | |
3358 value is @code{t}, which puts the comment-end delimiter @samp{*/} at the | |
3359 end of the last line of the comment text. | |
3360 | |
3361 @item c-hanging-comment-starter-p | |
3362 @vindex c-hanging-comment-starter-p | |
3363 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the | |
3364 starting delimiter of a block comment on a line by itself. The default | |
3365 value is @code{t}, which puts the comment-start delimiter @samp{/*} at | |
3366 the beginning of the first line of the comment text. | |
3367 @end table | |
3368 | |
3369 @node Fortran | |
3370 @section Fortran Mode | |
3371 @cindex Fortran mode | |
3372 @cindex mode, Fortran | |
3373 | |
3374 Fortran mode provides special motion commands for Fortran statements and | |
3375 subprograms, and indentation commands that understand Fortran conventions | |
3376 of nesting, line numbers and continuation statements. Fortran mode has | |
3377 its own Auto Fill mode that breaks long lines into proper Fortran | |
3378 continuation lines. | |
3379 | |
3380 Special commands for comments are provided because Fortran comments | |
3381 are unlike those of other languages. Built-in abbrevs optionally save | |
3382 typing when you insert Fortran keywords. | |
3383 | |
3384 Use @kbd{M-x fortran-mode} to switch to this major mode. This command | |
3385 runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). | |
3386 | |
36263
11db0318031d
Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents:
36198
diff
changeset
|
3387 @cindex Fortran77 and Fortran90 |
26106 | 3388 @findex f90-mode |
3389 @findex fortran-mode | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3390 Fortan mode is meant for editing Fortran77 ``fixed format'' source |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3391 code. For editing the modern Fortran90 ``free format'' source code, |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3392 use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3393 files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3394 for the extension @samp{.f90}. GNU Fortran supports both kinds of |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3395 format. |
26106 | 3396 |
25829 | 3397 @menu |
3398 * Motion: Fortran Motion. Moving point by statements or subprograms. | |
3399 * Indent: Fortran Indent. Indentation commands for Fortran. | |
3400 * Comments: Fortran Comments. Inserting and aligning comments. | |
3401 * Autofill: Fortran Autofill. Auto fill minor mode for Fortran. | |
3402 * Columns: Fortran Columns. Measuring columns for valid Fortran. | |
3403 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. | |
3404 @end menu | |
3405 | |
3406 @node Fortran Motion | |
3407 @subsection Motion Commands | |
3408 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3409 In addition to the normal commands for moving by and operating on |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3410 ``defuns'' (Fortran subprograms---functions and subroutines), Fortran |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3411 mode provides special commands to move by statements. |
25829 | 3412 |
3413 @table @kbd | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3414 @kindex C-c C-n @r{(Fortran mode)} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3415 @findex fortran-next-statement |
25829 | 3416 @item C-c C-n |
3417 Move to beginning of current or next statement | |
3418 (@code{fortran-next-statement}). | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3419 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3420 @kindex C-c C-p @r{(Fortran mode)} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3421 @findex fortran-previous-statement |
25829 | 3422 @item C-c C-p |
3423 Move to beginning of current or previous statement | |
3424 (@code{fortran-previous-statement}). | |
3425 @end table | |
3426 | |
3427 @node Fortran Indent | |
3428 @subsection Fortran Indentation | |
3429 | |
3430 Special commands and features are needed for indenting Fortran code in | |
3431 order to make sure various syntactic entities (line numbers, comment line | |
3432 indicators and continuation line flags) appear in the columns that are | |
3433 required for standard Fortran. | |
3434 | |
3435 @menu | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3436 * Commands: ForIndent Commands. Commands for indenting and filling Fortran. |
25829 | 3437 * Contline: ForIndent Cont. How continuation lines indent. |
3438 * Numbers: ForIndent Num. How line numbers auto-indent. | |
3439 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. | |
3440 * Vars: ForIndent Vars. Variables controlling Fortran indent style. | |
3441 @end menu | |
3442 | |
3443 @node ForIndent Commands | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3444 @subsubsection Fortran Indentation and Filling Commands |
25829 | 3445 |
3446 @table @kbd | |
3447 @item C-M-j | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3448 Break the current line and set up a continuation line |
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3449 (@code{fortran-split-line}). |
25829 | 3450 @item M-^ |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3451 Join this line to the previous line (@code{fortran-join-line}). |
25829 | 3452 @item C-M-q |
3453 Indent all the lines of the subprogram point is in | |
3454 (@code{fortran-indent-subprogram}). | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3455 @item M-q |
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3456 Fill a comment block or statement. |
25829 | 3457 @end table |
3458 | |
3459 @kindex C-M-q @r{(Fortran mode)} | |
3460 @findex fortran-indent-subprogram | |
3461 The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command | |
3462 to reindent all the lines of the Fortran subprogram (function or | |
3463 subroutine) containing point. | |
3464 | |
3465 @kindex C-M-j @r{(Fortran mode)} | |
3466 @findex fortran-split-line | |
3467 The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits | |
3468 a line in the appropriate fashion for Fortran. In a non-comment line, | |
3469 the second half becomes a continuation line and is indented | |
3470 accordingly. In a comment line, both halves become separate comment | |
3471 lines. | |
3472 | |
3473 @kindex M-^ @r{(Fortran mode)} | |
26106 | 3474 @kindex C-c C-d @r{(Fortran mode)} |
3475 @findex fortran-join-line | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3476 @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, |
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3477 which joins a continuation line back to the previous line, roughly as |
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3478 the inverse of @code{fortran-split-line}. The point must be on a |
26106 | 3479 continuation line when this command is invoked. |
3480 | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3481 @kindex M-q @r{(Fortran mode)} |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3482 @kbd{M-q} in Fortran mode fills the comment block or statement that |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3483 point is in. This removes any excess statement continuations. |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3484 |
25829 | 3485 @node ForIndent Cont |
3486 @subsubsection Continuation Lines | |
3487 @cindex Fortran continuation lines | |
3488 | |
3489 @vindex fortran-continuation-string | |
3490 Most modern Fortran compilers allow two ways of writing continuation | |
3491 lines. If the first non-space character on a line is in column 5, then | |
3492 that line is a continuation of the previous line. We call this | |
3493 @dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The | |
3494 variable @code{fortran-continuation-string} specifies what character to | |
3495 put on column 5. A line that starts with a tab character followed by | |
3496 any digit except @samp{0} is also a continuation line. We call this | |
3497 style of continuation @dfn{tab format}. | |
3498 | |
3499 @vindex indent-tabs-mode @r{(Fortran mode)} | |
3500 Fortran mode can make either style of continuation line, but you | |
3501 must specify which one you prefer. The value of the variable | |
3502 @code{indent-tabs-mode} controls the choice: @code{nil} for fixed | |
3503 format, and non-@code{nil} for tab format. You can tell which style | |
3504 is presently in effect by the presence or absence of the string | |
3505 @samp{Tab} in the mode line. | |
3506 | |
3507 If the text on a line starts with the conventional Fortran | |
3508 continuation marker @samp{$}, or if it begins with any non-whitespace | |
3509 character in column 5, Fortran mode treats it as a continuation line. | |
3510 When you indent a continuation line with @key{TAB}, it converts the line | |
3511 to the current continuation style. When you split a Fortran statement | |
3512 with @kbd{C-M-j}, the continuation marker on the newline is created | |
3513 according to the continuation style. | |
3514 | |
3515 The setting of continuation style affects several other aspects of | |
3516 editing in Fortran mode. In fixed format mode, the minimum column | |
3517 number for the body of a statement is 6. Lines inside of Fortran | |
3518 blocks that are indented to larger column numbers always use only the | |
3519 space character for whitespace. In tab format mode, the minimum | |
3520 column number for the statement body is 8, and the whitespace before | |
3521 column 8 must always consist of one tab character. | |
3522 | |
3523 @vindex fortran-tab-mode-default | |
3524 @vindex fortran-analyze-depth | |
3525 When you enter Fortran mode for an existing file, it tries to deduce the | |
3526 proper continuation style automatically from the file contents. The first | |
3527 line that begins with either a tab character or six spaces determines the | |
3528 choice. The variable @code{fortran-analyze-depth} specifies how many lines | |
3529 to consider (at the beginning of the file); if none of those lines | |
3530 indicates a style, then the variable @code{fortran-tab-mode-default} | |
3531 specifies the style. If it is @code{nil}, that specifies fixed format, and | |
3532 non-@code{nil} specifies tab format. | |
3533 | |
3534 @node ForIndent Num | |
3535 @subsubsection Line Numbers | |
3536 | |
3537 If a number is the first non-whitespace in the line, Fortran | |
3538 indentation assumes it is a line number and moves it to columns 0 | |
3539 through 4. (Columns always count from 0 in GNU Emacs.) | |
3540 | |
3541 @vindex fortran-line-number-indent | |
3542 Line numbers of four digits or less are normally indented one space. | |
3543 The variable @code{fortran-line-number-indent} controls this; it | |
3544 specifies the maximum indentation a line number can have. Line numbers | |
3545 are indented to right-justify them to end in column 4 unless that would | |
3546 require more than this maximum indentation. The default value of the | |
3547 variable is 1. | |
3548 | |
3549 @vindex fortran-electric-line-number | |
3550 Simply inserting a line number is enough to indent it according to | |
3551 these rules. As each digit is inserted, the indentation is recomputed. | |
3552 To turn off this feature, set the variable | |
3553 @code{fortran-electric-line-number} to @code{nil}. Then inserting line | |
3554 numbers is like inserting anything else. | |
3555 | |
3556 @node ForIndent Conv | |
3557 @subsubsection Syntactic Conventions | |
3558 | |
3559 Fortran mode assumes that you follow certain conventions that simplify | |
3560 the task of understanding a Fortran program well enough to indent it | |
3561 properly: | |
3562 | |
3563 @itemize @bullet | |
3564 @item | |
3565 Two nested @samp{do} loops never share a @samp{continue} statement. | |
3566 | |
3567 @item | |
3568 Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} | |
3569 and others are written without embedded whitespace or line breaks. | |
3570 | |
3571 Fortran compilers generally ignore whitespace outside of string | |
3572 constants, but Fortran mode does not recognize these keywords if they | |
3573 are not contiguous. Constructs such as @samp{else if} or @samp{end do} | |
3574 are acceptable, but the second word should be on the same line as the | |
3575 first and not on a continuation line. | |
3576 @end itemize | |
3577 | |
3578 @noindent | |
3579 If you fail to follow these conventions, the indentation commands may | |
3580 indent some lines unaesthetically. However, a correct Fortran program | |
3581 retains its meaning when reindented even if the conventions are not | |
3582 followed. | |
3583 | |
3584 @node ForIndent Vars | |
3585 @subsubsection Variables for Fortran Indentation | |
3586 | |
3587 @vindex fortran-do-indent | |
3588 @vindex fortran-if-indent | |
3589 @vindex fortran-structure-indent | |
3590 @vindex fortran-continuation-indent | |
3591 @vindex fortran-check-all-num@dots{} | |
3592 @vindex fortran-minimum-statement-indent@dots{} | |
3593 Several additional variables control how Fortran indentation works: | |
3594 | |
3595 @table @code | |
3596 @item fortran-do-indent | |
3597 Extra indentation within each level of @samp{do} statement (default 3). | |
3598 | |
3599 @item fortran-if-indent | |
3600 Extra indentation within each level of @samp{if} statement (default 3). | |
3601 This value is also used for extra indentation within each level of the | |
3602 Fortran 90 @samp{where} statement. | |
3603 | |
3604 @item fortran-structure-indent | |
3605 Extra indentation within each level of @samp{structure}, @samp{union}, or | |
3606 @samp{map} statements (default 3). | |
3607 | |
3608 @item fortran-continuation-indent | |
3609 Extra indentation for bodies of continuation lines (default 5). | |
3610 | |
3611 @item fortran-check-all-num-for-matching-do | |
3612 If this is @code{nil}, indentation assumes that each @samp{do} statement | |
3613 ends on a @samp{continue} statement. Therefore, when computing | |
3614 indentation for a statement other than @samp{continue}, it can save time | |
3615 by not checking for a @samp{do} statement ending there. If this is | |
3616 non-@code{nil}, indenting any numbered statement must check for a | |
3617 @samp{do} that ends there. The default is @code{nil}. | |
3618 | |
3619 @item fortran-blink-matching-if | |
3620 If this is @code{t}, indenting an @samp{endif} statement moves the | |
3621 cursor momentarily to the matching @samp{if} statement to show where it | |
3622 is. The default is @code{nil}. | |
3623 | |
3624 @item fortran-minimum-statement-indent-fixed | |
3625 Minimum indentation for fortran statements when using fixed format | |
3626 continuation line style. Statement bodies are never indented less than | |
3627 this much. The default is 6. | |
3628 | |
3629 @item fortran-minimum-statement-indent-tab | |
3630 Minimum indentation for fortran statements for tab format continuation line | |
3631 style. Statement bodies are never indented less than this much. The | |
3632 default is 8. | |
3633 @end table | |
3634 | |
3635 @node Fortran Comments | |
3636 @subsection Fortran Comments | |
3637 | |
3638 The usual Emacs comment commands assume that a comment can follow a line | |
3639 of code. In Fortran, the standard comment syntax requires an entire line | |
3640 to be just a comment. Therefore, Fortran mode replaces the standard Emacs | |
3641 comment commands and defines some new variables. | |
3642 | |
27221
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3643 Fortran mode can also handle the Fortran90 comment syntax where comments |
4a723a7bc25a
Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents:
26462
diff
changeset
|
3644 start with @samp{!} and can follow other text. Because only some Fortran77 |
25829 | 3645 compilers accept this syntax, Fortran mode will not insert such comments |
3646 unless you have said in advance to do so. To do this, set the variable | |
3647 @code{comment-start} to @samp{"!"} (@pxref{Variables}). | |
3648 | |
3649 @table @kbd | |
3650 @item M-; | |
3651 Align comment or insert new comment (@code{fortran-comment-indent}). | |
3652 | |
3653 @item C-x ; | |
3654 Applies to nonstandard @samp{!} comments only. | |
3655 | |
3656 @item C-c ; | |
3657 Turn all lines of the region into comments, or (with argument) turn them back | |
3658 into real code (@code{fortran-comment-region}). | |
3659 @end table | |
3660 | |
3661 @kbd{M-;} in Fortran mode is redefined as the command | |
3662 @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this | |
3663 recognizes any kind of existing comment and aligns its text appropriately; | |
3664 if there is no existing comment, a comment is inserted and aligned. But | |
3665 inserting and aligning comments are not the same in Fortran mode as in | |
3666 other modes. | |
3667 | |
3668 When a new comment must be inserted, if the current line is blank, a | |
3669 full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} | |
3670 comment is inserted if you have said you want to use them. Otherwise a | |
3671 full-line comment is inserted on a new line before the current line. | |
3672 | |
3673 Nonstandard @samp{!} comments are aligned like comments in other | |
3674 languages, but full-line comments are different. In a standard full-line | |
3675 comment, the comment delimiter itself must always appear in column zero. | |
3676 What can be aligned is the text within the comment. You can choose from | |
3677 three styles of alignment by setting the variable | |
3678 @code{fortran-comment-indent-style} to one of these values: | |
3679 | |
3680 @vindex fortran-comment-indent-style | |
3681 @vindex fortran-comment-line-extra-indent | |
3682 @table @code | |
3683 @item fixed | |
3684 Align the text at a fixed column, which is the sum of | |
3685 @code{fortran-comment-line-extra-indent} and the minimum statement | |
3686 indentation. This is the default. | |
3687 | |
3688 The minimum statement indentation is | |
3689 @code{fortran-minimum-statement-indent-fixed} for fixed format | |
3690 continuation line style and @code{fortran-minimum-statement-indent-tab} | |
3691 for tab format style. | |
3692 | |
3693 @item relative | |
3694 Align the text as if it were a line of code, but with an additional | |
3695 @code{fortran-comment-line-extra-indent} columns of indentation. | |
3696 | |
3697 @item nil | |
3698 Don't move text in full-line comments automatically at all. | |
3699 @end table | |
3700 | |
3701 @vindex fortran-comment-indent-char | |
3702 In addition, you can specify the character to be used to indent within | |
3703 full-line comments by setting the variable | |
3704 @code{fortran-comment-indent-char} to the single-character string you want | |
3705 to use. | |
3706 | |
3707 @vindex comment-line-start | |
3708 @vindex comment-line-start-skip | |
3709 Fortran mode introduces two variables @code{comment-line-start} and | |
3710 @code{comment-line-start-skip}, which play for full-line comments the same | |
3711 roles played by @code{comment-start} and @code{comment-start-skip} for | |
3712 ordinary text-following comments. Normally these are set properly by | |
3713 Fortran mode, so you do not need to change them. | |
3714 | |
3715 The normal Emacs comment command @kbd{C-x ;} has not been redefined. If | |
3716 you use @samp{!} comments, this command can be used with them. Otherwise | |
3717 it is useless in Fortran mode. | |
3718 | |
3719 @kindex C-c ; @r{(Fortran mode)} | |
3720 @findex fortran-comment-region | |
3721 @vindex fortran-comment-region | |
3722 The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the | |
3723 lines of the region into comments by inserting the string @samp{C$$$} at | |
3724 the front of each one. With a numeric argument, it turns the region | |
3725 back into live code by deleting @samp{C$$$} from the front of each line | |
3726 in it. The string used for these comments can be controlled by setting | |
3727 the variable @code{fortran-comment-region}. Note that here we have an | |
3728 example of a command and a variable with the same name; these two uses | |
3729 of the name never conflict because in Lisp and in Emacs it is always | |
3730 clear from the context which one is meant. | |
3731 | |
3732 @node Fortran Autofill | |
3733 @subsection Fortran Auto Fill Mode | |
3734 | |
3735 Fortran Auto Fill mode is a minor mode which automatically splits | |
3736 Fortran statements as you insert them when they become too wide. | |
3737 Splitting a statement involves making continuation lines using | |
3738 @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This | |
3739 splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and | |
3740 also in the Fortran indentation commands. | |
3741 | |
3742 @findex fortran-auto-fill-mode | |
3743 @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it | |
3744 was off, or off if it was on. This command works the same as @kbd{M-x | |
3745 auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A | |
3746 positive numeric argument turns Fortran Auto Fill mode on, and a | |
3747 negative argument turns it off. You can see when Fortran Auto Fill mode | |
3748 is in effect by the presence of the word @samp{Fill} in the mode line, | |
3749 inside the parentheses. Fortran Auto Fill mode is a minor mode, turned | |
3750 on or off for each buffer individually. @xref{Minor Modes}. | |
3751 | |
3752 @vindex fortran-break-before-delimiters | |
3753 Fortran Auto Fill mode breaks lines at spaces or delimiters when the | |
3754 lines get longer than the desired width (the value of @code{fill-column}). | |
3755 The delimiters that Fortran Auto Fill mode may break at are @samp{,}, | |
3756 @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}. | |
3757 The line break comes after the delimiter if the variable | |
3758 @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by | |
3759 default), the break comes before the delimiter. | |
3760 | |
3761 By default, Fortran Auto Fill mode is not enabled. If you want this | |
3762 feature turned on permanently, add a hook function to | |
3763 @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}. | |
3764 @xref{Hooks}. | |
3765 | |
3766 @node Fortran Columns | |
3767 @subsection Checking Columns in Fortran | |
3768 | |
3769 @table @kbd | |
3770 @item C-c C-r | |
3771 Display a ``column ruler'' momentarily above the current line | |
3772 (@code{fortran-column-ruler}). | |
3773 @item C-c C-w | |
3774 Split the current window horizontally temporarily so that it is 72 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3775 columns wide (@code{fortran-window-create-momentarily}). This may |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3776 help you avoid making lines longer than the 72-character limit that |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3777 some Fortran compilers impose. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3778 @item C-u C-c C-w |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3779 Split the current window horizontally so that it is 72 columns wide |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3780 (@code{fortran-window-create}). You can then continue editing. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3781 @item M-x fortran-strip-sequence-nos |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3782 Delete all text in column 72 and beyond. |
25829 | 3783 @end table |
3784 | |
3785 @kindex C-c C-r @r{(Fortran mode)} | |
3786 @findex fortran-column-ruler | |
3787 The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column | |
3788 ruler momentarily above the current line. The comment ruler is two lines | |
3789 of text that show you the locations of columns with special significance in | |
3790 Fortran programs. Square brackets show the limits of the columns for line | |
3791 numbers, and curly brackets show the limits of the columns for the | |
3792 statement body. Column numbers appear above them. | |
3793 | |
3794 Note that the column numbers count from zero, as always in GNU Emacs. | |
3795 As a result, the numbers may be one less than those you are familiar | |
3796 with; but the positions they indicate in the line are standard for | |
3797 Fortran. | |
3798 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3799 @vindex fortran-column-ruler-fixed |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3800 @vindex fortran-column-ruler-tabs |
26264 | 3801 The text used to display the column ruler depends on the value of |
25829 | 3802 the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is |
3803 @code{nil}, then the value of the variable | |
3804 @code{fortran-column-ruler-fixed} is used as the column ruler. | |
3805 Otherwise, the variable @code{fortran-column-ruler-tab} is displayed. | |
3806 By changing these variables, you can change the column ruler display. | |
3807 | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3808 @kindex C-c C-w @r{(Fortran mode)} |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3809 @findex fortran-window-create-momentarily |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3810 @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3811 splits the current window horizontally, making a window 72 columns |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3812 wide, so you can see which lines that is too long. Type a space to |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3813 restore the normal width. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3814 |
26106 | 3815 @kindex C-u C-c C-w @r{(Fortran mode)} |
25829 | 3816 @findex fortran-window-create |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3817 You can also split the window horizontally and continue editing with |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3818 the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3819 fortran-window-create}). By editing in this window you can |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3820 immediately see when you make a line too wide to be correct Fortran. |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3821 |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3822 @findex fortran-strip-sequence-nos |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3823 The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3824 column 72 and beyond, on all lines in the current buffer. This is the |
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3825 easiest way to get rid of old sequence numbers. |
26106 | 3826 |
25829 | 3827 @node Fortran Abbrev |
3828 @subsection Fortran Keyword Abbrevs | |
3829 | |
3830 Fortran mode provides many built-in abbrevs for common keywords and | |
3831 declarations. These are the same sort of abbrev that you can define | |
3832 yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. | |
3833 | |
3834 The built-in abbrevs are unusual in one way: they all start with a | |
3835 semicolon. You cannot normally use semicolon in an abbrev, but Fortran | |
3836 mode makes this possible by changing the syntax of semicolon to ``word | |
3837 constituent.'' | |
3838 | |
3839 For example, one built-in Fortran abbrev is @samp{;c} for | |
3840 @samp{continue}. If you insert @samp{;c} and then insert a punctuation | |
3841 character such as a space or a newline, the @samp{;c} expands automatically | |
3842 to @samp{continue}, provided Abbrev mode is enabled.@refill | |
3843 | |
3844 Type @samp{;?} or @samp{;C-h} to display a list of all the built-in | |
3845 Fortran abbrevs and what they stand for. | |
3846 | |
3847 @node Asm Mode | |
3848 @section Asm Mode | |
3849 | |
3850 @cindex Asm mode | |
36183
d3f65290e6b2
Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents:
35477
diff
changeset
|
3851 @cindex assembler mode |
25829 | 3852 Asm mode is a major mode for editing files of assembler code. It |
3853 defines these commands: | |
3854 | |
3855 @table @kbd | |
3856 @item @key{TAB} | |
3857 @code{tab-to-tab-stop}. | |
3858 @item C-j | |
3859 Insert a newline and then indent using @code{tab-to-tab-stop}. | |
3860 @item : | |
3861 Insert a colon and then remove the indentation from before the label | |
3862 preceding colon. Then do @code{tab-to-tab-stop}. | |
3863 @item ; | |
3864 Insert or align a comment. | |
3865 @end table | |
3866 | |
3867 The variable @code{asm-comment-char} specifies which character | |
3868 starts comments in assembler syntax. |