Re: ElementTraversal comments

Hi, Anne-

Thanks for your feedback.

Anne van Kesteren wrote (on 2/25/08 4:25 PM):
> 
> Some comments on 
> http://dev.w3.org/2006/webapi/ElementTraversal/publish/ElementTraversal.html 
> below
> 
> * As mentioned on IRC, node types should probably be capitalized. E.g. 
> Text instead of text.

Yes, I think I've caught all these now.


> * It's not clear from the introduction why we need childElementCount. 
> Having both linked list and array like traversing for the DOM is already 
> slightly unclear to me, but childElementCount seems to provide neither.

I've reworded the introduction slightly, in hopes of making it more 
clear.  I've also added explanatory text to example 3.2, which 
demonstrates the use of childElementCount.


> * I don't understand why 1.1 is marked as informative and section 1. is 
> not.

Fixed.


> * 2. talks about implementing methods where you mean attributes.

They are methods in Java (see appendix C), but I've changed it to say 
attributes.


> * In 2. ElementTraversal is not marked up.

I've made an extensive check for stuff that should be marked up and 
linked, and I think I've caught everything now.


> * I don't understand "A User Agent may implement similar interfaces in 
> other specifications, but such implementation is not required for 
> conformance to this specification, if the User Agent is designed for a 
> minimal code footprint." I suggest dropping this sentence.

That's an odd request.  A better suggestion might be to clarify the 
sentence, since I wouldn't have put it in if I didn't think the point 
needed to be made.

Most of the functionality of this spec is an optimized subset of DOM2 
Traversal & Range, and it is intended that a UA could implement both by 
aliasing; however, this isn't required for conformance to this 
specification.  I hope that clarifies it for you.


> * It's not clear to me how "For the purpose of ElementTraversal, an 
> entity reference node which represents an element must be treated as an 
> element node." works. Does this mean that an EntityReference node also 
> implements this interface? I suggest dropping this sentence or stating 
> that this interface assumes that all entities are normalized away or 
> something. 

I put this in as a response to an earlier comment [1].  While I think 
it's an edge case, the commenter was satisfied by the response.  I'm 
reluctant to mandate how a UA implements the solution, whether by 
implementing this interface on the entity reference node or only on the 
expanded resulting DOM, because I don't know how every UA does so.  I 
don't think it effects interoperability, so I prefer to leave it as is.



> (We should really get rid of syntactic sugar in the DOM in 
> due course...)

I'm not sure I'd consider entities as "syntactic sugar".  On the other 
hand, I'd totally consider this spec as syntactic sugar (making it 
easier for authors while not changing the underlying functionality of 
the language), so I disagree with the premise.


> * "Accessing this attribute of an element must return a reference to the 
> first child node of that element which is of nodeType 1, as an Element 
> object." I don't think ", as an Element object." makes much sense in 
> this sentence. (Likewise for similar sentences.)

I don't agree, but if you care to suggest alternate wording, I'll 
consider it.


> * I don't think the IDL should be in the appendix. It's a useful 
> overview of what the draft defines. 

I think this is a stylistic change that doesn't affect the readability 
or usefulness of the specification.  I prefer to keep it as is, since it 
makes more sense to me this way.


> I would also like to see pointers
> from the IDL bits to their definitions. As we've done in the 
> XMLHttpRequest specification.

As stated above, I've added many more links and markup, so I hope that 
helps.  As far as I can see, though, XHR doesn't contain an IDL per se.


Since I made only editorial, non-normative changes, I published them in 
the upcoming LCWD document, to be published next Monday.


[1] http://lists.w3.org/Archives/Public/public-webapi/2007Mar/0065.html

Regards-
-Doug Schepers
W3C Team Contact, SVG, CDF, and WebAPI

Received on Tuesday, 26 February 2008 05:42:58 UTC