doc/emacs/indent.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 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 Shift each line in the region by a fixed distance, to the right or
 131 left (@code{indent-rigidly}).  The distance to move is determined by
 132 the numeric argument (positive to move rightward, negative to move
 133 leftward).
 134
 135 This command can be used to remove all indentation from the lines in
 136 the region, by invoking it with a large negative argument,
 137 e.g., @kbd{C-u -1000 C-x @key{TAB}}.
 138 @end table
 139
 140 @node Tab Stops
 141 @section Tab Stops
 142 @cindex tab stops
 143
 144 @vindex tab-stop-list
 145   Emacs defines certain column numbers to be @dfn{tab stops}.  These
 146 are used as stopping points by @key{TAB} when inserting whitespace in
 147 Text mode and related modes (@pxref{Indentation}), and by commands
 148 like @kbd{M-i} (@pxref{Indentation Commands}).  By default, tab stops
 149 are located every 8 columns.  These positions are stored in the
 150 variable @code{tab-stop-list}, whose value is a list of column numbers
 151 in increasing order.
 152
 153 @findex edit-tab-stops
 154 @kindex C-c C-c @r{(Edit Tab Stops)}
 155   Instead of customizing the variable @code{tab-stop-list} directly, a
 156 convenient way to view and set tab stops is via the command @kbd{M-x
 157 edit-tab-stops}.  This switches to a buffer containing a description
 158 of the tab stop settings, which looks like this:
 159
 160 @example
 161         :       :       :       :       :       :
 162 0         1         2         3         4
 163 0123456789012345678901234567890123456789012345678
 164 To install changes, type C-c C-c
 165 @end example
 166
 167 @noindent
 168 The first line contains a colon at each tab stop.  The numbers on the
 169 next two lines are present just to indicate where the colons are.
 170
 171   You can edit this buffer to specify different tab stops by placing
 172 colons on the desired columns.  The buffer uses Overwrite mode
 173 (@pxref{Minor Modes}).  When you are done, type @kbd{C-c C-c} to make
 174 the new tab stops take effect.  Normally, the new tab stop settings
 175 apply to all buffers.  However, if you have made the
 176 @code{tab-stop-list} variable local to the buffer where you called
 177 @kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
 178 settings apply only to that buffer.  To save the tab stop settings for
 179 future Emacs sessions, use the Customize interface to save the value
 180 of @code{tab-stop-list} (@pxref{Easy Customization}).
 181
 182   Note that the tab stops discussed in this section have nothing to do
 183 with how tab characters are displayed in the buffer.  Tab characters
 184 are always displayed as empty spaces extending to the next
 185 @dfn{display tab stop}.  @xref{Text Display}.
 186
 187 @node Just Spaces
 188 @section Tabs vs. Spaces
 189
 190 @vindex tab-width
 191   Normally, indentation commands insert (or remove) an optimal mix of
 192 space characters and tab characters to align to the desired column.
 193 Tab characters are displayed as a stretch of empty space extending to
 194 the next @dfn{display tab stop}.  By default, there is one display tab
 195 stop every @code{tab-width} columns (the default is 8).  @xref{Text
 196 Display}.
 197
 198 @vindex indent-tabs-mode
 199   If you prefer, all indentation can be made from spaces only.  To
 200 request this, set the buffer-local variable @code{indent-tabs-mode} to
 201 @code{nil}.  @xref{Locals}, for information about setting buffer-local
 202 variables.  Note, however, that @kbd{C-q @key{TAB}} always inserts a
 203 tab character, regardless of the value of @code{indent-tabs-mode}.
 204
 205   One reason to set @code{indent-tabs-mode} to @code{nil} is that not
 206 all editors display tab characters in the same way.  Emacs users, too,
 207 may have different customized values of @code{tab-width}.  By using
 208 spaces only, you can make sure that your file always looks the same.
 209 If you only care about how it looks within Emacs, another way to
 210 tackle this problem is to set the @code{tab-width} variable in a
 211 file-local variable (@pxref{File Variables}).
 212
 213 @findex tabify
 214 @findex untabify
 215   There are also commands to convert tabs to spaces or vice versa, always
 216 preserving the columns of all non-whitespace text.  @kbd{M-x tabify} scans the
 217 region for sequences of spaces, and converts sequences of at least two
 218 spaces to tabs if that can be done without changing indentation.  @kbd{M-x
 219 untabify} changes all tabs in the region to appropriate numbers of spaces.
 220
 221 @node Indent Convenience
 222 @section Convenience Features for Indentation
 223
 224 @vindex tab-always-indent
 225   The variable @code{tab-always-indent} tweaks the behavior of the
 226 @key{TAB} (@code{indent-for-tab-command}) command.  The default value,
 227 @code{t}, gives the behavior described in @ref{Indentation}.  If you
 228 change the value to the symbol @code{complete}, then @key{TAB} first
 229 tries to indent the current line, and if the line was already
 230 indented, it tries to complete the text at point (@pxref{Symbol
 231 Completion}).  If the value is @code{nil}, then @key{TAB} indents the
 232 current line only if point is at the left margin or in the line's
 233 indentation; otherwise, it inserts a tab character.
 234
 235 @cindex Electric Indent mode
 236 @cindex mode, Electric Indent
 237 @findex electric-indent-mode
 238   Electric Indent mode is a global minor mode that automatically
 239 indents the line after every @key{RET} you type.  To toggle this minor
 240 mode, type @kbd{M-x electric-indent-mode}.