Re: (pos-visible-in-window-p t nil t) returns wrong position/is suboptimally documented.

[Alan Mackenzie]

Hello, Eli.

On Wed, Sep 30, 2015 at 12:32:39PM +0300, Eli Zaretskii wrote:
> > Date: Wed, 30 Sep 2015 08:56:11 +0000
> > Cc: address@hidden
> > From: Alan Mackenzie <address@hidden>

> >     "If POSITION is `t', that means to check the first visible position
> >      of the last visible screen line in WINDOW."

> > doesn't seem quite right.  If the text in the window is scrolled such
> > that EOB is in the middle of the window, POSITION t gives the
> > coordinates of the last line containing text, not the last visible
> > screen line.

> You mean, it isn't clear that "screen line" means line with text?  I
> could add "with text" if that's the issue (I thought it was obvious).

> > How about something like:

> >     "If POSITION is `t', that means to check the first visible position
> >     of the last visible screen line in WINDOW which is at or above the
> >     end of the window's buffer."

> Too complex, IMO.  It took me 4 readings to understand what you mean,
> and that's _after_ I've read the description of the situation you were
> taking about.

> > However 2: I think there's a bug in the functionality, too.  If there is
> >   o - a text buffer
> >   o - with no terminating LF on its last line, and
> >   o - that last line is above the window's last line
> > then (pos-visible-in-window t nil t) returns the coordinates of the last
> > lines's EOL.  This is the case in both a Linux virtual terminal and an X
> > windows session.

> It's not a bug.  If you think it's important to mention this marginal
> use case, I can add that, too.

OK, it's deliberate.  It's a touch puzzling, though.  I should grep the
elisp sources to find out what it's for.  I do think it should be
mentioned in the doc, even if only for preventing somebody like me
raising a spurious bug report in the future.

How about expressing the piece of documentation as:

    "If POSITION is `t', that means to check the position the first
    visible position of the last visible screen line with text in
    WINDOW; but if the end of the window's buffer is on the window, this
    position is used instead."

?  It's a bit convoluted, but then again, the function isn't simple
either.

-- 
Alan Mackenzie (Nuremberg, Germany).