+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)
@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.
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
@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
@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}
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
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
@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
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
@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 /
@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)}
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.
+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.
@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
@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.
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
@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
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'.
projects / emacs.git / commitdiff