annotate man/indent.texi @ 45412:8c610da8ea94

* xfaces.c (merge_face_vector_with_property): Use SYMBOL_NAME and XSTRING instead of XSYMBOL and name field.
author Ken Raeburn <raeburn@raeburn.org>
date Mon, 20 May 2002 08:06:45 +0000
parents a093cd4ed690
children c48cc0f16c0e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
Dave Love <fx@gnu.org>
parents:
diff changeset
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @node Indentation, Text, Major Modes, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @chapter Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @cindex indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @cindex columns (indentation)
Dave Love <fx@gnu.org>
parents:
diff changeset
8
Dave Love <fx@gnu.org>
parents:
diff changeset
9 This chapter describes the Emacs commands that add, remove, or
Dave Love <fx@gnu.org>
parents:
diff changeset
10 adjust indentation.
Dave Love <fx@gnu.org>
parents:
diff changeset
11
Dave Love <fx@gnu.org>
parents:
diff changeset
12 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
13 @item @key{TAB}
38461
23f63206a867 Proofreading fixes from Chris Green <chris_e_green@yahoo.com>.
Eli Zaretskii <eliz@gnu.org>
parents: 38150
diff changeset
14 Indent the current line ``appropriately'' in a mode-dependent fashion.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
15 @item @kbd{C-j}
Dave Love <fx@gnu.org>
parents:
diff changeset
16 Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
Dave Love <fx@gnu.org>
parents:
diff changeset
17 @item M-^
38461
23f63206a867 Proofreading fixes from Chris Green <chris_e_green@yahoo.com>.
Eli Zaretskii <eliz@gnu.org>
parents: 38150
diff changeset
18 Merge the previous and the current line (@code{delete-indentation}).
23f63206a867 Proofreading fixes from Chris Green <chris_e_green@yahoo.com>.
Eli Zaretskii <eliz@gnu.org>
parents: 38150
diff changeset
19 This would cancel out the effect of @kbd{C-j}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
20 @item C-M-o
38490
1518ad710658 Fix last changes.
Eli Zaretskii <eliz@gnu.org>
parents: 38461
diff changeset
21 Split the current line at point; text on the line after point becomes a
1518ad710658 Fix last changes.
Eli Zaretskii <eliz@gnu.org>
parents: 38461
diff changeset
22 new line indented to the same column where point is located
1518ad710658 Fix last changes.
Eli Zaretskii <eliz@gnu.org>
parents: 38461
diff changeset
23 (@code{split-line}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
24 @item M-m
Dave Love <fx@gnu.org>
parents:
diff changeset
25 Move (forward or back) to the first nonblank character on the current
Dave Love <fx@gnu.org>
parents:
diff changeset
26 line (@code{back-to-indentation}).
Dave Love <fx@gnu.org>
parents:
diff changeset
27 @item C-M-\
38461
23f63206a867 Proofreading fixes from Chris Green <chris_e_green@yahoo.com>.
Eli Zaretskii <eliz@gnu.org>
parents: 38150
diff changeset
28 Indent several lines to the same column (@code{indent-region}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
29 @item C-x @key{TAB}
38461
23f63206a867 Proofreading fixes from Chris Green <chris_e_green@yahoo.com>.
Eli Zaretskii <eliz@gnu.org>
parents: 38150
diff changeset
30 Shift a block of lines rigidly right or left (@code{indent-rigidly}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
31 @item M-i
Dave Love <fx@gnu.org>
parents:
diff changeset
32 Indent from point to the next prespecified tab stop column
Dave Love <fx@gnu.org>
parents:
diff changeset
33 (@code{tab-to-tab-stop}).
Dave Love <fx@gnu.org>
parents:
diff changeset
34 @item M-x indent-relative
Dave Love <fx@gnu.org>
parents:
diff changeset
35 Indent from point to under an indentation point in the previous line.
Dave Love <fx@gnu.org>
parents:
diff changeset
36 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
37
Dave Love <fx@gnu.org>
parents:
diff changeset
38 Most programming languages have some indentation convention. For Lisp
Dave Love <fx@gnu.org>
parents:
diff changeset
39 code, lines are indented according to their nesting in parentheses. The
Dave Love <fx@gnu.org>
parents:
diff changeset
40 same general idea is used for C code, though many details are different.
Dave Love <fx@gnu.org>
parents:
diff changeset
41
Dave Love <fx@gnu.org>
parents:
diff changeset
42 @kindex TAB
Dave Love <fx@gnu.org>
parents:
diff changeset
43 Whatever the language, to indent a line, use the @key{TAB} command. Each
Dave Love <fx@gnu.org>
parents:
diff changeset
44 major mode defines this command to perform the sort of indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
45 appropriate for the particular language. In Lisp mode, @key{TAB} aligns
Dave Love <fx@gnu.org>
parents:
diff changeset
46 the line according to its depth in parentheses. No matter where in the
Dave Love <fx@gnu.org>
parents:
diff changeset
47 line you are when you type @key{TAB}, it aligns the line as a whole. In C
Dave Love <fx@gnu.org>
parents:
diff changeset
48 mode, @key{TAB} implements a subtle and sophisticated indentation style that
Dave Love <fx@gnu.org>
parents:
diff changeset
49 knows about many aspects of C syntax.
Dave Love <fx@gnu.org>
parents:
diff changeset
50
Dave Love <fx@gnu.org>
parents:
diff changeset
51 In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
Dave Love <fx@gnu.org>
parents:
diff changeset
52 indents to the next tab stop column. You can set the tab stops with
Dave Love <fx@gnu.org>
parents:
diff changeset
53 @kbd{M-x edit-tab-stops}.
Dave Love <fx@gnu.org>
parents:
diff changeset
54
38743
daea04400144 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 38490
diff changeset
55 Normally, @key{TAB} inserts an optimal mix of tabs and spaces for
daea04400144 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 38490
diff changeset
56 the intended indentation. @xref{Just Spaces}, for how to prevent use
daea04400144 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 38490
diff changeset
57 of tabs.
38008
710f2cbdd6ab Add a cross-reference to the description of indent-tabs-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 37420
diff changeset
58
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
59 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
60 * Indentation Commands:: Various commands and techniques for indentation.
Dave Love <fx@gnu.org>
parents:
diff changeset
61 * Tab Stops:: You can set arbitrary "tab stops" and then
Dave Love <fx@gnu.org>
parents:
diff changeset
62 indent to the next tab stop when you want to.
Dave Love <fx@gnu.org>
parents:
diff changeset
63 * Just Spaces:: You can request indentation using just spaces.
Dave Love <fx@gnu.org>
parents:
diff changeset
64 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
65
Dave Love <fx@gnu.org>
parents:
diff changeset
66 @node Indentation Commands, Tab Stops, Indentation, Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
67 @section Indentation Commands and Techniques
Dave Love <fx@gnu.org>
parents:
diff changeset
68
Dave Love <fx@gnu.org>
parents:
diff changeset
69 @kindex M-m
Dave Love <fx@gnu.org>
parents:
diff changeset
70 @findex back-to-indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
71 To move over the indentation on a line, do @kbd{M-m}
Dave Love <fx@gnu.org>
parents:
diff changeset
72 (@code{back-to-indentation}). This command, given anywhere on a line,
Dave Love <fx@gnu.org>
parents:
diff changeset
73 positions point at the first nonblank character on the line.
Dave Love <fx@gnu.org>
parents:
diff changeset
74
Dave Love <fx@gnu.org>
parents:
diff changeset
75 To insert an indented line before the current line, do @kbd{C-a C-o
Dave Love <fx@gnu.org>
parents:
diff changeset
76 @key{TAB}}. To make an indented line after the current line, use
Dave Love <fx@gnu.org>
parents:
diff changeset
77 @kbd{C-e C-j}.
Dave Love <fx@gnu.org>
parents:
diff changeset
78
Dave Love <fx@gnu.org>
parents:
diff changeset
79 If you just want to insert a tab character in the buffer, you can type
Dave Love <fx@gnu.org>
parents:
diff changeset
80 @kbd{C-q @key{TAB}}.
Dave Love <fx@gnu.org>
parents:
diff changeset
81
Dave Love <fx@gnu.org>
parents:
diff changeset
82 @kindex C-M-o
Dave Love <fx@gnu.org>
parents:
diff changeset
83 @findex split-line
Dave Love <fx@gnu.org>
parents:
diff changeset
84 @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
Dave Love <fx@gnu.org>
parents:
diff changeset
85 the line vertically down, so that the current line becomes two lines.
Dave Love <fx@gnu.org>
parents:
diff changeset
86 @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it
Dave Love <fx@gnu.org>
parents:
diff changeset
87 inserts after point a newline and enough indentation to reach the same
Dave Love <fx@gnu.org>
parents:
diff changeset
88 column point is on. Point remains before the inserted newline; in this
Dave Love <fx@gnu.org>
parents:
diff changeset
89 regard, @kbd{C-M-o} resembles @kbd{C-o}.
Dave Love <fx@gnu.org>
parents:
diff changeset
90
Dave Love <fx@gnu.org>
parents:
diff changeset
91 @kindex M-^
Dave Love <fx@gnu.org>
parents:
diff changeset
92 @findex delete-indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
93 To join two lines cleanly, use the @kbd{M-^}
Dave Love <fx@gnu.org>
parents:
diff changeset
94 (@code{delete-indentation}) command. It deletes the indentation at the
Dave Love <fx@gnu.org>
parents:
diff changeset
95 front of the current line, and the line boundary as well, replacing them
Dave Love <fx@gnu.org>
parents:
diff changeset
96 with a single space. As a special case (useful for Lisp code) the
Dave Love <fx@gnu.org>
parents:
diff changeset
97 single space is omitted if the characters to be joined are consecutive
Dave Love <fx@gnu.org>
parents:
diff changeset
98 open parentheses or closing parentheses, or if the junction follows
Dave Love <fx@gnu.org>
parents:
diff changeset
99 another newline. To delete just the indentation of a line, go to the
Dave Love <fx@gnu.org>
parents:
diff changeset
100 beginning of the line and use @kbd{M-\}
Dave Love <fx@gnu.org>
parents:
diff changeset
101 (@code{delete-horizontal-space}), which deletes all spaces and tabs
Dave Love <fx@gnu.org>
parents:
diff changeset
102 around the cursor.
Dave Love <fx@gnu.org>
parents:
diff changeset
103
Dave Love <fx@gnu.org>
parents:
diff changeset
104 If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
Dave Love <fx@gnu.org>
parents:
diff changeset
105 appears after the newline that is deleted. @xref{Fill Prefix}.
Dave Love <fx@gnu.org>
parents:
diff changeset
106
Dave Love <fx@gnu.org>
parents:
diff changeset
107 @kindex C-M-\
Dave Love <fx@gnu.org>
parents:
diff changeset
108 @kindex C-x TAB
Dave Love <fx@gnu.org>
parents:
diff changeset
109 @findex indent-region
Dave Love <fx@gnu.org>
parents:
diff changeset
110 @findex indent-rigidly
Dave Love <fx@gnu.org>
parents:
diff changeset
111 There are also commands for changing the indentation of several lines
Dave Love <fx@gnu.org>
parents:
diff changeset
112 at once. @kbd{C-M-\} (@code{indent-region}) applies to all the lines
Dave Love <fx@gnu.org>
parents:
diff changeset
113 that begin in the region; it indents each line in the ``usual'' way, as
Dave Love <fx@gnu.org>
parents:
diff changeset
114 if you had typed @key{TAB} at the beginning of the line. A numeric
Dave Love <fx@gnu.org>
parents:
diff changeset
115 argument specifies the column to indent to, and each line is shifted
Dave Love <fx@gnu.org>
parents:
diff changeset
116 left or right so that its first nonblank character appears in that
Dave Love <fx@gnu.org>
parents:
diff changeset
117 column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of the
Dave Love <fx@gnu.org>
parents:
diff changeset
118 lines in the region right by its argument (left, for negative
Dave Love <fx@gnu.org>
parents:
diff changeset
119 arguments). The whole group of lines moves rigidly sideways, which is
Dave Love <fx@gnu.org>
parents:
diff changeset
120 how the command gets its name.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
121
Dave Love <fx@gnu.org>
parents:
diff changeset
122 @findex indent-relative
Dave Love <fx@gnu.org>
parents:
diff changeset
123 @kbd{M-x indent-relative} indents at point based on the previous line
Dave Love <fx@gnu.org>
parents:
diff changeset
124 (actually, the last nonempty line). It inserts whitespace at point, moving
Dave Love <fx@gnu.org>
parents:
diff changeset
125 point, until it is underneath an indentation point in the previous line.
Dave Love <fx@gnu.org>
parents:
diff changeset
126 An indentation point is the end of a sequence of whitespace or the end of
Dave Love <fx@gnu.org>
parents:
diff changeset
127 the line. If point is farther right than any indentation point in the
Dave Love <fx@gnu.org>
parents:
diff changeset
128 previous line, the whitespace before point is deleted and the first
Dave Love <fx@gnu.org>
parents:
diff changeset
129 indentation point then applicable is used. If no indentation point is
Dave Love <fx@gnu.org>
parents:
diff changeset
130 applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop}
Dave Love <fx@gnu.org>
parents:
diff changeset
131 @ifinfo
38150
e8daadee7c3c (Indentation Commands): Document what indent-relative does when called
Eli Zaretskii <eliz@gnu.org>
parents: 38008
diff changeset
132 (@pxref{Tab Stops}),
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
133 @end ifinfo
Dave Love <fx@gnu.org>
parents:
diff changeset
134 @iftex
38150
e8daadee7c3c (Indentation Commands): Document what indent-relative does when called
Eli Zaretskii <eliz@gnu.org>
parents: 38008
diff changeset
135 (see next section),
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
136 @end iftex
38150
e8daadee7c3c (Indentation Commands): Document what indent-relative does when called
Eli Zaretskii <eliz@gnu.org>
parents: 38008
diff changeset
137 unless it is called with a numeric argument, in which case it does
e8daadee7c3c (Indentation Commands): Document what indent-relative does when called
Eli Zaretskii <eliz@gnu.org>
parents: 38008
diff changeset
138 nothing.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
139
Dave Love <fx@gnu.org>
parents:
diff changeset
140 @code{indent-relative} is the definition of @key{TAB} in Indented Text
Dave Love <fx@gnu.org>
parents:
diff changeset
141 mode. @xref{Text}.
Dave Love <fx@gnu.org>
parents:
diff changeset
142
Dave Love <fx@gnu.org>
parents:
diff changeset
143 @xref{Format Indentation}, for another way of specifying the
Dave Love <fx@gnu.org>
parents:
diff changeset
144 indentation for part of your text.
Dave Love <fx@gnu.org>
parents:
diff changeset
145
Dave Love <fx@gnu.org>
parents:
diff changeset
146 @node Tab Stops, Just Spaces, Indentation Commands, Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
147 @section Tab Stops
Dave Love <fx@gnu.org>
parents:
diff changeset
148
Dave Love <fx@gnu.org>
parents:
diff changeset
149 @cindex tab stops
Dave Love <fx@gnu.org>
parents:
diff changeset
150 @cindex using tab stops in making tables
Dave Love <fx@gnu.org>
parents:
diff changeset
151 @cindex tables, indentation for
Dave Love <fx@gnu.org>
parents:
diff changeset
152 @kindex M-i
Dave Love <fx@gnu.org>
parents:
diff changeset
153 @findex tab-to-tab-stop
Dave Love <fx@gnu.org>
parents:
diff changeset
154 For typing in tables, you can use Text mode's definition of @key{TAB},
Dave Love <fx@gnu.org>
parents:
diff changeset
155 @code{tab-to-tab-stop}. This command inserts indentation before point,
Dave Love <fx@gnu.org>
parents:
diff changeset
156 enough to reach the next tab stop column. If you are not in Text mode,
Dave Love <fx@gnu.org>
parents:
diff changeset
157 this command can be found on the key @kbd{M-i}.
Dave Love <fx@gnu.org>
parents:
diff changeset
158
Dave Love <fx@gnu.org>
parents:
diff changeset
159 @findex edit-tab-stops
Dave Love <fx@gnu.org>
parents:
diff changeset
160 @findex edit-tab-stops-note-changes
Dave Love <fx@gnu.org>
parents:
diff changeset
161 @kindex C-c C-c @r{(Edit Tab Stops)}
Dave Love <fx@gnu.org>
parents:
diff changeset
162 @vindex tab-stop-list
Dave Love <fx@gnu.org>
parents:
diff changeset
163 You can specify the tab stops used by @kbd{M-i}. They are stored in a
Dave Love <fx@gnu.org>
parents:
diff changeset
164 variable called @code{tab-stop-list}, as a list of column-numbers in
Dave Love <fx@gnu.org>
parents:
diff changeset
165 increasing order.
Dave Love <fx@gnu.org>
parents:
diff changeset
166
Dave Love <fx@gnu.org>
parents:
diff changeset
167 The convenient way to set the tab stops is with @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
168 edit-tab-stops}, which creates and selects a buffer containing a
Dave Love <fx@gnu.org>
parents:
diff changeset
169 description of the tab stop settings. You can edit this buffer to
Dave Love <fx@gnu.org>
parents:
diff changeset
170 specify different tab stops, and then type @kbd{C-c C-c} to make those
Dave Love <fx@gnu.org>
parents:
diff changeset
171 new tab stops take effect. @code{edit-tab-stops} records which buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
172 was current when you invoked it, and stores the tab stops back in that
Dave Love <fx@gnu.org>
parents:
diff changeset
173 buffer; normally all buffers share the same tab stops and changing them
Dave Love <fx@gnu.org>
parents:
diff changeset
174 in one buffer affects all, but if you happen to make
Dave Love <fx@gnu.org>
parents:
diff changeset
175 @code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
Dave Love <fx@gnu.org>
parents:
diff changeset
176 that buffer will edit the local settings.
Dave Love <fx@gnu.org>
parents:
diff changeset
177
Dave Love <fx@gnu.org>
parents:
diff changeset
178 Here is what the text representing the tab stops looks like for ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
179 tab stops every eight columns.
Dave Love <fx@gnu.org>
parents:
diff changeset
180
Dave Love <fx@gnu.org>
parents:
diff changeset
181 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
182 : : : : : :
Dave Love <fx@gnu.org>
parents:
diff changeset
183 0 1 2 3 4
Dave Love <fx@gnu.org>
parents:
diff changeset
184 0123456789012345678901234567890123456789012345678
Dave Love <fx@gnu.org>
parents:
diff changeset
185 To install changes, type C-c C-c
Dave Love <fx@gnu.org>
parents:
diff changeset
186 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
187
Dave Love <fx@gnu.org>
parents:
diff changeset
188 The first line contains a colon at each tab stop. The remaining lines
Dave Love <fx@gnu.org>
parents:
diff changeset
189 are present just to help you see where the colons are and know what to do.
Dave Love <fx@gnu.org>
parents:
diff changeset
190
Dave Love <fx@gnu.org>
parents:
diff changeset
191 Note that the tab stops that control @code{tab-to-tab-stop} have nothing
36208
898561c41ba0 FIx xref to Display Custom.
Richard M. Stallman <rms@gnu.org>
parents: 25829
diff changeset
192 to do with displaying tab characters in the buffer. @xref{Display Custom},
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
193 for more information on that.
Dave Love <fx@gnu.org>
parents:
diff changeset
194
Dave Love <fx@gnu.org>
parents:
diff changeset
195 @node Just Spaces,, Tab Stops, Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
196 @section Tabs vs. Spaces
Dave Love <fx@gnu.org>
parents:
diff changeset
197
Dave Love <fx@gnu.org>
parents:
diff changeset
198 @vindex indent-tabs-mode
37420
e495884180bb Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 36208
diff changeset
199 Emacs normally uses both tabs and spaces to indent lines. If you
e495884180bb Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 36208
diff changeset
200 prefer, all indentation can be made from spaces only. To request
e495884180bb Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 36208
diff changeset
201 this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer
e495884180bb Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 36208
diff changeset
202 variable, so altering the variable affects only the current buffer,
e495884180bb Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 36208
diff changeset
203 but there is a default value which you can change as well.
e495884180bb Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 36208
diff changeset
204 @xref{Locals}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
205
Dave Love <fx@gnu.org>
parents:
diff changeset
206 @findex tabify
Dave Love <fx@gnu.org>
parents:
diff changeset
207 @findex untabify
Dave Love <fx@gnu.org>
parents:
diff changeset
208 There are also commands to convert tabs to spaces or vice versa, always
Dave Love <fx@gnu.org>
parents:
diff changeset
209 preserving the columns of all nonblank text. @kbd{M-x tabify} scans the
Dave Love <fx@gnu.org>
parents:
diff changeset
210 region for sequences of spaces, and converts sequences of at least three
Dave Love <fx@gnu.org>
parents:
diff changeset
211 spaces to tabs if that can be done without changing indentation. @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
212 untabify} changes all tabs in the region to appropriate numbers of spaces.