[Emacs-diffs] emacs-26 73babba: Clarify documentation of fractional vertical scrolling and some doc strings

[Alan Mackenzie]

branch: emacs-26
commit 73babba26aa714c34aa8d9473ba5b55ce110a215
Author: Alan Mackenzie <address@hidden>
Commit: Alan Mackenzie <address@hidden>

    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.
---
 doc/lispref/windows.texi | 20 +++++++++++---------
 src/window.c             |  4 ++++
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 2650671..960573d 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4200,18 +4200,20 @@ point at the middle, top, and bottom of the window.
 @cindex vertical scroll position
 
    @dfn{Vertical fractional scrolling} means shifting text in a window
-up or down by a specified multiple or fraction of a line.  Each window
-has a @dfn{vertical scroll position}, which is a number, never less than
-zero.  It specifies how far to raise the contents of the window.
-Raising the window 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.
+up or down by a specified multiple or fraction of a line.  Emacs uses
+it, for example, on images and screen lines which are taller than the
+window.  Each window has a @dfn{vertical scroll position}, which is a
+number, never less than zero.  It specifies how far to raise the
+contents of the window when displaying them.  Raising the window
+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
 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
-height.  If it is 3.3, that means the window contents are scrolled up
-somewhat over three times the normal line height.
+.5, that means the window contents will be scrolled up half the normal
+line height.  If it is 3.3, that means the window contents are scrolled
+up somewhat over three times the normal line height.
 
    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
diff --git a/src/window.c b/src/window.c
index 409b01f..9026a7b 100644
--- a/src/window.c
+++ b/src/window.c
@@ -7322,6 +7322,8 @@ value.  */)
 
 DEFUN ("window-vscroll", Fwindow_vscroll, Swindow_vscroll, 0, 2, 0,
        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.
 Normally, value is a multiple of the canonical character height of WINDOW;
 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,
        2, 3, 0,
        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
 non-negative multiple of the canonical character height of WINDOW;
 optional third arg PIXELS-P non-nil means that VSCROLL is in pixels.