*** empty log message ***
[emacs.git] / man / indent.texi
blob1a7310f8c8023914a5f4b472ccd0db67c0f7787c
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   Most programming languages have some indentation convention.  For Lisp
39 code, lines are indented according to their nesting in parentheses.  The
40 same general idea is used for C code, though many details are different.
42 @kindex TAB
43   Whatever the language, to indent a line, use the @key{TAB} command.  Each
44 major mode defines this command to perform the sort of indentation
45 appropriate for the particular language.  In Lisp mode, @key{TAB} aligns
46 the line according to its depth in parentheses.  No matter where in the
47 line you are when you type @key{TAB}, it aligns the line as a whole.  In C
48 mode, @key{TAB} implements a subtle and sophisticated indentation style that
49 knows about many aspects of C syntax.
51   In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
52 indents to the next tab stop column.  You can set the tab stops with
53 @kbd{M-x edit-tab-stops}.
55   Normally, @key{TAB} inserts an optimal mix of tabs and spaces for
56 the intended indentation.  @xref{Just Spaces}, for how to prevent use
57 of tabs.
59 @menu
60 * Indentation Commands::  Various commands and techniques for indentation.
61 * Tab Stops::             You can set arbitrary "tab stops" and then
62                             indent to the next tab stop when you want to.
63 * Just Spaces::           You can request indentation using just spaces.
64 @end menu
66 @node Indentation Commands, Tab Stops, Indentation, Indentation
67 @section Indentation Commands and Techniques
69 @kindex M-m
70 @findex back-to-indentation
71   To move over the indentation on a line, do @kbd{M-m}
72 (@code{back-to-indentation}).  This command, given anywhere on a line,
73 positions point at the first nonblank character on the line.
75   To insert an indented line before the current line, do @kbd{C-a C-o
76 @key{TAB}}.  To make an indented line after the current line, use
77 @kbd{C-e C-j}.
79   If you just want to insert a tab character in the buffer, you can type
80 @kbd{C-q @key{TAB}}.
82 @kindex C-M-o
83 @findex split-line
84   @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
85 the line vertically down, so that the current line becomes two lines.
86 @kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
87 inserts after point a newline and enough indentation to reach the same
88 column point is on.  Point remains before the inserted newline; in this
89 regard, @kbd{C-M-o} resembles @kbd{C-o}.
91 @kindex M-^
92 @findex delete-indentation
93   To join two lines cleanly, use the @kbd{M-^}
94 (@code{delete-indentation}) command.  It deletes the indentation at the
95 front of the current line, and the line boundary as well, replacing them
96 with a single space.  As a special case (useful for Lisp code) the
97 single space is omitted if the characters to be joined are consecutive
98 open parentheses or closing parentheses, or if the junction follows
99 another newline.  To delete just the indentation of a line, go to the
100 beginning of the line and use @kbd{M-\}
101 (@code{delete-horizontal-space}), which deletes all spaces and tabs
102 around the cursor.
104   If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
105 appears after the newline that is deleted.  @xref{Fill Prefix}.
107 @kindex C-M-\
108 @kindex C-x TAB
109 @findex indent-region
110 @findex indent-rigidly
111   There are also commands for changing the indentation of several lines
112 at once.  @kbd{C-M-\} (@code{indent-region}) applies to all the lines
113 that begin in the region; it indents each line in the ``usual'' way, as
114 if you had typed @key{TAB} at the beginning of the line.  A numeric
115 argument specifies the column to indent to, and each line is shifted
116 left or right so that its first nonblank character appears in that
117 column.  @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of the
118 lines in the region right by its argument (left, for negative
119 arguments).  The whole group of lines moves rigidly sideways, which is
120 how the command gets its name.@refill
122 @cindex remove indentation
123   If you want to remove all indentation from all of the line in the
124 region, invoke @kbd{C-x @key{TAB}} with a large negative argument,
125 such as -1000.
127 @findex indent-relative
128   @kbd{M-x indent-relative} indents at point based on the previous line
129 (actually, the last nonempty line).  It inserts whitespace at point, moving
130 point, until it is underneath an indentation point in the previous line.
131 An indentation point is the end of a sequence of whitespace or the end of
132 the line.  If point is farther right than any indentation point in the
133 previous line, the whitespace before point is deleted and the first
134 indentation point then applicable is used.  If no indentation point is
135 applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop}
136 @ifinfo
137 (@pxref{Tab Stops}),
138 @end ifinfo
139 @iftex
140 (see next section),
141 @end iftex
142 unless it is called with a numeric argument, in which case it does
143 nothing.
145   @code{indent-relative} is the definition of @key{TAB} in Indented Text
146 mode.  @xref{Text}.
148   @xref{Format Indentation}, for another way of specifying the
149 indentation for part of your text.
151 @node Tab Stops, Just Spaces, Indentation Commands, Indentation
152 @section Tab Stops
154 @cindex tab stops 
155 @cindex using tab stops in making tables
156 @cindex tables, indentation for
157 @kindex M-i
158 @findex tab-to-tab-stop
159   For typing in tables, you can use Text mode's definition of @key{TAB},
160 @code{tab-to-tab-stop}.  This command inserts indentation before point,
161 enough to reach the next tab stop column.  If you are not in Text mode,
162 this command can be found on the key @kbd{M-i}.
164 @findex edit-tab-stops
165 @findex edit-tab-stops-note-changes
166 @kindex C-c C-c @r{(Edit Tab Stops)}
167 @vindex tab-stop-list
168   You can specify the tab stops used by @kbd{M-i}.  They are stored in a
169 variable called @code{tab-stop-list}, as a list of column-numbers in
170 increasing order.
172   The convenient way to set the tab stops is with @kbd{M-x
173 edit-tab-stops}, which creates and selects a buffer containing a
174 description of the tab stop settings.  You can edit this buffer to
175 specify different tab stops, and then type @kbd{C-c C-c} to make those
176 new tab stops take effect.  @code{edit-tab-stops} records which buffer
177 was current when you invoked it, and stores the tab stops back in that
178 buffer; normally all buffers share the same tab stops and changing them
179 in one buffer affects all, but if you happen to make
180 @code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
181 that buffer will edit the local settings.
183   Here is what the text representing the tab stops looks like for ordinary
184 tab stops every eight columns.
186 @example
187         :       :       :       :       :       :
188 0         1         2         3         4
189 0123456789012345678901234567890123456789012345678
190 To install changes, type C-c C-c
191 @end example
193   The first line contains a colon at each tab stop.  The remaining lines
194 are present just to help you see where the colons are and know what to do.
196   Note that the tab stops that control @code{tab-to-tab-stop} have nothing
197 to do with displaying tab characters in the buffer.  @xref{Display Custom},
198 for more information on that.
200 @node Just Spaces,, Tab Stops, Indentation
201 @section Tabs vs. Spaces
203 @vindex indent-tabs-mode
204   Emacs normally uses both tabs and spaces to indent lines.  If you
205 prefer, all indentation can be made from spaces only.  To request
206 this, set @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer
207 variable, so altering the variable affects only the current buffer,
208 but there is a default value which you can change as well.
209 @xref{Locals}.
211 @findex tabify
212 @findex untabify
213   There are also commands to convert tabs to spaces or vice versa, always
214 preserving the columns of all nonblank text.  @kbd{M-x tabify} scans the
215 region for sequences of spaces, and converts sequences of at least three
216 spaces to tabs if that can be done without changing indentation.  @kbd{M-x
217 untabify} changes all tabs in the region to appropriate numbers of spaces.