Commit 6d262977 authored by Chong Yidong's avatar Chong Yidong
Browse files

Update Indentation chapter of Emacs manual.

* indent.texi (Indentation): Rewrite introduction.  Move table to
Indentation Commands node.
(Indentation Commands): Add index entries to table.  Copyedits.
(Tab Stops, Just Spaces): Copyedits.
(Indent Convenience): New node.  Document electric-indent-mode.

* programs.texi (Basic Indent):
* windows.texi (Pop Up Window): Fix kindex entry.
parent 3c2727e8
...@@ -173,7 +173,7 @@ fortran-xtra.texi ...@@ -173,7 +173,7 @@ fortran-xtra.texi
frames.texi cyd frames.texi cyd
glossary.texi glossary.texi
help.texi cyd help.texi cyd
indent.texi indent.texi cyd
killing.texi cyd killing.texi cyd
kmacro.texi cyd kmacro.texi cyd
macos.texi macos.texi
......
2011-11-28 Chong Yidong <cyd@gnu.org>
* indent.texi (Indentation): Rewrite introduction. Move table to
Indentation Commands node.
(Indentation Commands): Add index entries to table. Copyedits.
(Tab Stops, Just Spaces): Copyedits.
(Indent Convenience): New node. Document electric-indent-mode.
* programs.texi (Basic Indent):
* windows.texi (Pop Up Window): Fix kindex entry.
2011-11-28 Chong Yidong <cyd@gnu.org> 2011-11-28 Chong Yidong <cyd@gnu.org>
* modes.texi (Major Modes): Move major-mode variable doc here from * modes.texi (Major Modes): Move major-mode variable doc here from
......
...@@ -551,10 +551,10 @@ Modes ...@@ -551,10 +551,10 @@ Modes
Indentation Indentation
* Indentation Commands:: Various commands and techniques for indentation. * Indentation Commands:: More commands for performing indentation.
* Tab Stops:: You can set arbitrary "tab stops" and then * Tab Stops:: Stop points for indentation in Text modes.
indent to the next tab stop when you want to. * Just Spaces:: Using only space characters for indentation.
* Just Spaces:: You can request indentation using just spaces. * Indent Convenience:: Optional indentation features.
Commands for Human Languages Commands for Human Languages
......
...@@ -8,214 +8,154 @@ ...@@ -8,214 +8,154 @@
@cindex tabs @cindex tabs
@cindex columns (indentation) @cindex columns (indentation)
This chapter describes the Emacs commands that add, remove, or @cindex whitespace character
adjust indentation. @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace
characters} (space and/or tab characters) at the beginning of a line
@table @kbd of text. This chapter documents indentation commands and options
@item @key{TAB} which are common to Text mode and related modes, as well as
Indent the current line appropriately, in a mode-dependent fashion. programming language modes. @xref{Program Indent}, for additional
@item @kbd{C-j} documentation about indenting in programming modes.
Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@item M-^ @findex indent-for-tab-command
Merge the previous and the current line (@code{delete-indentation}). @kindex TAB @r{(indentation)}
This would cancel the effect of a preceding @kbd{C-j}. The simplest way to perform indentation is the @key{TAB} key. In
@item C-M-o most major modes, this runs the command @code{indent-for-tab-command}.
Split the current line at point; text on the line after point becomes a (In C and related modes, @key{TAB} runs the command
new line indented to the same column where point is located @code{c-indent-line-or-region}, which behaves similarly).
(@code{split-line}).
@item M-m @table @key
Move (forward or back) to the first nonblank character on the current @item TAB
line (@code{back-to-indentation}). Insert whitespace, or indent the current line, in a mode-appropriate
@item C-M-\ way (@code{indent-for-tab-command}). If the region is active, indent
Indent lines in the region to the same column (@code{indent-region}). all the lines within it.
@item C-x @key{TAB}
Shift lines in the region rigidly right or left (@code{indent-rigidly}).
@item M-i
Indent from point to the next prespecified tab stop column
(@code{tab-to-tab-stop}).
@item M-x indent-relative
Indent from point to under an indentation point in the previous line.
@end table @end table
@noindent The exact behavior of @key{TAB} depends on the major mode. In Text
The @key{TAB} key runs @code{indent-for-tab-command} in most major mode and related major modes, @key{TAB} normally inserts some
modes (in C and related modes, @key{TAB} runs a separate command, combination of space and tab characters to advance point to the next
@code{c-indent-line-or-region}, which behaves similarly). The major tab stop (@pxref{Tab Stops}). For this purpose, the position of the
mode determines just what this entails. 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
In text modes, @key{TAB} inserts some combination of space and tab the preceding line. If the region is active (@pxref{Using Region}),
characters to advance point to the next tab stop (@pxref{Tab Stops}). @key{TAB} acts specially: it indents each line in the region so that
If the region is active and spans multiple lines, it advances the its first non-whitespace character is aligned with the preceding line.
first character of each of those lines to the next tab stop
(@pxref{Using Region}). For the purposes of this command, the In programming modes, @key{TAB} indents the current line of code in
position of the first non-whitespace character on the preceding line a way that makes sense given the code in the preceding lines. If the
is treated as an additional tab stop. Thus, you can use @key{TAB} to region is active, all the lines in the region are indented this way.
``align'' point with the preceding line. If point was initially within the current line's indentation, it is
repositioned to the first non-whitespace character on the 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 If you just want to insert a tab character in the buffer, type
Normally, indentation commands insert (or remove) an optimal mix of @kbd{C-q @key{TAB}} (@pxref{Inserting Text}).
@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 @menu
@findex tab-to-tab-stop * Indentation Commands:: More commands for performing indentation.
@kindex M-i * Tab Stops:: Stop points for indentation in Text modes.
The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the * Just Spaces:: Using only space characters for indentation.
whitespace characters around point, inserting just enough whitespace * Indent Convenience:: Optional indentation features.
to advance point up to the next tab stop. By default, this involves @end menu
deleting the existing whitespace and inserting a single tab character.
@xref{Just Spaces}, for how to disable use of tabs. However, @node Indentation Commands
@kbd{C-q @key{TAB}} always inserts a tab, even when tabs are disabled @section Indentation Commands
for the indentation commands.
@vindex tab-always-indent Apart from the @key{TAB} (@code{indent-for-tab-command}) command,
The variable @code{tab-always-indent} tweaks the behavior of the Emacs provides a variety of commands to perform indentation in other
@key{TAB} (@code{indent-for-tab-command}) command. The default value, ways.
@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 @table @kbd
* Indentation Commands:: Various commands and techniques for indentation. @item C-j
* Tab Stops:: You can set arbitrary "tab stops" and then @kindex C-j
indent to the next tab stop when you want to. @findex newline-and-indent
* Just Spaces:: You can request indentation using just spaces. Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@end menu
@node Indentation Commands, Tab Stops, Indentation, Indentation @item C-M-o
@section Indentation Commands and Techniques @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 @kindex M-m
@findex back-to-indentation @findex back-to-indentation
To move over the indentation on a line, do @kbd{M-m} @item M-m
(@code{back-to-indentation}). This command, given anywhere on a line, Move (forward or back) to the first non-whitespace character on the
positions point at the first nonblank character on the line, if any, current line (@code{back-to-indentation}). If there are no
or else at the end of the line. non-whitespace characters on the line, move to the end of the line.
To insert an indented line before the current line, do @kbd{C-a C-o
@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, type @item M-i
@kbd{C-q @key{TAB}}. @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}.
@kindex C-M-o @findex indent-relative
@findex split-line @item M-x indent-relative
@kbd{C-M-o} (@code{split-line}) moves the text from point to the end of Insert whitespace at point, until point is aligned with the first
the line vertically down, so that the current line becomes two lines. non-whitespace character on the previous line (actually, the last
@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it non-blank line). If point is already farther right than that, run
inserts after point a newline and enough indentation to reach the same @code{tab-to-tab-stop} instead---unless called with a numeric
column point is on. Point remains before the inserted newline; in this argument, in which case do nothing.
regard, @kbd{C-M-o} resembles @kbd{C-o}.
@item M-^
@kindex M-^ @kindex M-^
@findex delete-indentation @findex delete-indentation
To join two lines cleanly, use the @kbd{M-^} Merge the previous and the current line (@code{delete-indentation}).
(@code{delete-indentation}) command. It deletes the indentation at This ``joins'' the two lines cleanly, by replacing any indentation at
the front of the current line, and the line boundary as well, the front of the current line, together with the line boundary, with a
replacing them with a single space. As a special case (useful for single space.
Lisp code) the single space is omitted if the characters to be joined
are consecutive open parentheses or closing parentheses, or if the As a special case (useful for Lisp code), the single space is omitted
junction follows another newline. To delete just the indentation of a if the characters to be joined are consecutive opening and closing
line, go to the beginning of the line and use @kbd{M-\} parentheses, or if the junction follows another newline.
(@code{delete-horizontal-space}), which deletes all spaces and tabs
around the cursor. If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it
If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
appears after the newline that is deleted. @xref{Fill Prefix}. appears after the newline that is deleted. @xref{Fill Prefix}.
@item C-M-\
@kindex C-M-\ @kindex C-M-\
@kindex C-x TAB
@findex indent-region @findex indent-region
@findex indent-rigidly Indent all the lines in the region, as though you had typed @key{TAB}
There are also commands for changing the indentation of several lines at the beginning of each line (@code{indent-region}).
at once. They apply to all the lines that begin in the region.
@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual''
way, as if you had typed @key{TAB} at the beginning of the line. A
numeric argument specifies the column to indent to, and each line is
shifted left or right so that its first nonblank character appears in
that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of
the lines in the region right by its argument (left, for negative
arguments). The whole group of lines moves rigidly sideways, which is
how the command gets its name.
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 @cindex remove indentation
To remove all indentation from all of the lines in the region, Shift each line in the region by a fixed distance, to the right or
invoke @kbd{C-x @key{TAB}} with a large negative argument, such as left (@code{indent-rigidly}). The distance to move is determined by
-1000. the numeric argument (positive to move rightward, negative to move
leftward).
This command can be used to remove all indentation from the lines in
the region, by invoking it with a large negative argument,
e.g. @kbd{C-u -1000 C-x @key{TAB}}.
@end table
@findex indent-relative @node Tab Stops
@kbd{M-x indent-relative} indents at point based on the previous line
(actually, the last nonempty line). It inserts whitespace at point, moving
point, until it is underneath the next indentation point in the previous line.
An indentation point is the end of a sequence of whitespace or the end of
the line. If point is farther right than any indentation point in the
previous line, @code{indent-relative} runs @code{tab-to-tab-stop}
@ifnottex
(@pxref{Tab Stops}),
@end ifnottex
@iftex
(see next section),
@end iftex
unless it is called with a numeric argument, in which case it does
nothing.
@xref{Format Indentation}, for another way of specifying the
indentation for part of your text.
@node Tab Stops, Just Spaces, Indentation Commands, Indentation
@section Tab Stops @section Tab Stops
@cindex tab stops @cindex tab stops
@cindex using tab stops in making tables
@cindex tables, indentation for @vindex tab-stop-list
@kindex M-i Emacs defines certain column numbers to be @dfn{tab stops}. These
@findex tab-to-tab-stop are used as stopping points by @key{TAB} when inserting whitespace in
For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}). Text mode and related modes (@pxref{Indentation}), and by commands
This command inserts indentation before point, enough to reach the like @kbd{M-i} (@pxref{Indentation Commands}). By default, tab stops
next tab stop column. are located every 8 columns. These positions are stored in the
variable @code{tab-stop-list}, whose value is a list of column numbers
in increasing order.
@findex edit-tab-stops @findex edit-tab-stops
@findex edit-tab-stops-note-changes
@kindex C-c C-c @r{(Edit Tab Stops)} @kindex C-c C-c @r{(Edit Tab Stops)}
@vindex tab-stop-list Instead of customizing the variable @code{tab-stop-list} directly, a
You can change the tab stops used by @kbd{M-i} and other indentation convenient way to view and set tab stops is via the command @kbd{M-x
commands, so that they need not be spaced every eight characters, or edit-tab-stops}. This switches to a buffer containing a description
even regularly spaced. The tab stops are stored in the variable of the tab stop settings, which looks like this:
@code{tab-stop-list}, as a list of column numbers in increasing order.
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
new tab stops take effect. The buffer uses Overwrite mode
(@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was
current when you invoked it, and stores the tab stops back in that
buffer; normally all buffers share the same tab stops and changing
them in one buffer affects all, but if you happen to make
@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
that buffer will edit the local settings.
Here is what the text representing the tab stops looks like for ordinary
tab stops every eight columns.
@example @example
: : : : : : : : : : : :
...@@ -224,37 +164,77 @@ tab stops every eight columns. ...@@ -224,37 +164,77 @@ tab stops every eight columns.
To install changes, type C-c C-c To install changes, type C-c C-c
@end example @end example
The first line contains a colon at each tab stop. The remaining lines @noindent
are present just to help you see where the colons are and know what to do. 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.
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}). 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
Note that the tab stops that control @code{tab-to-tab-stop} have @vindex tab-width
nothing to do with how tab characters are displayed in the buffer. Normally, indentation commands insert (or remove) an optimal mix of
Tab characters are always displayed as empty spaces extending to the space characters and tab characters to align to the desired column.
next display tab stop, which occurs every @code{tab-width} columns Tab characters are displayed as a stretch of empty space extending to
regardless of the contents of @code{tab-stop-list}. @xref{Text 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}. Display}.
@node Just Spaces,, Tab Stops, Indentation
@section Tabs vs. Spaces
@vindex indent-tabs-mode @vindex indent-tabs-mode
Emacs normally uses both tabs and spaces to indent lines. If you If you prefer, all indentation can be made from spaces only. To
prefer, all indentation can be made from spaces only. To request request this, set the buffer-local variable @code{indent-tabs-mode} to
this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer @code{nil}. @xref{Locals}, for information about setting buffer-local
variable, so altering the variable affects only the current buffer, variables. Note, however, that @kbd{C-q @key{TAB}} always inserts a
but there is a default value which you can change as well. tab character, regardless of the value of @code{indent-tabs-mode}.
@xref{Locals}.
One reason to set @code{indent-tabs-mode} to @code{nil} is that not
A tab is not always displayed in the same way. By default, tabs are all editors display tab characters in the same way. Emacs users, too,
eight columns wide, but some people like to customize their editors to may have different customized values of @code{tab-width}. By using
use a different tab width (e.g., by changing the variable spaces only, you can make sure that your file always looks the same.
@code{tab-width} in Emacs). By using spaces only, you can make sure If you only care about how it looks within Emacs, another way to
that your file looks the same regardless of the tab width setting. tackle this problem is to set the @code{tab-width} variable in a
file-local variable (@pxref{File Variables}).
@findex tabify @findex tabify
@findex untabify @findex untabify
There are also commands to convert tabs to spaces or vice versa, always There are also commands to convert tabs to spaces or vice versa, always
preserving the columns of all nonblank text. @kbd{M-x tabify} scans the 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 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 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. 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.
@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. To toggle this minor
mode, type @kbd{M-x electric-indent-mode}.
...@@ -397,7 +397,7 @@ the syntax and conventions for its particular language. ...@@ -397,7 +397,7 @@ the syntax and conventions for its particular language.
Use @kbd{C-q @key{TAB}} to insert a tab character at point. Use @kbd{C-q @key{TAB}} to insert a tab character at point.
@kindex C-j @kindex C-j @r{(indenting source code)}
@findex newline-and-indent @findex newline-and-indent
When entering lines of new code, use @kbd{C-j} When entering lines of new code, use @kbd{C-j}
(@code{newline-and-indent}), which inserts a newline and then adjusts (@code{newline-and-indent}), which inserts a newline and then adjusts
......
...@@ -193,6 +193,7 @@ Select buffer @var{bufname} in another window ...@@ -193,6 +193,7 @@ Select buffer @var{bufname} in another window
@findex display-buffer @findex display-buffer
@item C-x 4 C-o @var{bufname} @key{RET} @item C-x 4 C-o @var{bufname} @key{RET}
@kindex C-x 4 C-o
Display buffer @var{bufname} in some window, without trying to select Display buffer @var{bufname} in some window, without trying to select
it (@code{display-buffer}). @xref{Displaying Buffers}, for details it (@code{display-buffer}). @xref{Displaying Buffers}, for details
about how the window is chosen. about how the window is chosen.
...@@ -421,7 +422,7 @@ and display the buffer there. ...@@ -421,7 +422,7 @@ and display the buffer there.
@end itemize @end itemize
@node Window Convenience @node Window Convenience
@section Window Handling Convenience Features and Customization @section Convenience Features for Window Handling
@findex winner-mode @findex winner-mode
@cindex Winner mode @cindex Winner mode
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment