Document some Emacs 24 scrolling changes.

* doc/emacs/basic.texi (Moving Point):
* doc/emacs/custom.texi (Mouse Buttons):
* doc/emacs/rmail.texi (Rmail Scrolling):
* doc/emacs/search.texi (Isearch Scroll):

* doc/emacs/display.texi (Scrolling): Replace scroll-up/down with
scroll-up/down-command.  Fix scroll-preserve-screen-position
description.  Document scroll-error-top-bottom.

* doc/lispref/windows.texi (Textual Scrolling): Document scroll-up-command,
scroll-down-command, scroll-error-top-bottom, and the
scroll-command symbol property.

2 files changed, 86 insertions, 56 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index afd32ad4ebe..7755fd65bff 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2011-10-01  Chong Yidong  <cyd@stupidchicken.com>
+
+        * windows.texi (Textual Scrolling): Document scroll-up-command,
+        scroll-down-command, scroll-error-top-bottom, and the
+        scroll-command symbol property.
+
 2011-09-28  Juanma Barranquero  <lekktu@gmail.com>
 
         * windows.texi (Splitting Windows): Fix typos.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 6a7206f459d..2ba52ef8b59 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3100,67 +3100,77 @@ text line, @var{ypos} is negative.
 @cindex scrolling textually
 
   @dfn{Textual scrolling} means moving the text up or down through a
-window.  It works by changing the value of the window's display-start
-location.  It may also change the value of @code{window-point} to keep
-point on the screen.
-
-  Textual scrolling was formerly called ``vertical scrolling,'' but we
-changed its name to distinguish it from the new vertical fractional
-scrolling feature (@pxref{Vertical Scrolling}).
-
-  In the commands @code{scroll-up} and @code{scroll-down}, the directions
-``up'' and ``down'' refer to the motion of the text in the buffer at which
-you are looking through the window.  Imagine that the text is
-written on a long roll of paper and that the scrolling commands move the
-paper up and down.  Thus, if you are looking at text in the middle of a
-buffer and repeatedly call @code{scroll-down}, you will eventually see
-the beginning of the buffer.
+window.  It works by changing the window's display-start location.  It
+may also change the value of @code{window-point} to keep point on the
+screen (@pxref{Window Point}).
+
+  The basic textual scrolling functions are @code{scroll-up} (which
+scrolls forward) and @code{scroll-down} (which scrolls backward).  In
+these function names, ``up'' and ``down'' refer to the direction of
+motion of the buffer text relative to the window.  Imagine that the
+text is written on a long roll of paper and that the scrolling
+commands move the paper up and down.  Thus, if you are looking at the
+middle of a buffer and repeatedly call @code{scroll-down}, you will
+eventually see the beginning of the buffer.
 
   Some people have urged that the opposite convention be used: they
-imagine that the window moves over text that remains in place.  Then
-``down'' commands would take you to the end of the buffer.  This view is
-more consistent with the actual relationship between windows and the
-text in the buffer, but it is less like what the user sees.  The
-position of a window on the terminal does not move, and short scrolling
-commands clearly move the text up or down on the screen.  We have chosen
-names that fit the user's point of view.
-
-  The textual scrolling functions (aside from
-@code{scroll-other-window}) have unpredictable results if the current
-buffer is different from the buffer that is displayed in the selected
-window.  @xref{Current Buffer}.
-
-  If the window contains a row which is taller than the height of the
-window (for example in the presence of a large image), the scroll
-functions will adjust the window's vertical scroll position to scroll
-the partially visible row.  To disable this feature, Lisp code may bind
-the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical
-Scrolling}).
+imagine the window moving over text that remains in place, so that
+``down'' commands take you to the end of the buffer.  This convention
+is consistent with fact that such a command is bound to a key named
+@key{PageDown} on modern keyboards.  We have not switched to this
+convention as that is likely to break existing Emacs Lisp code.
+
+  Textual scrolling functions (aside from @code{scroll-other-window})
+have unpredictable results if the current buffer is not the one
+displayed in the selected window.  @xref{Current Buffer}.
+
+  If the window contains a row taller than the height of the window
+(for example in the presence of a large image), the scroll functions
+will adjust the window's vertical scroll position to scroll the
+partially visible row.  Lisp callers can disable this feature by
+binding the variable @code{auto-window-vscroll} to @code{nil}
+(@pxref{Vertical Scrolling}).
 
 @deffn Command scroll-up &optional count
-This function scrolls the text in the selected window upward
-@var{count} lines.  If @var{count} is negative, scrolling is actually
-downward.
+This function scrolls forward by @var{count} lines in the selected
+window.
 
-If @var{count} is @code{nil} (or omitted), then the length of scroll
-is @code{next-screen-context-lines} lines less than the usable height of
-the window (not counting its mode line).
+If @var{count} is negative, it scrolls backward instead.  If
+@var{count} is @code{nil} (or omitted), the distance scrolled is
+@code{next-screen-context-lines} lines less than the height of the
+window's text area.
 
-@code{scroll-up} returns @code{nil}, unless it gets an error
-because it can't scroll any further.
+If the selected window cannot be scrolled any further, this function
+signals an error.  Otherwise, it returns @code{nil}.
 @end deffn
 
 @deffn Command scroll-down &optional count
-This function scrolls the text in the selected window downward
-@var{count} lines.  If @var{count} is negative, scrolling is actually
-upward.
+This function scrolls backward by @var{count} lines in the selected
+window.
+
+If @var{count} is negative, it scrolls forward instead.  If
+@var{count} is omitted or @code{nil}, the distance scrolled is
+@code{next-screen-context-lines} lines less than the height of the
+window's text area.
 
-If @var{count} is omitted or @code{nil}, then the length of the scroll
-is @code{next-screen-context-lines} lines less than the usable height of
-the window (not counting its mode line).
+If the selected window cannot be scrolled any further, this function
+signals an error.  Otherwise, it returns @code{nil}.
+@end deffn
+
+@deffn Command scroll-up-command &optional count
+This behaves like @code{scroll-up}, except that if the selected window
+cannot be scrolled any further and the value of the variable
+@code{scroll-error-top-bottom} is @code{t}, it tries to move to the
+end of the buffer instead.  If point is already there, it signals an
+error.
+@end deffn
 
-@code{scroll-down} returns @code{nil}, unless it gets an error because
-it can't scroll any further.
+@deffn Command scroll-down-command &optional count
+This behaves like @code{scroll-down}, except that if the selected
+window cannot be scrolled any further and the value of the variable
+@code{scroll-error-top-bottom} is @code{t}, it tries to move to the
+beginning of the buffer instead.  If point is already there, it
+signals an error.
 @end deffn
 
 @deffn Command scroll-other-window &optional count
@@ -3190,7 +3200,6 @@ line reappears after the echo area momentarily displays the message
 @samp{Beginning of buffer}.
 @end deffn
 
-@c Emacs 19 feature
 @defvar other-window-scroll-buffer
 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
 which buffer's window to scroll.
@@ -3245,13 +3254,18 @@ only by precisely @var{n} lines, not a smaller number.  This feature
 does not work with @code{scroll-margin}.  The default value is zero.
 @end defopt
 
+@cindex @code{scroll-command} property
 @defopt scroll-preserve-screen-position
-If this option is @code{t}, scrolling which would move the current
-point position out of the window chooses the new position of point
-so that the vertical position of the cursor is unchanged, if possible.
+If this option is @code{t}, whenever a scrolling command moves point
+off-window, Emacs tries to adjust point to keep the cursor at its old
+vertical position in the window, rather than the window edge.
+
+If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
+to keep the cursor at the same vertical position, even if the
+scrolling command didn't move point off-window.
 
-If it is non-@code{nil} and not @code{t}, then the scrolling functions
-always preserve the vertical position of point, if possible.
+This option affects all scroll commands that have a non-@code{nil}
+@code{scroll-command} symbol property.
 @end defopt
 
 @defopt next-screen-context-lines
@@ -3262,6 +3276,16 @@ bottom of the window appear instead at the top.  The default value is
 @code{2}.
 @end defopt
 
+@defopt scroll-error-top-bottom
+If this option is @code{nil} (the default), @code{scroll-up-command}
+and @code{scroll-down-command} simply signal an error when no more
+scrolling is possible.
+
+If the value is @code{t}, these commands instead move point to the
+beginning or end of the buffer (depending on scrolling direction);
+only if point is already on that position do they signal an error.
+@end defopt
+
 @deffn Command recenter &optional count
 @cindex centering point
 This function scrolls the text in the selected window so that point is