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}).  The variable
 161 @code{tab-stop-list} controls these positions.  The default value
 162 is @code{nil}, which means a tab stop every 8 columns.  The value
 163 can also be a list of column numbers (in increasing order) at which to
 164 place tab stops.  Emacs extends the list forever by repeating the
 165 difference between the last and next-to-last elements.
 166
 167 @findex edit-tab-stops
 168 @kindex C-c C-c @r{(Edit Tab Stops)}
 169   Instead of customizing the variable @code{tab-stop-list} directly, a
 170 convenient way to view and set tab stops is via the command @kbd{M-x
 171 edit-tab-stops}.  This switches to a buffer containing a description
 172 of the tab stop settings, which looks like this:
 173
 174 @example
 175         :       :       :       :       :       :
 176 0         1         2         3         4
 177 0123456789012345678901234567890123456789012345678
 178 To install changes, type C-c C-c
 179 @end example
 180
 181 @noindent
 182 The first line contains a colon at each tab stop.  The numbers on the
 183 next two lines are present just to indicate where the colons are.
 184 If the value of @code{tab-stop-list} is @code{nil}, as it is by default,
 185 no colons are displayed initially.
 186
 187   You can edit this buffer to specify different tab stops by placing
 188 colons on the desired columns.  The buffer uses Overwrite mode
 189 (@pxref{Minor Modes}).  Remember that Emacs will extend the list of
 190 tab stops forever by repeating the difference between the last two
 191 explicit stops that you place.  When you are done, type @kbd{C-c C-c} to make
 192 the new tab stops take effect.  Normally, the new tab stop settings
 193 apply to all buffers.  However, if you have made the
 194 @code{tab-stop-list} variable local to the buffer where you called
 195 @kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
 196 settings apply only to that buffer.  To save the tab stop settings for
 197 future Emacs sessions, use the Customize interface to save the value
 198 of @code{tab-stop-list} (@pxref{Easy Customization}).
 199
 200   Note that the tab stops discussed in this section have nothing to do
 201 with how tab characters are displayed in the buffer.  Tab characters
 202 are always displayed as empty spaces extending to the next
 203 @dfn{display tab stop}.  @xref{Text Display}.
 204
 205 @node Just Spaces
 206 @section Tabs vs. Spaces
 207
 208 @vindex tab-width
 209   Normally, indentation commands insert (or remove) an optimal mix of
 210 space characters and tab characters to align to the desired column.
 211 Tab characters are displayed as a stretch of empty space extending to
 212 the next @dfn{display tab stop}.  By default, there is one display tab
 213 stop every @code{tab-width} columns (the default is 8).  @xref{Text
 214 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}.