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.