Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
ab422c4d PE |
2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software |
3 | @c Foundation, Inc. | |
6bf7aab6 | 4 | @c See file emacs.texi for copying conditions. |
abb9615e | 5 | @node Indentation |
6bf7aab6 DL |
6 | @chapter Indentation |
7 | @cindex indentation | |
70a9af81 | 8 | @cindex tabs |
6bf7aab6 DL |
9 | @cindex columns (indentation) |
10 | ||
6d262977 CY |
11 | @cindex whitespace character |
12 | @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace | |
13 | characters} (space and/or tab characters) at the beginning of a line | |
14 | of text. This chapter documents indentation commands and options | |
15 | which are common to Text mode and related modes, as well as | |
16 | programming language modes. @xref{Program Indent}, for additional | |
17 | documentation about indenting in programming modes. | |
18 | ||
19 | @findex indent-for-tab-command | |
20 | @kindex TAB @r{(indentation)} | |
21 | The simplest way to perform indentation is the @key{TAB} key. In | |
22 | most major modes, this runs the command @code{indent-for-tab-command}. | |
23 | (In C and related modes, @key{TAB} runs the command | |
24 | @code{c-indent-line-or-region}, which behaves similarly). | |
25 | ||
26 | @table @key | |
27 | @item TAB | |
28 | Insert whitespace, or indent the current line, in a mode-appropriate | |
29 | way (@code{indent-for-tab-command}). If the region is active, indent | |
30 | all the lines within it. | |
6bf7aab6 DL |
31 | @end table |
32 | ||
6d262977 CY |
33 | The exact behavior of @key{TAB} depends on the major mode. In Text |
34 | mode and related major modes, @key{TAB} normally inserts some | |
35 | combination of space and tab characters to advance point to the next | |
36 | tab stop (@pxref{Tab Stops}). For this purpose, the position of the | |
37 | first non-whitespace character on the preceding line is treated as an | |
38 | additional tab stop, so you can use @key{TAB} to ``align'' point with | |
39 | the preceding line. If the region is active (@pxref{Using Region}), | |
40 | @key{TAB} acts specially: it indents each line in the region so that | |
41 | its first non-whitespace character is aligned with the preceding line. | |
42 | ||
43 | In programming modes, @key{TAB} indents the current line of code in | |
44 | a way that makes sense given the code in the preceding lines. If the | |
45 | region is active, all the lines in the region are indented this way. | |
46 | If point was initially within the current line's indentation, it is | |
47 | repositioned to the first non-whitespace character on the line. | |
70a9af81 | 48 | |
6d262977 CY |
49 | If you just want to insert a tab character in the buffer, type |
50 | @kbd{C-q @key{TAB}} (@pxref{Inserting Text}). | |
70a9af81 | 51 | |
6d262977 CY |
52 | @menu |
53 | * Indentation Commands:: More commands for performing indentation. | |
54 | * Tab Stops:: Stop points for indentation in Text modes. | |
55 | * Just Spaces:: Using only space characters for indentation. | |
56 | * Indent Convenience:: Optional indentation features. | |
57 | @end menu | |
70a9af81 | 58 | |
6d262977 CY |
59 | @node Indentation Commands |
60 | @section Indentation Commands | |
15cf2f52 | 61 | |
6d262977 CY |
62 | Apart from the @key{TAB} (@code{indent-for-tab-command}) command, |
63 | Emacs provides a variety of commands to perform indentation in other | |
64 | ways. | |
99ffa7da | 65 | |
6d262977 CY |
66 | @table @kbd |
67 | @item C-j | |
68 | @kindex C-j | |
69 | @findex newline-and-indent | |
70 | Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). | |
6bf7aab6 | 71 | |
6d262977 CY |
72 | @item C-M-o |
73 | @kindex C-M-o | |
74 | @findex split-line | |
75 | Split the current line at point (@code{split-line}). The text on the | |
76 | line after point becomes a new line, indented to the same column where | |
77 | point is located. This command first moves point forward over any | |
78 | spaces and tabs. Afterward, point is positioned before the inserted | |
79 | newline. | |
6bf7aab6 DL |
80 | |
81 | @kindex M-m | |
82 | @findex back-to-indentation | |
6d262977 CY |
83 | @item M-m |
84 | Move (forward or back) to the first non-whitespace character on the | |
85 | current line (@code{back-to-indentation}). If there are no | |
86 | non-whitespace characters on the line, move to the end of the line. | |
6bf7aab6 | 87 | |
6d262977 CY |
88 | @item M-i |
89 | @kindex M-i | |
90 | @findex tab-to-tab-stop | |
91 | Indent whitespace at point, up to the next tab stop | |
92 | (@code{tab-to-tab-stop}). @xref{Tab Stops}. | |
6bf7aab6 | 93 | |
6d262977 CY |
94 | @findex indent-relative |
95 | @item M-x indent-relative | |
96 | Insert whitespace at point, until point is aligned with the first | |
97 | non-whitespace character on the previous line (actually, the last | |
98 | non-blank line). If point is already farther right than that, run | |
99 | @code{tab-to-tab-stop} instead---unless called with a numeric | |
100 | argument, in which case do nothing. | |
6bf7aab6 | 101 | |
6d262977 | 102 | @item M-^ |
6bf7aab6 DL |
103 | @kindex M-^ |
104 | @findex delete-indentation | |
6d262977 CY |
105 | Merge the previous and the current line (@code{delete-indentation}). |
106 | This ``joins'' the two lines cleanly, by replacing any indentation at | |
107 | the front of the current line, together with the line boundary, with a | |
108 | single space. | |
109 | ||
110 | As a special case (useful for Lisp code), the single space is omitted | |
111 | if the characters to be joined are consecutive opening and closing | |
112 | parentheses, or if the junction follows another newline. | |
113 | ||
114 | If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it | |
6bf7aab6 DL |
115 | appears after the newline that is deleted. @xref{Fill Prefix}. |
116 | ||
6d262977 | 117 | @item C-M-\ |
6bf7aab6 | 118 | @kindex C-M-\ |
6bf7aab6 | 119 | @findex indent-region |
6d262977 CY |
120 | Indent all the lines in the region, as though you had typed @key{TAB} |
121 | at the beginning of each line (@code{indent-region}). | |
6bf7aab6 | 122 | |
6d262977 CY |
123 | If a numeric argument is supplied, indent every line in the region to |
124 | that column number. | |
125 | ||
126 | @item C-x @key{TAB} | |
127 | @kindex C-x TAB | |
128 | @findex indent-rigidly | |
f98345fa | 129 | @cindex remove indentation |
6d262977 CY |
130 | Shift each line in the region by a fixed distance, to the right or |
131 | left (@code{indent-rigidly}). The distance to move is determined by | |
132 | the numeric argument (positive to move rightward, negative to move | |
133 | leftward). | |
134 | ||
135 | This command can be used to remove all indentation from the lines in | |
136 | the region, by invoking it with a large negative argument, | |
1df7defd | 137 | e.g., @kbd{C-u -1000 C-x @key{TAB}}. |
6d262977 | 138 | @end table |
f98345fa | 139 | |
6d262977 | 140 | @node Tab Stops |
6bf7aab6 | 141 | @section Tab Stops |
177c0ea7 | 142 | @cindex tab stops |
6d262977 CY |
143 | |
144 | @vindex tab-stop-list | |
145 | Emacs defines certain column numbers to be @dfn{tab stops}. These | |
146 | are used as stopping points by @key{TAB} when inserting whitespace in | |
147 | Text mode and related modes (@pxref{Indentation}), and by commands | |
148 | like @kbd{M-i} (@pxref{Indentation Commands}). By default, tab stops | |
149 | are located every 8 columns. These positions are stored in the | |
150 | variable @code{tab-stop-list}, whose value is a list of column numbers | |
151 | in increasing order. | |
6bf7aab6 DL |
152 | |
153 | @findex edit-tab-stops | |
6bf7aab6 | 154 | @kindex C-c C-c @r{(Edit Tab Stops)} |
6d262977 CY |
155 | Instead of customizing the variable @code{tab-stop-list} directly, a |
156 | convenient way to view and set tab stops is via the command @kbd{M-x | |
157 | edit-tab-stops}. This switches to a buffer containing a description | |
158 | of the tab stop settings, which looks like this: | |
6bf7aab6 DL |
159 | |
160 | @example | |
161 | : : : : : : | |
162 | 0 1 2 3 4 | |
163 | 0123456789012345678901234567890123456789012345678 | |
164 | To install changes, type C-c C-c | |
165 | @end example | |
166 | ||
6d262977 CY |
167 | @noindent |
168 | The first line contains a colon at each tab stop. The numbers on the | |
169 | next two lines are present just to indicate where the colons are. | |
170 | ||
171 | You can edit this buffer to specify different tab stops by placing | |
172 | colons on the desired columns. The buffer uses Overwrite mode | |
173 | (@pxref{Minor Modes}). When you are done, type @kbd{C-c C-c} to make | |
174 | the new tab stops take effect. Normally, the new tab stop settings | |
175 | apply to all buffers. However, if you have made the | |
176 | @code{tab-stop-list} variable local to the buffer where you called | |
177 | @kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop | |
178 | settings apply only to that buffer. To save the tab stop settings for | |
179 | future Emacs sessions, use the Customize interface to save the value | |
180 | of @code{tab-stop-list} (@pxref{Easy Customization}). | |
181 | ||
182 | Note that the tab stops discussed in this section have nothing to do | |
183 | with how tab characters are displayed in the buffer. Tab characters | |
184 | are always displayed as empty spaces extending to the next | |
185 | @dfn{display tab stop}. @xref{Text Display}. | |
186 | ||
187 | @node Just Spaces | |
188 | @section Tabs vs. Spaces | |
6bf7aab6 | 189 | |
6d262977 CY |
190 | @vindex tab-width |
191 | Normally, indentation commands insert (or remove) an optimal mix of | |
192 | space characters and tab characters to align to the desired column. | |
193 | Tab characters are displayed as a stretch of empty space extending to | |
194 | the next @dfn{display tab stop}. By default, there is one display tab | |
195 | stop every @code{tab-width} columns (the default is 8). @xref{Text | |
70a9af81 | 196 | Display}. |
6bf7aab6 | 197 | |
6bf7aab6 | 198 | @vindex indent-tabs-mode |
6d262977 CY |
199 | If you prefer, all indentation can be made from spaces only. To |
200 | request this, set the buffer-local variable @code{indent-tabs-mode} to | |
201 | @code{nil}. @xref{Locals}, for information about setting buffer-local | |
202 | variables. Note, however, that @kbd{C-q @key{TAB}} always inserts a | |
203 | tab character, regardless of the value of @code{indent-tabs-mode}. | |
204 | ||
205 | One reason to set @code{indent-tabs-mode} to @code{nil} is that not | |
206 | all editors display tab characters in the same way. Emacs users, too, | |
207 | may have different customized values of @code{tab-width}. By using | |
208 | spaces only, you can make sure that your file always looks the same. | |
209 | If you only care about how it looks within Emacs, another way to | |
210 | tackle this problem is to set the @code{tab-width} variable in a | |
211 | file-local variable (@pxref{File Variables}). | |
99ffa7da | 212 | |
6bf7aab6 DL |
213 | @findex tabify |
214 | @findex untabify | |
215 | There are also commands to convert tabs to spaces or vice versa, always | |
6d262977 | 216 | preserving the columns of all non-whitespace text. @kbd{M-x tabify} scans the |
2aa2f8b8 | 217 | region for sequences of spaces, and converts sequences of at least two |
6bf7aab6 DL |
218 | spaces to tabs if that can be done without changing indentation. @kbd{M-x |
219 | untabify} changes all tabs in the region to appropriate numbers of spaces. | |
6d262977 CY |
220 | |
221 | @node Indent Convenience | |
222 | @section Convenience Features for Indentation | |
223 | ||
224 | @vindex tab-always-indent | |
225 | The variable @code{tab-always-indent} tweaks the behavior of the | |
226 | @key{TAB} (@code{indent-for-tab-command}) command. The default value, | |
227 | @code{t}, gives the behavior described in @ref{Indentation}. If you | |
228 | change the value to the symbol @code{complete}, then @key{TAB} first | |
229 | tries to indent the current line, and if the line was already | |
230 | indented, it tries to complete the text at point (@pxref{Symbol | |
231 | Completion}). If the value is @code{nil}, then @key{TAB} indents the | |
232 | current line only if point is at the left margin or in the line's | |
233 | indentation; otherwise, it inserts a tab character. | |
234 | ||
235 | @cindex Electric Indent mode | |
236 | @cindex mode, Electric Indent | |
237 | @findex electric-indent-mode | |
238 | Electric Indent mode is a global minor mode that automatically | |
239 | indents the line after every @key{RET} you type. To toggle this minor | |
240 | mode, type @kbd{M-x electric-indent-mode}. |