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-j
  68 @kindex C-j
  69 @findex newline-and-indent
  70 Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
  71
  72 @item C-M-o
  73 @kindex C-M-o
  74 @findex split-line
  75 Split the current line at point (@code{split-line}).  The text on the
  76 line after point becomes a new line, indented to the same column where
  77 point is located.  This command first moves point forward over any
  78 spaces and tabs.  Afterward, point is positioned before the inserted
  79 newline.
  80
  81 @kindex M-m
  82 @findex back-to-indentation
  83 @item M-m
  84 Move (forward or back) to the first non-whitespace character on the
  85 current line (@code{back-to-indentation}).  If there are no
  86 non-whitespace characters on the line, move to the end of the line.
  87
  88 @item M-i
  89 @kindex M-i
  90 @findex tab-to-tab-stop
  91 Indent whitespace at point, up to the next tab stop
  92 (@code{tab-to-tab-stop}).  @xref{Tab Stops}.
  93
  94 @findex indent-relative
  95 @item M-x indent-relative
  96 Insert whitespace at point, until point is aligned with the first
  97 non-whitespace character on the previous line (actually, the last
  98 non-blank line).  If point is already farther right than that, run
  99 @code{tab-to-tab-stop} instead---unless called with a numeric
 100 argument, in which case do nothing.
 101
 102 @item M-^
 103 @kindex M-^
 104 @findex delete-indentation
 105 Merge the previous and the current line (@code{delete-indentation}).
 106 This ``joins'' the two lines cleanly, by replacing any indentation at
 107 the front of the current line, together with the line boundary, with a
 108 single space.
 109
 110 As a special case (useful for Lisp code), the single space is omitted
 111 if the characters to be joined are consecutive opening and closing
 112 parentheses, or if the junction follows another newline.
 113
 114 If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it
 115 appears after the newline that is deleted.  @xref{Fill Prefix}.
 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 @key{TAB}
 121 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 @key{LEFT} or @key{RIGHT}
 136 indents leftward and rightward, respectively, by one space.  You can
 137 also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to indent leftward
 138 or rightward to the next tab stop (@pxref{Tab Stops}).  Typing any
 139 other key disables the transient mode, and resumes normal editing.
 140
 141 If called with a prefix argument @var{n}, this command indents the
 142 lines forward by @var{n} spaces (without enabling the transient mode).
 143 Negative values of @var{n} indent backward, so you can remove all
 144 indentation from the lines in the region using a large negative
 145 argument, like this:
 146
 147 @smallexample
 148 C-u -999 C-x @key{TAB}
 149 @end smallexample
 150 @end table
 151
 152 @node Tab Stops
 153 @section Tab Stops
 154 @cindex tab stops
 155
 156 @vindex tab-stop-list
 157   Emacs defines certain column numbers to be @dfn{tab stops}.  These
 158 are used as stopping points by @key{TAB} when inserting whitespace in
 159 Text mode and related modes (@pxref{Indentation}), and by commands
 160 like @kbd{M-i} (@pxref{Indentation Commands}).  By default, tab stops
 161 are located every 8 columns.  These positions are stored in the
 162 variable @code{tab-stop-list}, whose value is a list of column numbers
 163 in increasing order.
 164
 165 @findex edit-tab-stops
 166 @kindex C-c C-c @r{(Edit Tab Stops)}
 167   Instead of customizing the variable @code{tab-stop-list} directly, a
 168 convenient way to view and set tab stops is via the command @kbd{M-x
 169 edit-tab-stops}.  This switches to a buffer containing a description
 170 of the tab stop settings, which looks like this:
 171
 172 @example
 173         :       :       :       :       :       :
 174 0         1         2         3         4
 175 0123456789012345678901234567890123456789012345678
 176 To install changes, type C-c C-c
 177 @end example
 178
 179 @noindent
 180 The first line contains a colon at each tab stop.  The numbers on the
 181 next two lines are present just to indicate where the colons are.  It
 182 is implicitly extended to infinity by repeating the last step.
 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}).  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}.