Commit | Line | Data |
---|---|---|
6bf7aab6 DL |
1 | @c This is part of the Emacs manual. |
2 | @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. | |
3 | @c See file emacs.texi for copying conditions. | |
4 | @node Indentation, Text, Major Modes, Top | |
5 | @chapter Indentation | |
6 | @cindex indentation | |
7 | @cindex columns (indentation) | |
8 | ||
9 | This chapter describes the Emacs commands that add, remove, or | |
10 | adjust indentation. | |
11 | ||
6bf7aab6 DL |
12 | @table @kbd |
13 | @item @key{TAB} | |
58fa012d | 14 | Indent the current line ``appropriately'' in a mode-dependent fashion. |
6bf7aab6 DL |
15 | @item @kbd{C-j} |
16 | Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
17 | @item M-^ | |
58fa012d EZ |
18 | Merge the previous and the current line (@code{delete-indentation}). |
19 | This would cancel out the effect of @kbd{C-j}. | |
6bf7aab6 | 20 | @item C-M-o |
4125ceb0 EZ |
21 | Split the current line at point; text on the line after point becomes a |
22 | new line indented to the same column where point is located | |
23 | (@code{split-line}). | |
6bf7aab6 DL |
24 | @item M-m |
25 | Move (forward or back) to the first nonblank character on the current | |
26 | line (@code{back-to-indentation}). | |
27 | @item C-M-\ | |
58fa012d | 28 | Indent several lines to the same column (@code{indent-region}). |
6bf7aab6 | 29 | @item C-x @key{TAB} |
58fa012d | 30 | Shift a block of lines rigidly right or left (@code{indent-rigidly}). |
6bf7aab6 DL |
31 | @item M-i |
32 | Indent from point to the next prespecified tab stop column | |
33 | (@code{tab-to-tab-stop}). | |
34 | @item M-x indent-relative | |
35 | Indent from point to under an indentation point in the previous line. | |
36 | @end table | |
37 | ||
99ffa7da KG |
38 | Emacs supports four general categories of operations that could all |
39 | be called `indentation': | |
40 | ||
41 | @enumerate | |
42 | @item | |
5ba75c80 | 43 | Insert a tab character. You can type @kbd{C-q @key{TAB}} to do this. |
99ffa7da KG |
44 | |
45 | A tab character is displayed as a stretch of whitespace which extends | |
46 | to the next display tab stop position, and the default width of a tab | |
47 | stop is eight. @xref{Display Custom}, for more details. | |
48 | ||
49 | @item | |
5ba75c80 RS |
50 | Advance to the next tab stop. You can set tab stops at your choice of |
51 | column positions, then type @kbd{M-i} to advance to the next tab stop. | |
52 | The default is to have tab stops every eight columns, which means by | |
53 | default @kbd{M-i} inserts a tab character. To set the tab stops, use | |
54 | @kbd{M-x edit-tab-stops}. | |
99ffa7da KG |
55 | |
56 | @item | |
5ba75c80 RS |
57 | Align a line with the previous line. More precisely, the command |
58 | @kbd{M-x indent-relative} indents the current line under the beginning | |
59 | of some word in the previous line. In Fundamental mode and in Text | |
60 | mode, @key{TAB} runs the command @code{indent-relative}. | |
99ffa7da KG |
61 | |
62 | @item | |
5ba75c80 RS |
63 | The most sophisticated method is @dfn{syntax-driven indentation}. |
64 | Most programming languages have an indentation convention. For Lisp | |
65 | code, lines are indented according to their nesting in parentheses. C | |
66 | code uses the same general idea, but many details are different. | |
99ffa7da | 67 | |
6bf7aab6 | 68 | @kindex TAB |
5ba75c80 RS |
69 | Type @key{TAB} to do syntax-driven indentation, in a mode that |
70 | supports it. It realigns the current line according with the syntax | |
71 | of the preceding lines. No matter where in the line you are when you | |
72 | type @key{TAB}, it aligns the line as a whole. | |
99ffa7da | 73 | @end enumerate |
6bf7aab6 | 74 | |
99ffa7da | 75 | Normally, all of the above methods insert an optimal mix of tabs and |
5ba75c80 RS |
76 | spaces to align to the desired column. @xref{Just Spaces}, for how to |
77 | disable use of tabs. However, @kbd{C-q @key{TAB}} always inserts a | |
78 | tab, even they are disabled for the indentation commands. | |
99ffa7da KG |
79 | |
80 | @c In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which | |
81 | @c indents to the next tab stop column. You can set the tab stops with | |
82 | @c @kbd{M-x edit-tab-stops}. | |
83 | ||
6bf7aab6 DL |
84 | @menu |
85 | * Indentation Commands:: Various commands and techniques for indentation. | |
86 | * Tab Stops:: You can set arbitrary "tab stops" and then | |
87 | indent to the next tab stop when you want to. | |
88 | * Just Spaces:: You can request indentation using just spaces. | |
89 | @end menu | |
90 | ||
91 | @node Indentation Commands, Tab Stops, Indentation, Indentation | |
92 | @section Indentation Commands and Techniques | |
93 | ||
94 | @kindex M-m | |
95 | @findex back-to-indentation | |
96 | To move over the indentation on a line, do @kbd{M-m} | |
97 | (@code{back-to-indentation}). This command, given anywhere on a line, | |
98 | positions point at the first nonblank character on the line. | |
99 | ||
100 | To insert an indented line before the current line, do @kbd{C-a C-o | |
101 | @key{TAB}}. To make an indented line after the current line, use | |
102 | @kbd{C-e C-j}. | |
103 | ||
104 | If you just want to insert a tab character in the buffer, you can type | |
105 | @kbd{C-q @key{TAB}}. | |
106 | ||
107 | @kindex C-M-o | |
108 | @findex split-line | |
109 | @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of | |
110 | the line vertically down, so that the current line becomes two lines. | |
111 | @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it | |
112 | inserts after point a newline and enough indentation to reach the same | |
113 | column point is on. Point remains before the inserted newline; in this | |
114 | regard, @kbd{C-M-o} resembles @kbd{C-o}. | |
115 | ||
116 | @kindex M-^ | |
117 | @findex delete-indentation | |
118 | To join two lines cleanly, use the @kbd{M-^} | |
119 | (@code{delete-indentation}) command. It deletes the indentation at the | |
120 | front of the current line, and the line boundary as well, replacing them | |
121 | with a single space. As a special case (useful for Lisp code) the | |
122 | single space is omitted if the characters to be joined are consecutive | |
123 | open parentheses or closing parentheses, or if the junction follows | |
124 | another newline. To delete just the indentation of a line, go to the | |
125 | beginning of the line and use @kbd{M-\} | |
126 | (@code{delete-horizontal-space}), which deletes all spaces and tabs | |
127 | around the cursor. | |
128 | ||
129 | If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it | |
130 | appears after the newline that is deleted. @xref{Fill Prefix}. | |
131 | ||
132 | @kindex C-M-\ | |
133 | @kindex C-x TAB | |
134 | @findex indent-region | |
135 | @findex indent-rigidly | |
136 | There are also commands for changing the indentation of several lines | |
137 | at once. @kbd{C-M-\} (@code{indent-region}) applies to all the lines | |
138 | that begin in the region; it indents each line in the ``usual'' way, as | |
139 | if you had typed @key{TAB} at the beginning of the line. A numeric | |
140 | argument specifies the column to indent to, and each line is shifted | |
141 | left or right so that its first nonblank character appears in that | |
142 | column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of the | |
143 | lines in the region right by its argument (left, for negative | |
144 | arguments). The whole group of lines moves rigidly sideways, which is | |
145 | how the command gets its name.@refill | |
146 | ||
f98345fa EZ |
147 | @cindex remove indentation |
148 | If you want to remove all indentation from all of the line in the | |
149 | region, invoke @kbd{C-x @key{TAB}} with a large negative argument, | |
150 | such as -1000. | |
151 | ||
6bf7aab6 DL |
152 | @findex indent-relative |
153 | @kbd{M-x indent-relative} indents at point based on the previous line | |
154 | (actually, the last nonempty line). It inserts whitespace at point, moving | |
155 | point, until it is underneath an indentation point in the previous line. | |
156 | An indentation point is the end of a sequence of whitespace or the end of | |
157 | the line. If point is farther right than any indentation point in the | |
158 | previous line, the whitespace before point is deleted and the first | |
159 | indentation point then applicable is used. If no indentation point is | |
160 | applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop} | |
161 | @ifinfo | |
3b01b911 | 162 | (@pxref{Tab Stops}), |
6bf7aab6 DL |
163 | @end ifinfo |
164 | @iftex | |
3b01b911 | 165 | (see next section), |
6bf7aab6 | 166 | @end iftex |
3b01b911 EZ |
167 | unless it is called with a numeric argument, in which case it does |
168 | nothing. | |
6bf7aab6 DL |
169 | |
170 | @code{indent-relative} is the definition of @key{TAB} in Indented Text | |
171 | mode. @xref{Text}. | |
172 | ||
173 | @xref{Format Indentation}, for another way of specifying the | |
174 | indentation for part of your text. | |
175 | ||
176 | @node Tab Stops, Just Spaces, Indentation Commands, Indentation | |
177 | @section Tab Stops | |
178 | ||
177c0ea7 | 179 | @cindex tab stops |
6bf7aab6 DL |
180 | @cindex using tab stops in making tables |
181 | @cindex tables, indentation for | |
182 | @kindex M-i | |
183 | @findex tab-to-tab-stop | |
184 | For typing in tables, you can use Text mode's definition of @key{TAB}, | |
185 | @code{tab-to-tab-stop}. This command inserts indentation before point, | |
186 | enough to reach the next tab stop column. If you are not in Text mode, | |
187 | this command can be found on the key @kbd{M-i}. | |
188 | ||
189 | @findex edit-tab-stops | |
190 | @findex edit-tab-stops-note-changes | |
191 | @kindex C-c C-c @r{(Edit Tab Stops)} | |
192 | @vindex tab-stop-list | |
193 | You can specify the tab stops used by @kbd{M-i}. They are stored in a | |
194 | variable called @code{tab-stop-list}, as a list of column-numbers in | |
195 | increasing order. | |
196 | ||
197 | The convenient way to set the tab stops is with @kbd{M-x | |
198 | edit-tab-stops}, which creates and selects a buffer containing a | |
199 | description of the tab stop settings. You can edit this buffer to | |
200 | specify different tab stops, and then type @kbd{C-c C-c} to make those | |
201 | new tab stops take effect. @code{edit-tab-stops} records which buffer | |
202 | was current when you invoked it, and stores the tab stops back in that | |
203 | buffer; normally all buffers share the same tab stops and changing them | |
204 | in one buffer affects all, but if you happen to make | |
205 | @code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in | |
206 | that buffer will edit the local settings. | |
207 | ||
208 | Here is what the text representing the tab stops looks like for ordinary | |
209 | tab stops every eight columns. | |
210 | ||
211 | @example | |
212 | : : : : : : | |
213 | 0 1 2 3 4 | |
214 | 0123456789012345678901234567890123456789012345678 | |
215 | To install changes, type C-c C-c | |
216 | @end example | |
217 | ||
218 | The first line contains a colon at each tab stop. The remaining lines | |
219 | are present just to help you see where the colons are and know what to do. | |
220 | ||
221 | Note that the tab stops that control @code{tab-to-tab-stop} have nothing | |
8748f1d7 | 222 | to do with displaying tab characters in the buffer. @xref{Display Custom}, |
6bf7aab6 DL |
223 | for more information on that. |
224 | ||
225 | @node Just Spaces,, Tab Stops, Indentation | |
226 | @section Tabs vs. Spaces | |
227 | ||
228 | @vindex indent-tabs-mode | |
2e4a0639 RS |
229 | Emacs normally uses both tabs and spaces to indent lines. If you |
230 | prefer, all indentation can be made from spaces only. To request | |
231 | this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer | |
232 | variable, so altering the variable affects only the current buffer, | |
233 | but there is a default value which you can change as well. | |
234 | @xref{Locals}. | |
6bf7aab6 | 235 | |
99ffa7da KG |
236 | A tab is not always displayed in the same way. By default, tabs are |
237 | eight columns wide, but some people like to customize their tools to | |
238 | use a different tab width. So by using spaces only, you can make sure | |
239 | that your file looks the same regardless of the tab width setting. | |
240 | ||
6bf7aab6 DL |
241 | @findex tabify |
242 | @findex untabify | |
243 | There are also commands to convert tabs to spaces or vice versa, always | |
244 | preserving the columns of all nonblank text. @kbd{M-x tabify} scans the | |
245 | region for sequences of spaces, and converts sequences of at least three | |
246 | spaces to tabs if that can be done without changing indentation. @kbd{M-x | |
247 | untabify} changes all tabs in the region to appropriate numbers of spaces. | |
ab5796a9 MB |
248 | |
249 | @ignore | |
250 | arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb | |
251 | @end ignore |