@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Indentation, Text, Major Modes, Top
@chapter Indentation
@cindex indentation
+@cindex tabs
@cindex columns (indentation)
This chapter describes the Emacs commands that add, remove, or
@table @kbd
@item @key{TAB}
-Indent the current line ``appropriately'' in a mode-dependent fashion.
+Indent the current line appropriately, in a mode-dependent fashion.
@item @kbd{C-j}
Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@item M-^
Indent from point to under an indentation point in the previous line.
@end table
- Emacs supports four general categories of operations that could all
-be called `indentation':
-
-@enumerate
-@item
-Insert a tab character. You can type @kbd{C-q @key{TAB}} to do this.
-
-A tab character is displayed as a stretch of whitespace which extends
-to the next display tab stop position, and the default width of a tab
-stop is eight. @xref{Text Display}, for more details.
-
-@item
-Insert whitespace up to the next tab stop. You can set tab stops at
-your choice of column positions, then type @kbd{M-i} to advance to the
-next tab stop. The default tab stop settings have a tab stop every
-eight columns, which means by default @kbd{M-i} inserts a tab
-character. To set the tab stops, use @kbd{M-x edit-tab-stops}.
-
-@item
-Align a line with the previous line. More precisely, the command
-@kbd{M-x indent-relative} indents the current line under the beginning
-of some word in the previous line. In Fundamental mode and in Text
-mode, @key{TAB} runs the command @code{indent-relative}.
-
-@item
-The most sophisticated method is @dfn{syntax-driven indentation}.
-Most programming languages have an indentation convention. For Lisp
-code, lines are indented according to their nesting in parentheses. C
-code uses the same general idea, but many details are different.
-
-@kindex TAB
-Type @key{TAB} to do syntax-driven indentation, in a mode that
-supports it. It realigns the current line according with the syntax
-of the preceding lines. No matter where in the line you are when you
-type @key{TAB}, it aligns the line as a whole.
-@end enumerate
-
- Normally, most of the above methods insert an optimal mix of tabs and
-spaces to align to the desired column. @xref{Just Spaces}, for how to
-disable use of tabs. However, @kbd{C-q @key{TAB}} always inserts a
-tab, even when tabs are disabled for the indentation commands.
+@noindent
+The @key{TAB} key runs @code{indent-for-tab-command} in most major
+modes (in C and related modes, @key{TAB} runs a separate command,
+@code{c-indent-line-or-region}, which behaves similarly). The major
+mode determines just what this entails.
+
+ In text modes, @key{TAB} inserts some combination of space and tab
+characters to advance point to the next tab stop (@pxref{Tab Stops}).
+If the region is active and spans multiple lines, it advances the
+first character of each of those lines to the next tab stop
+(@pxref{Using Region}). For the purposes of this command, the
+position of the first non-whitespace character on the preceding line
+is treated as an additional tab stop. Thus, you can use @key{TAB} to
+``align'' point with the preceding line.
+
+ In programming modes, @key{TAB} adds or removes some combination of
+space and tab characters at the start of the line, in a way that makes
+sense given the text in the preceding lines. If the region is active
+and spans multiple lines, all those lines are indented this way. If
+point was initially within the current line's indentation, it is
+positioned after that indentation; otherwise, it remains at same point
+in the newly-indented text. @xref{Program Indent}.
+
+@vindex tab-width
+ Normally, indentation commands insert (or remove) an optimal mix of
+@dfn{tab characters} and spaces to align to the desired column. Tab
+characters (@acronym{ASCII} code 9) are displayed as a stretch of
+empty space extending to the next @dfn{display tab stop}. By default,
+there is one display tab stop every eight columns; the number of
+columns is determined by the variable @code{tab-width}. You can
+insert a single tab character by typing @kbd{C-q @key{TAB}}.
+@xref{Text Display}.
+
+@findex edit-tab-stops
+@findex tab-to-tab-stop
+@kindex M-i
+ The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the
+whitespace characters around point, inserting just enough whitespace
+to advance point up to the next tab stop. By default, this involves
+deleting the existing whitespace and inserting a single tab character.
+
+ @xref{Just Spaces}, for how to disable use of tabs. However,
+@kbd{C-q @key{TAB}} always inserts a tab, even when tabs are disabled
+for the indentation commands.
+
+@vindex tab-always-indent
+ The variable @code{tab-always-indent} tweaks the behavior of the
+@key{TAB} (@code{indent-for-tab-command}) command. The default value,
+@code{t}, gives the behavior described above. If you change the value
+to the symbol @code{complete}, then @key{TAB} first tries to indent
+the current line, and if the line was already indented, it tries to
+complete the text at point (@pxref{Symbol Completion}). If the value
+is @code{nil}, then @key{TAB} indents the current line only if point
+is at the left margin or in the line's indentation; otherwise, it
+inserts a real tab character.
@menu
* Indentation Commands:: Various commands and techniques for indentation.
@key{TAB}}. To make an indented line after the current line, use
@kbd{C-e C-j}.
- If you just want to insert a tab character in the buffer, you can type
+ If you just want to insert a tab character in the buffer, type
@kbd{C-q @key{TAB}}.
@kindex C-M-o
@findex edit-tab-stops-note-changes
@kindex C-c C-c @r{(Edit Tab Stops)}
@vindex tab-stop-list
- You can specify the tab stops used by @kbd{M-i}. They are stored in a
-variable called @code{tab-stop-list}, as a list of column-numbers in
-increasing order.
+ You can change the tab stops used by @kbd{M-i} and other indentation
+commands, so that they need not be spaced every eight characters, or
+even regularly spaced. The tab stops are stored in the variable
+@code{tab-stop-list}, as a list of column numbers in increasing order.
- The convenient way to set the tab stops is with @kbd{M-x
+ A convenient way to set the tab stops is with @kbd{M-x
edit-tab-stops}, which creates and selects a buffer containing a
description of the tab stop settings. You can edit this buffer to
specify different tab stops, and then type @kbd{C-c C-c} to make those
The first line contains a colon at each tab stop. The remaining lines
are present just to help you see where the colons are and know what to do.
- Note that the tab stops that control @code{tab-to-tab-stop} have nothing
-to do with displaying tab characters in the buffer. @xref{Text Display},
-for more information on that.
+ Note that the tab stops that control @code{tab-to-tab-stop} have
+nothing to do with how tab characters are displayed in the buffer.
+Tab characters are always displayed as empty spaces extending to the
+next display tab stop, which occurs every @code{tab-width} columns
+regardless of the contents of @code{tab-stop-list}. @xref{Text
+Display}.
@node Just Spaces,, Tab Stops, Indentation
@section Tabs vs. Spaces
@xref{Locals}.
A tab is not always displayed in the same way. By default, tabs are
-eight columns wide, but some people like to customize their tools to
-use a different tab width. So by using spaces only, you can make sure
+eight columns wide, but some people like to customize their editors to
+use a different tab width (e.g., by changing the variable
+@code{tab-width} in Emacs). By using spaces only, you can make sure
that your file looks the same regardless of the tab width setting.
@findex tabify
HCoop / bpt / emacs.git / blobdiff