Boris Zbarsky wrote:
* It's not clear what the DOM3Core reference at the end of the first
paragraph is there for. Is that a reference for the Document and
Element interfaces? This could use clarification.
Yes, that was the intention. I have attempted to clarify it.
* It's not clear which IDL, if any, is being used when defining the
DocumentSelector and ElementSelector interfaces. For example, the DOM
Level 2 Core specification has a normative OMG IDL set of interface
definitions, with normative text that says that OMG IDL is being used. I
see no such normative text here, which I assume is a simple oversight.
This issue has not yet been addressed.
* I don't see any indication of what the language bindings for this IDL
should look like in languages which do not support function overloading
based on number of arguments and do not allow functions with variable
numbers of arguments. If it has been decided that no one is ever going
to implement bindings for this specification in such a language , it
might be good to explicitly say so in the specification so that it's
clear that the problem has been considered. Another possible solution
is to take the approach taken in other existing DOM specifications and
tack "NS" onto the end of the name of a namespace-aware version of a
method that is also available in a non-namespace-aware version. If the
intent is to indicate that the bindings in some languages may allow
omitting the second argument, I think that should be done via some
mechanism that doesn't look like normative IDL.
This issue has not yet been addressed. These two issues above will
likely be addressed by using and referencing Language Bindings for DOM
Specifications.
* The text following the interface definition is difficult to read due
to all the modifying clauses and has some grammar issues. (For example,
what alternative does "otherwise" refer to in the second sentence of the
first paragraph after the IDL? What is 'it' in that sentence, given
that the subject of the previous sentence is plural?) I would suggest
rewording as follows:
The term 'first' used in the definitions of the
querySelector methods means 'first in document order'.
The term 'document order' means a depth-first pre-order
traversal of the DOM tree or subtree in question.
The querySelector() methods on the DocumentSelector interface
MUST, when invoked, return the first Element node within the
document which matches the group of selectors (selectors). If there
is no node that matches the group of selectors, the methods MUST
return null.
and similarly for the other definitions in this section. In particular,
please make sure that the "that match the group of selectors (selectors)
in document order" text goes away; I see no way to make sense of it as
written, other than by assuming a copy/paste error.
I have modified the text to clarify those, and other issues, based on
your suggestion.
* The "User agents must use the nsresolver argument to resolve namespace
prefixes to namespaces or to get the default namespace. When the
nsresolver argument is null user agents must ignore it." text is
confusing to me. I think what it's trying to say is more like:
If the nsresolver argument is non-null, the user agent
MUST look up the default namespace for the group of
selectors by calling lookupNamespaceURI method of the
nsresolver object with an empty string argument.
If the group of selectors includes namespace prefixes, and
the user-agent MUST use the nsresolver provided to resolve
these prefixes to namespaces. It MUST NOT use any other
resolution mechanism.
The process used to resolve namespaces was already defined elsewhere in
the spec. However, I clarified that paragraph to more clearly refer to
those definitions.
* It's not clear whether ECMAScript authors are allowed to pass an
NSResolver object, or whether they have to pass a Function. This should
be clarified.
This has been clarified by defining that ECMAScript implementations must
support both a function and an object, and that authors may use a
function instead.
* I would refer to "callers" or "conforming applications" and not
"authors". There is no reason to expect that the caller of the API will
be an "author" in any sense of the word.
I now refer to conforming applications.
* Similarly, I'm not convinced that the term "user-agent" is better than
"implementation" in referring to the implementation of these methods. We
still want the term "conforming user agent" to refer to user agents that
include an implementation of this specification, of course.
I have replaced the relevant uses of "user agent" throughout the spec
with "implementation".
* I would replace the text
When using namespace prefixes within selectors or if there needs to be
a default namespace, authors must pass an NSResolver object
with:
If the group of selectors uses namespace prefixes, or if the default
namespace for the group of selectors is not the null namespace, the
caller MUST pass in a NSResolver object
I have updated the text based on your suggestion.
* It's not clear what it means for a group of selectors to be "invalid".
Does the term mean that the group of selectors is not tokenizable
according to the CSS grammar? Or that there are unrecognized simple
selectors or combinators in the group? Or both? How should vendor
extensions to CSS be handled?
The Selectors specification defines the conformance criteria for a group
of selectors, and thus an invalid selector is one that does not conform
to those requirements. I have updated the text to more clearly refer to
the conformance requirements in Selectors.
* Is there any requirement that the same Selectors implementation be
used for both the implementation of this API and for CSS if the user
agent implements both? If there is, that needs to be stated; if not, it
may be worth saying so. Not sure whether this belongs in this section,
but it came to mind when thinking about what it means for a selector to
be "invalid".
I do not believe specific implementation details such as that belong in
the specification. As long as the resulting implementation conforms to
the spec, it is irrelevant whether the user agent shares the selectors
implementation between this and CSS, or redundantly implements it twice
(despite the fact that doing so would not be wise for the implementor).
* It's not clear to me what algorithm is used to parse the selector
group. This includes both issues of whitespace in the selector group
and the issue of character escapes. Both should be defined, either
explicitly or by reference to the Selectors grammar as needed. Possibly
both for maximal clarity, though that introduces the possibility of
divergent definitions if the Selectors grammar changes.
The spec now defines that the selectors must be processed according to
the grammar specified in the Selectors specification.
* It's not clear to me what "the given NSResolver does not return a
namespace for the namespace prefix" means. Does that mean that it
returns a null or empty string? Please specify.
I have made this clarified this to say an empty string, or equivalent.
* It's not clear to me what the note:
The default namespace does not need to be defined.
means.
I have clarified the note to say that unresolvable namespaces can only
occur for prefixes, since the resolving the default namespace will
always resolve to something.
Does this mean that if the NSResolver returns a null or empty
string when passed an empty string a NAMESPACE_ERR exception does not
need to be raised and instead a null default namespace should be used?
This should be clarified.
How to interpret such return values is defined in the algorithm to get
the default namespace.
* I'm not sure what the note about pseudo-elements is trying to say, nor
why it appears out of the blue where it does.
This has been moved up to the section where the spec defines how to
process selectors, and has been rephrased as an advisory to authors
about the use of pseudo-elements.
* The example text "The querySelector() method also accepts a group of
selectors and it will return the first element that matches either
selector in the group (if any)" should perhaps be:
The querySelector() methods also accept a group of
selectors and they will return the first element (if any)
that matches any of the selectors in the group.
Your suggested text has been added to the spec.
The remaining issues in this mail that have not yet been addressed will
be addressed in the near future.
Please see the latest version of the spec in CVS to review the changes.
http://dev.w3.org/2006/webapi/selectors-api/
Please let me know if you are not satisified with any of these responses
or changes.
--
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/
