man/indent.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 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 @c WideCommands
  13 @table @kbd
  14 @item @key{TAB}
  15 Indent 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 two lines (@code{delete-indentation}).  This would cancel out
  20 the effect of @kbd{C-j}.
  21 @item C-M-o
  22 Split line at point; text on the line after point becomes a new line
  23 indented to the same column that it now starts in (@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 same column (@code{indent-region}).
  29 @item C-x @key{TAB}
  30 Shift 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   Most programming languages have some indentation convention.  For Lisp
  39 code, lines are indented according to their nesting in parentheses.  The
  40 same general idea is used for C code, though many details are different.
  41
  42 @kindex TAB
  43   Whatever the language, to indent a line, use the @key{TAB} command.  Each
  44 major mode defines this command to perform the sort of indentation
  45 appropriate for the particular language.  In Lisp mode, @key{TAB} aligns
  46 the line according to its depth in parentheses.  No matter where in the
  47 line you are when you type @key{TAB}, it aligns the line as a whole.  In C
  48 mode, @key{TAB} implements a subtle and sophisticated indentation style that
  49 knows about many aspects of C syntax.
  50
  51   In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
  52 indents to the next tab stop column.  You can set the tab stops with
  53 @kbd{M-x edit-tab-stops}.
  54
  55   Normally, @key{TAB} inserts a mix of tabs and spaces to indent lines.
  56 @xref{Just Spaces}, for how to override that.
  57
  58 @menu
  59 * Indentation Commands::  Various commands and techniques for indentation.
  60 * Tab Stops::             You can set arbitrary "tab stops" and then
  61                             indent to the next tab stop when you want to.
  62 * Just Spaces::           You can request indentation using just spaces.
  63 @end menu
  64
  65 @node Indentation Commands, Tab Stops, Indentation, Indentation
  66 @section Indentation Commands and Techniques
  67
  68 @kindex M-m
  69 @findex back-to-indentation
  70   To move over the indentation on a line, do @kbd{M-m}
  71 (@code{back-to-indentation}).  This command, given anywhere on a line,
  72 positions point at the first nonblank character on the line.
  73
  74   To insert an indented line before the current line, do @kbd{C-a C-o
  75 @key{TAB}}.  To make an indented line after the current line, use
  76 @kbd{C-e C-j}.
  77
  78   If you just want to insert a tab character in the buffer, you can type
  79 @kbd{C-q @key{TAB}}.
  80
  81 @kindex C-M-o
  82 @findex split-line
  83   @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
  84 the line vertically down, so that the current line becomes two lines.
  85 @kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
  86 inserts after point a newline and enough indentation to reach the same
  87 column point is on.  Point remains before the inserted newline; in this
  88 regard, @kbd{C-M-o} resembles @kbd{C-o}.
  89
  90 @kindex M-^
  91 @findex delete-indentation
  92   To join two lines cleanly, use the @kbd{M-^}
  93 (@code{delete-indentation}) command.  It deletes the indentation at the
  94 front of the current line, and the line boundary as well, replacing them
  95 with a single space.  As a special case (useful for Lisp code) the
  96 single space is omitted if the characters to be joined are consecutive
  97 open parentheses or closing parentheses, or if the junction follows
  98 another newline.  To delete just the indentation of a line, go to the
  99 beginning of the line and use @kbd{M-\}
 100 (@code{delete-horizontal-space}), which deletes all spaces and tabs
 101 around the cursor.
 102
 103   If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
 104 appears after the newline that is deleted.  @xref{Fill Prefix}.
 105
 106 @kindex C-M-\
 107 @kindex C-x TAB
 108 @findex indent-region
 109 @findex indent-rigidly
 110   There are also commands for changing the indentation of several lines
 111 at once.  @kbd{C-M-\} (@code{indent-region}) applies to all the lines
 112 that begin in the region; it indents each line in the ``usual'' way, as
 113 if you had typed @key{TAB} at the beginning of the line.  A numeric
 114 argument specifies the column to indent to, and each line is shifted
 115 left or right so that its first nonblank character appears in that
 116 column.  @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of the
 117 lines in the region right by its argument (left, for negative
 118 arguments).  The whole group of lines moves rigidly sideways, which is
 119 how the command gets its name.@refill
 120
 121 @findex indent-relative
 122   @kbd{M-x indent-relative} indents at point based on the previous line
 123 (actually, the last nonempty line).  It inserts whitespace at point, moving
 124 point, until it is underneath an indentation point in the previous line.
 125 An indentation point is the end of a sequence of whitespace or the end of
 126 the line.  If point is farther right than any indentation point in the
 127 previous line, the whitespace before point is deleted and the first
 128 indentation point then applicable is used.  If no indentation point is
 129 applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop}
 130 @ifinfo
 131 (@pxref{Tab Stops}),
 132 @end ifinfo
 133 @iftex
 134 (see next section),
 135 @end iftex
 136 unless it is called with a numeric argument, in which case it does
 137 nothing.
 138
 139   @code{indent-relative} is the definition of @key{TAB} in Indented Text
 140 mode.  @xref{Text}.
 141
 142   @xref{Format Indentation}, for another way of specifying the
 143 indentation for part of your text.
 144
 145 @node Tab Stops, Just Spaces, Indentation Commands, Indentation
 146 @section Tab Stops
 147
 148 @cindex tab stops
 149 @cindex using tab stops in making tables
 150 @cindex tables, indentation for
 151 @kindex M-i
 152 @findex tab-to-tab-stop
 153   For typing in tables, you can use Text mode's definition of @key{TAB},
 154 @code{tab-to-tab-stop}.  This command inserts indentation before point,
 155 enough to reach the next tab stop column.  If you are not in Text mode,
 156 this command can be found on the key @kbd{M-i}.
 157
 158 @findex edit-tab-stops
 159 @findex edit-tab-stops-note-changes
 160 @kindex C-c C-c @r{(Edit Tab Stops)}
 161 @vindex tab-stop-list
 162   You can specify the tab stops used by @kbd{M-i}.  They are stored in a
 163 variable called @code{tab-stop-list}, as a list of column-numbers in
 164 increasing order.
 165
 166   The convenient way to set the tab stops is with @kbd{M-x
 167 edit-tab-stops}, which creates and selects a buffer containing a
 168 description of the tab stop settings.  You can edit this buffer to
 169 specify different tab stops, and then type @kbd{C-c C-c} to make those
 170 new tab stops take effect.  @code{edit-tab-stops} records which buffer
 171 was current when you invoked it, and stores the tab stops back in that
 172 buffer; normally all buffers share the same tab stops and changing them
 173 in one buffer affects all, but if you happen to make
 174 @code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
 175 that buffer will edit the local settings.
 176
 177   Here is what the text representing the tab stops looks like for ordinary
 178 tab stops every eight columns.
 179
 180 @example
 181         :       :       :       :       :       :
 182 0         1         2         3         4
 183 0123456789012345678901234567890123456789012345678
 184 To install changes, type C-c C-c
 185 @end example
 186
 187   The first line contains a colon at each tab stop.  The remaining lines
 188 are present just to help you see where the colons are and know what to do.
 189
 190   Note that the tab stops that control @code{tab-to-tab-stop} have nothing
 191 to do with displaying tab characters in the buffer.  @xref{Display Custom},
 192 for more information on that.
 193
 194 @node Just Spaces,, Tab Stops, Indentation
 195 @section Tabs vs. Spaces
 196
 197 @vindex indent-tabs-mode
 198   Emacs normally uses both tabs and spaces to indent lines.  If you
 199 prefer, all indentation can be made from spaces only.  To request
 200 this, set @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer
 201 variable, so altering the variable affects only the current buffer,
 202 but there is a default value which you can change as well.
 203 @xref{Locals}.
 204
 205 @findex tabify
 206 @findex untabify
 207   There are also commands to convert tabs to spaces or vice versa, always
 208 preserving the columns of all nonblank text.  @kbd{M-x tabify} scans the
 209 region for sequences of spaces, and converts sequences of at least three
 210 spaces to tabs if that can be done without changing indentation.  @kbd{M-x
 211 untabify} changes all tabs in the region to appropriate numbers of spaces.