annotate man/programs.texi @ 37630:5a2458f097b0

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