Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
73b0cd50 GM |
2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 |
3 | @c Free Software Foundation, Inc. | |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Indentation, Text, Major Modes, Top | |
6 | @chapter Indentation | |
7 | @cindex indentation | |
70a9af81 | 8 | @cindex tabs |
6bf7aab6 DL |
9 | @cindex columns (indentation) |
10 | ||
11 | This chapter describes the Emacs commands that add, remove, or | |
12 | adjust indentation. | |
13 | ||
6bf7aab6 DL |
14 | @table @kbd |
15 | @item @key{TAB} | |
70a9af81 | 16 | Indent the current line appropriately, in a mode-dependent fashion. |
6bf7aab6 DL |
17 | @item @kbd{C-j} |
18 | Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
19 | @item M-^ | |
58fa012d | 20 | Merge the previous and the current line (@code{delete-indentation}). |
66375f06 | 21 | This would cancel the effect of a preceding @kbd{C-j}. |
6bf7aab6 | 22 | @item C-M-o |
4125ceb0 EZ |
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}). | |
6bf7aab6 DL |
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-\ | |
66375f06 | 30 | Indent lines in the region to the same column (@code{indent-region}). |
6bf7aab6 | 31 | @item C-x @key{TAB} |
66375f06 | 32 | Shift lines in the region rigidly right or left (@code{indent-rigidly}). |
6bf7aab6 DL |
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 | ||
15cf2f52 CY |
40 | @noindent |
41 | The @key{TAB} key runs @code{indent-for-tab-command} in most major | |
42 | modes (in C and related modes, @key{TAB} runs a separate command, | |
43 | @code{c-indent-line-or-region}, which behaves similarly). The major | |
44 | mode determines just what this entails. | |
70a9af81 | 45 | |
15cf2f52 CY |
46 | In text modes, @key{TAB} inserts some combination of space and tab |
47 | characters to advance point to the next tab stop (@pxref{Tab Stops}). | |
48 | If the region is active and spans multiple lines, it advances the | |
49 | first character of each of those lines to the next tab stop | |
50 | (@pxref{Using Region}). For the purposes of this command, the | |
51 | position of the first non-whitespace character on the preceding line | |
52 | is treated as an additional tab stop. Thus, you can use @key{TAB} to | |
53 | ``align'' point with the preceding line. | |
70a9af81 | 54 | |
15cf2f52 CY |
55 | In programming modes, @key{TAB} adds or removes some combination of |
56 | space and tab characters at the start of the line, in a way that makes | |
57 | sense given the text in the preceding lines. If the region is active | |
58 | and spans multiple lines, all those lines are indented this way. If | |
59 | point was initially within the current line's indentation, it is | |
60 | positioned after that indentation; otherwise, it remains at same point | |
61 | in the newly-indented text. @xref{Program Indent}. | |
70a9af81 CY |
62 | |
63 | @vindex tab-width | |
15cf2f52 CY |
64 | Normally, indentation commands insert (or remove) an optimal mix of |
65 | @dfn{tab characters} and spaces to align to the desired column. Tab | |
66 | characters (@acronym{ASCII} code 9) are displayed as a stretch of | |
67 | empty space extending to the next @dfn{display tab stop}. By default, | |
68 | there is one display tab stop every eight columns; the number of | |
69 | columns is determined by the variable @code{tab-width}. You can | |
70 | insert a single tab character by typing @kbd{C-q @key{TAB}}. | |
71 | @xref{Text Display}. | |
70a9af81 CY |
72 | |
73 | @findex edit-tab-stops | |
74 | @findex tab-to-tab-stop | |
75 | @kindex M-i | |
76 | The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the | |
77 | whitespace characters around point, inserting just enough whitespace | |
78 | to advance point up to the next tab stop. By default, this involves | |
79 | deleting the existing whitespace and inserting a single tab character. | |
80 | ||
15cf2f52 CY |
81 | @xref{Just Spaces}, for how to disable use of tabs. However, |
82 | @kbd{C-q @key{TAB}} always inserts a tab, even when tabs are disabled | |
83 | for the indentation commands. | |
84 | ||
85 | @vindex tab-always-indent | |
86 | The variable @code{tab-always-indent} tweaks the behavior of the | |
87 | @key{TAB} (@code{indent-for-tab-command}) command. The default value, | |
88 | @code{t}, gives the behavior described above. If you change the value | |
89 | to the symbol @code{complete}, then @key{TAB} first tries to indent | |
90 | the current line, and if the line was already indented, it tries to | |
91 | complete the text at point (@pxref{Symbol Completion}). If the value | |
92 | is @code{nil}, then @key{TAB} indents the current line only if point | |
93 | is at the left margin or in the line's indentation; otherwise, it | |
94 | inserts a real tab character. | |
99ffa7da | 95 | |
6bf7aab6 DL |
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, | |
2aa2f8b8 LT |
110 | positions point at the first nonblank character on the line, if any, |
111 | or else at the end of the line. | |
6bf7aab6 DL |
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 | ||
70a9af81 | 117 | If you just want to insert a tab character in the buffer, type |
6bf7aab6 DL |
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-^} | |
a3053e27 RS |
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-\} | |
6bf7aab6 DL |
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 | |
2aa2f8b8 LT |
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 | |
6bf7aab6 | 157 | arguments). The whole group of lines moves rigidly sideways, which is |
a3053e27 | 158 | how the command gets its name. |
6bf7aab6 | 159 | |
f98345fa | 160 | @cindex remove indentation |
a3053e27 RS |
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. | |
f98345fa | 164 | |
6bf7aab6 DL |
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 | |
2aa2f8b8 | 168 | point, until it is underneath the next indentation point in the previous line. |
6bf7aab6 DL |
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 | |
2aa2f8b8 | 171 | previous line, @code{indent-relative} runs @code{tab-to-tab-stop} |
29848974 | 172 | @ifnottex |
3b01b911 | 173 | (@pxref{Tab Stops}), |
29848974 | 174 | @end ifnottex |
6bf7aab6 | 175 | @iftex |
3b01b911 | 176 | (see next section), |
6bf7aab6 | 177 | @end iftex |
3b01b911 EZ |
178 | unless it is called with a numeric argument, in which case it does |
179 | nothing. | |
6bf7aab6 | 180 | |
6bf7aab6 DL |
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 | ||
177c0ea7 | 187 | @cindex tab stops |
6bf7aab6 DL |
188 | @cindex using tab stops in making tables |
189 | @cindex tables, indentation for | |
190 | @kindex M-i | |
191 | @findex tab-to-tab-stop | |
2aa2f8b8 LT |
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. | |
6bf7aab6 DL |
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 | |
70a9af81 CY |
200 | You can change the tab stops used by @kbd{M-i} and other indentation |
201 | commands, so that they need not be spaced every eight characters, or | |
202 | even regularly spaced. The tab stops are stored in the variable | |
203 | @code{tab-stop-list}, as a list of column numbers in increasing order. | |
6bf7aab6 | 204 | |
70a9af81 | 205 | A convenient way to set the tab stops is with @kbd{M-x |
6bf7aab6 DL |
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 | |
2aa2f8b8 LT |
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 | |
6bf7aab6 DL |
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 | ||
70a9af81 CY |
230 | Note that the tab stops that control @code{tab-to-tab-stop} have |
231 | nothing to do with how tab characters are displayed in the buffer. | |
232 | Tab characters are always displayed as empty spaces extending to the | |
233 | next display tab stop, which occurs every @code{tab-width} columns | |
234 | regardless of the contents of @code{tab-stop-list}. @xref{Text | |
235 | Display}. | |
6bf7aab6 DL |
236 | |
237 | @node Just Spaces,, Tab Stops, Indentation | |
238 | @section Tabs vs. Spaces | |
239 | ||
240 | @vindex indent-tabs-mode | |
2e4a0639 RS |
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}. | |
6bf7aab6 | 247 | |
99ffa7da | 248 | A tab is not always displayed in the same way. By default, tabs are |
70a9af81 CY |
249 | eight columns wide, but some people like to customize their editors to |
250 | use a different tab width (e.g., by changing the variable | |
251 | @code{tab-width} in Emacs). By using spaces only, you can make sure | |
99ffa7da KG |
252 | that your file looks the same regardless of the tab width setting. |
253 | ||
6bf7aab6 DL |
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 | |
2aa2f8b8 | 258 | region for sequences of spaces, and converts sequences of at least two |
6bf7aab6 DL |
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. |