man/indent.texi

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