Code cleanup -- inconsistent "width" and "height" etc.

Code cleanup -- inconsistent "width" and "height" etc.

[Kim F. Storm]

Looking through the C code, the words width and height are not used
consistently.  Sometimes they are in columns/lines (canonical units),
and sometimes they are in pixels.

Similar for top/left specs (they are in pixels for a frame and
in canonical units for a window).

Some variables/macros like FRAME_SCROLL_BAR_COLS and
FRAME_SCROLL_BAR_WIDTH are pretty confusing, as they are both measured
in columns, but the first gives the "configured width" unconditionally
while the second may return zero if scroll bars are not shown, and
otherwise equals FRAME_SCROLL_BAR_COLS...

And things like FRAME_WIDTH and FRAME_WINDOW_WIDTH are also confusing.
Both are measured in columns, but the former does not include the
width of scroll bars and fringes.

Compare this to "WINDOW_DISPLAY_PIXEL_WIDTH" which is another way of
naming a macro which does not include scroll bars or fringes (thus
implicating that a macro named WINDOW_PIXEL_WIDTH would return the
total width of the window).


I would like to fix such discrepancies as follows:

Things measured in columns/lines are named as _CANON_WIDTH and
_CANON_HEIGHT resp., while things measured in pixels are named as
_PIXEL_WIDTH and _PIXEL_HEIGHT resp.

To differentiate between macros which return a value unconditionally,
and macros which return the value only if some condition, I propose
to name them as e.g. FRAME_CONFIG_SCROLL_BAR_CANON_WIDTH and
FRAME_ACTUAL_SCROLL_BAR_CANON_WIDTH.

For things which differs by including or not including e.g. scroll
bars and fringes I propose using e.g. FRAME_TEXT_CANON_WIDTH (or
FRAME_DISPLAY_CANON_WIDTH) and FRAME_TOTAL_CANON_WIDTH.


It is a tedious work to clean this up, but the current state of the
source code is pretty messy, and cleaning it up would make an
important step (I think) towards lifting some of the restrictions we
currently have on measuring everything in columns and lines (since it
makes the code clearer to read, and thus easier to change correctly).

DWYT?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Kenichi Handa]

In article <5xhe97dsr3.fsf@kfs2.cua.dk>, storm@cua.dk (Kim F. Storm) writes:
> I would like to fix such discrepancies as follows:

> Things measured in columns/lines are named as _CANON_WIDTH and
> _CANON_HEIGHT resp., while things measured in pixels are named as
> _PIXEL_WIDTH and _PIXEL_HEIGHT resp.

How about _WIDTH vs _PIXEL_WIDTH instead of _CANON_WIDTH vs
_PIXEL_WIDTH?  Doesn't it make the required change smaller?
Lisp APIs have that convention (e.g. frame-width vs
frame-pixel-width).
---
Ken'ichi HANDA
handa@m17n.org

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Miles Bader]

storm@cua.dk (Kim F. Storm) writes:
> Things measured in columns/lines are named as _CANON_WIDTH and
> _CANON_HEIGHT resp., while things measured in pixels are named as
> _PIXEL_WIDTH and _PIXEL_HEIGHT resp.

`_CANON_WIDTH' sounds annoyingly redundant; if that's the canonical
representation, then just use `_WIDTH,' and save additional adjectives
for exceptional cases.

Adding unnecessary verbosity simply makes the code more tedious (and
thus harder) to read.

[For the same reason, such adjectives _shouldn't_ be used in cases where
only one representation is possible by definition; e.g., the width of a
character in a font is obviously in pixels, so adding `_pixel' would be
unnecessary and harmful.]

-Miles
-- 
Is it true that nothing can be known?  If so how do we know this?  -Woody Allen

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Kim F. Storm]

Miles Bader <miles@lsi.nec.co.jp> writes:

> storm@cua.dk (Kim F. Storm) writes:
> > Things measured in columns/lines are named as _CANON_WIDTH and
> > _CANON_HEIGHT resp., while things measured in pixels are named as
> > _PIXEL_WIDTH and _PIXEL_HEIGHT resp.
> 
> `_CANON_WIDTH' sounds annoyingly redundant; if that's the canonical
> representation, then just use `_WIDTH,' and save additional adjectives
> for exceptional cases.

Alternatively, we could use *_COLS in general as a short precise name
when the width is measured in columns (the canonical X unit).
Similarly, we could use *_LINES for heights measured in lines (the
canonical Y unit).

If we do that consistently, we could simply use *_WIDTH and *_HEIGHT to
mean pixel width and height.

For example, we would use FRAME_COLS and FRAME_LINES rather than the
current FRAME_WIDTH and FRAME_HEIGHT.

And, if necessary, FRAME_WIDTH and FRAME_HEIGHT would now be measured
in pixels; they could be defined as

#define FRAME_WIDTH(f) (FRAME_COLS (f) * FRAME_CANON_X_UNIT (f))
#define FRAME_HEIGHT(f) (FRAME_LINES (f) * FRAME_CANON_Y_UNIT (f))


I like this -- it is simple (names are still short) and precise!

WDYT?

> 
> Adding unnecessary verbosity simply makes the code more tedious (and
> thus harder) to read.

Maybe, but it definitely cannot be harder to _understand_ than the
current code that uses all those inconsistent names.

> 
> [For the same reason, such adjectives _shouldn't_ be used in cases where
> only one representation is possible by definition; e.g., the width of a
> character in a font is obviously in pixels, so adding `_pixel' would be
> unnecessary and harmful.]

Actually, with the above proposal, FONT_WIDTH and FONT_HEIGHT
(measured in pixels) would be consistent with the new naming rules.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Kenichi Handa]

In article <5xptnuihqd.fsf@kfs2.cua.dk>, storm@cua.dk (Kim F. Storm) writes:
> Alternatively, we could use *_COLS in general as a short precise name
> when the width is measured in columns (the canonical X unit).
> Similarly, we could use *_LINES for heights measured in lines (the
> canonical Y unit).

> If we do that consistently, we could simply use *_WIDTH and *_HEIGHT to
> mean pixel width and height.

But, as I wrote, Lisp APIs are already using
...-width/...-height for columns and lines.  Even if we
implement pixel-base APIs in the future, we can't change the
current ones, then we'll use ...-pixel-width...-pixel-height
for the new APIs.  In that case, having a different
convention in C code is not good.

---
Ken'ichi HANDA
handa@m17n.org

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Kim F. Storm]

Kenichi Handa <handa@m17n.org> writes:

> In article <5xptnuihqd.fsf@kfs2.cua.dk>, storm@cua.dk (Kim F. Storm) writes:
> > Alternatively, we could use *_COLS in general as a short precise name
> > when the width is measured in columns (the canonical X unit).
> > Similarly, we could use *_LINES for heights measured in lines (the
> > canonical Y unit).
> 
> > If we do that consistently, we could simply use *_WIDTH and *_HEIGHT to
> > mean pixel width and height.
> 
> But, as I wrote, Lisp APIs are already using
> ...-width/...-height for columns and lines.  Even if we
> implement pixel-base APIs in the future, we can't change the
> current ones, then we'll use ...-pixel-width...-pixel-height
> for the new APIs.  In that case, having a different
> convention in C code is not good.

So there is no hope of cleaning up the current mess ?

How can we ever make progress towards removing the column/lines
limitation on frame and window dimensions if we cannot find
a way to clean up the current naming mess?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Miles Bader]

On Fri, Apr 11, 2003 at 02:08:32AM +0200, Kim F. Storm wrote:
> So there is no hope of cleaning up the current mess ?
> 
> How can we ever make progress towards removing the column/lines
> limitation on frame and window dimensions if we cannot find
> a way to clean up the current naming mess?

I really don't think it's that bad.  I've spent a lot of time trying to
understand the redislay parts of the code, and though that code is certainly
very confusing in many places, had absolutely no problem with the particular
issue you cite.  [I suspect that in most cases, it's clear enough from
context what units are being used.]

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Kenichi Handa]

In article <5xbrzddhfj.fsf@kfs2.cua.dk>, storm@cua.dk (Kim F. Storm) writes:
>>  But, as I wrote, Lisp APIs are already using
>>  ...-width/...-height for columns and lines.  Even if we
>>  implement pixel-base APIs in the future, we can't change the
>>  current ones, then we'll use ...-pixel-width...-pixel-height
>>  for the new APIs.  In that case, having a different
>>  convention in C code is not good.

> So there is no hope of cleaning up the current mess ?

> How can we ever make progress towards removing the column/lines
> limitation on frame and window dimensions if we cannot find
> a way to clean up the current naming mess?

Now we have two problems as to the naming; inconsistency and
unclearness.  I think fixing the former is more important
than fixing the latter.

Always using _WIDTH (or -width) for columns and _PIXEL_WIDTH
(or -pixel-width) for pixels is to fix inconsistency, but
using _COLS or _CANON_WIDTH for columns is to fix
unclearness.

You wrote:
> To differentiate between macros which return a value unconditionally,
> and macros which return the value only if some condition, I propose
> to name them as e.g. FRAME_CONFIG_SCROLL_BAR_CANON_WIDTH and
> FRAME_ACTUAL_SCROLL_BAR_CANON_WIDTH.

It seems that this CONFIG vs ACTUAL itself is a good idea
for fixing unclearness without introducing inconsistency.

> For things which differs by including or not including e.g. scroll
> bars and fringes I propose using e.g. FRAME_TEXT_CANON_WIDTH (or
> FRAME_DISPLAY_CANON_WIDTH) and FRAME_TOTAL_CANON_WIDTH.

This TEXT vs TOTAL is also a good idea.

By the way, I've just found this inconsistency.
frame-width -> not including scroll bars and fringes
frame-pixel-width -> including them

Perhaps, we should make them obsolete aliases of
frame-text-width and frame-total-pixel-width respectively.

---
Ken'ichi HANDA
handa@m17n.org

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Richard Stallman]

    By the way, I've just found this inconsistency.
    frame-width -> not including scroll bars and fringes
    frame-pixel-width -> including them

If you look at this very strictly, this may seem inconsistent, but I
think it is logical.  The scroll bars and fringes are not columns, so
a width measured in columns naturally won't include them.

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Kenichi Handa]

In article <E1948DM-0007Rx-00@fencepost.gnu.org>, Richard Stallman <rms@gnu.org> writes:
>     By the way, I've just found this inconsistency.
>     frame-width -> not including scroll bars and fringes
>     frame-pixel-width -> including them

> If you look at this very strictly, this may seem inconsistent, but I
> think it is logical.  The scroll bars and fringes are not columns, so
> a width measured in columns naturally won't include them.

It is ok that frame-width doesn't including them.  But, if
width is measured in pixels, which is natural; including
them or not?  If we are going to have pixel based APIs,
perhaps, most often used API will be window-pixel-width that
doesn't include scroll bars and fringes.

---
Ken'ichi HANDA
handa@m17n.org

Re: Code cleanup -- inconsistent "width" and "height" etc.

[Richard Stallman]

    For example, we would use FRAME_COLS and FRAME_LINES rather than the
    current FRAME_WIDTH and FRAME_HEIGHT.

I like this idea.  The names are short and clear.

Handa wrote:

    But, as I wrote, Lisp APIs are already using
    ...-width/...-height for columns and lines.

We don't HAVE to use the same convention internally as we do for Lisp.
It is true that it is better if the convention is the same, but that
has to be weighed against other advantages and disadvantages.