001: @c This is part of the Emacs manual.
002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 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: @item C-M-\
114: @kindex C-M-\
115: @findex indent-region
116: Indent all the lines in the region, as though you had typed
117: @kbd{@key{TAB}} at the beginning of each line (@code{indent-region}).
118: 
119: If a numeric argument is supplied, indent every line in the region to
120: that column number.
121: 
122: @item C-x @key{TAB}
123: @kindex C-x TAB
124: @findex indent-rigidly
125: @cindex remove indentation
126: This command is used to change the indentation of all lines that begin
127: in the region, moving the affected lines as a rigid unit.
128: 
129: If called with no argument, the command activates a transient mode for
130: adjusting the indentation of the affected lines interactively.  While
131: this transient mode is active, typing @kbd{@key{LEFT}} or
132: @kbd{@key{RIGHT}} indents leftward and rightward, respectively, by one
133: space.  You can also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to
134: indent leftward or rightward to the next tab stop (@pxref{Tab Stops}).
135: Typing any other key disables the transient mode, and resumes normal
136: editing.
137: 
138: If called with a prefix argument @var{n}, this command indents the
139: lines forward by @var{n} spaces (without enabling the transient mode).
140: Negative values of @var{n} indent backward, so you can remove all
141: indentation from the lines in the region using a large negative
142: argument, like this:
143: 
144: @smallexample
145: C-u -999 C-x @key{TAB}
146: @end smallexample
147: @end table
148: 
149: @node Tab Stops
150: @section Tab Stops
151: @cindex tab stops
152: 
153: @vindex tab-stop-list
154:   Emacs defines certain column numbers to be @dfn{tab stops}.  These
155: are used as stopping points by @key{TAB} when inserting whitespace in
156: Text mode and related modes (@pxref{Indentation}), and by commands
157: like @kbd{M-i} (@pxref{Indentation Commands}).  The variable
158: @code{tab-stop-list} controls these positions.  The default value is
159: @code{nil}, which means a tab stop every 8 columns.  The value can
160: also be a list of zero-based column numbers (in increasing order) at
161: which to place tab stops.  Emacs extends the list forever by repeating
162: the difference between the last and next-to-last elements.
163: 
164: @findex edit-tab-stops
165: @kindex C-c C-c @r{(Edit Tab Stops)}
166:   Instead of customizing the variable @code{tab-stop-list} directly, a
167: convenient way to view and set tab stops is via the command @kbd{M-x
168: edit-tab-stops}.  This switches to a buffer containing a description
169: of the tab stop settings, which looks like this:
170: 
171: @example
172:         :       :       :       :       :       :
173: 0         1         2         3         4
174: 0123456789012345678901234567890123456789012345678
175: To install changes, type C-c C-c
176: @end example
177: 
178: @noindent
179: The first line contains a colon at each tab stop.  The numbers on the
180: next two lines are present just to indicate where the colons are.
181: If the value of @code{tab-stop-list} is @code{nil}, as it is by default,
182: no colons are displayed initially.
183: 
184:   You can edit this buffer to specify different tab stops by placing
185: colons on the desired columns.  The buffer uses Overwrite mode
186: (@pxref{Minor Modes}).  Remember that Emacs will extend the list of
187: tab stops forever by repeating the difference between the last two
188: explicit stops that you place.  When you are done, type @kbd{C-c C-c} to make
189: the new tab stops take effect.  Normally, the new tab stop settings
190: apply to all buffers.  However, if you have made the
191: @code{tab-stop-list} variable local to the buffer where you called
192: @kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
193: settings apply only to that buffer.  To save the tab stop settings for
194: future Emacs sessions, use the Customize interface to save the value
195: of @code{tab-stop-list} (@pxref{Easy Customization}).
196: 
197:   Note that the tab stops discussed in this section have nothing to do
198: with how tab characters are displayed in the buffer.  Tab characters
199: are always displayed as empty spaces extending to the next
200: @dfn{display tab stop}.  @xref{Text Display}.
201: 
202: @node Just Spaces
203: @section Tabs vs.@: Spaces
204: 
205:   Normally, indentation commands insert (or remove) the shortest
206: possible series of tab and space characters so as to align to the
207: desired column.  Tab characters are displayed as a stretch of empty
208: space extending to the next @dfn{display tab stop}.  By default, there
209: is one display tab stop every @code{tab-width} columns (the default is
210: 8).  @xref{Text Display}.
211: 
212: @vindex indent-tabs-mode
213:   If you prefer, all indentation can be made from spaces only.  To
214: request this, set the buffer-local variable @code{indent-tabs-mode} to
215: @code{nil}.  @xref{Locals}, for information about setting buffer-local
216: variables.  Note, however, that @kbd{C-q @key{TAB}} always inserts a
217: tab character, regardless of the value of @code{indent-tabs-mode}.
218: 
219:   One reason to set @code{indent-tabs-mode} to @code{nil} is that not
220: all editors display tab characters in the same way.  Emacs users, too,
221: may have different customized values of @code{tab-width}.  By using
222: spaces only, you can make sure that your file always looks the same.
223: If you only care about how it looks within Emacs, another way to
224: tackle this problem is to set the @code{tab-width} variable in a
225: file-local variable (@pxref{File Variables}).
226: 
227: @findex tabify
228: @findex untabify
229:   There are also commands to convert tabs to spaces or vice versa, always
230: preserving the columns of all non-whitespace text.  @kbd{M-x tabify} scans the
231: region for sequences of spaces, and converts sequences of at least two
232: spaces to tabs if that can be done without changing indentation.  @kbd{M-x
233: untabify} changes all tabs in the region to appropriate numbers of spaces.
234: 
235: @node Indent Convenience
236: @section Convenience Features for Indentation
237: 
238: @vindex tab-always-indent
239:   The variable @code{tab-always-indent} tweaks the behavior of the
240: @key{TAB} (@code{indent-for-tab-command}) command.  The default value,
241: @code{t}, gives the behavior described in @ref{Indentation}.  If you
242: change the value to the symbol @code{complete}, then @key{TAB} first
243: tries to indent the current line, and if the line was already
244: indented, it tries to complete the text at point (@pxref{Symbol
245: Completion}).  If the value is @code{nil}, then @key{TAB} indents the
246: current line only if point is at the left margin or in the line's
247: indentation; otherwise, it inserts a tab character.
248: 
249: @cindex Electric Indent mode
250: @cindex mode, Electric Indent
251: @findex electric-indent-mode
252:   Electric Indent mode is a global minor mode that automatically
253: indents the line after every @key{RET} you type.  This mode is enabled
254: by default.  To toggle this minor mode, type @kbd{M-x
255: electric-indent-mode}.  To toggle the mode in a single buffer,
256: use @kbd{M-x electric-indent-local-mode}.
257: