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