From: Chong Yidong Date: Sat, 1 Oct 2011 21:54:33 +0000 (-0400) Subject: Document some Emacs 24 scrolling changes. X-Git-Tag: emacs-pretest-24.0.91~229 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=550f41cdba7ebc49996d8fd17eacff86a2456f35;p=emacs.git 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. --- 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 + + * 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 * 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 + + * 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 * 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'.