bug#7296: display-pixel-height not enough

["Drew Adams" <drew.adams@oracle.com>]

For some reason, it seems this message never made it to the BUGS list.  Sending
again. 

-----Original Message-----
From: Drew Adams Sent: Monday, November 01, 2010 11:36 AM
To: 'Lennart Borgman' Cc: 'YAMAMOTO Mitsuharu'; '7296@debbugs.gnu.org'

> > It's not that one or the other is better; it's that they 
> > are different.  If you change the meaning and return value
> > of an existing function then you break existing code.  If
> > you want to add an additional function that returns some
> > other value that you find more useful, that's one thing.  
> > Proposing to change the existing function is something else again.
> 
> There is no clear description of what display-pixel-height currently
> returns. So how do we know how it is currently used?

I know how I currently use it (and I pointed you to the code).  And my code has
been been used by others as well (it is included in Aquamacs, AFAIK).  It seems
to DTRT.

How did I find out what `display-pixel-height' returns?  Well, I tried it out,
for one thing.  And I read the doc string, which I found clear enough.

You cannot change the behavior of something radically just because you feel the
doc is not precise enough.  Imprecise doc is not a license to change up to down
or whole to part.

These functions have been around quite a while.  If you want something
incompatibly different then create a new function.  Do not try to turn the
existing functions upside down.

> It looks like it is difficult to get this information, but as I said
> the current return value must be documented. I suggest that we just
> change the doc string and says that it returns value for the total
> display.

I'm all for clear doc.  But in this case I don't see the difference.  If I tell
you that function `foobar' returns the diameter of its input circle, is that
different from telling you that it returns the "total" diameter?

Is the length of your bicycle different from the length of your whole bicycle?
With no qualifier I think that the entire display is understood implicitly.

> And in addition to that it would probably be good to have the
> "opposite" function too. At least I need it.

It is in the doc of your new, partial-height function that you would state that
it returns the height of only part of the (total) display.

In sum, you are looking for a different behavior from what
`display-pixel-height' provides.  For that you should be asking for a different
function - exactly as you would do if you wanted to change the return units from
pixels to lines.

This is not a doc issue IMO, and IMO it is not a problem with
`display-pixel-height'.  What you are asking for is (or should be) a new,
additional function.