Document 'M-x align' in the Emacs manual
* doc/emacs/indent.texi (Alignment): New section. * doc/emacs/emacs.texi: Update menu. (Bug#66303)
This commit is contained in:
Eshel Yaron
Eli Zaretskii
parent
06a8773811
commit
8141d73ea7
2 changed files with 235 additions and 0 deletions
|
|
@ -592,6 +592,7 @@ Indentation
|
||||||
* Tab Stops:: Stop points for indentation in Text modes.
|
* Tab Stops:: Stop points for indentation in Text modes.
|
||||||
* Just Spaces:: Using only space characters for indentation.
|
* Just Spaces:: Using only space characters for indentation.
|
||||||
* Indent Convenience:: Optional indentation features.
|
* Indent Convenience:: Optional indentation features.
|
||||||
|
* Code Alignment:: Making common parts of lines start at the same column.
|
||||||
|
|
||||||
Commands for Human Languages
|
Commands for Human Languages
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -55,6 +55,7 @@ repositioned to the first non-whitespace character on the line.
|
||||||
* Tab Stops:: Stop points for indentation in Text modes.
|
* Tab Stops:: Stop points for indentation in Text modes.
|
||||||
* Just Spaces:: Using only space characters for indentation.
|
* Just Spaces:: Using only space characters for indentation.
|
||||||
* Indent Convenience:: Optional indentation features.
|
* Indent Convenience:: Optional indentation features.
|
||||||
|
* Code Alignment:: Making common parts of lines start at the same column.
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
@node Indentation Commands
|
@node Indentation Commands
|
||||||
|
|
@ -265,3 +266,236 @@ indents the line after every @key{RET} you type. This mode is enabled
|
||||||
by default. To toggle this minor mode, type @kbd{M-x
|
by default. To toggle this minor mode, type @kbd{M-x
|
||||||
electric-indent-mode}. To toggle the mode in a single buffer,
|
electric-indent-mode}. To toggle the mode in a single buffer,
|
||||||
use @kbd{M-x electric-indent-local-mode}.
|
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.
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue