[Emacs-diffs] /srv/bzr/emacs/trunk r105977: Document some Emacs 24 scrolling changes.

[Chong Yidong]

------------------------------------------------------------
revno: 105977
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-10-01 17:54:33 -0400
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/basic.texi
  doc/emacs/custom.texi
  doc/emacs/display.texi
  doc/emacs/rmail.texi
  doc/emacs/search.texi
  doc/lispref/ChangeLog
  doc/lispref/windows.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-09-30 18:17:34 +0000
+++ b/doc/emacs/ChangeLog       2011-10-01 21:54:33 +0000
@@ -1,3 +1,14 @@
+2011-10-01  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * commands.texi (Keys): Whitespace fix.  (Bug#9635)

=== modified file 'doc/emacs/basic.texi'
--- a/doc/emacs/basic.texi      2011-09-04 16:53:44 +0000
+++ b/doc/emacs/basic.texi      2011-10-01 21:54:33 +0000
@@ -219,21 +219,19 @@
 @xref{Arguments}, for more information on numeric address@hidden
 @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
address@hidden key (sometimes labelled @key{next}), it does the same
-thing as @key{C-v}.  Scrolling commands are described further in
address@hidden
+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
address@hidden
+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.

=== modified file 'doc/emacs/custom.texi'
--- a/doc/emacs/custom.texi     2011-08-26 15:48:19 +0000
+++ b/doc/emacs/custom.texi     2011-10-01 21:54:33 +0000
@@ -1854,10 +1854,10 @@
 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

=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi    2011-08-28 21:15:20 +0000
+++ b/doc/emacs/display.texi    2011-10-01 21:54:33 +0000
@@ -39,21 +39,22 @@
 
 @node Scrolling
 @section 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.
-
 @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 happens automatically if you move point past the bottom or
-top of the window.  You can also scroll explicitly with these
-commands:
+
+  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.
+
+  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.
+
+  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 @@
 
 @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 @@
 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
address@hidden 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 @@
 lines from the bottom.  When given an argument, @kbd{C-l} does not
 clear the screen or cycle through different screen positions.
 
address@hidden recenter-redisplay
+  If the variable @code{recenter-redisplay} has a address@hidden
+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}).
+
address@hidden recenter
   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}.
-
address@hidden recenter-redisplay
-  If the variable @code{recenter-redisplay} has a address@hidden
-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}).
 
 @kindex C-v
 @kindex M-v
@@ -126,16 +126,15 @@
 @kindex prior
 @kindex PageDown
 @kindex PageUp
address@hidden scroll-up
address@hidden 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.
address@hidden scroll-up-command
address@hidden 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 @@
 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
address@hidden
+text moves in the window.  For instance, @code{scroll-up-command}
+moves the text upward on the screen.  The keys @key{PageUp} and
address@hidden 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
address@hidden to a address@hidden 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
address@hidden  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 address@hidden value, Emacs
+adjusts point this way even if the scroll command leaves point in the
+window.
+
address@hidden 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
address@hidden 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-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

=== modified file 'doc/emacs/rmail.texi'
--- a/doc/emacs/rmail.texi      2011-08-25 16:30:46 +0000
+++ b/doc/emacs/rmail.texi      2011-10-01 21:54:33 +0000
@@ -100,9 +100,9 @@
 
 @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 @@
 
 @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
address@hidden (@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)}

=== modified file 'doc/emacs/search.texi'
--- a/doc/emacs/search.texi     2011-07-10 03:11:47 +0000
+++ b/doc/emacs/search.texi     2011-10-01 21:54:33 +0000
@@ -306,11 +306,11 @@
 search (without exiting the search) by setting the customizable
 variable @code{isearch-allow-scroll} to a address@hidden 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
address@hidden 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.

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-09-28 00:59:28 +0000
+++ b/doc/lispref/ChangeLog     2011-10-01 21:54:33 +0000
@@ -1,3 +1,9 @@
+2011-10-01  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * windows.texi (Splitting Windows): Fix typos.

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2011-09-28 00:59:28 +0000
+++ b/doc/lispref/windows.texi  2011-10-01 21:54:33 +0000
@@ -3100,67 +3100,77 @@
 @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
address@hidden) 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
address@hidden 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
address@hidden lines.  If @var{count} is negative, scrolling is actually
-downward.
-
-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).
-
address@hidden returns @code{nil}, unless it gets an error
-because it can't scroll any further.
+This function scrolls forward by @var{count} lines in the selected
+window.
+
+If @var{count} is negative, it scrolls backward instead.  If
address@hidden is @code{nil} (or omitted), the distance scrolled is
address@hidden lines less than the height of the
+window's text area.
+
+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
address@hidden lines.  If @var{count} is negative, scrolling is actually
-upward.
-
-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).
-
address@hidden returns @code{nil}, unless it gets an error because
-it can't scroll any further.
+This function scrolls backward by @var{count} lines in the selected
+window.
+
+If @var{count} is negative, it scrolls forward instead.  If
address@hidden is omitted or @code{nil}, the distance scrolled is
address@hidden lines less than the height of the
+window's text area.
+
+If the selected window cannot be scrolled any further, this function
+signals an error.  Otherwise, it returns @code{nil}.
address@hidden deffn
+
address@hidden 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
address@hidden is @code{t}, it tries to move to the
+end of the buffer instead.  If point is already there, it signals an
+error.
address@hidden deffn
+
address@hidden 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
address@hidden 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 @@
 @samp{Beginning of buffer}.
 @end deffn
 
address@hidden Emacs 19 feature
 @defvar other-window-scroll-buffer
 If this variable is address@hidden, it tells @code{scroll-other-window}
 which buffer's window to scroll.
@@ -3245,13 +3254,18 @@
 does not work with @code{scroll-margin}.  The default value is zero.
 @end defopt
 
address@hidden @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 it is address@hidden and not @code{t}, then the scrolling functions
-always preserve the vertical position of point, 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 address@hidden 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.
+
+This option affects all scroll commands that have a address@hidden
address@hidden symbol property.
 @end defopt
 
 @defopt next-screen-context-lines
@@ -3262,6 +3276,16 @@
 @code{2}.
 @end defopt
 
address@hidden 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.
address@hidden defopt
+
 @deffn Command recenter &optional count
 @cindex centering point
 This function scrolls the text in the selected window so that point is

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-09-26 15:05:52 +0000
+++ b/etc/NEWS  2011-10-01 21:54:33 +0000
@@ -288,15 +288,19 @@
 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'.