[Emacs-diffs] /srv/bzr/emacs/trunk r106171: Document scroll-up-line and scroll-down-line in Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106171
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2011-10-24 10:01:54 +0800
message:
  Document scroll-up-line and scroll-down-line in Emacs manual.
  
  * doc/emacs/display.texi (Scrolling): Document scroll-up-line and
  scroll-down-line.  Document scroll-command property.
  (Recentering): New node, split off from Scrolling.
  
  Also, minor copyedits to standardize on the phrase "key binding"
  rather than "keybinding" in the manual.
modified:
  doc/emacs/ChangeLog
  doc/emacs/display.texi
  doc/emacs/emacs.texi
  doc/emacs/kmacro.texi
  doc/emacs/macos.texi
  doc/emacs/programs.texi
  doc/emacs/rmail.texi
  doc/emacs/search.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-10-23 14:57:53 +0000
+++ b/doc/emacs/ChangeLog       2011-10-24 02:01:54 +0000
@@ -1,3 +1,9 @@
+2011-10-24  Chong Yidong  <address@hidden>
+
+       * display.texi (Scrolling): Document scroll-up-line and
+       scroll-down-line.  Document scroll-command property.
+       (Recentering): New node, split off from Scrolling.
+
 2011-10-23  Chong Yidong  <address@hidden>
 
        * frames.texi (Scroll Bars): GTK uses right scroll bars now.

=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi    2011-10-21 14:45:34 +0000
+++ b/doc/emacs/display.texi    2011-10-24 02:01:54 +0000
@@ -13,6 +13,7 @@
 
 @menu
 * Scrolling::              Commands to move text up and down in a window.
+* Recentering::            A scroll command that centers the current line.
 * Auto Scrolling::         Redisplay scrolls text automatically when needed.
 * Horizontal Scrolling::   Moving text left and right in a window.
 * Narrowing::              Restricting display and editing to a portion
@@ -48,15 +49,15 @@
   Scrolling ``forward'' or ``up'' advances the portion of the buffer
 displayed in the window; equivalently, it moves the buffer text
 upwards relative to the window.  Scrolling ``backward'' or ``down''
-moves the displayed portion backwards, and moves the text downwards
-relative to the window.  In Emacs, scrolling ``up'' or ``down'' refers
-to the direction that the text moves in the window, @emph{not} the
-direction that the window moves relative to the text; this terminology
-was taken up by Emacs before the modern meaning of ``scrolling up''
-and ``scrolling down'' became widely adopted.  Hence the strange
-result that @key{PageDown} scrolls ``up'' in the Emacs sense.  In this
-manual, we refer to scrolling ``forward'' and ``backward'' where
-possible, in order to minimize confusion.
+displays an earlier portion of the buffer, and moves the text
+downwards relative to the window.
+
+  In Emacs, scrolling ``up'' or ``down'' refers to the direction that
+the text moves in the window, @emph{not} the direction that the window
+moves relative to the text.  This terminology was adopted by Emacs
+before the modern meaning of ``scrolling up'' and ``scrolling down''
+became widespread.  Hence, the strange result that @key{PageDown}
+scrolls ``up'' in the Emacs sense.
 
   The portion of a buffer displayed in a window always contains point.
 If you move point past the bottom or top of the window, scrolling
@@ -64,11 +65,6 @@
 Scrolling}).  You can also scroll explicitly with these commands:
 
 @table @kbd
address@hidden C-l
-Scroll the selected window so that the current line is the center-most
-text line; on subsequent consecutive invocations, make the current
-line the top-most line, the bottom-most line, and so on in cyclic
-order; also, maybe redisplay the screen (@code{recenter-top-bottom}).
 @item C-v
 @itemx @key{next}
 @itemx @key{PageDown}
@@ -77,6 +73,86 @@
 @itemx @key{prior}
 @itemx @key{PageUp}
 Scroll backward (@code{scroll-down-command}).
address@hidden table
+
address@hidden C-v
address@hidden M-v
address@hidden next
address@hidden prior
address@hidden PageDown
address@hidden PageUp
address@hidden scroll-up-command
address@hidden scroll-down-command
+  @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
+whole window height.  The effect is to take the two lines at the
+bottom of the window and put them at the top, followed by lines that
+were not previously visible.  If point was in the text that scrolled
+off the top, it ends up on the window's new topmost line.  The
address@hidden (or @key{PageDown}) key is equivalent to @kbd{C-v}.
+
+  @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar
+way.  The @key{prior} (or @key{PageUp}) key is equivalent to
address@hidden
+
address@hidden next-screen-context-lines
+  The number of lines of overlap left by these scroll commands is
+controlled by the variable @code{next-screen-context-lines}, whose
+default value is 2.  You can supply the commands with a numeric prefix
+argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave
+point unchanged, so that the text and point move up or down together.
address@hidden with a negative argument is like @kbd{M-v} and vice versa.
+
address@hidden scroll-error-top-bottom
+  By default, these commands signal an error (by beeping or flashing
+the screen) if no more scrolling is possible, because the window has
+reached the beginning or end of the buffer.  If you change the
+variable @code{scroll-error-top-bottom} to @code{t}, the command moves
+point to the farthest possible position.  If point is already there,
+the command signals an error.
+
address@hidden scroll-preserve-screen-position
address@hidden @code{scroll-command} property
+  Some users like scroll commands to keep point at the same screen
+position, so that scrolling back to the same screen conveniently
+returns point to its original position.  You can enable this behavior
+via the variable @code{scroll-preserve-screen-position}.  If the value
+is @code{t}, Emacs adjusts point to keep the cursor at the same screen
+position whenever a scroll command moves it off-window, rather than
+moving it to the topmost or bottommost line.  With any other
address@hidden value, Emacs adjusts point this way even if the scroll
+command leaves point in the window.  This variable affects all the
+scroll commands documented in this section, as well as scrolling with
+the mouse wheel (@pxref{Wheeled Mice}); in general, it affects any
+command that has a address@hidden @code{scroll-command} property.
address@hidden Lists,,, elisp, The Emacs Lisp Reference Manual}.
+
address@hidden scroll-up
address@hidden scroll-down
address@hidden scroll-up-line
address@hidden scroll-down-line
+  The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave
+similarly to @code{scroll-up-command} and @code{scroll-down-command},
+except they do not obey @code{scroll-error-top-bottom}.  Prior to
+Emacs 24, these were the default commands for scrolling up and down.
+The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line}
+scroll the current window by one line at a time.  If you intend to use
+any of these commands, you might want to give them key bindings
+(@pxref{Init Rebinding}).
+
address@hidden Recentering
address@hidden Recentering
+
address@hidden @kbd
address@hidden C-l
+Scroll the selected window so the current line is the center-most text
+line; on subsequent consecutive invocations, make the current line the
+top line, the bottom line, and so on in cyclic order.  Possibly
+redisplay the screen too (@code{recenter-top-bottom}).
+
address@hidden M-x recenter
+Scroll the selected window so the current line is the center-most text
+line.  Possibly redisplay the screen too.
+
 @item C-M-l
 Scroll heuristically to bring useful information onto the screen
 (@code{reposition-window}).
@@ -107,14 +183,13 @@
 screen lines between point and the top or bottom of the window
 (@pxref{Auto Scrolling}).
 
-  You can also supply @kbd{C-l} with a prefix argument.  With a plain
-prefix argument, @kbd{C-u C-l}, Emacs simply recenters point.  With a
-positive argument @var{n}, it scrolls to place point @var{n} lines
-down from the top of the window.  An argument of zero puts point on
-the topmost line.  A negative argument @var{-n} puts point @var{n}
-lines from the bottom of the window.  When given an argument,
address@hidden does not clear the screen or cycle through different screen
-positions.
+  You can also give @kbd{C-l} a prefix argument.  A plain prefix
+argument, @kbd{C-u C-l}, simply recenters point.  A positive argument
address@hidden puts point @var{n} lines down from the top of the window.  An
+argument of zero puts point on the topmost line.  A negative argument
address@hidden puts point @var{n} lines from the bottom of the window.  When
+given an argument, @kbd{C-l} does not clear the screen or cycle
+through different screen positions.
 
 @vindex recenter-redisplay
   If the variable @code{recenter-redisplay} has a address@hidden
@@ -127,62 +202,6 @@
   The more primitive command @kbd{M-x recenter} behaves like
 @code{recenter-top-bottom}, but does not cycle among screen positions.
 
address@hidden C-v
address@hidden M-v
address@hidden next
address@hidden prior
address@hidden PageDown
address@hidden PageUp
address@hidden scroll-up-command
address@hidden scroll-down-command
-  @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
-whole window height.  The effect is to take the two lines at the
-bottom of the window and put them at the top, followed by lines that
-were not previously visible.  If point was in the text that scrolled
-off the top, it ends up on the window's new topmost line.
-
-  Similarly, @kbd{M-v} (@code{scroll-down-command}) scrolls backward.
-
-  We refer to @kbd{C-v} and @kbd{M-v} as @dfn{full-screen scroll
-commands}.  The function key @key{next}, or @key{PageDown}, is
-equivalent to @kbd{C-v}; the function key @key{prior}, or
address@hidden, is equivalent to @kbd{M-v}.
-
address@hidden next-screen-context-lines
-  The variable @code{next-screen-context-lines} controls the number of
-lines of overlap left by the full-screen scroll commands; by default,
-it is 2.  You can supply these commands with a numeric prefix argument
address@hidden  This scrolls the window by @var{n} lines, while attempting
-to leave point unchanged (so that the text and point move up or down
-together).  @kbd{C-v} with a negative argument is like @kbd{M-v} and
-vice versa.
-
address@hidden scroll-error-top-bottom
-  By default, the full-screen scroll commands signal an error (by
-beeping or flashing the screen) if no more scrolling is possible,
-because the window has reached the beginning or end of the buffer.  If
-you change the variable @code{scroll-error-top-bottom} to @code{t},
-Emacs instead moves point to the farthest possible position.  If point
-is already there, the command signals an error.
-
address@hidden scroll-preserve-screen-position
-  Some users like scroll commands to keep point at the same screen
-position.  Then, scrolling back to the same screen also conveniently
-returns point to its original position.  You can enable this via the
-variable @code{scroll-preserve-screen-position}.  If the value is
address@hidden, Emacs adjusts point to keep it at the same vertical position
-within the window, rather than the window edge, whenever a scroll
-command moves it off the window.  With any other address@hidden value,
-Emacs adjusts point this way even if the scroll command leaves point
-in the window.
-
address@hidden scroll-up
address@hidden scroll-down
-  The commands @code{scroll-up} and @code{scroll-down} behave
-similarly to @code{scroll-up-command} and @code{scroll-down-command},
-except they do not obey @code{scroll-error-top-bottom}.  Prior to
-Emacs 24, these were the default commands for scrolling up and down.
-
 @kindex C-M-l
 @findex reposition-window
   @kbd{C-M-l} (@code{reposition-window}) scrolls the current window

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-10-22 01:17:33 +0000
+++ b/doc/emacs/emacs.texi      2011-10-24 02:01:54 +0000
@@ -342,6 +342,7 @@
 Controlling the Display
 
 * Scrolling::              Commands to move text up and down in a window.
+* Recentering::            A scrolling command that centers the current line.
 * Auto Scrolling::         Redisplay scrolls text automatically when needed.
 * Horizontal Scrolling::   Moving text left and right in a window.
 * Narrowing::              Restricting display and editing to a portion

=== modified file 'doc/emacs/kmacro.texi'
--- a/doc/emacs/kmacro.texi     2011-07-11 15:41:41 +0000
+++ b/doc/emacs/kmacro.texi     2011-10-24 02:01:54 +0000
@@ -147,7 +147,7 @@
 @findex kmacro-start-macro
 @findex kmacro-end-macro
   In addition to the @key{F3} and @key{F4} commands described above,
-Emacs also supports an older set of keybindings for defining and
+Emacs also supports an older set of key bindings for defining and
 executing keyboard macros.  To begin a macro definition, type @kbd{C-x
 (} (@code{kmacro-start-macro}); as with @key{F3}, a prefix argument
 appends this definition to the last keyboard macro.  To end a macro

=== modified file 'doc/emacs/macos.texi'
--- a/doc/emacs/macos.texi      2011-10-18 01:42:28 +0000
+++ b/doc/emacs/macos.texi      2011-10-24 02:01:54 +0000
@@ -36,7 +36,7 @@
 
   By default, the @key{alt} and @key{option} keys are the same as
 @key{Meta}.  The Mac @key{Cmd} key is the same as @key{Super}, and
-Emacs provides a set of keybindings using this modifier key that mimic
+Emacs provides a set of key bindings using this modifier key that mimic
 other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}).  You
 can change these bindings in the usual way (@pxref{Key Bindings}).
 

=== modified file 'doc/emacs/programs.texi'
--- a/doc/emacs/programs.texi   2011-10-12 17:38:34 +0000
+++ b/doc/emacs/programs.texi   2011-10-24 02:01:54 +0000
@@ -1441,7 +1441,7 @@
 @kindex C-c , @key{SPC}
 Display a list of possible completions for the symbol at point
 (@code{semantic-complete-analyze-inline}).  This also activates a set
-of special keybindings for choosing a completion: @key{RET} accepts
+of special key bindings for choosing a completion: @key{RET} accepts
 the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
 completions, @key{TAB} completes as far as possible and then cycles,
 and @kbd{C-g} or any other key aborts completion.

=== modified file 'doc/emacs/rmail.texi'
--- a/doc/emacs/rmail.texi      2011-10-20 00:41:15 +0000
+++ b/doc/emacs/rmail.texi      2011-10-24 02:01:54 +0000
@@ -1242,11 +1242,12 @@
 @node Rmail Editing
 @section Editing Within a Message
 
-  Most of the usual Emacs keybindings are available in Rmail mode, though a
-few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
-other purposes.  However, the Rmail buffer is normally read only, and
-most of the letters are redefined as Rmail commands.  If you want to
-edit the text of a message, you must use the Rmail command @kbd{e}.
+  Most of the usual Emacs key bindings are available in Rmail mode,
+though a few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by
+Rmail for other purposes.  However, the Rmail buffer is normally read
+only, and most of the letters are redefined as Rmail commands.  If you
+want to edit the text of a message, you must use the Rmail command
address@hidden
 
 @table @kbd
 @item e

=== modified file 'doc/emacs/search.texi'
--- a/doc/emacs/search.texi     2011-10-21 14:45:34 +0000
+++ b/doc/emacs/search.texi     2011-10-24 02:01:54 +0000
@@ -268,8 +268,8 @@
 
 @vindex isearch-mode-map
   When incremental search is active, you can type @kbd{C-h C-h} to
-access interactive help options, including a list of special
-keybindings.  These keybindings are part of the keymap
+access interactive help options, including a list of special key
+bindings.  These key bindings are part of the keymap
 @code{isearch-mode-map} (@pxref{Keymaps}).
 
 @node Isearch Yank

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-10-23 14:57:53 +0000
+++ b/etc/NEWS  2011-10-24 02:01:54 +0000
@@ -293,7 +293,7 @@
 when `scroll-error-top-bottom' is non-nil.
 +++
 *** New variable `scroll-error-top-bottom' (see above).
-
++++
 *** New scrolling commands `scroll-up-line' and `scroll-down-line'
 scroll a line instead of full screen.
 +++