man/indent.texi

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