comparison man/indent.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Indentation, Text, Major Modes, Top
@chapter Indentation
@cindex indentation
@cindex columns (indentation)

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-^
Merge the previous and the current line (@code{delete-indentation}).
This would cancel out the effect of @kbd{C-j}.
@item C-M-o
Split the current line at point; text on the line after point becomes a
new line indented to the same column where point is located
(@code{split-line}).
@item M-m
Move (forward or back) to the first nonblank character on the current
line (@code{back-to-indentation}).
@item C-M-\
Indent several lines to the same column (@code{indent-region}).
@item C-x @key{TAB}
Shift a block of lines 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

  Most programming languages have some indentation convention.  For Lisp
code, lines are indented according to their nesting in parentheses.  The
same general idea is used for C code, though many details are different.

@kindex TAB
  Whatever the language, to indent a line, use the @key{TAB} command.  Each
major mode defines this command to perform the sort of indentation
appropriate for the particular language.  In Lisp mode, @key{TAB} aligns
the line according to its depth in parentheses.  No matter where in the
line you are when you type @key{TAB}, it aligns the line as a whole.  In C
mode, @key{TAB} implements a subtle and sophisticated indentation style that
knows about many aspects of C syntax.

  In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
indents to the next tab stop column.  You can set the tab stops with
@kbd{M-x edit-tab-stops}.

  Normally, @key{TAB} inserts an optimal mix of tabs and spaces for
the intended indentation.  @xref{Just Spaces}, for how to prevent use
of tabs.

@menu
* Indentation Commands::  Various commands and techniques for indentation.
* Tab Stops::             You can set arbitrary "tab stops" and then
                            indent to the next tab stop when you want to.

@kindex M-m
@findex back-to-indentation
  To move over the indentation on a line, do @kbd{M-m}
(@code{back-to-indentation}).  This command, given anywhere on a line,
positions point at the first nonblank character on 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}.

@kindex C-M-\
@kindex C-x TAB
@findex indent-region
@findex indent-rigidly
  There are also commands for changing the indentation of several lines
at once.  @kbd{C-M-\} (@code{indent-region}) applies to all the lines
that begin in the region; it 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.@refill

@cindex remove indentation
  If you want to remove all indentation from all of the line in the

such as -1000.

@findex indent-relative
  @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 an 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, the whitespace before point is deleted and the first
indentation point then applicable is used.  If no indentation point is
applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop}
@ifinfo
(@pxref{Tab Stops}),
@end ifinfo
@iftex
(see next section),
@end iftex
unless it is called with a numeric argument, in which case it does
nothing.

  @code{indent-relative} is the definition of @key{TAB} in Indented Text
mode.  @xref{Text}.

  @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

@cindex tab stops
@cindex using tab stops in making tables
@cindex tables, indentation for
@kindex M-i
@findex tab-to-tab-stop
  For typing in tables, you can use Text mode's definition of @key{TAB},
@code{tab-to-tab-stop}.  This command inserts indentation before point,
enough to reach the next tab stop column.  If you are not in Text mode,
this command can be found on the key @kbd{M-i}.

@findex edit-tab-stops
@findex edit-tab-stops-note-changes
@kindex C-c C-c @r{(Edit Tab Stops)}
@vindex tab-stop-list

  The 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.  @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.

this, set @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer
variable, so altering the variable affects only the current buffer,
but there is a default value which you can change as well.
@xref{Locals}.

@findex tabify
@findex untabify
  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
region for sequences of spaces, and converts sequences of at least three
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.

88155:d7ddb3e565de

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2002, 2003,
@c   2004, 2005 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Indentation, Text, Major Modes, Top
@chapter Indentation
@cindex indentation
@cindex columns (indentation)

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-^
Merge the previous and the current line (@code{delete-indentation}).
This would cancel the effect of a preceding @kbd{C-j}.
@item C-M-o
Split the current line at point; text on the line after point becomes a
new line indented to the same column where point is located
(@code{split-line}).
@item M-m
Move (forward or back) to the first nonblank character on the current
line (@code{back-to-indentation}).
@item C-M-\
Indent lines in the region to the same column (@code{indent-region}).
@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

  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{Display Custom}, 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.

@menu
* Indentation Commands::  Various commands and techniques for indentation.
* Tab Stops::             You can set arbitrary "tab stops" and then
                            indent to the next tab stop when you want to.

@kindex M-m
@findex back-to-indentation
  To move over the indentation on a line, do @kbd{M-m}
(@code{back-to-indentation}).  This command, given anywhere on a line,
positions point at the first nonblank character on the line, if any,
or else at 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}.

@kindex C-M-\
@kindex C-x TAB
@findex indent-region
@findex indent-rigidly
  There are also commands for changing the indentation of several lines
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.@refill

@cindex remove indentation
  If you want to remove all indentation from all of the line in the

such as -1000.

@findex indent-relative
  @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}
@ifinfo
(@pxref{Tab Stops}),
@end ifinfo
@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

@cindex tab stops
@cindex using tab stops in making tables
@cindex tables, indentation for
@kindex M-i
@findex tab-to-tab-stop
  For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}).
This command inserts indentation before point, enough to reach the
next tab stop column.

@findex edit-tab-stops
@findex edit-tab-stops-note-changes
@kindex C-c C-c @r{(Edit Tab Stops)}
@vindex tab-stop-list

  The 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.

this, set @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer
variable, so altering the variable affects only the current buffer,
but there is a default value which you can change as well.
@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
that your file looks the same regardless of the tab width setting.

@findex tabify
@findex untabify
  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
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.

@ignore
   arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb
@end ignore