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.

9 files changed, 187 insertions, 128 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 88c208ce295..7d883a6eb91 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,14 @@
+2011-10-01  Chong Yidong  <cyd@stupidchicken.com>
+
+        * basic.texi (Moving Point):
+        * custom.texi (Mouse Buttons):
+        * rmail.texi (Rmail Scrolling):
+        * search.texi (Isearch Scroll):
+
+        * display.texi (Scrolling): Replace scroll-up/down with
+        scroll-up/down-command.  Fix scroll-preserve-screen-position
+        description.  Document scroll-error-top-bottom.
+
 2011-09-30  Glenn Morris  <rgm@gnu.org>
 
         * commands.texi (Keys): Whitespace fix.  (Bug#9635)
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index b06391f004c..8c8708a3b51 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -219,21 +219,19 @@ numeric argument @var{n}, move to @var{n}/10 of the way from the top.
 @xref{Arguments}, for more information on numeric arguments.@refill
 @item M->
 Move to the end of the buffer (@code{end-of-buffer}).
+
 @item C-v
 @itemx @key{PageDown}
 @itemx @key{next}
-Scroll the display one screen forward, and move point if necessary to
-put it on the screen (@code{scroll-up}).  If your keyboard has a
-@key{PageDown} key (sometimes labelled @key{next}), it does the same
-thing as @key{C-v}.  Scrolling commands are described further in
-@ref{Scrolling}.
+Scroll the display one screen forward, and move point onscreen if
+necessary (@code{scroll-up-command}).  @xref{Scrolling}.
+
 @item M-v
 @itemx @key{PageUp}
 @itemx @key{prior}
-Scroll one screen backward, and move point if necessary to put it on
-the screen (@code{scroll-down}).  If your keyboard has a @key{PageUp}
-key (sometimes labelled @key{prior}), it does the same thing as
-@kbd{M-v}.
+Scroll one screen backward, and move point onscreen if necessary
+(@code{scroll-down-command}).  @xref{Scrolling}.
+
 @item M-x goto-char
 Read a number @var{n} and move point to buffer position @var{n}.
 Position 1 is the beginning of the buffer.
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index a22d6c1f5dd..6af77374d07 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1854,10 +1854,10 @@ comes from a special area of the screen by means of dummy ``prefix
 keys.''  For example, if you click the mouse in the mode line, you get
 the prefix key @code{mode-line} before the ordinary mouse-button symbol.
 Thus, here is how to define the command for clicking the first button in
-a mode line to run @code{scroll-up}:
+a mode line to run @code{scroll-up-command}:
 
 @example
-(global-set-key [mode-line mouse-1] 'scroll-up)
+(global-set-key [mode-line mouse-1] 'scroll-up-command)
 @end example
 
   Here is the complete list of these dummy prefix keys and their
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 09e365d9d5f..2df31c88c1e 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -39,21 +39,22 @@ want to see, and how to display it.
 
 @node Scrolling
 @section Scrolling
+@cindex scrolling
 
-  If a buffer contains text that is too large to fit entirely within a
-window that is displaying the buffer, Emacs shows a contiguous portion of
-the text.  The portion shown always contains point.
+  If a window is too small to display all the text in its buffer, it
+displays only a portion of it.  @dfn{Scrolling} commands change which
+portion of the buffer is displayed.
 
-@cindex scrolling
-  @dfn{Scrolling} means moving text up or down in the window so that
-different parts of the text are visible.  Scrolling ``forward'' or
-``up'' means that text moves up, and new text appears at the bottom.
-Scrolling ``backward'' or ``down'' moves text down, and new text
-appears at the top.
+  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.
 
-  Scrolling happens automatically if you move point past the bottom or
-top of the window.  You can also scroll explicitly with these
-commands:
+  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
+occurs automatically to bring it back onscreen (@pxref{Auto
+Scrolling}).  You can also scroll explicitly with these commands:
 
 @table @kbd
 @item C-l
@@ -76,10 +77,10 @@ Scroll heuristically to bring useful information onto the screen
 
 @kindex C-l
 @findex recenter-top-bottom
-  @kbd{C-l} (@code{recenter-top-bottom}) is a basic scrolling command.
-It @dfn{recenters} the selected window, scrolling it so that the
-current screen line is exactly in the center of the window, or as
-close to the center as possible.
+  The @kbd{C-l} (@code{recenter-top-bottom}) command @dfn{recenters}
+the selected window, scrolling it so that the current screen line is
+exactly in the center of the window, or as close to the center as
+possible.
 
   Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window
 so that point is on the topmost screen line.  Typing a third @kbd{C-l}
@@ -95,7 +96,7 @@ floating-point number between 0.0 and 1.0 specifies a percentage of
 the screen space from the top.  The default, @code{(middle top
 bottom)}, is the cycling order described above.  Furthermore, if you
 change the variable @code{scroll-margin} to a non-zero value @var{n},
-Emacs always leaves @var{n} screen lines between point and the top or
+@kbd{C-l} leaves @var{n} 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
@@ -108,17 +109,16 @@ puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five
 lines from the bottom.  When given an argument, @kbd{C-l} does not
 clear the screen or cycle through different screen positions.
 
-  The more primitive command @code{recenter} behaves like
-@code{recenter-top-bottom}, but does not cycle among screen positions.
-Prior to Emacs 23, @kbd{C-l} was bound to @code{recenter}.
-
 @vindex recenter-redisplay
   If the variable @code{recenter-redisplay} has a non-@code{nil}
-value, Emacs clears and redisplays the screen each time @kbd{C-l}
-recenters the window; the special value @code{tty} (the default) says
-to do this on text-terminal frames only.  Redisplaying is useful in
-case the screen becomes garbled for any reason (@pxref{Screen
-Garbled}).
+value, each invocation of @kbd{C-l} also clears and redisplays the
+screen; the special value @code{tty} (the default) says to do this on
+text-terminal frames only.  Redisplaying is useful in case the screen
+becomes garbled for any reason (@pxref{Screen Garbled}).
+
+@findex recenter
+  The more primitive command @code{recenter} behaves like
+@code{recenter-top-bottom}, but does not cycle among screen positions.
 
 @kindex C-v
 @kindex M-v
@@ -126,16 +126,15 @@ Garbled}).
 @kindex prior
 @kindex PageDown
 @kindex PageUp
-@findex scroll-up
-@findex scroll-down
-  To read the buffer a windowful at a time, type @kbd{C-v}
-(@code{scroll-up}).  This 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 at the new top of the window.
+@findex scroll-up-command
+@findex scroll-down-command
+  The @kbd{C-v} (@code{scroll-up-command}) 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 at the new top of the window.
 
-  @kbd{M-v} (@code{scroll-down}) scrolls backward in a similar way.
+  Similarly, @kbd{M-v} (@code{scroll-down-command}) scrolls backward.
 
 @vindex next-screen-context-lines
   The variable @code{next-screen-context-lines} controls the number of
@@ -150,23 +149,39 @@ together).  @kbd{C-v} with a negative argument is like @kbd{M-v} and
 vice versa.
 
   The names of scroll commands are based on the direction that the
-text moves in the window.  Thus, the command to scroll forward is
-called @code{scroll-up} because it moves the text upward on the
-screen.  The keys @key{PageUp} and @key{PageDown} derive their names
-and customary meanings from a different convention that developed
-elsewhere; hence the strange result that @key{PageDown} runs
-@code{scroll-up}.
+text moves in the window.  For instance, @code{scroll-up-command}
+moves the text upward on the screen.  The keys @key{PageUp} and
+@key{PageDown} derive their names and customary meanings from a
+different convention that developed elsewhere; hence the strange
+result that @key{PageDown} runs @code{scroll-up-command}.
 
 @vindex scroll-preserve-screen-position
   Some users like the full-screen scroll commands to keep point at the
-same screen position.  To enable this behavior, set the variable
-@code{scroll-preserve-screen-position} to a non-@code{nil} value.
-Then, whenever a command scrolls the text around point offscreen (or
-within @code{scroll-margin} lines of the edge), Emacs moves point to
-keep it at the same vertical and horizontal position within the
-window.  This mode is convenient for browsing through a file by
-scrolling by screenfuls; if you come back to the screen where you
-started, point goes back to the line where it started.
+same screen position.  This behavior is convenient because scrolling
+back to the same screen also returns point to its original position.
+You can enable this via the variable
+@code{scroll-preserve-screen-position}.  If the value is @code{t},
+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 non-@code{nil} value, Emacs
+adjusts point this way even if the scroll command leaves point in the
+window.
+
+@vindex scroll-error-top-bottom
+  By default, @code{scroll-up-command} and @code{scroll-down-command}
+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.
+
+@vindex scroll-up
+@vindex 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
diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi
index 0a9594d3798..b894d01b9bb 100644
--- a/doc/emacs/rmail.texi
+++ b/doc/emacs/rmail.texi
@@ -100,9 +100,9 @@ frequent that it deserves to be easier.
 
 @table @kbd
 @item @key{SPC}
-Scroll forward (@code{scroll-up}).
+Scroll forward (@code{scroll-up-command}).
 @item @key{DEL}
-Scroll backward (@code{scroll-down}).
+Scroll backward (@code{scroll-down-command}).
 @item .
 Scroll to start of message (@code{rmail-beginning-of-message}).
 @item /
@@ -111,9 +111,10 @@ Scroll to end of message (@code{rmail-end-of-message}).
 
 @kindex SPC @r{(Rmail)}
 @kindex DEL @r{(Rmail)}
-  Since the most common thing to do while reading a message is to scroll
-through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
-@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
+  Since the most common thing to do while reading a message is to
+scroll through it by screenfuls, Rmail makes @key{SPC} and @key{DEL}
+do the same as @kbd{C-v} (@code{scroll-up-command}) and @kbd{M-v}
+(@code{scroll-down-command}) respectively.
 
 @kindex . @r{(Rmail)}
 @kindex / @r{(Rmail)}
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 015f9529b73..caf03291fbc 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -306,11 +306,11 @@ minibuffer.
 search (without exiting the search) by setting the customizable
 variable @code{isearch-allow-scroll} to a non-@code{nil} value.  This
 applies to using the vertical scroll-bar and to certain keyboard
-commands such as @key{prior} (@code{scroll-down}), @key{next}
-(@code{scroll-up}) and @kbd{C-l} (@code{recenter}).  You must run
-these commands via their key sequences to stay in the search---typing
-@kbd{M-x} will terminate the search.  You can give prefix arguments to
-these commands in the usual way.
+commands such as @code{scroll-down-command}, @code{scroll-up-command}
+and @code{recenter} (@pxref{Scrolling}).  You must run these commands
+via their key sequences to stay in the search---typing @kbd{M-x} will
+terminate the search.  You can give prefix arguments to these commands
+in the usual way.
 
   This feature won't let you scroll the current match out of visibility,
 however.
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
diff --git a/etc/NEWS b/etc/NEWS
index f6901e3b88f..ae2f137e1f9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -288,15 +288,19 @@ If you have code that adds something to kill-emacs-hook, you should
 consider if it is still appropriate to add it in the noninteractive case.
 
 ** Scrolling changes
-
++++
 *** New scrolling commands `scroll-up-command' and `scroll-down-command'
 (bound to C-v/[next] and M-v/[prior]) do not signal errors at top/bottom
 of buffer at first key-press (instead move to top/bottom of buffer)
-when a new variable `scroll-error-top-bottom' is non-nil.
+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.
 
++++
 *** New property `scroll-command' should be set on a command's symbol to
 define it as a scroll command affected by `scroll-preserve-screen-position'.