Add some entries missing from 2002-11-16.
[emacs.git] / man / indent.texi
blobd21341032409c21d3c7bb3234e6046f332d230a3
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)
9   This chapter describes the Emacs commands that add, remove, or
10 adjust indentation.
12 @table @kbd
13 @item @key{TAB}
14 Indent the current line ``appropriately'' in a mode-dependent fashion.
15 @item @kbd{C-j}
16 Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
17 @item M-^
18 Merge the previous and the current line (@code{delete-indentation}).
19 This would cancel out the effect of @kbd{C-j}.
20 @item C-M-o
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}).
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-\
28 Indent several lines to the same column (@code{indent-region}).
29 @item C-x @key{TAB}
30 Shift a block of lines rigidly right or left (@code{indent-rigidly}).
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
38   Emacs supports four general categories of operations that could all
39 be called `indentation':
41 @enumerate
42 @item
43 Insert a tab character.  You can type @kbd{C-q @key{TAB}} to do this.
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.
49 @item
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}.
56 @item
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}.
62 @item
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.
68 @kindex TAB
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.
73 @end enumerate
75   Normally, all of the above methods insert an optimal mix of tabs and
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.
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}.
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
91 @node Indentation Commands, Tab Stops, Indentation, Indentation
92 @section Indentation Commands and Techniques
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.
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}.
104   If you just want to insert a tab character in the buffer, you can type
105 @kbd{C-q @key{TAB}}.
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}.
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.
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}.
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
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.
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
162 (@pxref{Tab Stops}),
163 @end ifinfo
164 @iftex
165 (see next section),
166 @end iftex
167 unless it is called with a numeric argument, in which case it does
168 nothing.
170   @code{indent-relative} is the definition of @key{TAB} in Indented Text
171 mode.  @xref{Text}.
173   @xref{Format Indentation}, for another way of specifying the
174 indentation for part of your text.
176 @node Tab Stops, Just Spaces, Indentation Commands, Indentation
177 @section Tab Stops
179 @cindex tab stops
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}.
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.
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.
208   Here is what the text representing the tab stops looks like for ordinary
209 tab stops every eight columns.
211 @example
212         :       :       :       :       :       :
213 0         1         2         3         4
214 0123456789012345678901234567890123456789012345678
215 To install changes, type C-c C-c
216 @end example
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.
221   Note that the tab stops that control @code{tab-to-tab-stop} have nothing
222 to do with displaying tab characters in the buffer.  @xref{Display Custom},
223 for more information on that.
225 @node Just Spaces,, Tab Stops, Indentation
226 @section Tabs vs. Spaces
228 @vindex indent-tabs-mode
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}.
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.
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.
249 @ignore
250    arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb
251 @end ignore