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

From: IRIE Shinsuke <[email-masked]>
Date: Sat, 31 Jul 2010 06:18:54 +0900

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