doc/emacs/indent.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software
   3 @c Foundation, Inc.
   4 @c See file emacs.texi for copying conditions.
   5 @node Indentation
   6 @chapter Indentation
   7 @cindex indentation
   8 @cindex tabs
   9 @cindex columns (indentation)
  10
  11 @cindex whitespace character
  12   @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace
  13 characters} (space and/or tab characters) at the beginning of a line
  14 of text.  This chapter documents indentation commands and options
  15 which are common to Text mode and related modes, as well as
  16 programming language modes.  @xref{Program Indent}, for additional
  17 documentation about indenting in programming modes.
  18
  19 @findex indent-for-tab-command
  20 @kindex TAB @r{(indentation)}
  21   The simplest way to perform indentation is the @key{TAB} key.  In
  22 most major modes, this runs the command @code{indent-for-tab-command}.
  23 (In C and related modes, @key{TAB} runs the command
  24 @code{c-indent-line-or-region}, which behaves similarly).
  25
  26 @table @key
  27 @item TAB
  28 Insert whitespace, or indent the current line, in a mode-appropriate
  29 way (@code{indent-for-tab-command}).  If the region is active, indent
  30 all the lines within it.
  31 @end table
  32
  33   The exact behavior of @key{TAB} depends on the major mode.  In Text
  34 mode and related major modes, @key{TAB} normally inserts some
  35 combination of space and tab characters to advance point to the next
  36 tab stop (@pxref{Tab Stops}).  For this purpose, the position of the
  37 first non-whitespace character on the preceding line is treated as an
  38 additional tab stop, so you can use @key{TAB} to ``align'' point with
  39 the preceding line.  If the region is active (@pxref{Using Region}),
  40 @key{TAB} acts specially: it indents each line in the region so that
  41 its first non-whitespace character is aligned with the preceding line.
  42
  43   In programming modes, @key{TAB} indents the current line of code in
  44 a way that makes sense given the code in the preceding lines.  If the
  45 region is active, all the lines in the region are indented this way.
  46 If point was initially within the current line's indentation, it is
  47 repositioned to the first non-whitespace character on the line.
  48
  49   If you just want to insert a tab character in the buffer, type
  50 @kbd{C-q @key{TAB}} (@pxref{Inserting Text}).
  51
  52 @menu
  53 * Indentation Commands::  More commands for performing indentation.
  54 * Tab Stops::             Stop points for indentation in Text modes.
  55 * Just Spaces::           Using only space characters for indentation.
  56 * Indent Convenience::    Optional indentation features.
  57 @end menu
  58
  59 @node Indentation Commands
  60 @section Indentation Commands
  61
  62 Apart from the @key{TAB} (@code{indent-for-tab-command}) command,
  63 Emacs provides a variety of commands to perform indentation in other
  64 ways.
  65
  66 @table @kbd
  67 @item C-M-o
  68 @kindex C-M-o
  69 @findex split-line
  70 Split the current line at point (@code{split-line}).  The text on the
  71 line after point becomes a new line, indented to the same column where
  72 point is located.  This command first moves point forward over any
  73 spaces and tabs.  Afterward, point is positioned before the inserted
  74 newline.
  75
  76 @kindex M-m
  77 @findex back-to-indentation
  78 @item M-m
  79 Move (forward or back) to the first non-whitespace character on the
  80 current line (@code{back-to-indentation}).  If there are no
  81 non-whitespace characters on the line, move to the end of the line.
  82
  83 @item M-i
  84 @kindex M-i
  85 @findex tab-to-tab-stop
  86 Indent whitespace at point, up to the next tab stop
  87 (@code{tab-to-tab-stop}).  @xref{Tab Stops}.
  88
  89 @findex indent-relative
  90 @item M-x indent-relative
  91 Insert whitespace at point, until point is aligned with the first
  92 non-whitespace character on the previous line (actually, the last
  93 non-blank line).  If point is already farther right than that, run
  94 @code{tab-to-tab-stop} instead---unless called with a numeric
  95 argument, in which case do nothing.
  96
  97 @item M-^
  98 @kindex M-^
  99 @findex delete-indentation
 100 Merge the previous and the current line (@code{delete-indentation}).
 101 This ``joins'' the two lines cleanly, by replacing any indentation at
 102 the front of the current line, together with the line boundary, with a
 103 single space.
 104
 105 As a special case (useful for Lisp code), the single space is omitted
 106 if the characters to be joined are consecutive opening and closing
 107 parentheses, or if the junction follows another newline.
 108
 109 If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it
 110 appears after the newline that is deleted.  @xref{Fill Prefix}.
 111
 112 @item C-M-\
 113 @kindex C-M-\
 114 @findex indent-region
 115 Indent all the lines in the region, as though you had typed @key{TAB}
 116 at the beginning of each line (@code{indent-region}).
 117
 118 If a numeric argument is supplied, indent every line in the region to
 119 that column number.
 120
 121 @item C-x @key{TAB}
 122 @kindex C-x TAB
 123 @findex indent-rigidly
 124 @cindex remove indentation
 125 This command is used to change the indentation of all lines that begin
 126 in the region, moving the affected lines as a ``rigid'' unit.
 127
 128 If called with no argument, the command activates a transient mode for
 129 adjusting the indentation of the affected lines interactively.  While
 130 this transient mode is active, typing @key{LEFT} or @key{RIGHT}
 131 indents leftward and rightward, respectively, by one space.  You can
 132 also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to indent leftward
 133 or rightward to the next tab stop (@pxref{Tab Stops}).  Typing any
 134 other key disables the transient mode, and resumes normal editing.
 135
 136 If called with a prefix argument @var{n}, this command indents the
 137 lines forward by @var{n} spaces (without enabling the transient mode).
 138 Negative values of @var{n} indent backward, so you can remove all
 139 indentation from the lines in the region using a large negative
 140 argument, like this:
 141
 142 @smallexample
 143 C-u -999 C-x @key{TAB}
 144 @end smallexample
 145 @end table
 146
 147 @node Tab Stops
 148 @section Tab Stops
 149 @cindex tab stops
 150
 151 @vindex tab-stop-list
 152   Emacs defines certain column numbers to be @dfn{tab stops}.  These
 153 are used as stopping points by @key{TAB} when inserting whitespace in
 154 Text mode and related modes (@pxref{Indentation}), and by commands
 155 like @kbd{M-i} (@pxref{Indentation Commands}).  The variable
 156 @code{tab-stop-list} controls these positions.  The default value is
 157 @code{nil}, which means a tab stop every 8 columns.  The value can
 158 also be a list of zero-based column numbers (in increasing order) at
 159 which to place tab stops.  Emacs extends the list forever by repeating
 160 the difference between the last and next-to-last elements.
 161
 162 @findex edit-tab-stops
 163 @kindex C-c C-c @r{(Edit Tab Stops)}
 164   Instead of customizing the variable @code{tab-stop-list} directly, a
 165 convenient way to view and set tab stops is via the command @kbd{M-x
 166 edit-tab-stops}.  This switches to a buffer containing a description
 167 of the tab stop settings, which looks like this:
 168
 169 @example
 170         :       :       :       :       :       :
 171 0         1         2         3         4
 172 0123456789012345678901234567890123456789012345678
 173 To install changes, type C-c C-c
 174 @end example
 175
 176 @noindent
 177 The first line contains a colon at each tab stop.  The numbers on the
 178 next two lines are present just to indicate where the colons are.
 179 If the value of @code{tab-stop-list} is @code{nil}, as it is by default,
 180 no colons are displayed initially.
 181
 182   You can edit this buffer to specify different tab stops by placing
 183 colons on the desired columns.  The buffer uses Overwrite mode
 184 (@pxref{Minor Modes}).  Remember that Emacs will extend the list of
 185 tab stops forever by repeating the difference between the last two
 186 explicit stops that you place.  When you are done, type @kbd{C-c C-c} to make
 187 the new tab stops take effect.  Normally, the new tab stop settings
 188 apply to all buffers.  However, if you have made the
 189 @code{tab-stop-list} variable local to the buffer where you called
 190 @kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
 191 settings apply only to that buffer.  To save the tab stop settings for
 192 future Emacs sessions, use the Customize interface to save the value
 193 of @code{tab-stop-list} (@pxref{Easy Customization}).
 194
 195   Note that the tab stops discussed in this section have nothing to do
 196 with how tab characters are displayed in the buffer.  Tab characters
 197 are always displayed as empty spaces extending to the next
 198 @dfn{display tab stop}.  @xref{Text Display}.
 199
 200 @node Just Spaces
 201 @section Tabs vs. Spaces
 202
 203 @vindex tab-width
 204   Normally, indentation commands insert (or remove) an optimal mix of
 205 space characters and tab characters to align to the desired column.
 206 Tab characters are displayed as a stretch of empty space extending to
 207 the next @dfn{display tab stop}.  By default, there is one display tab
 208 stop every @code{tab-width} columns (the default is 8).  @xref{Text
 209 Display}.
 210
 211 @vindex indent-tabs-mode
 212   If you prefer, all indentation can be made from spaces only.  To
 213 request this, set the buffer-local variable @code{indent-tabs-mode} to
 214 @code{nil}.  @xref{Locals}, for information about setting buffer-local
 215 variables.  Note, however, that @kbd{C-q @key{TAB}} always inserts a
 216 tab character, regardless of the value of @code{indent-tabs-mode}.
 217
 218   One reason to set @code{indent-tabs-mode} to @code{nil} is that not
 219 all editors display tab characters in the same way.  Emacs users, too,
 220 may have different customized values of @code{tab-width}.  By using
 221 spaces only, you can make sure that your file always looks the same.
 222 If you only care about how it looks within Emacs, another way to
 223 tackle this problem is to set the @code{tab-width} variable in a
 224 file-local variable (@pxref{File Variables}).
 225
 226 @findex tabify
 227 @findex untabify
 228   There are also commands to convert tabs to spaces or vice versa, always
 229 preserving the columns of all non-whitespace text.  @kbd{M-x tabify} scans the
 230 region for sequences of spaces, and converts sequences of at least two
 231 spaces to tabs if that can be done without changing indentation.  @kbd{M-x
 232 untabify} changes all tabs in the region to appropriate numbers of spaces.
 233
 234 @node Indent Convenience
 235 @section Convenience Features for Indentation
 236
 237 @vindex tab-always-indent
 238   The variable @code{tab-always-indent} tweaks the behavior of the
 239 @key{TAB} (@code{indent-for-tab-command}) command.  The default value,
 240 @code{t}, gives the behavior described in @ref{Indentation}.  If you
 241 change the value to the symbol @code{complete}, then @key{TAB} first
 242 tries to indent the current line, and if the line was already
 243 indented, it tries to complete the text at point (@pxref{Symbol
 244 Completion}).  If the value is @code{nil}, then @key{TAB} indents the
 245 current line only if point is at the left margin or in the line's
 246 indentation; otherwise, it inserts a tab character.
 247
 248 @cindex Electric Indent mode
 249 @cindex mode, Electric Indent
 250 @findex electric-indent-mode
 251   Electric Indent mode is a global minor mode that automatically
 252 indents the line after every @key{RET} you type.  This mode is enabled
 253 by default.  To toggle this minor mode, type @kbd{M-x
 254 electric-indent-mode}.  To toggle the mode in a single buffer,
 255 use @kbd{M-x electric-indent-local-mode}.