mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-04-18 03:51:48 -07:00
Code Issues Projects Releases Wiki Activity

Document some Emacs 24 scrolling changes.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2011-10-01 17:54:33 -04:00
parent ce3cefcca3
commit 550f41cdba
9 changed files with 185 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

11
doc/emacs/ChangeLog
View file

@ -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)

16
doc/emacs/basic.texi
View file

@ -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.

4
doc/emacs/custom.texi
View file

@ -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

115
doc/emacs/display.texi
View file

@ -39,21 +39,22 @@ want to see, and how to display it.
@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 @@ 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

11
doc/emacs/rmail.texi
View file

@ -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)}

10
doc/emacs/search.texi
View file

@ -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.

6
doc/lispref/ChangeLog
View file

@ -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.

130
doc/lispref/windows.texi
View file

@ -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.
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}).
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.
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.
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.
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}.
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 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}).
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 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 @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.
@code{scroll-down} 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-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
@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 it is non-@code{nil} and not @code{t}, then the scrolling functions
always preserve the vertical position of point, if possible.
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.
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

8
etc/NEWS
View file

@ -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'.