Re: [cssom-view] small update

* Anne van Kesteren wrote:
>   http://dev.w3.org/csswg/cssom-view/

You need a reference to DOM Level 2 Views. DOM Level 2 Views defines how
the module interacts with the DOM .hasFeature(...) and related methods,
but such a definition is absent from your draft. Since it is meant to
update the older DOM module, you need to have some discussion of this.

The specification ought to have some kind of introduction that puts it
into some context beyond what you say in the Abstract of the document.

"The HTML body element is the first body HTML element child of the root
HTML element html." might be better written as "In documents whose root
element is the HTML element html, the HTML body element is the first
body HTML element child of the root element, if any." The current text
is unclear whether <svg ...><html ...><body> is a HTML body element, at
least assuming obvious definitions of the terms.

In section 2.1 you have a [CSS21] reference that is no link and has no
entry in the References section. Why is the method called "query"? I'd
think an .isX, .hasX, .canX, .supportsX, .doesX, ... name would be more
appropriate.

I don't quite understand the colorDepth and pixelDepth attributes.

The elementFromPoint(...) method takes two integers that specify the
point. Could you comment on why, other than status quo, these should not
be floats? Many of the interfaces in the document specify coordinates as
floats. If the arguments are to be integers, perhaps a note about that
would be useful.

For RangeView.getBoundingClientRect(...) you have:

  3. Otherwise, return a union of the boxes in list, excluding boxes
     that are empty, as a single TextRectangle object. If all boxes are
     empty let the top attribute of the new TextRectangle object be the
     value of the top attribute of the first border box in the list
     returned. Do likewise for left and then let bottom be equal to top
     and right to left. 

Couldn't this be written as follows:

  3. Otherwise, return a (static) TextRectangle object describing the
     smallest rectangle that includes the first item in list and all
     non-empty rectangles in list.

This would precisely define which among the many possible unions to use
and avoids several redundant points in the original (such as that the
items in the list describe border boxes and what to do with only empty
rectangles). If my text is equivalent, I would rather you use the short
version.

Objects implementing the MouseEvent interface are required to also im-
plement the MouseEventView interface, however there are name clashes in
the two interfaces (specifically the screenX/Y and clientX/Y attributes)
which needs to be explained or otherwise resolved in your draft.

The MouseEventView has two redundant attributes x and y, there should be
a note which one authors should use to avoid confusion and promote con-
sistency.

Why is the TextRectangle called thusly? Wouldn't, say, ClientRectangle
be a better name?

Editorially, I rather dislike the high amounts of redundant text you've
included, it makes it very difficult to read the text correctly (you'll
either ignore parts that look similar and miss differences, or you'll
try very hard not to, which I find rather exhausting). The same goes for
the rather elaborate text.

As an example, section 6.3 would be better written like so:

  If an element does not have an associated CSS layout box or if it is
  an inline box, all the following attributes have the value zero. All
  values are in number of CSS pixels.

  clientTop
     The computed value of the border-top-width property plus the
     width of any scrollbar rendered between the top padding box
     and top border box.

  clientWidth
    If element A is the root element, the width of the viewport;
    otherwise the width of the padding box of element A (excluding the
    width of any rendered scrollbar between the padding and border box)

  ...

By the way, instead of referring to the width of the viewport, it might
be wise to refer to the viewport's .innerWidth attribute if that is what
you mean (the name clientWidth would suggest using the .outerWidth).

Similarily, it would be very useful if you would use more mathematical
notation instead of text where approprate, for example, rather than

    2. If x is negative act as if it was zero. 

    3. If x is greater than the content width minus the content box
       width act as if it was the content width minus the content box
       width.

define to use `min(content width - content box width, max(0, x))`. This
saves readers from checking that the two phrases above are the same and
it translates more naturally into code, in addition to being shorter.

The main point here is that many people do not bother to fully read and
understand all the text, so keeping the key points as brief as possible
goes a long way of ensuring that people understand them.

On a further note I would suggest avoiding constructs like If X does not
have A or B as in "If element A does not have an associated CSS layout
box or vertical overflow stop this algorithm" -- it's not clear whether
you stop if just one of them is absent. Using "Unless X has A and/or B"
would be better.

There are many terms that you use, like content width, context box with,
associated CSS layout box, and current rendering mode, that you never
properly introduce. Links to their definitions would be very useful.

I think Microsoft's MSDN has a nice diagram that illustrates the various
measures and coordinates, is there a chance you could include something
similar in the draft?
-- 
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

Received on Friday, 7 March 2008 06:58:28 UTC