[Emacs-diffs] /srv/bzr/emacs/trunk r106539: Update Indentation chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106539
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2011-11-28 19:12:00 +0800
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/indent.texi
  doc/emacs/programs.texi
  doc/emacs/windows.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2011-11-28 06:24:48 +0000
+++ b/admin/FOR-RELEASE 2011-11-28 11:12:00 +0000
@@ -173,7 +173,7 @@
 frames.texi       cyd
 glossary.texi
 help.texi         cyd
-indent.texi       
+indent.texi       cyd
 killing.texi      cyd
 kmacro.texi       cyd
 macos.texi        

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-11-28 06:24:48 +0000
+++ b/doc/emacs/ChangeLog       2011-11-28 11:12:00 +0000
@@ -1,5 +1,16 @@
 2011-11-28  Chong Yidong  <address@hidden>
 
+       * 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  <address@hidden>
+
        * modes.texi (Major Modes): Move major-mode variable doc here from
        Choosing Modes.  Document describe-mode.  Document prog-mode-hook
        and text-mode-hook.  Add example of using hooks.

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-11-27 08:22:37 +0000
+++ b/doc/emacs/emacs.texi      2011-11-28 11:12:00 +0000
@@ -551,10 +551,10 @@
 
 Indentation
 
-* 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.
-* Just Spaces::           You can request indentation using just spaces.
+* 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.
 
 Commands for Human Languages
 

=== modified file 'doc/emacs/indent.texi'
--- a/doc/emacs/indent.texi     2011-07-10 04:05:33 +0000
+++ b/doc/emacs/indent.texi     2011-11-28 11:12:00 +0000
@@ -8,214 +8,154 @@
 @cindex tabs
 @cindex columns (indentation)
 
-  This chapter describes the Emacs commands that add, remove, or
-adjust indentation.
address@hidden 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.
+
address@hidden indent-for-tab-command
address@hidden 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
address@hidden, which behaves similarly).
+
address@hidden @key
address@hidden 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.
address@hidden 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}),
address@hidden 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
address@hidden @key{TAB}} (@pxref{Inserting Text}).
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Indentation Commands
address@hidden Indentation Commands
+
+Apart from the @key{TAB} (@code{indent-for-tab-command}) command,
+Emacs provides a variety of commands to perform indentation in other
+ways.
 
 @table @kbd
address@hidden @key{TAB}
-Indent the current line appropriately, in a mode-dependent fashion.
address@hidden @kbd{C-j}
address@hidden C-j
address@hidden C-j
address@hidden newline-and-indent
 Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
address@hidden 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}).
address@hidden C-M-o
address@hidden 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.
+
address@hidden M-m
address@hidden back-to-indentation
 @item M-m
-Move (forward or back) to the first nonblank character on the current
-line (@code{back-to-indentation}).
address@hidden C-M-\
-Indent lines in the region to the same column (@code{indent-region}).
address@hidden C-x @key{TAB}
-Shift lines in the region rigidly right or left (@code{indent-rigidly}).
+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
-Indent from point to the next prespecified tab stop column
-(@code{tab-to-tab-stop}).
address@hidden M-i
address@hidden tab-to-tab-stop
+Indent whitespace at point, up to the next tab stop
+(@code{tab-to-tab-stop}).  @xref{Tab Stops}.
+
address@hidden indent-relative
 @item M-x indent-relative
-Indent from point to under an indentation point in the previous line.
address@hidden table
-
address@hidden
-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,
address@hidden, 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}.
-
address@hidden tab-width
-  Normally, indentation commands insert (or remove) an optimal mix of
address@hidden 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}}.
address@hidden Display}.
-
address@hidden edit-tab-stops
address@hidden tab-to-tab-stop
address@hidden 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,
address@hidden @key{TAB}} always inserts a tab, even when tabs are disabled
-for the indentation commands.
-
address@hidden tab-always-indent
-  The variable @code{tab-always-indent} tweaks the behavior of the
address@hidden (@code{indent-for-tab-command}) command.  The default value,
address@hidden, 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.
-
address@hidden
-* 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.
-* Just Spaces::           You can request indentation using just spaces.
address@hidden menu
-
address@hidden Indentation Commands, Tab Stops, Indentation, Indentation
address@hidden Indentation Commands and Techniques
-
address@hidden M-m
address@hidden 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
address@hidden  To make an indented line after the current line, use
address@hidden C-j}.
-
-  If you just want to insert a tab character in the buffer, type
address@hidden @key{TAB}}.
-
address@hidden C-M-o
address@hidden split-line
-  @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
-the line vertically down, so that the current line becomes two lines.
address@hidden first moves point forward over any spaces and tabs.  Then it
-inserts after point a newline and enough indentation to reach the same
-column point is on.  Point remains before the inserted newline; in this
-regard, @kbd{C-M-o} resembles @kbd{C-o}.
-
+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
address@hidden instead---unless called with a numeric
+argument, in which case do nothing.
+
address@hidden M-^
 @kindex M-^
 @findex delete-indentation
-  To join two lines cleanly, use the @kbd{M-^}
-(@code{delete-indentation}) command.  It deletes the indentation at
-the front of the current line, and the line boundary as well,
-replacing them 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 open parentheses or closing parentheses, or if the
-junction follows another newline.  To delete just the indentation of a
-line, go to the beginning of the line and use @kbd{M-\}
-(@code{delete-horizontal-space}), which deletes all spaces and tabs
-around the cursor.
-
-  If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
+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}.
 
address@hidden C-M-\
 @kindex C-M-\
address@hidden indent-region
+Indent all the lines in the region, as though you had typed @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.
+
address@hidden C-x @key{TAB}
 @kindex C-x TAB
address@hidden 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.
address@hidden (@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.
-
 @cindex remove indentation
-  To remove all indentation from all of the lines in the region,
-invoke @kbd{C-x @key{TAB}} with a large negative argument, such as
--1000.
-
address@hidden 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}
address@hidden
-(@pxref{Tab Stops}),
address@hidden ifnottex
address@hidden
-(see next section),
address@hidden 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.
-
address@hidden Tab Stops, Just Spaces, Indentation Commands, Indentation
+Shift each line in the region by a fixed distance, to the right or
+left (@code{indent-rigidly}).  The distance to move is determined by
+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}}.
address@hidden table
+
address@hidden Tab Stops
 @section Tab Stops
-
 @cindex tab stops
address@hidden using tab stops in making tables
address@hidden tables, indentation for
address@hidden M-i
address@hidden 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.
+
address@hidden 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}).  By default, tab stops
+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
address@hidden edit-tab-stops-note-changes
 @kindex C-c C-c @r{(Edit Tab Stops)}
address@hidden tab-stop-list
-  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
address@hidden, 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
address@hidden 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.
+  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
         :       :       :       :       :       :
@@ -224,37 +164,77 @@
 To install changes, type C-c C-c
 @end example
 
-  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 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
address@hidden
+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
address@hidden variable local to the buffer where you called
address@hidden 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
address@hidden tab stop}.  @xref{Text Display}.
+
address@hidden Just Spaces
address@hidden Tabs vs. Spaces
+
address@hidden tab-width
+  Normally, indentation commands insert (or remove) an optimal mix of
+space characters and tab characters 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}.
 
address@hidden Just Spaces,, Tab Stops, Indentation
address@hidden Tabs vs. Spaces
-
 @vindex indent-tabs-mode
-  Emacs normally uses both tabs and spaces to indent lines.  If you
-prefer, all indentation can be made from spaces only.  To request
-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.
address@hidden
+  If you prefer, all indentation can be made from spaces only.  To
+request this, set the buffer-local variable @code{indent-tabs-mode} to
address@hidden  @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}.
 
-  A tab is not always displayed in the same way.  By default, tabs are
-eight columns wide, but some people like to customize their editors to
-use a different tab width (e.g., by changing the variable
address@hidden in Emacs).  By using spaces only, you can make sure
-that your file looks the same regardless of the tab width setting.
+  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 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
 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.
+
address@hidden Indent Convenience
address@hidden Convenience Features for Indentation
+
address@hidden tab-always-indent
+  The variable @code{tab-always-indent} tweaks the behavior of the
address@hidden (@code{indent-for-tab-command}) command.  The default value,
address@hidden, 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.
+
address@hidden Electric Indent mode
address@hidden mode, Electric Indent
address@hidden 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}.

=== modified file 'doc/emacs/programs.texi'
--- a/doc/emacs/programs.texi   2011-10-24 02:01:54 +0000
+++ b/doc/emacs/programs.texi   2011-11-28 11:12:00 +0000
@@ -397,7 +397,7 @@
 
   Use @kbd{C-q @key{TAB}} to insert a tab character at point.
 
address@hidden C-j
address@hidden C-j @r{(indenting source code)}
 @findex newline-and-indent
   When entering lines of new code, use @kbd{C-j}
 (@code{newline-and-indent}), which inserts a newline and then adjusts

=== modified file 'doc/emacs/windows.texi'
--- a/doc/emacs/windows.texi    2011-11-27 08:22:37 +0000
+++ b/doc/emacs/windows.texi    2011-11-28 11:12:00 +0000
@@ -193,6 +193,7 @@
 
 @findex display-buffer
 @item C-x 4 C-o @var{bufname} @key{RET}
address@hidden C-x 4 C-o
 Display buffer @var{bufname} in some window, without trying to select
 it (@code{display-buffer}).  @xref{Displaying Buffers}, for details
 about how the window is chosen.
@@ -421,7 +422,7 @@
 @end itemize
 
 @node Window Convenience
address@hidden Window Handling Convenience Features and Customization
address@hidden Convenience Features for Window Handling
 
 @findex winner-mode
 @cindex Winner mode