indent.texi 11.1 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1
@c This is part of the Emacs manual.
2 3
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011
@c   Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
4
@c See file emacs.texi for copying conditions.
5
@node Indentation, Text, Modes, Top
Dave Love's avatar
#  
Dave Love committed
6 7
@chapter Indentation
@cindex indentation
8
@cindex tabs
Dave Love's avatar
#  
Dave Love committed
9 10 11 12 13 14 15
@cindex columns (indentation)

  This chapter describes the Emacs commands that add, remove, or
adjust indentation.

@table @kbd
@item @key{TAB}
16
Indent the current line appropriately, in a mode-dependent fashion.
Dave Love's avatar
#  
Dave Love committed
17 18 19
@item @kbd{C-j}
Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@item M-^
20
Merge the previous and the current line (@code{delete-indentation}).
21
This would cancel the effect of a preceding @kbd{C-j}.
Dave Love's avatar
#  
Dave Love committed
22
@item C-M-o
Eli Zaretskii's avatar
Eli Zaretskii committed
23 24 25
Split the current line at point; text on the line after point becomes a
new line indented to the same column where point is located
(@code{split-line}).
Dave Love's avatar
#  
Dave Love committed
26 27 28 29
@item M-m
Move (forward or back) to the first nonblank character on the current
line (@code{back-to-indentation}).
@item C-M-\
30
Indent lines in the region to the same column (@code{indent-region}).
Dave Love's avatar
#  
Dave Love committed
31
@item C-x @key{TAB}
32
Shift lines in the region rigidly right or left (@code{indent-rigidly}).
Dave Love's avatar
#  
Dave Love committed
33 34 35 36 37 38 39
@item M-i
Indent from point to the next prespecified tab stop column
(@code{tab-to-tab-stop}).
@item M-x indent-relative
Indent from point to under an indentation point in the previous line.
@end table

40 41 42 43 44
@noindent
The @key{TAB} key runs @code{indent-for-tab-command} in most major
modes (in C and related modes, @key{TAB} runs a separate command,
@code{c-indent-line-or-region}, which behaves similarly).  The major
mode determines just what this entails.
45

46 47 48 49 50 51 52 53
  In text modes, @key{TAB} inserts some combination of space and tab
characters to advance point to the next tab stop (@pxref{Tab Stops}).
If the region is active and spans multiple lines, it advances the
first character of each of those lines to the next tab stop
(@pxref{Using Region}).  For the purposes of this command, the
position of the first non-whitespace character on the preceding line
is treated as an additional tab stop.  Thus, you can use @key{TAB} to
``align'' point with the preceding line.
54

55 56 57 58 59 60 61
  In programming modes, @key{TAB} adds or removes some combination of
space and tab characters at the start of the line, in a way that makes
sense given the text in the preceding lines.  If the region is active
and spans multiple lines, all those lines are indented this way.  If
point was initially within the current line's indentation, it is
positioned after that indentation; otherwise, it remains at same point
in the newly-indented text.  @xref{Program Indent}.
62 63

@vindex tab-width
64 65 66 67 68 69 70 71
  Normally, indentation commands insert (or remove) an optimal mix of
@dfn{tab characters} and spaces to align to the desired column.  Tab
characters (@acronym{ASCII} code 9) are displayed as a stretch of
empty space extending to the next @dfn{display tab stop}.  By default,
there is one display tab stop every eight columns; the number of
columns is determined by the variable @code{tab-width}.  You can
insert a single tab character by typing @kbd{C-q @key{TAB}}.
@xref{Text Display}.
72 73 74 75 76 77 78 79 80

@findex edit-tab-stops
@findex tab-to-tab-stop
@kindex M-i
  The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the
whitespace characters around point, inserting just enough whitespace
to advance point up to the next tab stop.  By default, this involves
deleting the existing whitespace and inserting a single tab character.

81 82 83 84 85 86 87 88 89 90 91 92 93 94
  @xref{Just Spaces}, for how to disable use of tabs.  However,
@kbd{C-q @key{TAB}} always inserts a tab, even when tabs are disabled
for the indentation commands.

@vindex tab-always-indent
  The variable @code{tab-always-indent} tweaks the behavior of the
@key{TAB} (@code{indent-for-tab-command}) command.  The default value,
@code{t}, gives the behavior described above.  If you change the value
to the symbol @code{complete}, then @key{TAB} first tries to indent
the current line, and if the line was already indented, it tries to
complete the text at point (@pxref{Symbol Completion}).  If the value
is @code{nil}, then @key{TAB} indents the current line only if point
is at the left margin or in the line's indentation; otherwise, it
inserts a real tab character.
95

Dave Love's avatar
#  
Dave Love committed
96 97 98 99 100 101 102 103 104 105 106 107 108 109
@menu
* Indentation Commands::  Various commands and techniques for indentation.
* Tab Stops::             You can set arbitrary "tab stops" and then
                            indent to the next tab stop when you want to.
* Just Spaces::           You can request indentation using just spaces.
@end menu

@node Indentation Commands, Tab Stops, Indentation, Indentation
@section Indentation Commands and Techniques

@kindex M-m
@findex back-to-indentation
  To move over the indentation on a line, do @kbd{M-m}
(@code{back-to-indentation}).  This command, given anywhere on a line,
110 111
positions point at the first nonblank character on the line, if any,
or else at the end of the line.
Dave Love's avatar
#  
Dave Love committed
112 113 114 115 116

  To insert an indented line before the current line, do @kbd{C-a C-o
@key{TAB}}.  To make an indented line after the current line, use
@kbd{C-e C-j}.

117
  If you just want to insert a tab character in the buffer, type
Dave Love's avatar
#  
Dave Love committed
118 119 120 121 122 123 124 125 126 127 128 129 130 131
@kbd{C-q @key{TAB}}.

@kindex C-M-o
@findex split-line
  @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
the line vertically down, so that the current line becomes two lines.
@kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
inserts after point a newline and enough indentation to reach the same
column point is on.  Point remains before the inserted newline; in this
regard, @kbd{C-M-o} resembles @kbd{C-o}.

@kindex M-^
@findex delete-indentation
  To join two lines cleanly, use the @kbd{M-^}
Richard M. Stallman's avatar
Richard M. Stallman committed
132 133 134 135 136 137 138
(@code{delete-indentation}) command.  It deletes the indentation at
the front of the current line, and the line boundary as well,
replacing them with a single space.  As a special case (useful for
Lisp code) the single space is omitted if the characters to be joined
are consecutive open parentheses or closing parentheses, or if the
junction follows another newline.  To delete just the indentation of a
line, go to the beginning of the line and use @kbd{M-\}
Dave Love's avatar
#  
Dave Love committed
139 140 141 142 143 144 145 146 147 148 149
(@code{delete-horizontal-space}), which deletes all spaces and tabs
around the cursor.

  If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
appears after the newline that is deleted.  @xref{Fill Prefix}.

@kindex C-M-\
@kindex C-x TAB
@findex indent-region
@findex indent-rigidly
  There are also commands for changing the indentation of several lines
150 151 152 153 154 155 156
at once.  They apply to all the lines that begin in the region.
@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual''
way, as if you had typed @key{TAB} at the beginning of the line.  A
numeric argument specifies the column to indent to, and each line is
shifted left or right so that its first nonblank character appears in
that column.  @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of
the lines in the region right by its argument (left, for negative
Dave Love's avatar
#  
Dave Love committed
157
arguments).  The whole group of lines moves rigidly sideways, which is
Richard M. Stallman's avatar
Richard M. Stallman committed
158
how the command gets its name.
Dave Love's avatar
#  
Dave Love committed
159

160
@cindex remove indentation
Richard M. Stallman's avatar
Richard M. Stallman committed
161 162 163
  To remove all indentation from all of the lines in the region,
invoke @kbd{C-x @key{TAB}} with a large negative argument, such as
-1000.
164

Dave Love's avatar
#  
Dave Love committed
165 166 167
@findex indent-relative
  @kbd{M-x indent-relative} indents at point based on the previous line
(actually, the last nonempty line).  It inserts whitespace at point, moving
168
point, until it is underneath the next indentation point in the previous line.
Dave Love's avatar
#  
Dave Love committed
169 170
An indentation point is the end of a sequence of whitespace or the end of
the line.  If point is farther right than any indentation point in the
171
previous line, @code{indent-relative} runs @code{tab-to-tab-stop}
172
@ifnottex
173
(@pxref{Tab Stops}),
174
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
175
@iftex
176
(see next section),
Dave Love's avatar
#  
Dave Love committed
177
@end iftex
178 179
unless it is called with a numeric argument, in which case it does
nothing.
Dave Love's avatar
#  
Dave Love committed
180 181 182 183 184 185 186

  @xref{Format Indentation}, for another way of specifying the
indentation for part of your text.

@node Tab Stops, Just Spaces, Indentation Commands, Indentation
@section Tab Stops

187
@cindex tab stops
Dave Love's avatar
#  
Dave Love committed
188 189 190 191
@cindex using tab stops in making tables
@cindex tables, indentation for
@kindex M-i
@findex tab-to-tab-stop
192 193 194
  For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}).
This command inserts indentation before point, enough to reach the
next tab stop column.
Dave Love's avatar
#  
Dave Love committed
195 196 197 198 199

@findex edit-tab-stops
@findex edit-tab-stops-note-changes
@kindex C-c C-c @r{(Edit Tab Stops)}
@vindex tab-stop-list
200 201 202 203
  You can change the tab stops used by @kbd{M-i} and other indentation
commands, so that they need not be spaced every eight characters, or
even regularly spaced.  The tab stops are stored in the variable
@code{tab-stop-list}, as a list of column numbers in increasing order.
Dave Love's avatar
#  
Dave Love committed
204

205
  A convenient way to set the tab stops is with @kbd{M-x
Dave Love's avatar
#  
Dave Love committed
206 207 208
edit-tab-stops}, which creates and selects a buffer containing a
description of the tab stop settings.  You can edit this buffer to
specify different tab stops, and then type @kbd{C-c C-c} to make those
209 210 211 212 213
new tab stops take effect.  The buffer uses Overwrite mode
(@pxref{Minor Modes}).  @code{edit-tab-stops} records which buffer was
current when you invoked it, and stores the tab stops back in that
buffer; normally all buffers share the same tab stops and changing
them in one buffer affects all, but if you happen to make
Dave Love's avatar
#  
Dave Love committed
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
that buffer will edit the local settings.

  Here is what the text representing the tab stops looks like for ordinary
tab stops every eight columns.

@example
        :       :       :       :       :       :
0         1         2         3         4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c
@end example

  The first line contains a colon at each tab stop.  The remaining lines
are present just to help you see where the colons are and know what to do.

230 231 232 233 234 235
  Note that the tab stops that control @code{tab-to-tab-stop} have
nothing to do with how tab characters are displayed in the buffer.
Tab characters are always displayed as empty spaces extending to the
next display tab stop, which occurs every @code{tab-width} columns
regardless of the contents of @code{tab-stop-list}.  @xref{Text
Display}.
Dave Love's avatar
#  
Dave Love committed
236 237 238 239 240

@node Just Spaces,, Tab Stops, Indentation
@section Tabs vs. Spaces

@vindex indent-tabs-mode
Richard M. Stallman's avatar
Richard M. Stallman committed
241 242 243 244 245 246
  Emacs normally uses both tabs and spaces to indent lines.  If you
prefer, all indentation can be made from spaces only.  To request
this, set @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer
variable, so altering the variable affects only the current buffer,
but there is a default value which you can change as well.
@xref{Locals}.
Dave Love's avatar
#  
Dave Love committed
247

248
  A tab is not always displayed in the same way.  By default, tabs are
249 250 251
eight columns wide, but some people like to customize their editors to
use a different tab width (e.g., by changing the variable
@code{tab-width} in Emacs).  By using spaces only, you can make sure
252 253
that your file looks the same regardless of the tab width setting.

Dave Love's avatar
#  
Dave Love committed
254 255 256 257
@findex tabify
@findex untabify
  There are also commands to convert tabs to spaces or vice versa, always
preserving the columns of all nonblank text.  @kbd{M-x tabify} scans the
258
region for sequences of spaces, and converts sequences of at least two
Dave Love's avatar
#  
Dave Love committed
259 260
spaces to tabs if that can be done without changing indentation.  @kbd{M-x
untabify} changes all tabs in the region to appropriate numbers of spaces.