bug#32863: Unsatisfactory "definition" of "vertical scroll position" in Emacs lisp manual and doc string of window-vscroll

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 28 Sep 2018 15:28:32 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> In the Emacs-26.1 Emacs Lisp manual, on page "Vertical Scrolling" there
> is an ostensible definition for "vertical scroll position".
> 
> This "definition" says it "is a number, never less than zero.  It
> specifies how far to raise the contents of the window."
> 
> What should be doing this raising?

The call to set-window-vscroll does that.

> When might it do this?

The automatic calls to set-window-vscroll happen when a screen line is
too tall to be completely visible in a window, and Emacs is asked to
scroll.  Try scrolling or vertical motion commands when the window
displays a tall image.

> For what purpose might the contents of the window be raised?

To show the portion of the current line that is not currently visible.

> I find this "definition" totally obscure.  I can not make sense of it at
> all.  Without understanding what "vertical scroll position" means, the
> entire manual page is meaningless.

Do you understand it now?

> I came to this manual page through not understanding the doc string for
> the function window-vscroll.  This says just "Return the amount by which
> WINDOW is scrolled vertically.".
> 
> _Is_ scrolled vertically.  What on earth does that mean?

See above.

> What is the zero point from which this scrolling is measured?

The zero point is when the top pixel of the window's first screen line
is visible.

> Does this "is" refer to the current visible scrolling, or the
> intended scrolling after the next redisplay?

Since redisplay runs when Emacs is idle, the answer should be obvious,
right?

> This doc string needs clarification.

I'm all ears.