Re: [selectors-api] Kudos on find/findAll, feedback on spec readability

On 2012-09-16 23:40, David Greenspan wrote:
> 6.2 -  "... first matching Element node within the subtrees..."
>
> Don't define a new term "subtrees" which just means "descendants."  Say,
> "... first matching Element node that is a descendant of the context
> object."

I could do that, but doing so makes it harder to rephrase this statement 
without making it more complex.

   3. The implementation must then run the algorithm to evaluate a
      selector against element nodes in the specified tree or subtrees
      using parsed selector as the selector and reference nodes as the
      contextual reference element set, as needed to return the required
      result for the invoked method.

If you have a suggestion for how to rephrase that to remove "subtrees" 
in a readable way without altering the meaning, please let me know.

> The main take-away from section 6.2 should be that find/findAll use a
> *different algorithm* from querySelector/querySelectorAll, or the same
> algorithm with a different setting (relative=true).  This point is almost
> entirely lost.

I think the clearest of those two alternatives is to clearly separate 
the two algorithms.  I have made this change in the spec.

> I think the intent is for the reader to perform a sort of
> "dispatch on type" when the algorithm in 6.5 is invoked, but it's confusing
> because you can't really look at a selector and a relative selector and
> tell them apart, and certainly not before parsing them.

The intent was that the reader is supposed to know whether you have a 
selector or relative selector based on which method was invoked. The 
above changes now make that clearer.

> 6.2 - "When either method is invoked..." - there are four methods, not 2

Good point, but with the above changes, I also made it more explicit 
about which methods are being referred to in each case.

> 6.5 - "... begins with a combinator and that combinator is not ' ' (space)"
> - how can a relative selector, in a comma-separated list with whitespace,
> physically start with a space, i.e. a descendant combinator??

This was added to clarify that ' ' is excluded from the set of possible 
combinators that trigger automatic prepending of :scope, regardless of 
whether the selector meets any of the other conditions.  At this stage 
in the algorithm, no whitespace has been trimmed from the selector, so 
if the input is " div", then it needs to be clear that :scope is not 
prepended in step 1.

Note that there is a known bug in the way the grammar is defined that 
does actually allow for a relative selector to begin with a descendant 
combinator. I just haven't figured out a good way to fix this.  I have 
now noted this issue in the spec.

>  Supposing it can (at the beginning of the string, perhaps), why would 
you special-case
> it and prepend what's presumably a second descendant combinator in step 5?

Because if steps 2, 3 or 4 apply, then step 5 doesn't apply and :scope 
is not prepended.

e.g.
   document.find(" div");          // Matches condition in step 2
   elm.find(" not(:scope)");       // Matches condition in step 3
   elm.find(" body.foo :scope p"); // Matches condition in step 4

If space was not excluded, the the spec could be interpreted such that 
:scope should be prepended in those cases.

> 7 - "contextual reference element" - This term is revealed to mean simply a
> potential :scope element.  I would call it something like a "scope
> candidate" -- or basically anything besides what it's called.

This section was intended to be dropped now that Selectors 4 defines 
:scope adequately, and as such the term "contextual reference element" 
has been removed.  However, the term "contextual reference element set" 
still remains due to its definition in Selectors 4.  If you wish to have 
that changed, please follow this up with the CSS WG.

I have now removed section 7 "The :scope Pseudo-class" entirely from 
this spec.

> 8 - Feature Strings - Change last paragraph to: "Conforming implementations
> must return true ... if they are perfectly compliant, and false if they are
> not."

No.  Feature strings are a notoriously unreliably method of determining 
support for a given feature and it only exists to provide an indication 
that there is some support for the API, without specifying how compliant 
a given implementation is.

> 9 - Examples of find() and :scope MUST be added here.  Seriously.  This
> section is the last chance to push that lucky reader over the final
> threshold to feeling like they fully understand the spec.

They will be added in due course.  They hadn't been added yet due to the 
prior instability of the new API design and their low priority. However, 
feel free to contribute some examples if you like and I will consider 
including them.

-- 
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/

Received on Thursday, 4 October 2012 14:16:00 UTC