502 lines
21 KiB
Plaintext
502 lines
21 KiB
Plaintext
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2001--2026 Free Software
|
|
@c Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@node Indentation
|
|
@chapter Indentation
|
|
@cindex indentation
|
|
@cindex tabs
|
|
@cindex columns (indentation)
|
|
|
|
@cindex whitespace character
|
|
@dfn{Indentation} refers to inserting or adjusting @dfn{whitespace
|
|
characters} (space and/or tab characters) at the beginning of a line
|
|
of text. This chapter documents indentation commands and options
|
|
which are common to Text mode and related modes, as well as
|
|
programming language modes. @xref{Program Indent}, for additional
|
|
documentation about indenting in programming modes.
|
|
|
|
@findex indent-for-tab-command
|
|
@kindex TAB @r{(indentation)}
|
|
The simplest way to perform indentation is the @key{TAB} key. In
|
|
most major modes, this runs the command @code{indent-for-tab-command}.
|
|
(In C and related modes, @key{TAB} runs the command
|
|
@code{c-indent-line-or-region}, which behaves similarly, @pxref{C
|
|
Indent}).
|
|
|
|
@table @key
|
|
@item TAB
|
|
Insert whitespace, or indent the current line, in a mode-appropriate
|
|
way (@code{indent-for-tab-command}). If the region is active, indent
|
|
all the lines within it.
|
|
@end table
|
|
|
|
The exact behavior of @key{TAB} depends on the major mode. In Text
|
|
mode and related major modes, @key{TAB} normally inserts some
|
|
combination of space and tab characters to advance point to the next
|
|
tab stop (@pxref{Tab Stops}). For this purpose, the position of the
|
|
first non-whitespace character on the preceding line is treated as an
|
|
additional tab stop, so you can use @key{TAB} to align point with
|
|
the preceding line. If the region is active (@pxref{Using Region}),
|
|
@key{TAB} acts specially: it indents each line in the region so that
|
|
its first non-whitespace character is aligned with the preceding line.
|
|
|
|
In programming modes, @key{TAB} indents the current line of code in
|
|
a way that makes sense given the code in the preceding lines. If the
|
|
region is active, all the lines in the region are indented this way.
|
|
If point was initially within the current line's indentation, it is
|
|
repositioned to the first non-whitespace character on the line.
|
|
|
|
If you just want to insert a tab character in the buffer, type
|
|
@kbd{C-q @key{TAB}} (@pxref{Inserting Text}).
|
|
|
|
@menu
|
|
* Indentation Commands:: More commands for performing indentation.
|
|
* Tab Stops:: Stop points for indentation in Text modes.
|
|
* Just Spaces:: Using only space characters for indentation.
|
|
* Indent Convenience:: Optional indentation features.
|
|
* Code Alignment:: Making common parts of lines start at the same column.
|
|
@end menu
|
|
|
|
@node Indentation Commands
|
|
@section Indentation Commands
|
|
|
|
Apart from the @kbd{@key{TAB}} (@code{indent-for-tab-command})
|
|
command, Emacs provides a variety of commands to perform indentation
|
|
in other ways.
|
|
|
|
@table @kbd
|
|
@item C-M-o
|
|
@kindex C-M-o
|
|
@findex split-line
|
|
Split the current line at point (@code{split-line}). The text on the
|
|
line after point becomes a new line, indented to the same column where
|
|
point is located. This command first moves point forward over any
|
|
spaces and tabs. Afterward, point is positioned before the inserted
|
|
newline.
|
|
|
|
@kindex M-m
|
|
@findex back-to-indentation
|
|
@item M-m
|
|
Move (forward or back) to the first non-whitespace character on the
|
|
current line (@code{back-to-indentation}). If there are no
|
|
non-whitespace characters on the line, move to the end of the line.
|
|
|
|
@item M-i
|
|
@kindex M-i
|
|
@findex tab-to-tab-stop
|
|
Indent whitespace at point, up to the next tab stop
|
|
(@code{tab-to-tab-stop}). @xref{Tab Stops}.
|
|
|
|
@findex indent-relative
|
|
@item M-x indent-relative
|
|
Insert whitespace at point, until point is aligned with the first
|
|
non-whitespace character on the previous line (actually, the last
|
|
non-blank line). If point is already farther right than that, run
|
|
@code{tab-to-tab-stop} instead---unless called with a numeric
|
|
argument, in which case do nothing.
|
|
|
|
@item M-^
|
|
@kindex M-^
|
|
@findex delete-indentation
|
|
Merge the previous and the current line (@code{delete-indentation}).
|
|
This joins the two lines cleanly, by replacing any indentation at
|
|
the front of the current line, together with the line boundary, with a
|
|
single space.
|
|
|
|
As a special case (useful for Lisp code), the single space is omitted
|
|
if the characters to be joined are consecutive opening and closing
|
|
parentheses, or if the junction follows another newline.
|
|
|
|
If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it
|
|
appears after the newline that is deleted. @xref{Fill Prefix}.
|
|
|
|
With a prefix argument, join the current line to the following line.
|
|
If the region is active, and no prefix argument is given, join all
|
|
lines in the region instead.
|
|
|
|
@item C-M-\
|
|
@kindex C-M-\
|
|
@findex indent-region
|
|
Indent all the lines in the region, as though you had typed
|
|
@kbd{@key{TAB}} at the beginning of each line (@code{indent-region}).
|
|
|
|
If a numeric argument is supplied, indent every line in the region to
|
|
that column number.
|
|
|
|
@item C-x @key{TAB}
|
|
@kindex C-x TAB
|
|
@findex indent-rigidly
|
|
@cindex remove indentation
|
|
Indent all lines that begin in the region, moving the affected lines
|
|
as a rigid unit (@code{indent-rigidly}).
|
|
|
|
If called with no argument, this command activates a transient mode for
|
|
adjusting the indentation of the affected lines interactively. While
|
|
this transient mode is active, typing @kbd{@key{LEFT}} or
|
|
@kbd{@key{RIGHT}} indents leftward and rightward, respectively, by one
|
|
space. You can also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to
|
|
indent leftward or rightward to the next tab stop (@pxref{Tab Stops}).
|
|
Typing any other key disables the transient mode, and this key is then
|
|
acted upon as normally.
|
|
|
|
If called with a prefix argument @var{n}, this command indents the
|
|
lines forward by @var{n} spaces (without enabling the transient mode).
|
|
Negative values of @var{n} indent backward, so you can remove all
|
|
indentation from the lines in the region using a large negative
|
|
argument, like this:
|
|
|
|
@smallexample
|
|
C-u -999 C-x @key{TAB}
|
|
@end smallexample
|
|
@end table
|
|
|
|
@node Tab Stops
|
|
@section Tab Stops
|
|
@cindex tab stops
|
|
|
|
@vindex tab-stop-list
|
|
Emacs defines certain column numbers to be @dfn{tab stops}. These
|
|
are used as stopping points by @key{TAB} when inserting whitespace in
|
|
Text mode and related modes (@pxref{Indentation}), and by commands
|
|
like @kbd{M-i} (@pxref{Indentation Commands}). The variable
|
|
@code{tab-stop-list} controls these positions. The default value is
|
|
@code{nil}, which means a tab stop every 8 columns. The value can
|
|
also be a list of zero-based column numbers (in increasing order) at
|
|
which to place tab stops. Emacs extends the list forever by repeating
|
|
the difference between the last and next-to-last elements.
|
|
|
|
@findex edit-tab-stops
|
|
@kindex C-c C-c @r{(Edit Tab Stops)}
|
|
Instead of customizing the variable @code{tab-stop-list} directly, a
|
|
convenient way to view and set tab stops is via the command @kbd{M-x
|
|
edit-tab-stops}. This switches to a buffer containing a description
|
|
of the tab stop settings, which looks like this:
|
|
|
|
@example
|
|
: : : : : :
|
|
0 1 2 3 4
|
|
0123456789012345678901234567890123456789012345678
|
|
To install changes, type C-c C-c
|
|
@end example
|
|
|
|
@noindent
|
|
The first line contains a colon at each tab stop. The numbers on the
|
|
next two lines are present just to indicate where the colons are.
|
|
If the value of @code{tab-stop-list} is @code{nil}, as it is by default,
|
|
no colons are displayed initially.
|
|
|
|
You can edit this buffer to specify different tab stops by placing
|
|
colons on the desired columns. The buffer uses Overwrite mode
|
|
(@pxref{Minor Modes}). Remember that Emacs will extend the list of
|
|
tab stops forever by repeating the difference between the last two
|
|
explicit stops that you place. When you are done, type @kbd{C-c C-c} to make
|
|
the new tab stops take effect. Normally, the new tab stop settings
|
|
apply to all buffers. However, if you have made the
|
|
@code{tab-stop-list} variable local to the buffer where you called
|
|
@kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
|
|
settings apply only to that buffer. To save the tab stop settings for
|
|
future Emacs sessions, use the Customize interface to save the value
|
|
of @code{tab-stop-list} (@pxref{Easy Customization}).
|
|
|
|
Note that the tab stops discussed in this section 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
|
|
@dfn{display tab stop}. @xref{Text Display}.
|
|
|
|
@node Just Spaces
|
|
@section Tabs vs.@: Spaces
|
|
|
|
Normally, indentation commands insert (or remove) the shortest
|
|
possible series of tab and space characters so as to align to the
|
|
desired column. Tab characters 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 @code{tab-width} columns (the default is
|
|
8). @xref{Text Display}.
|
|
|
|
@vindex indent-tabs-mode
|
|
If you prefer, all indentation can be made from spaces only. To
|
|
request this, set the buffer-local variable @code{indent-tabs-mode} to
|
|
@code{nil}. @xref{Locals}, for information about setting buffer-local
|
|
variables. Note, however, that @kbd{C-q @key{TAB}} always inserts a
|
|
tab character, regardless of the value of @code{indent-tabs-mode}.
|
|
|
|
One reason to set @code{indent-tabs-mode} to @code{nil} is that not
|
|
all editors display tab characters in the same way. Emacs users, too,
|
|
may have different customized values of @code{tab-width}. By using
|
|
spaces only, you can make sure that your file always looks the same.
|
|
If you only care about how it looks within Emacs, another way to
|
|
tackle this problem is to set the @code{tab-width} variable in a
|
|
file-local variable (@pxref{File Variables}).
|
|
|
|
@findex tabify
|
|
@findex untabify
|
|
There are also commands to convert tabs to spaces or vice versa, always
|
|
preserving the columns of all non-whitespace text. @kbd{M-x tabify} scans the
|
|
region for sequences of spaces, and converts sequences of at least two
|
|
spaces to tabs if that can be done without changing indentation. @kbd{M-x
|
|
untabify} changes all tabs in the region to appropriate numbers of spaces.
|
|
|
|
@node Indent Convenience
|
|
@section Convenience Features for Indentation
|
|
|
|
@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 in @ref{Indentation}. 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 tab character.
|
|
|
|
@vindex tab-first-completion
|
|
If @code{tab-always-indent} is @code{complete}, whether to expand or
|
|
indent can be further customized via the @code{tab-first-completion}
|
|
variable. For instance, if that variable is @code{eol}, only complete
|
|
if point is at the end of a line. @xref{Mode-Specific Indent,,,
|
|
elisp, The Emacs Lisp Reference Manual}, for further details.
|
|
|
|
@cindex Electric Indent mode
|
|
@cindex mode, Electric Indent
|
|
@findex electric-indent-mode
|
|
Electric Indent mode is a global minor mode that automatically
|
|
indents the line after every @key{RET} you type. This mode is enabled
|
|
by default. To toggle this minor mode, type @kbd{M-x
|
|
electric-indent-mode}. To toggle the mode in a single buffer,
|
|
use @kbd{M-x electric-indent-local-mode}.
|
|
|
|
@node Code Alignment
|
|
@section Code Alignment
|
|
@cindex code alignment
|
|
@cindex aligning code
|
|
|
|
@dfn{Alignment} is the process of adjusting whitespace in a sequence
|
|
of lines in the region such that in all lines certain parts begin at
|
|
the same column. This is usually something you do to enhance
|
|
readability of a piece of text or code. The classic example is
|
|
aligning a series of assignments in C-like programming languages:
|
|
|
|
@example
|
|
int a = 1;
|
|
short foo = 2;
|
|
double blah = 4;
|
|
@end example
|
|
|
|
@noindent
|
|
is commonly aligned to:
|
|
|
|
@example
|
|
int a = 1;
|
|
short foo = 2;
|
|
double blah = 4;
|
|
@end example
|
|
|
|
@cindex alignment rules
|
|
@findex align
|
|
You can use the command @kbd{M-x align} to align lines in the
|
|
current region. This command knows about common alignment patterns
|
|
across many markup and programming languages. It encodes these
|
|
patterns as a set of @dfn{alignment rules}, that say how to align
|
|
different kinds of text in different contexts.
|
|
|
|
@vindex align-rules-list
|
|
@vindex align-mode-rules-list
|
|
The user option @code{align-rules-list} says which alignment rules
|
|
@kbd{M-x align} should consult. The value of this option is a list
|
|
with elements describing alignment rules. Each element is a cons cell
|
|
@code{(@var{title} . @var{attributes})}, where @var{title} is the name
|
|
of the alignment rule as a symbol, and @var{attributes} is a list of
|
|
rule attributes that define when the rule should apply and how it
|
|
partitions and aligns lines. Each rule attribute is a cons cell
|
|
@code{(@var{attribute} . @var{value})}, where @var{attribute} is the
|
|
name of attribute and @var{value} is its value. The only required
|
|
attribute is @code{regexp}, whose value is a regular expression with
|
|
sub-expressions matching the parts of each line where @kbd{M-x align}
|
|
should expand or contract whitespace (@pxref{Regexp Backslash}). See
|
|
the documentation string of @code{align-rules-list} (@kbd{C-h v
|
|
align-rules-list @key{RET}}) for a full description of possible
|
|
alignment rule attributes. By default, this option is set to a long
|
|
list of alignment rules for many languages that Emacs supports. The
|
|
default rules use the @code{modes} rule attribute to specify major
|
|
modes in which @kbd{M-x align} should apply them. Major modes can
|
|
also override @code{align-rules-list} by setting the buffer-local
|
|
variable @code{align-mode-rules-list} to a non-@code{nil} list of
|
|
alignment rules. When @code{align-mode-rules-list} is non-@code{nil},
|
|
@kbd{M-x align} consults it instead of @code{align-rules-list}.
|
|
|
|
@cindex align exclusion rules
|
|
@vindex align-exclude-rules-list
|
|
@vindex align-mode-exclude-rules-list
|
|
Besides alignment rules, @kbd{M-x align} uses another kind of rules
|
|
called @dfn{exclusion rules}. The exclusion rules say which parts in
|
|
the region @kbd{M-x align} should not align and instead leave them
|
|
intact. The user option @code{align-exclude-rules-list} specifies
|
|
these exclusion rules. Similarly to @code{align-rules-list}, the
|
|
value of @code{align-exclude-rules-list} is also a list of cons cells
|
|
that describe the exclusion rules. By default,
|
|
@code{align-exclude-rules-list} includes rules that exclude alignment
|
|
in quoted strings and comments in Lisp, C and other languages. Beyond
|
|
the default exclusion rules in @code{align-exclude-rules-list}, major
|
|
modes can define bespoke exclusion rules by setting
|
|
@code{align-mode-exclude-rules-list} to a non-@code{nil} list of
|
|
rules, this overrides @code{align-exclude-rules-list} just like
|
|
@code{align-mode-rules-list} overrides @code{align-rules-list}.
|
|
|
|
@cindex alignment sections
|
|
@vindex align-region-separate
|
|
@kbd{M-x align} splits the region into a series of @dfn{sections},
|
|
usually sequences of non-blank lines, and aligns each section
|
|
according to all matching alignment rule by expanding or contracting
|
|
stretches of whitespace. @kbd{M-x align} consistently aligns all
|
|
lines inside a single section, but it may align different sections in
|
|
the region differently. The user option @code{align-region-separate}
|
|
specifies how @kbd{M-x align} separates the region to sections. This
|
|
option can be one of the symbols @code{entire}, @code{group}, or a
|
|
regular expression. If @code{align-region-separate} is @code{entire},
|
|
Emacs aligns the entire region as a single section. If this option is
|
|
@code{group}, Emacs aligns each group of consecutive non-blank lines
|
|
in the region as a separate section. If @code{align-region-separate}
|
|
is a regular expression, @kbd{M-x align} scans the region for matches
|
|
to that regular expression and treats them as section separators. By
|
|
default @code{align-region-separate} is set to a regular expression
|
|
that matches blank lines and lines that contains only whitespace and a
|
|
single curly brace (@samp{@{} or @samp{@}}). For special cases where
|
|
regular expressions are not accurate enough, you can also set
|
|
@code{align-region-separate} to a function that says how to separate
|
|
the region to alignment sections. See the documentation string of
|
|
@code{align-region-separate} for more details. Specific alignment
|
|
rules can override the value of @code{align-region-separate} and
|
|
define their own section separator by specifying the @code{separate}
|
|
rule attribute.
|
|
|
|
If you call @kbd{M-x align} with a prefix argument (@kbd{C-u}), it
|
|
enables more alignment rules that are often useful but may sometimes
|
|
be too intrusive. For example, in a Lisp buffer with the following
|
|
form:
|
|
|
|
@lisp
|
|
(set-face-attribute 'mode-line-inactive nil
|
|
:box nil
|
|
:background nil
|
|
:underline "black")
|
|
@end lisp
|
|
|
|
@noindent
|
|
Typing (@kbd{C-u M-x align}) yields:
|
|
|
|
@lisp
|
|
(set-face-attribute 'mode-line-inactive nil
|
|
:box nil
|
|
:background nil
|
|
:underline "black")
|
|
@end lisp
|
|
|
|
In most cases, you should try @kbd{M-x align} without a prefix
|
|
argument first, and if that doesn't produce the right result you can
|
|
undo with @kbd{C-/} and try again with @kbd{C-u M-x align}.
|
|
|
|
@findex align-highlight-rule
|
|
@findex align-unhighlight-rule
|
|
You can use the command @kbd{M-x align-highlight-rule} to visualize
|
|
the effect of a specific alignment or exclusion rule in the current
|
|
region. This command prompts you for the title of a rule and
|
|
highlights the parts on the region that this rule affects. For
|
|
alignment rules, this command highlights the whitespace that @kbd{M-x
|
|
align} would expand or contract, and for exclusion this command
|
|
highlights the parts that @kbd{M-x align} would exclude from
|
|
alignment. To remove the highlighting that this command creates, type
|
|
@kbd{M-x align-unhighlight-rule}.
|
|
|
|
@findex align-current
|
|
@findex align-entire
|
|
The command @kbd{M-x align-current} is similar to @kbd{M-x align},
|
|
except that it operates only on the alignment section that contains
|
|
point regardless of the current region. This command determines the
|
|
boundaries of the current section according to the section separators
|
|
that @code{align-region-separate} define. @kbd{M-x align-entire} is
|
|
another variant of @kbd{M-x align}, that disregards
|
|
@code{align-region-separate} and aligns the entire region as a single
|
|
alignment section with consistent alignment. If you set
|
|
@code{align-region-separate} to @code{entire}, @kbd{M-x align} behaves
|
|
like @kbd{M-x align-entire} by default. To illustrate the effect of
|
|
aligning the entire region as a single alignment section, consider the
|
|
following code:
|
|
|
|
@example
|
|
one = 1;
|
|
foobarbaz = 2;
|
|
|
|
spam = 3;
|
|
emacs = 4;
|
|
@end example
|
|
|
|
@noindent
|
|
when the region covers all of these lines, typing @kbd{M-x align}
|
|
yields:
|
|
|
|
@example
|
|
one = 1;
|
|
foobarbaz = 2;
|
|
|
|
spam = 3;
|
|
emacs = 4;
|
|
@end example
|
|
|
|
@noindent
|
|
On the other hand, @kbd{M-x align-entire} aligns all of the lines as a
|
|
single section, so the @samp{=} appears at the same column in all
|
|
lines:
|
|
|
|
@example
|
|
one = 1;
|
|
foobarbaz = 2;
|
|
|
|
spam = 3;
|
|
emacs = 4;
|
|
@end example
|
|
|
|
@findex align-regexp
|
|
The command @kbd{M-x align-regexp} lets you align the current region
|
|
with an alignment rule that you define ad-hoc, instead of using the
|
|
predefined rules in @code{align-rules-list}. @kbd{M-x align-regexp}
|
|
prompts you for a regular expression and uses that expression as the
|
|
@code{regexp} attribute for an ad-hoc alignment rule that this command
|
|
uses to align the current region. By default, this command adjusts
|
|
the whitespace that matches the first sub-expression of the regular
|
|
expression you specify. If you call @kbd{M-x align-regexp} with a
|
|
prefix argument, it also prompts you for the sub-expression to use and
|
|
lets you specify the amount of whitespace to use as padding, as well
|
|
as whether to apply the rule repeatedly to all matches of the regular
|
|
expression in each line. @xref{Regexp Backslash}, for more
|
|
information about regular expressions and their sub-expressions.
|
|
|
|
@vindex align-indent-before-aligning
|
|
If the user option @code{align-indent-before-aligning} is
|
|
non-@code{nil}, Emacs indents the region before aligning it with
|
|
@kbd{M-x align}. @xref{Indentation}. By default
|
|
@code{align-indent-before-aligning} is set to @code{nil}.
|
|
|
|
@vindex align-to-tab-stop
|
|
The user option @code{align-to-tab-stop} says whether aligned parts
|
|
should start at a tab stop (@pxref{Tab Stops}). If this option is
|
|
@code{nil}, @kbd{M-x align} uses just enough whitespace for alignment,
|
|
disregarding tab stops. If this is a non-@code{nil} symbol, @kbd{M-x
|
|
align} checks the value of that symbol, and if this value is
|
|
non-@code{nil}, @kbd{M-x align} aligns to tab stops. By default, this
|
|
option is set to @code{indent-tabs-mode}, so alignment respects tab
|
|
stops in buffers that use tabs for indentation. @xref{Just Spaces}.
|
|
|
|
@vindex align-default-spacing
|
|
The user option @code{align-default-spacing} specifies the default
|
|
amount of whitespace that @kbd{M-x align} and its related commands use
|
|
for padding between the different parts of each line when aligning it.
|
|
When @code{align-to-tab-stop} is @code{nil}, the value of
|
|
@code{align-default-spacing} is the number of spaces to use for
|
|
padding; when @code{align-to-tab-stop} is non-@code{nil}, the value of
|
|
@code{align-default-spacing} is instead the number of tab stops to
|
|
use. Each alignment rule can override the default that
|
|
@code{align-default-spacing} specifies with the @code{spacing}
|
|
attribute rule.
|