- From: Bjoern Hoehrmann <derhoermi@gmx.net>
- Date: Fri, 07 Mar 2008 07:58:09 +0100
- To: "Anne van Kesteren" <annevk@opera.com>
- Cc: www-style@w3.org
* 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