W3C home > Mailing lists > Public > public-webapi@w3.org > June 2006

Re: [ANN] Selectors API

From: Cameron McCormack <cam@mcc.id.au>
Date: Thu, 15 Jun 2006 21:59:21 +1000
To: "Web APIs WG (public)" <public-webapi@w3.org>
Message-ID: <20060615115921.GA24627@port.mcc.id.au>

Hi Anne.

Cameron McCormack:
> >  ▪ (1) “This specification introduces two methods which take a
> >    selector (technically a group of selectors) as argument and return
> >    the matched elements as result.”
> >
> >    Why not just call them a group of selectors from the get go, since
> >    that’s the correct term?

Anne van Kesteren:
> Since it's the introduction.

Ok, but with the current wording it sounds like you are contradicting
yourself, equivalent to something like “the methods take a selector—no
that’s not right, they really take a group of selectors”.  Perhaps:

  This specification introduces two methods which take a group of
  selectors (often mistakenly just called “selectors”) as argument
  and return the matched elements as result.

where “group of selectors” is a link to the definition in CSS 2.1 or CSS
3 Selectors.  Or something.  (Actually, checking CSS 3 Selectors, there
isn’t a nice definition for a group of selectors in section 5 like there
is for selector in section 4.)

> >  ▪ (1.1) The example ‘test’ function uses matchAll to select 
> >  “:root”.
> >    This returns a StaticNodeList, but you compare it for strict
> >    equality with the document element.  This is always going to be
> >    false.
> 
> The node is not a copy, why would it be false?

Oh I totally ignored the “[0]” after the “c” in the return statement, my
mistake!

Aside: the wording for :root in in CSS 3 Selectors is a bit weird:

  The :root pseudo-class represents an element that is the root of the
  document. In HTML 4, this is the HTML element. In XML, it is whatever
  is appropriate for the DTD or schema and namespace for that XML
  document.

This seems to imply to me that with a document like this:

  <!DOCTYPE abc>
  <def/>

that is processed in non-validating mode, selecting :root wouldn’t match
the document element, since it’s not “abc”.  I wonder why the text
doesn’t just say that it should match the document element.

> >  ▪ (1.3) Although it’s obviously a reasonably subjective issue, FWIW I
> >    say to use select and selectAll.
> 
> I registered more votes for this and I personally would like to use them  
> as well, but the main concern is that authors would confuse them with  
> selectNode and selectSingleNode (used for XPath). What's your take on that?

For those authors not just copying and pasting code, I don’t think it
will be much of a problem.  If they do confuse them initially, it won’t
take them long to work out they have typed the wrong one.

If you find that it is important to take into account these IE XPath
function names, perhaps you can align them more closely by using
matchNodes and matchSingleNode.

> >  ▪ (2.1) I think the term “document order” is sufficiently known 
> >  that
> >    it’s unnecessary to say that it uses a “depth-first pre-order
> >    traversal”.
> 
> I think being clear doesn't hurt here.

Ok.  Maybe move the “document order” to the previous paragraph, since
that’s where the “depth-first pre-order traversal” is first mentioned.

> >  ▪ (2.1.1) “Authors may use extension mechanisms specific to the host
> >    language, like .prototype in ECMAScript.”  I don’t know what kind 
> >    of
> >    extensibility this is meant to be referring to.  Assigning to
> >    myNSResolver.prototype.lookupNamespaceURI for some reason?
> 
> This is just some text to make people complain. I hope to be able to  
> remove the section...

Cool.

Thanks,

Cameron

-- 
Cameron McCormack, http://mcc.id.au/
	xmpp:heycam@jabber.org  ▪  ICQ 26955922  ▪  MSN cam@mcc.id.au
Received on Thursday, 15 June 2006 12:23:20 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:18:55 GMT