Clarify documentation of fractional vertical scrolling and some doc strings

* doc/lispref/windows.texi (vertical scrolling): Clarify the meaning of
vertical scrolling by referring to tall screen lines, images, and the display
action.  Clarify an ambiguous English tense.

* src/window.c (window-vscroll, set-window-vscroll): Amend doc strings to
refer to display.
This commit is contained in:
Alan Mackenzie 2018-10-15 19:04:05 +00:00
parent b20c51d62f
commit 73babba26a
2 changed files with 15 additions and 9 deletions

View file

@ -4200,18 +4200,20 @@ point at the middle, top, and bottom of the window.
@cindex vertical scroll position @cindex vertical scroll position
@dfn{Vertical fractional scrolling} means shifting text in a window @dfn{Vertical fractional scrolling} means shifting text in a window
up or down by a specified multiple or fraction of a line. Each window up or down by a specified multiple or fraction of a line. Emacs uses
has a @dfn{vertical scroll position}, which is a number, never less than it, for example, on images and screen lines which are taller than the
zero. It specifies how far to raise the contents of the window. window. Each window has a @dfn{vertical scroll position}, which is a
Raising the window contents generally makes all or part of some lines number, never less than zero. It specifies how far to raise the
disappear off the top, and all or part of some other lines appear at the contents of the window when displaying them. Raising the window
bottom. The usual value is zero. contents generally makes all or part of some lines disappear off the
top, and all or part of some other lines appear at the bottom. The
usual value is zero.
The vertical scroll position is measured in units of the normal line The vertical scroll position is measured in units of the normal line
height, which is the height of the default font. Thus, if the value is height, which is the height of the default font. Thus, if the value is
.5, that means the window contents are scrolled up half the normal line .5, that means the window contents will be scrolled up half the normal
height. If it is 3.3, that means the window contents are scrolled up line height. If it is 3.3, that means the window contents are scrolled
somewhat over three times the normal line height. up somewhat over three times the normal line height.
What fraction of a line the vertical scrolling covers, or how many What fraction of a line the vertical scrolling covers, or how many
lines, depends on what the lines contain. A value of .5 could scroll a lines, depends on what the lines contain. A value of .5 could scroll a

View file

@ -7322,6 +7322,8 @@ value. */)
DEFUN ("window-vscroll", Fwindow_vscroll, Swindow_vscroll, 0, 2, 0, DEFUN ("window-vscroll", Fwindow_vscroll, Swindow_vscroll, 0, 2, 0,
doc: /* Return the amount by which WINDOW is scrolled vertically. doc: /* Return the amount by which WINDOW is scrolled vertically.
This takes effect when displaying tall lines or images.
If WINDOW is omitted or nil, it defaults to the selected window. If WINDOW is omitted or nil, it defaults to the selected window.
Normally, value is a multiple of the canonical character height of WINDOW; Normally, value is a multiple of the canonical character height of WINDOW;
optional second arg PIXELS-P means value is measured in pixels. */) optional second arg PIXELS-P means value is measured in pixels. */)
@ -7344,6 +7346,8 @@ optional second arg PIXELS-P means value is measured in pixels. */)
DEFUN ("set-window-vscroll", Fset_window_vscroll, Sset_window_vscroll, DEFUN ("set-window-vscroll", Fset_window_vscroll, Sset_window_vscroll,
2, 3, 0, 2, 3, 0,
doc: /* Set amount by which WINDOW should be scrolled vertically to VSCROLL. doc: /* Set amount by which WINDOW should be scrolled vertically to VSCROLL.
This takes effect when displaying tall lines or images.
WINDOW nil means use the selected window. Normally, VSCROLL is a WINDOW nil means use the selected window. Normally, VSCROLL is a
non-negative multiple of the canonical character height of WINDOW; non-negative multiple of the canonical character height of WINDOW;
optional third arg PIXELS-P non-nil means that VSCROLL is in pixels. optional third arg PIXELS-P non-nil means that VSCROLL is in pixels.