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

[Alan Mackenzie <acm@muc.de>]

Hello, Eli.

Thanks for such a rapid review!

On Mon, Oct 15, 2018 at 18:32:05 +0300, Eli Zaretskii wrote:
> > Date: Mon, 15 Oct 2018 11:48:03 +0000
> > Cc: 32863@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > I propose to amend windows.texi, and two doc strings in windows.c in the
> > emacs-26 branch as follows.  I think that these amendments would have
> > prevented my initial puzzlement.  Any comments?

> The changes to doc strings are fine (but please use "display" instead
> of "redisplay", as the latter is a technical term not necessarily
> accurate in this context).

Done.

> As for the changes to windows.texi, I admit that I don't really
> understand how such insignificant changes could prevent your
> puzzlement.  Are you sure it isn't the result of reading my
> explanations, which caused the text to "talk" to you more clearly?

I've thought of that, and been as careful as I can be to reconstruct my
mental state at the time I raised the bug.  I think my emphasis on "when
displaying it" is sufficient to establish a context for understanding.

> >     @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 it
> > +on images and text rows which are taller than the window.  Each window

> Here you added a sentence that tells when is this feature used.  (Btw,
> nothing prevents Emacs from using it even with lines that are not
> taller than the window, and it even does so sometimes.  So this is
> just an example, and I'd suggest to say that.  Also, please don't use
> "rows" in the manual: that is the terminology of xdisp.c, but Lisp
> programmers are unfamiliar with it.  I prefer to use "screen lines".)

Done (both).

> >  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.
> > +zero.  It specifies how far to raise the contents of the window when
> > +redisplaying it.  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.

> Here you just added "when redisplaying it".  If this is such a
> crucially important detail, I'm all for it (but again, please say
> "displaying").  However, I wonder whether it really is all that
> stood between you and the eureka.

I believe it is.

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

> And here, you just replaced "are scrolled" with "will be scrolled"
> (only once out of 2 instances).  Again, one wonders whether this is
> all that you missed to see the light.

This attempts to fix a fundamental ambiguity in the use of the words "is"
and "are" with a past participle.  For example, compare these two sentences:

1. Emacs 26.1 is released.
2. Emacs is released every few months.

In the first, "is released" refers to a one-time event in the past.  In
the second, it refers to a habitual action, still happening.  That same
ambiguity with "are" in "...means the window contents are scrolled up"
confused me.  The "will be" helps eliminate the interpretation "have
ALREADY been scrolled up", the 1. above.

> I'm not saying I object to these changes -- I don't -- but I'm a bit
> surprised that such minor changes could have such a profound effect on
> clarity.

When I first read the page I was totally lacking in context.  I think
I've added enough context to have helped me, were I coming to it again
for the first time.

OK, amended (final?) version:


diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 265067146d..960573d865 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4200,18 +4200,20 @@ Vertical Scrolling
 @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

> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).