doc/emacs/indent.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
   3 @c   2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.
   4 @c See file emacs.texi for copying conditions.
   5 @node Indentation, Text, Major Modes, Top
   6 @chapter Indentation
   7 @cindex indentation
   8 @cindex tabs
   9 @cindex columns (indentation)
  10
  11   This chapter describes the Emacs commands that add, remove, or
  12 adjust indentation.
  13
  14 @table @kbd
  15 @item @key{TAB}
  16 Indent the current line appropriately, in a mode-dependent fashion.
  17 @item @kbd{C-j}
  18 Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
  19 @item M-^
  20 Merge the previous and the current line (@code{delete-indentation}).
  21 This would cancel the effect of a preceding @kbd{C-j}.
  22 @item C-M-o
  23 Split the current line at point; text on the line after point becomes a
  24 new line indented to the same column where point is located
  25 (@code{split-line}).
  26 @item M-m
  27 Move (forward or back) to the first nonblank character on the current
  28 line (@code{back-to-indentation}).
  29 @item C-M-\
  30 Indent lines in the region to the same column (@code{indent-region}).
  31 @item C-x @key{TAB}
  32 Shift lines in the region rigidly right or left (@code{indent-rigidly}).
  33 @item M-i
  34 Indent from point to the next prespecified tab stop column
  35 (@code{tab-to-tab-stop}).
  36 @item M-x indent-relative
  37 Indent from point to under an indentation point in the previous line.
  38 @end table
  39
  40   In most major modes, the @key{TAB} key runs the command
  41 @code{indent-for-tab-command}, which either performs indentation or
  42 inserts whitespace at point, depending on the situation.
  43
  44   In programming modes such as Lisp mode and C mode, @key{TAB} indents
  45 the current line if the region is inactive.  If the region is active,
  46 it indents every line in the region (@pxref{Mark}).  Indentation means
  47 adding or removing some combination of space and tab characters
  48 (@dfn{whitespace characters}) at the start of the line, in a way that
  49 makes sense given the text in the preceding lines.  Exactly how
  50 indentation is performed depends on the major mode.  @xref{Program
  51 Indent}.
  52
  53   In text modes, @key{TAB} inserts some whitespace characters to
  54 advance point to the next tab stop (@pxref{Tab Stops}).  For the
  55 purposes of this command, the position of the first non-whitespace
  56 character on the preceding line is treated as an additional tab stop.
  57 You can therefore use @key{TAB} to ``align'' point with the preceding
  58 line.  If the region is active, @key{TAB} performs this action on
  59 every line in the region.
  60
  61 @vindex tab-width
  62   Indentation is often performed with the help of @dfn{tab characters}
  63 (@acronym{ASCII} code 9), which are displayed as a stretch of empty space
  64 extending to the next @dfn{display tab stop}.  By default, there is
  65 one display tab stop every eight columns; the number of columns is
  66 determined by the variable @code{tab-width}.  You can insert a single
  67 tab character by typing @kbd{C-q @key{TAB}}.  @xref{Text Display}.
  68
  69 @findex edit-tab-stops
  70 @findex tab-to-tab-stop
  71 @kindex M-i
  72   The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the
  73 whitespace characters around point, inserting just enough whitespace
  74 to advance point up to the next tab stop.  By default, this involves
  75 deleting the existing whitespace and inserting a single tab character.
  76
  77   Normally, most of these indentation commands insert an optimal mix
  78 of tabs and spaces to align to the desired column.  @xref{Just
  79 Spaces}, for how to disable use of tabs.  However, @kbd{C-q @key{TAB}}
  80 always inserts a tab, even when tabs are disabled for the indentation
  81 commands.
  82
  83 @menu
  84 * Indentation Commands::  Various commands and techniques for indentation.
  85 * Tab Stops::             You can set arbitrary "tab stops" and then
  86                             indent to the next tab stop when you want to.
  87 * Just Spaces::           You can request indentation using just spaces.
  88 @end menu
  89
  90 @node Indentation Commands, Tab Stops, Indentation, Indentation
  91 @section Indentation Commands and Techniques
  92
  93 @kindex M-m
  94 @findex back-to-indentation
  95   To move over the indentation on a line, do @kbd{M-m}
  96 (@code{back-to-indentation}).  This command, given anywhere on a line,
  97 positions point at the first nonblank character on the line, if any,
  98 or else at the end of the line.
  99
 100   To insert an indented line before the current line, do @kbd{C-a C-o
 101 @key{TAB}}.  To make an indented line after the current line, use
 102 @kbd{C-e C-j}.
 103
 104   If you just want to insert a tab character in the buffer, type
 105 @kbd{C-q @key{TAB}}.
 106
 107 @kindex C-M-o
 108 @findex split-line
 109   @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
 110 the line vertically down, so that the current line becomes two lines.
 111 @kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
 112 inserts after point a newline and enough indentation to reach the same
 113 column point is on.  Point remains before the inserted newline; in this
 114 regard, @kbd{C-M-o} resembles @kbd{C-o}.
 115
 116 @kindex M-^
 117 @findex delete-indentation
 118   To join two lines cleanly, use the @kbd{M-^}
 119 (@code{delete-indentation}) command.  It deletes the indentation at
 120 the front of the current line, and the line boundary as well,
 121 replacing them with a single space.  As a special case (useful for
 122 Lisp code) the single space is omitted if the characters to be joined
 123 are consecutive open parentheses or closing parentheses, or if the
 124 junction follows another newline.  To delete just the indentation of a
 125 line, go to the beginning of the line and use @kbd{M-\}
 126 (@code{delete-horizontal-space}), which deletes all spaces and tabs
 127 around the cursor.
 128
 129   If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
 130 appears after the newline that is deleted.  @xref{Fill Prefix}.
 131
 132 @kindex C-M-\
 133 @kindex C-x TAB
 134 @findex indent-region
 135 @findex indent-rigidly
 136   There are also commands for changing the indentation of several lines
 137 at once.  They apply to all the lines that begin in the region.
 138 @kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual''
 139 way, as if you had typed @key{TAB} at the beginning of the line.  A
 140 numeric argument specifies the column to indent to, and each line is
 141 shifted left or right so that its first nonblank character appears in
 142 that column.  @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of
 143 the lines in the region right by its argument (left, for negative
 144 arguments).  The whole group of lines moves rigidly sideways, which is
 145 how the command gets its name.
 146
 147 @cindex remove indentation
 148   To remove all indentation from all of the lines in the region,
 149 invoke @kbd{C-x @key{TAB}} with a large negative argument, such as
 150 -1000.
 151
 152 @findex indent-relative
 153   @kbd{M-x indent-relative} indents at point based on the previous line
 154 (actually, the last nonempty line).  It inserts whitespace at point, moving
 155 point, until it is underneath the next indentation point in the previous line.
 156 An indentation point is the end of a sequence of whitespace or the end of
 157 the line.  If point is farther right than any indentation point in the
 158 previous line, @code{indent-relative} runs @code{tab-to-tab-stop}
 159 @ifnottex
 160 (@pxref{Tab Stops}),
 161 @end ifnottex
 162 @iftex
 163 (see next section),
 164 @end iftex
 165 unless it is called with a numeric argument, in which case it does
 166 nothing.
 167
 168   @xref{Format Indentation}, for another way of specifying the
 169 indentation for part of your text.
 170
 171 @node Tab Stops, Just Spaces, Indentation Commands, Indentation
 172 @section Tab Stops
 173
 174 @cindex tab stops
 175 @cindex using tab stops in making tables
 176 @cindex tables, indentation for
 177 @kindex M-i
 178 @findex tab-to-tab-stop
 179   For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}).
 180 This command inserts indentation before point, enough to reach the
 181 next tab stop column.
 182
 183 @findex edit-tab-stops
 184 @findex edit-tab-stops-note-changes
 185 @kindex C-c C-c @r{(Edit Tab Stops)}
 186 @vindex tab-stop-list
 187   You can change the tab stops used by @kbd{M-i} and other indentation
 188 commands, so that they need not be spaced every eight characters, or
 189 even regularly spaced.  The tab stops are stored in the variable
 190 @code{tab-stop-list}, as a list of column numbers in increasing order.
 191
 192   A convenient way to set the tab stops is with @kbd{M-x
 193 edit-tab-stops}, which creates and selects a buffer containing a
 194 description of the tab stop settings.  You can edit this buffer to
 195 specify different tab stops, and then type @kbd{C-c C-c} to make those
 196 new tab stops take effect.  The buffer uses Overwrite mode
 197 (@pxref{Minor Modes}).  @code{edit-tab-stops} records which buffer was
 198 current when you invoked it, and stores the tab stops back in that
 199 buffer; normally all buffers share the same tab stops and changing
 200 them in one buffer affects all, but if you happen to make
 201 @code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
 202 that buffer will edit the local settings.
 203
 204   Here is what the text representing the tab stops looks like for ordinary
 205 tab stops every eight columns.
 206
 207 @example
 208         :       :       :       :       :       :
 209 0         1         2         3         4
 210 0123456789012345678901234567890123456789012345678
 211 To install changes, type C-c C-c
 212 @end example
 213
 214   The first line contains a colon at each tab stop.  The remaining lines
 215 are present just to help you see where the colons are and know what to do.
 216
 217   Note that the tab stops that control @code{tab-to-tab-stop} have
 218 nothing to do with how tab characters are displayed in the buffer.
 219 Tab characters are always displayed as empty spaces extending to the
 220 next display tab stop, which occurs every @code{tab-width} columns
 221 regardless of the contents of @code{tab-stop-list}.  @xref{Text
 222 Display}.
 223
 224 @node Just Spaces,, Tab Stops, Indentation
 225 @section Tabs vs. Spaces
 226
 227 @vindex indent-tabs-mode
 228   Emacs normally uses both tabs and spaces to indent lines.  If you
 229 prefer, all indentation can be made from spaces only.  To request
 230 this, set @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer
 231 variable, so altering the variable affects only the current buffer,
 232 but there is a default value which you can change as well.
 233 @xref{Locals}.
 234
 235   A tab is not always displayed in the same way.  By default, tabs are
 236 eight columns wide, but some people like to customize their editors to
 237 use a different tab width (e.g., by changing the variable
 238 @code{tab-width} in Emacs).  By using spaces only, you can make sure
 239 that your file looks the same regardless of the tab width setting.
 240
 241 @findex tabify
 242 @findex untabify
 243   There are also commands to convert tabs to spaces or vice versa, always
 244 preserving the columns of all nonblank text.  @kbd{M-x tabify} scans the
 245 region for sequences of spaces, and converts sequences of at least two
 246 spaces to tabs if that can be done without changing indentation.  @kbd{M-x
 247 untabify} changes all tabs in the region to appropriate numbers of spaces.
 248
 249 @ignore
 250    arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb
 251 @end ignore