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

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

[Alan Mackenzie]

Hello Emacs.

In emacs -Q, with a buffer in a window such that there is text in the
window's last line, I run

    M-: (pos-visible-in-window-p t nil t)

.  (Those parameters are in order POS, WINDOW, and PARTIALLY)

The return value is, e.g., (0 64), the X and Y coordinates of the
_beginning_ of the last line.  (On an X window, the result is (0 920).)

With PARTIALLY non-nil, and POS set to t, the function should return the
coordinates of "the last visible position in WINDOW", according to elisp
page "Window Start and End".

I would expect the "last visible position" to mean the _end_ of the last
line, not the beginning.

Which is correct?  The function or the documentation?

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Eli Zaretskii]

> Date: Sun, 27 Sep 2015 10:40:41 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> Which is correct?  The function or the documentation?

The function.  This has always worked like that.

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

[Eli Zaretskii]

> Date: Sun, 27 Sep 2015 14:06:35 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> > Date: Sun, 27 Sep 2015 10:40:41 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > 
> > Which is correct?  The function or the documentation?
> 
> The function.  This has always worked like that.

I've clarified the documentation to match what the function does in
that case.

Thanks.

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 10:21:21AM +0300, Eli Zaretskii wrote:
> > Date: Sun, 27 Sep 2015 14:06:35 +0300
> > From: Eli Zaretskii <eliz@gnu.org>
> > Cc: emacs-devel@gnu.org
> > 
> > > Date: Sun, 27 Sep 2015 10:40:41 +0000
> > > From: Alan Mackenzie <acm@muc.de>
> > > 
> > > Which is correct?  The function or the documentation?
> > 
> > The function.  This has always worked like that.

> I've clarified the documentation to match what the function does in
> that case.

> Thanks.

Thank you!

However:

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

?

-------------------------------------------------------------------------

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.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Eli Zaretskii]

> Date: Wed, 30 Sep 2015 08:56:11 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
>     "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.

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: emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

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

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

[Eli Zaretskii]

> Date: Wed, 30 Sep 2015 10:22:31 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > 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."

I already committed a change to describe that.  The doc string now
says

  If POS is t, it specifies either the first position displayed on the
  last visible screen line in WINDOW, or the end-of-buffer position,
  whichever comes first.

and similar text is in the ELisp manual.

OK?

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 04:52:24PM +0300, Eli Zaretskii wrote:
> > Date: Wed, 30 Sep 2015 10:22:31 +0000
> > Cc: emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

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

> I already committed a change to describe that.  The doc string now
> says

>   If POS is t, it specifies either the first position displayed on the
>   last visible screen line in WINDOW, or the end-of-buffer position,
>   whichever comes first.

> and similar text is in the ELisp manual.

> OK?

Very much OK!  Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Eli Zaretskii]

> Date: Wed, 30 Sep 2015 10:22:31 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: emacs-devel@gnu.org
> 
> Hello, Eli.
> 
> > > 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.

To understand it, you need to keep in mind that this function
considers only the vertical dimension; the horizontal dimensions you
get are the side effect.  In particular when POS is t, the function
tries to get to the largest Y coordinate visible in the window; once
it gets there, it just reports where that is.