bug#6763: 24.0.50.1; Doc string of `window-line-height'

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[IRIE Shinsuke]

Hi,

Doc string of `window-line-height' says:

  Return nil if window display is not up-to-date.  In that case, use
  `pos-visible-in-window-p' to obtain the information.

However, using `pos-visible-in-window-p' seems ineffectual.
In fact, the following expression often returns nil:

  (progn (pos-visible-in-window-p)
         (window-line-height))

So I use `redisplay' instead of `pos-visible-in-window-p' as:

  (or (window-line-height)
      (and (redisplay t)
           (window-line-height)))

and it correctly works.

Please correct the doc string.

IRIE Shinsuke

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[Eli Zaretskii]

> Date: Fri, 30 Jul 2010 22:55:17 +0900
> From: IRIE Shinsuke <irieshinsuke@yahoo.co.jp>
> Cc: 
> 
> Doc string of `window-line-height' says:
> 
>   Return nil if window display is not up-to-date.  In that case, use
>   `pos-visible-in-window-p' to obtain the information.
> 
> However, using `pos-visible-in-window-p' seems ineffectual.
> In fact, the following expression often returns nil:
> 
>   (progn (pos-visible-in-window-p)
>          (window-line-height))

I think you misunderstood the doc string.  It means that instead of

  (window-line-height)

you should use

  (pos-visible-in-window-p)

Using progn doesn't cut it, since it always returns the value of the
last form.  What you mean is probably this:

  (or (window-line-height)
      (pos-visible-in-window-p))

If this doesn't work for you, please show a precise recipe, starting
from "emacs -Q", to reproduce the situation where
pos-visible-in-window-p returns nil when it shouldn't.

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[IRIE Shinsuke]

> I think you misunderstood the doc string.  It means that instead of
> 
>   (window-line-height)
> 
> you should use
> 
>   (pos-visible-in-window-p)

`pos-visible-in-window-p' doesn't return a line height, so we can never
use it as a substitute of `window-line-height'.

> Using progn doesn't cut it, since it always returns the value of the
> last form.  What you mean is probably this:
> 
>   (or (window-line-height)
>       (pos-visible-in-window-p))

Why? If `window-line-height' returns nil, the result of this expression
becomes t or nil. What I want to obtain is a line height, not a boolean.

I guess the doc string means "`pos-visible-in-window-p' updates the
matrices' information, so call it before `window-line-height'."
In that case, however, it seems redisplaying is necessary for getting
the useful result. As I wrote in the previous mail, the following
expression properly returns the line height.

  (progn (redisplay t)
         (window-line-height))

I think `pos-visible-in-window-p' in the doc string should be changed
to `redisplay'.

IRIE Shinsuke

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[Eli Zaretskii]

> Date: Sat, 31 Jul 2010 03:12:09 +0900
> From: IRIE Shinsuke <irieshinsuke@yahoo.co.jp>
> Cc: 6763@debbugs.gnu.org
> 
> > I think you misunderstood the doc string.  It means that instead of
> > 
> >   (window-line-height)
> > 
> > you should use
> > 
> >   (pos-visible-in-window-p)
> 
> `pos-visible-in-window-p' doesn't return a line height, so we can never
> use it as a substitute of `window-line-height'.

window-line-height doesn't return the line height, either.  It returns
a list of 4 values.  pos-visible-in-window-p can also return a similar
list, see its doc string.

> >   (or (window-line-height)
> >       (pos-visible-in-window-p))
> 
> Why? If `window-line-height' returns nil, the result of this expression
> becomes t or nil.

No, `or' returns the value of the first expression whose value is
non-nil.  It doesn't necessarily return a boolean.  See its doc
string.

> I guess the doc string means "`pos-visible-in-window-p' updates the
> matrices' information, so call it before `window-line-height'."

It doesn't update the matrices, it just works in a way that doesn't
need the glyph matrices to be up-to-date.  And no, calling
pos-visible-in-window-p before window-line-height will not help,
because the glyph matrices used by window-line-height are still not up
to date after a call to pos-visible-in-window-p.

> In that case, however, it seems redisplaying is necessary for getting
> the useful result. As I wrote in the previous mail, the following
> expression properly returns the line height.
> 
>   (progn (redisplay t)
>          (window-line-height))

Yes, but the call to `redisplay' is quite expensive, so this is
inappropriate in many use-cases.

> I think `pos-visible-in-window-p' in the doc string should be changed
> to `redisplay'.

Sorry, I disagree.  I think the doc string is generally correct, it
just might need an example to make clear what it means.

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[IRIE Shinsuke]

> > > I think you misunderstood the doc string.  It means that instead of
> > > 
> > >   (window-line-height)
> > > 
> > > you should use
> > > 
> > >   (pos-visible-in-window-p)
> > 
> > `pos-visible-in-window-p' doesn't return a line height, so we can never
> > use it as a substitute of `window-line-height'.
> 
> window-line-height doesn't return the line height, either.  It returns
> a list of 4 values.  pos-visible-in-window-p can also return a similar
> list, see its doc string.

Of course I've well known that both of them can return a list, but I
also know these lists contain the considerably different information.

  (window-line-height)                => (HEIGHT VPOS YPOS OFFBOT)

  (pos-visible-in-window-p nil nil t) => (X Y [RTOP RBOT ROWH VPOS])

If (window-line-height) is non-nil, we can obtain the number of pixels
of line height as:

  (car (window-line-height))

However, the latter has normally only two elements X and Y unless
point is in the bottom row, and never includes the line height. ROWH
is the height of displayed part of the bottom row, not a line height.
How can we obtain the line height from such a list???

> > >   (or (window-line-height)
> > >       (pos-visible-in-window-p))
> > 
> > Why? If `window-line-height' returns nil, the result of this expression
> > becomes t or nil.
> 
> No, `or' returns the value of the first expression whose value is
> non-nil.  It doesn't necessarily return a boolean.  See its doc
> string.

`pos-visible-in-window-p' with no args returns t or nil, so this
expression returns a boolean if (window-line-height) is nil.
Since `pos-visible-in-window-p' can't be the substitute, such an
expression merely causes a meaningless result.

> Sorry, I disagree.  I think the doc string is generally correct, it
> just might need an example to make clear what it means.

Yeah, even if the doc string is correct, it's quite unclear and
useless, unfortunately. As Drew reported a similar issue in #3602,
no one can resolve the problem by reading it.

IRIE Shinsuke

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[Lars Magne Ingebrigtsen]

IRIE Shinsuke <irieshinsuke@yahoo.co.jp> writes:

> `pos-visible-in-window-p' with no args returns t or nil, so this
> expression returns a boolean if (window-line-height) is nil.
> Since `pos-visible-in-window-p' can't be the substitute, such an
> expression merely causes a meaningless result.

Do you have a test case that shows this bug?

The doc of `pos-visible-in-window-p' says:

---
If POS is visible, return t if PARTIALLY is nil; if PARTIALLY is non-nil,
return value is a list of 2 or 6 elements (X Y [RTOP RBOT ROWH VPOS]),
where X and Y are the pixel coordinates relative to the top left corner
of the window.  The remaining elements are omitted if the character after
POS is fully visible; otherwise, RTOP and RBOT are the number of pixels
off-window at the top and bottom of the row, ROWH is the height of the
display row, and VPOS is the row number (0-based) containing POS.
---

ROWH should be what you're looking for, otherwise?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#6763: 24.0.50.1; Doc string of `window-line-height'

[Lars Magne Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> ROWH should be what you're looking for, otherwise?

No further response was made to this in three weeks, so I'm closing the
report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/