001: @c This is part of the Emacs manual.
002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software
003: @c Foundation, Inc.
004: @c See file emacs.texi for copying conditions.
005: @node Indentation
006: @chapter Indentation
007: @cindex indentation
008: @cindex tabs
009: @cindex columns (indentation)
010: 
011: @cindex whitespace character
012:   @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace
013: characters} (space and/or tab characters) at the beginning of a line
014: of text.  This chapter documents indentation commands and options
015: which are common to Text mode and related modes, as well as
016: programming language modes.  @xref{Program Indent}, for additional
017: documentation about indenting in programming modes.
018: 
019: @findex indent-for-tab-command
020: @kindex TAB @r{(indentation)}
021:   The simplest way to perform indentation is the @key{TAB} key.  In
022: most major modes, this runs the command @code{indent-for-tab-command}.
023: (In C and related modes, @key{TAB} runs the command
024: @code{c-indent-line-or-region}, which behaves similarly, @pxref{C
025: Indent}).
026: 
027: @table @key
028: @item TAB
029: Insert whitespace, or indent the current line, in a mode-appropriate
030: way (@code{indent-for-tab-command}).  If the region is active, indent
031: all the lines within it.
032: @end table
033: 
034:   The exact behavior of @key{TAB} depends on the major mode.  In Text
035: mode and related major modes, @key{TAB} normally inserts some
036: combination of space and tab characters to advance point to the next
037: tab stop (@pxref{Tab Stops}).  For this purpose, the position of the
038: first non-whitespace character on the preceding line is treated as an
039: additional tab stop, so you can use @key{TAB} to align point with
040: the preceding line.  If the region is active (@pxref{Using Region}),
041: @key{TAB} acts specially: it indents each line in the region so that
042: its first non-whitespace character is aligned with the preceding line.
043: 
044:   In programming modes, @key{TAB} indents the current line of code in
045: a way that makes sense given the code in the preceding lines.  If the
046: region is active, all the lines in the region are indented this way.
047: If point was initially within the current line's indentation, it is
048: repositioned to the first non-whitespace character on the line.
049: 
050:   If you just want to insert a tab character in the buffer, type
051: @kbd{C-q @key{TAB}} (@pxref{Inserting Text}).
052: 
053: @menu
054: * Indentation Commands::  More commands for performing indentation.
055: * Tab Stops::             Stop points for indentation in Text modes.
056: * Just Spaces::           Using only space characters for indentation.
057: * Indent Convenience::    Optional indentation features.
058: @end menu
059: 
060: @node Indentation Commands
061: @section Indentation Commands
062: 
063: Apart from the @kbd{@key{TAB}} (@code{indent-for-tab-command})
064: command, Emacs provides a variety of commands to perform indentation
065: in other ways.
066: 
067: @table @kbd
068: @item C-M-o
069: @kindex C-M-o
070: @findex split-line
071: Split the current line at point (@code{split-line}).  The text on the
072: line after point becomes a new line, indented to the same column where
073: point is located.  This command first moves point forward over any
074: spaces and tabs.  Afterward, point is positioned before the inserted
075: newline.
076: 
077: @kindex M-m
078: @findex back-to-indentation
079: @item M-m
080: Move (forward or back) to the first non-whitespace character on the
081: current line (@code{back-to-indentation}).  If there are no
082: non-whitespace characters on the line, move to the end of the line.
083: 
084: @item M-i
085: @kindex M-i
086: @findex tab-to-tab-stop
087: Indent whitespace at point, up to the next tab stop
088: (@code{tab-to-tab-stop}).  @xref{Tab Stops}.
089: 
090: @findex indent-relative
091: @item M-x indent-relative
092: Insert whitespace at point, until point is aligned with the first
093: non-whitespace character on the previous line (actually, the last
094: non-blank line).  If point is already farther right than that, run
095: @code{tab-to-tab-stop} instead---unless called with a numeric
096: argument, in which case do nothing.
097: 
098: @item M-^
099: @kindex M-^
100: @findex delete-indentation
101: Merge the previous and the current line (@code{delete-indentation}).
102: This joins the two lines cleanly, by replacing any indentation at
103: the front of the current line, together with the line boundary, with a
104: single space.
105: 
106: As a special case (useful for Lisp code), the single space is omitted
107: if the characters to be joined are consecutive opening and closing
108: parentheses, or if the junction follows another newline.
109: 
110: If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it
111: appears after the newline that is deleted.  @xref{Fill Prefix}.
112: 
113: With a prefix argument, join the current line line to the following
114: line.  If the region is active, and no prefix argument is given, join
115: all lines in the region instead.
116: 
117: @item C-M-\
118: @kindex C-M-\
119: @findex indent-region
120: Indent all the lines in the region, as though you had typed
121: @kbd{@key{TAB}} at the beginning of each line (@code{indent-region}).
122: 
123: If a numeric argument is supplied, indent every line in the region to
124: that column number.
125: 
126: @item C-x @key{TAB}
127: @kindex C-x TAB
128: @findex indent-rigidly
129: @cindex remove indentation
130: This command is used to change the indentation of all lines that begin
131: in the region, moving the affected lines as a rigid unit.
132: 
133: If called with no argument, the command activates a transient mode for
134: adjusting the indentation of the affected lines interactively.  While
135: this transient mode is active, typing @kbd{@key{LEFT}} or
136: @kbd{@key{RIGHT}} indents leftward and rightward, respectively, by one
137: space.  You can also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to
138: indent leftward or rightward to the next tab stop (@pxref{Tab Stops}).
139: Typing any other key disables the transient mode, and resumes normal
140: editing.
141: 
142: If called with a prefix argument @var{n}, this command indents the
143: lines forward by @var{n} spaces (without enabling the transient mode).
144: Negative values of @var{n} indent backward, so you can remove all
145: indentation from the lines in the region using a large negative
146: argument, like this:
147: 
148: @smallexample
149: C-u -999 C-x @key{TAB}
150: @end smallexample
151: @end table
152: 
153: @node Tab Stops
154: @section Tab Stops
155: @cindex tab stops
156: 
157: @vindex tab-stop-list
158:   Emacs defines certain column numbers to be @dfn{tab stops}.  These
159: are used as stopping points by @key{TAB} when inserting whitespace in
160: Text mode and related modes (@pxref{Indentation}), and by commands
161: like @kbd{M-i} (@pxref{Indentation Commands}).  The variable
162: @code{tab-stop-list} controls these positions.  The default value is
163: @code{nil}, which means a tab stop every 8 columns.  The value can
164: also be a list of zero-based column numbers (in increasing order) at
165: which to place tab stops.  Emacs extends the list forever by repeating
166: the difference between the last and next-to-last elements.
167: 
168: @findex edit-tab-stops
169: @kindex C-c C-c @r{(Edit Tab Stops)}
170:   Instead of customizing the variable @code{tab-stop-list} directly, a
171: convenient way to view and set tab stops is via the command @kbd{M-x
172: edit-tab-stops}.  This switches to a buffer containing a description
173: of the tab stop settings, which looks like this:
174: 
175: @example
176:         :       :       :       :       :       :
177: 0         1         2         3         4
178: 0123456789012345678901234567890123456789012345678
179: To install changes, type C-c C-c
180: @end example
181: 
182: @noindent
183: The first line contains a colon at each tab stop.  The numbers on the
184: next two lines are present just to indicate where the colons are.
185: If the value of @code{tab-stop-list} is @code{nil}, as it is by default,
186: no colons are displayed initially.
187: 
188:   You can edit this buffer to specify different tab stops by placing
189: colons on the desired columns.  The buffer uses Overwrite mode
190: (@pxref{Minor Modes}).  Remember that Emacs will extend the list of
191: tab stops forever by repeating the difference between the last two
192: explicit stops that you place.  When you are done, type @kbd{C-c C-c} to make
193: the new tab stops take effect.  Normally, the new tab stop settings
194: apply to all buffers.  However, if you have made the
195: @code{tab-stop-list} variable local to the buffer where you called
196: @kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
197: settings apply only to that buffer.  To save the tab stop settings for
198: future Emacs sessions, use the Customize interface to save the value
199: of @code{tab-stop-list} (@pxref{Easy Customization}).
200: 
201:   Note that the tab stops discussed in this section have nothing to do
202: with how tab characters are displayed in the buffer.  Tab characters
203: are always displayed as empty spaces extending to the next
204: @dfn{display tab stop}.  @xref{Text Display}.
205: 
206: @node Just Spaces
207: @section Tabs vs.@: Spaces
208: 
209:   Normally, indentation commands insert (or remove) the shortest
210: possible series of tab and space characters so as to align to the
211: desired column.  Tab characters are displayed as a stretch of empty
212: space extending to the next @dfn{display tab stop}.  By default, there
213: is one display tab stop every @code{tab-width} columns (the default is
214: 8).  @xref{Text Display}.
215: 
216: @vindex indent-tabs-mode
217:   If you prefer, all indentation can be made from spaces only.  To
218: request this, set the buffer-local variable @code{indent-tabs-mode} to
219: @code{nil}.  @xref{Locals}, for information about setting buffer-local
220: variables.  Note, however, that @kbd{C-q @key{TAB}} always inserts a
221: tab character, regardless of the value of @code{indent-tabs-mode}.
222: 
223:   One reason to set @code{indent-tabs-mode} to @code{nil} is that not
224: all editors display tab characters in the same way.  Emacs users, too,
225: may have different customized values of @code{tab-width}.  By using
226: spaces only, you can make sure that your file always looks the same.
227: If you only care about how it looks within Emacs, another way to
228: tackle this problem is to set the @code{tab-width} variable in a
229: file-local variable (@pxref{File Variables}).
230: 
231: @findex tabify
232: @findex untabify
233:   There are also commands to convert tabs to spaces or vice versa, always
234: preserving the columns of all non-whitespace text.  @kbd{M-x tabify} scans the
235: region for sequences of spaces, and converts sequences of at least two
236: spaces to tabs if that can be done without changing indentation.  @kbd{M-x
237: untabify} changes all tabs in the region to appropriate numbers of spaces.
238: 
239: @node Indent Convenience
240: @section Convenience Features for Indentation
241: 
242: @vindex tab-always-indent
243:   The variable @code{tab-always-indent} tweaks the behavior of the
244: @key{TAB} (@code{indent-for-tab-command}) command.  The default value,
245: @code{t}, gives the behavior described in @ref{Indentation}.  If you
246: change the value to the symbol @code{complete}, then @key{TAB} first
247: tries to indent the current line, and if the line was already
248: indented, it tries to complete the text at point (@pxref{Symbol
249: Completion}).  If the value is @code{nil}, then @key{TAB} indents the
250: current line only if point is at the left margin or in the line's
251: indentation; otherwise, it inserts a tab character.
252: 
253: @cindex Electric Indent mode
254: @cindex mode, Electric Indent
255: @findex electric-indent-mode
256:   Electric Indent mode is a global minor mode that automatically
257: indents the line after every @key{RET} you type.  This mode is enabled
258: by default.  To toggle this minor mode, type @kbd{M-x
259: electric-indent-mode}.  To toggle the mode in a single buffer,
260: use @kbd{M-x electric-indent-local-mode}.
261: