Re: ElementTraversal comments

Hi, Anne-

Anne van Kesteren wrote (on 2/26/08 4:52 AM):
> 
> On Tue, 26 Feb 2008 06:42:49 +0100, Doug Schepers <schepers@w3.org> wrote:
>> Anne van Kesteren wrote (on 2/25/08 4:25 PM):
>>> * 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.
> 
> Where is the draft located that contains these changes? It seems you 
> haven't updated the editor's copy which makes it hard for me to revew 
> the changes.

I've uploaded it to public CVS now [1].  I was having some trouble with 
that last night.


>>> * 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 a subset at all. Clarification is ok too, but I think the 
> sentence is a distraction.

It can be implemented as a subset of functionality.  If others agree 
with you, I will rework of remove the sentence in question, though.


>>> * 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.
> 
> That may very well be so, but I don't understand what it's saying.
> 
> 
>> 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.
> 
> Leaving it as does not satisfy me as I think the sentence is unclear.

I'm not sure how I can make it more clear without imposing undue 
restrictions on UAs.


>>> * "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.
> 
> "Getting this attribute of an element must return the first Element 
> child node of that element or null if there are no Element child nodes."

Ok, I'll consider something like that.


>>> * 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.
> 
> It would tell you upfront what the interface is and what members it 
> introduces and provide pointers to the definitions of those members. I 
> think that would make the draft more readable.

There are only 5 attributes, and I describe them in the introduction (in 
broad strokes), again (verbosely) in the interface description prose, 
and again (tersely) in the IDL.  I find it hard to credit that they are 
somehow unclear.

I don't agree that changing the structure of the document would make it 
more readable, and I think it would make it less discrete.


>> Since I made only editorial, non-normative changes, I published them 
>> in the upcoming LCWD document, to be published next Monday.
> 
> I don't understand why it's not in the editor's draft. Everything what 
> this group does, including editorial work, is captured in public 
> documents nowadays.

See above.  Relax, Anne, nobody's trying to pull anything shady.


[1] 
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/ElementTraversal/publish/ElementTraversal.html?rev=1.12

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

Received on Tuesday, 26 February 2008 16:27:11 UTC