Mercurial > emacs
annotate doc/emacs/indent.texi @ 109453:af9e12929a95
Merge latest fix to xg_event_is_for_menubar.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Sat, 17 Jul 2010 10:43:41 -0400 |
parents | ec5432ca82a4 |
children | 376148b31b5e |
rev | line source |
---|---|
84247 | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, | |
106815 | 3 @c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. |
84247 | 4 @c See file emacs.texi for copying conditions. |
5 @node Indentation, Text, Major Modes, Top | |
6 @chapter Indentation | |
7 @cindex indentation | |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
8 @cindex tabs |
84247 | 9 @cindex columns (indentation) |
10 | |
11 This chapter describes the Emacs commands that add, remove, or | |
12 adjust indentation. | |
13 | |
14 @table @kbd | |
15 @item @key{TAB} | |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
16 Indent the current line appropriately, in a mode-dependent fashion. |
84247 | 17 @item @kbd{C-j} |
18 Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
19 @item M-^ | |
20 Merge the previous and the current line (@code{delete-indentation}). | |
21 This would cancel the effect of a preceding @kbd{C-j}. | |
22 @item C-M-o | |
23 Split the current line at point; text on the line after point becomes a | |
24 new line indented to the same column where point is located | |
25 (@code{split-line}). | |
26 @item M-m | |
27 Move (forward or back) to the first nonblank character on the current | |
28 line (@code{back-to-indentation}). | |
29 @item C-M-\ | |
30 Indent lines in the region to the same column (@code{indent-region}). | |
31 @item C-x @key{TAB} | |
32 Shift lines in the region rigidly right or left (@code{indent-rigidly}). | |
33 @item M-i | |
34 Indent from point to the next prespecified tab stop column | |
35 (@code{tab-to-tab-stop}). | |
36 @item M-x indent-relative | |
37 Indent from point to under an indentation point in the previous line. | |
38 @end table | |
39 | |
107524
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
40 @noindent |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
41 The @key{TAB} key runs @code{indent-for-tab-command} in most major |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
42 modes (in C and related modes, @key{TAB} runs a separate command, |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
43 @code{c-indent-line-or-region}, which behaves similarly). The major |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
44 mode determines just what this entails. |
84247 | 45 |
107524
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
46 In text modes, @key{TAB} inserts some combination of space and tab |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
47 characters to advance point to the next tab stop (@pxref{Tab Stops}). |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
48 If the region is active and spans multiple lines, it advances the |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
49 first character of each of those lines to the next tab stop |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
50 (@pxref{Using Region}). For the purposes of this command, the |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
51 position of the first non-whitespace character on the preceding line |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
52 is treated as an additional tab stop. Thus, you can use @key{TAB} to |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
53 ``align'' point with the preceding line. |
84247 | 54 |
107524
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
55 In programming modes, @key{TAB} adds or removes some combination of |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
56 space and tab characters at the start of the line, in a way that makes |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
57 sense given the text in the preceding lines. If the region is active |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
58 and spans multiple lines, all those lines are indented this way. If |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
59 point was initially within the current line's indentation, it is |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
60 positioned after that indentation; otherwise, it remains at same point |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
61 in the newly-indented text. @xref{Program Indent}. |
84247 | 62 |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
63 @vindex tab-width |
107524
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
64 Normally, indentation commands insert (or remove) an optimal mix of |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
65 @dfn{tab characters} and spaces to align to the desired column. Tab |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
66 characters (@acronym{ASCII} code 9) are displayed as a stretch of |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
67 empty space extending to the next @dfn{display tab stop}. By default, |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
68 there is one display tab stop every eight columns; the number of |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
69 columns is determined by the variable @code{tab-width}. You can |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
70 insert a single tab character by typing @kbd{C-q @key{TAB}}. |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
71 @xref{Text Display}. |
84247 | 72 |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
73 @findex edit-tab-stops |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
74 @findex tab-to-tab-stop |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
75 @kindex M-i |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
76 The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
77 whitespace characters around point, inserting just enough whitespace |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
78 to advance point up to the next tab stop. By default, this involves |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
79 deleting the existing whitespace and inserting a single tab character. |
84247 | 80 |
107524
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
81 @xref{Just Spaces}, for how to disable use of tabs. However, |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
82 @kbd{C-q @key{TAB}} always inserts a tab, even when tabs are disabled |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
83 for the indentation commands. |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
84 |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
85 @vindex tab-always-indent |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
86 The variable @code{tab-always-indent} tweaks the behavior of the |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
87 @key{TAB} (@code{indent-for-tab-command}) command. The default value, |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
88 @code{t}, gives the behavior described above. If you change the value |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
89 to the symbol @code{complete}, then @key{TAB} first tries to indent |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
90 the current line, and if the line was already indented, it tries to |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
91 complete the text at point (@pxref{Symbol Completion}). If the value |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
92 is @code{nil}, then @key{TAB} indents the current line only if point |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
93 is at the left margin or in the line's indentation; otherwise, it |
ec5432ca82a4
Document multi-isearch-buffers and tab-always-indent.
Chong Yidong <cyd@stupidchicken.com>
parents:
106815
diff
changeset
|
94 inserts a real tab character. |
84247 | 95 |
96 @menu | |
97 * Indentation Commands:: Various commands and techniques for indentation. | |
98 * Tab Stops:: You can set arbitrary "tab stops" and then | |
99 indent to the next tab stop when you want to. | |
100 * Just Spaces:: You can request indentation using just spaces. | |
101 @end menu | |
102 | |
103 @node Indentation Commands, Tab Stops, Indentation, Indentation | |
104 @section Indentation Commands and Techniques | |
105 | |
106 @kindex M-m | |
107 @findex back-to-indentation | |
108 To move over the indentation on a line, do @kbd{M-m} | |
109 (@code{back-to-indentation}). This command, given anywhere on a line, | |
110 positions point at the first nonblank character on the line, if any, | |
111 or else at the end of the line. | |
112 | |
113 To insert an indented line before the current line, do @kbd{C-a C-o | |
114 @key{TAB}}. To make an indented line after the current line, use | |
115 @kbd{C-e C-j}. | |
116 | |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
117 If you just want to insert a tab character in the buffer, type |
84247 | 118 @kbd{C-q @key{TAB}}. |
119 | |
120 @kindex C-M-o | |
121 @findex split-line | |
122 @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of | |
123 the line vertically down, so that the current line becomes two lines. | |
124 @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it | |
125 inserts after point a newline and enough indentation to reach the same | |
126 column point is on. Point remains before the inserted newline; in this | |
127 regard, @kbd{C-M-o} resembles @kbd{C-o}. | |
128 | |
129 @kindex M-^ | |
130 @findex delete-indentation | |
131 To join two lines cleanly, use the @kbd{M-^} | |
132 (@code{delete-indentation}) command. It deletes the indentation at | |
133 the front of the current line, and the line boundary as well, | |
134 replacing them with a single space. As a special case (useful for | |
135 Lisp code) the single space is omitted if the characters to be joined | |
136 are consecutive open parentheses or closing parentheses, or if the | |
137 junction follows another newline. To delete just the indentation of a | |
138 line, go to the beginning of the line and use @kbd{M-\} | |
139 (@code{delete-horizontal-space}), which deletes all spaces and tabs | |
140 around the cursor. | |
141 | |
142 If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it | |
143 appears after the newline that is deleted. @xref{Fill Prefix}. | |
144 | |
145 @kindex C-M-\ | |
146 @kindex C-x TAB | |
147 @findex indent-region | |
148 @findex indent-rigidly | |
149 There are also commands for changing the indentation of several lines | |
150 at once. They apply to all the lines that begin in the region. | |
151 @kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual'' | |
152 way, as if you had typed @key{TAB} at the beginning of the line. A | |
153 numeric argument specifies the column to indent to, and each line is | |
154 shifted left or right so that its first nonblank character appears in | |
155 that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of | |
156 the lines in the region right by its argument (left, for negative | |
157 arguments). The whole group of lines moves rigidly sideways, which is | |
158 how the command gets its name. | |
159 | |
160 @cindex remove indentation | |
161 To remove all indentation from all of the lines in the region, | |
162 invoke @kbd{C-x @key{TAB}} with a large negative argument, such as | |
163 -1000. | |
164 | |
165 @findex indent-relative | |
166 @kbd{M-x indent-relative} indents at point based on the previous line | |
167 (actually, the last nonempty line). It inserts whitespace at point, moving | |
168 point, until it is underneath the next indentation point in the previous line. | |
169 An indentation point is the end of a sequence of whitespace or the end of | |
170 the line. If point is farther right than any indentation point in the | |
171 previous line, @code{indent-relative} runs @code{tab-to-tab-stop} | |
172 @ifnottex | |
173 (@pxref{Tab Stops}), | |
174 @end ifnottex | |
175 @iftex | |
176 (see next section), | |
177 @end iftex | |
178 unless it is called with a numeric argument, in which case it does | |
179 nothing. | |
180 | |
181 @xref{Format Indentation}, for another way of specifying the | |
182 indentation for part of your text. | |
183 | |
184 @node Tab Stops, Just Spaces, Indentation Commands, Indentation | |
185 @section Tab Stops | |
186 | |
187 @cindex tab stops | |
188 @cindex using tab stops in making tables | |
189 @cindex tables, indentation for | |
190 @kindex M-i | |
191 @findex tab-to-tab-stop | |
192 For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}). | |
193 This command inserts indentation before point, enough to reach the | |
194 next tab stop column. | |
195 | |
196 @findex edit-tab-stops | |
197 @findex edit-tab-stops-note-changes | |
198 @kindex C-c C-c @r{(Edit Tab Stops)} | |
199 @vindex tab-stop-list | |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
200 You can change the tab stops used by @kbd{M-i} and other indentation |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
201 commands, so that they need not be spaced every eight characters, or |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
202 even regularly spaced. The tab stops are stored in the variable |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
203 @code{tab-stop-list}, as a list of column numbers in increasing order. |
84247 | 204 |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
205 A convenient way to set the tab stops is with @kbd{M-x |
84247 | 206 edit-tab-stops}, which creates and selects a buffer containing a |
207 description of the tab stop settings. You can edit this buffer to | |
208 specify different tab stops, and then type @kbd{C-c C-c} to make those | |
209 new tab stops take effect. The buffer uses Overwrite mode | |
210 (@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was | |
211 current when you invoked it, and stores the tab stops back in that | |
212 buffer; normally all buffers share the same tab stops and changing | |
213 them in one buffer affects all, but if you happen to make | |
214 @code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in | |
215 that buffer will edit the local settings. | |
216 | |
217 Here is what the text representing the tab stops looks like for ordinary | |
218 tab stops every eight columns. | |
219 | |
220 @example | |
221 : : : : : : | |
222 0 1 2 3 4 | |
223 0123456789012345678901234567890123456789012345678 | |
224 To install changes, type C-c C-c | |
225 @end example | |
226 | |
227 The first line contains a colon at each tab stop. The remaining lines | |
228 are present just to help you see where the colons are and know what to do. | |
229 | |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
230 Note that the tab stops that control @code{tab-to-tab-stop} have |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
231 nothing to do with how tab characters are displayed in the buffer. |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
232 Tab characters are always displayed as empty spaces extending to the |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
233 next display tab stop, which occurs every @code{tab-width} columns |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
234 regardless of the contents of @code{tab-stop-list}. @xref{Text |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
235 Display}. |
84247 | 236 |
237 @node Just Spaces,, Tab Stops, Indentation | |
238 @section Tabs vs. Spaces | |
239 | |
240 @vindex indent-tabs-mode | |
241 Emacs normally uses both tabs and spaces to indent lines. If you | |
242 prefer, all indentation can be made from spaces only. To request | |
243 this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer | |
244 variable, so altering the variable affects only the current buffer, | |
245 but there is a default value which you can change as well. | |
246 @xref{Locals}. | |
247 | |
248 A tab is not always displayed in the same way. By default, tabs are | |
99174
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
249 eight columns wide, but some people like to customize their editors to |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
250 use a different tab width (e.g., by changing the variable |
72600bc4207e
(Indentation): Replace list with paragraphed text, putting description
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
251 @code{tab-width} in Emacs). By using spaces only, you can make sure |
84247 | 252 that your file looks the same regardless of the tab width setting. |
253 | |
254 @findex tabify | |
255 @findex untabify | |
256 There are also commands to convert tabs to spaces or vice versa, always | |
257 preserving the columns of all nonblank text. @kbd{M-x tabify} scans the | |
258 region for sequences of spaces, and converts sequences of at least two | |
259 spaces to tabs if that can be done without changing indentation. @kbd{M-x | |
260 untabify} changes all tabs in the region to appropriate numbers of spaces. | |
261 | |
262 @ignore | |
263 arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb | |
264 @end ignore |