Re: Selectors API naming

[Nicolas Mendoza]

On Fri, 22 Dec 2006 02:48:45 +0100, Maciej Stachowiak <[EMAIL PROTECTED]>  
wrote:


Based on this, I think that shorter names like "match" or "matchAll" are  
justified, if not necessarily those exact names.


How about (document+"").match(/Document/) vs. (document).match() -- sure,  
a bit exaggerated but it sure seems confusing to me ;/


Oh and just because one has failed earlier doesn't mean that one has to do  
it again.


I'd go for surprising the user the least.

If one really wanted to always use short and possible conflicting  
keywords, one should at least do it properly, and deprecate the old long  
and oh so hard to use getElementBy#? ones. If it really is a huge problem  
that libraries make aliases that is.


--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/

Re: Selectors API naming

[Doug Schepers]

Hi, Maciej-

Maciej Stachowiak wrote:


- "Microsoft representatives endorse a longer name" -- I don't think 
Microsoft's track record in design of web APIs for JavaScript justifies 
treating them as an authority. I hope their arguments will be evaluated 
on their merits, not the credentials of the speakers, and I would ask 
the same for mine.


I was not citing their authority.  I was citing their experience, in 
reference to Chris Wilson's first post on this thread. [1]


[1] http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0026.html

Regards-
-Doug

Re: Selectors API naming

[Maciej Stachowiak]

Hello Web API interested parties,

I've read this thread, and rather than replying to people's specific  
points, I would like to give some arguments in favor of a relatively  
short name.


Short Names For Common Idioms
---

Many have argued that classes, methods and properties should have  
clear, descriptive names. I agree with this general principle.  
However, I think the main reason for this is not learnability, but  
readability of resulting code. Ideally, well-written code using  
standard methods should be easy to understand and modify. Maintenance  
is a much larger part of the life cycle and development cost of most  
code than initial development.


Given this, there is a counterbalancing principle that common  
fundamental idioms should have short names. That's because these  
basic idioms become so well understood that extra verbosity just  
creates visual noise. I think in extreme cases of this, most people  
would agree.


Some examples:

Consider if in C++, the end of statement token was not the brief but  
arbitrary ";", but the far more explicit "end_of_statement". Reading  
code like this:


int x = get_value() end_of_statement
int y = x + 3 end_of_statement
printf("%d\n", y) end_of_statement

is way harder than the standard version:

int x = get_value();
int y = x + 3;
printf("%d\n", y);

Another idiom that is given a very brief lexical form in most  
languages is access to variables. Access to a variable for either  
reading or writing generally requires either a short single-character  
token (like $ in perl) or no decoration at all but just the variable  
name. ECMAScript could be much more explicit, and make you clearly  
identify your global and local variable references:


function addTag(tag)
{
getReferenceByGlobalVariableName("allTags") =  
getReferenceByLocalVariableName("tag");

}

But of course code like that would be wildly unreadable.

I hope we will all agree, given these examples, that very common  
constructs should be expressible concisely. Autocomplete may make  
long names easier to type, but it does not make the resulting code  
any easier to read.



Will Selectors API be a Common Idiom?
-

Now, the remaining question is whether the proposed Selectors API  
would be widely enough used to merit special short names, and if so  
how short. Here are some arguments that it merits a short name:


1) The DOM holds a large proportion of the information that most DOM  
scripts manipulate. Access to DOM elements is arguably analogous to  
access to variables, though of course not as common.


2) The Selectors API methods provide an improved superset of the  
capabilities of getElement(s)By{Id,TagName,Name,ClassName}. They do  
not suffer from the flaw of returning live lists. And they align well  
with the use of selectors with CSS in the web platform - using  
selectors to find nodes and process data or attach behavior lines up  
well with using them to attach presentational style. Therefore, if  
implemented interoperably, they are likely to be used quite widely.


3) There is some evidence, based on the shortcuts found in JS  
libraries, that document.getElementById is too long a name for how  
commonly this method is used. Some have argued that any name would be  
given a short alias, but I do not buy this; document.all seems short  
enough that no one needs a shortcut.


Based on this, I think that shorter names like "match" or "matchAll"  
are justified, if not necessarily those exact names.



Response to Some Other Arguments
--

- "These might conflict with short names in markup" -- I don't see  
why markup should get all the short names and script should be stuck  
with verbose ones. Also, the HTMLDocument interface (which it's  
likely will have to be implemented on every document in a browser for  
CDI to work sanely) already steps on such useful short names as  
"title", "URL", "images", "open", "close"...


- "It doesn't match names of other similar methods" -- I think  
selectSingleNode proves that slight inconsistency is not much of a  
problem in practice.


- "It will be too hard to learn" -- If all names were this pithy this  
might be true. But as it is I doubt it adds much to the learning curve.


- "Microsoft representatives endorse a longer name" -- I don't think  
Microsoft's track record in design of web APIs for JavaScript  
justifies treating them as an authority. I hope their arguments will  
be evaluated on their merits, not the credentials of the speakers,  
and I would ask the same for mine.



In conclusion, I think there is a strong case for short names. If  
"match" and "matchAll" are objectionable, I hope others will consider  
proposing some alternative relatively short names.


Regards,
Maciej

Re: Selectors API naming

[Jon Ferraiolo]

I agree with what Bjoern says below about the need to avoid name clashes.

If developers don't like the long names such as getElementsBySelectors(),
then they can write their own JavaScript wrapper functions that have
shorter names, such as function matchAll(...) { return
getElementsBySelectors(...); }

Jon

Jon Ferraiolo <[EMAIL PROTECTED]>
Web Architect, Emerging Technologies
IBM, Menlo Park, CA
Mobile: +1-650-926-5865



   
 Bjoern Hoehrmann  
 <[EMAIL PROTECTED] 
 t> To
 Sent by:  "Anne van Kesteren" 
 public-webapi-req <[EMAIL PROTECTED]>  
 [EMAIL PROTECTED]cc
   "Web API WG (public)"   
 
 12/21/2006 03:24  Subject
 PMRe: Selectors API naming
   
   
   
   
   
   





* Anne van Kesteren wrote:
>[...]

I would like to point out that there exists a valid technical reason for
using different method names than the ones in the current draft. One of
reasons why the DOM uses longer, more descriptive names is to avoid name
clashes. The current draft essentially reserves the names 'matchAll' and
'matchSingle' for attributes and methods on all specialized Document and
Element interfaces. This implies, among other things, that you cannot
make a markup language where you have

  These names would also be slightly confusing as they would not take a
>selector but rather a group of selectors. I suppose the group in favor of

>these methods find that acceptable. I wonder if they find the
>inconsistency with the other DOM methods to be acceptable as well.

I do not think that properties of return values such as liveness should
influence naming, so I do not really see how picking such a name would
introduce any new inconsistency. As for selector groups, you could just
use getElementsBySelectors(...) or getElementsByCssQuery(...) or just
cssQuery(...). I'd be fine with 'cssQuery' and 'cssQueryOne' instead of
the current methods; these names happen to be exactly as long, would not
have either of the problems mentioned above, and are already well-known
among developers if

  http://www.google.com/search?q=matchall+css
  http://www.google.com/search?q=cssquery+css

counts as "evidence". We already broke the getElementsBy... convention
with the .selectNodes(...) and .selectSingleNode(...) methods, we have
plenty of experience that this is not too big an issue. I'd be fine with
the getElementsBy... versions above though of course.

>It seems that libraries find there's a need to provide shortcuts for the
>several of the above mentioned methods (notably document.getElementById
>and document.getElementsByTagName). Several authors have argued that they

>don't see a need for such a thing but no "evidence" has been provided. No

>evidence to the contrary either, though.

These libraries typically do not simply set up some alias for a feature
like the Selectors API, they would add code to detect whether the user
agent supports the feature, might switch to an alternate pure-script im-
plementation in case it does not, they might have work arounds for known
issues, they might have a pre-defined namespace resolver so you have the
prefixes for all the common namespaces available, they might add some
tracing code for debugging purposes, and they might add other features.

Further, no name can remove the `document.` you have to put in front of
it, and if you can have document.matchAll(...) or cssQ(...), you'd pick
the latter. As such I do not think the argument, if we pick a short name
the library designers won't write wrapper functions, holds at all. If I
were to make considerable use of the API, I would certainly write one,
if only so I can use BH.cssQuery(...) instead of document.matchAll(...,
BH.stdNamespaceResolver).
--
Björn Höhrmann · mailto:[EMAIL PROTECTED] · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

Re: Selectors API naming

[Ian Hickson]

On Thu, 21 Dec 2006, Anne van Kesteren wrote:
> 
> Currently the following methods exist:
> 
>  * document.getElementsByTagName()
>  * document.getElementsByName() (HTML only)
>  * document.getElementById()
> 
> The following method is proposed by the WHATWG:
> 
>  * document.getElementsByClassName()

We should also not forget:

   * document.all
   * document.evaluate
   * document.selectNodes (XML only)
   * document.selectSingleNode (XML only)
   * document.getAnonymousNodes (XBL1 only)
   * document.getAnonymousElementByAttribute (XBL1 only)

...all of which are implementing and shipping. (In the case of 
document.all, my data indicates that it is used in around the same order 
of magnitude of pages as getElementById(), not counting cases like "if 
(document.all)", though of course since this is scripting it's very hard 
to tell for sure exactly what was going on.)

The feedback I've heard from devs at Google is that 
document.getElementsBySelector() is fine, so I'm happy either way.

I still say that this should just be up to the editor, though. IMHO 
forcing editor decisions is not a good way to get a spec. Editors should 
own their specification and be responsible for changes and decisions. 
Naturally, this should be based on all the feedback received, but 
sometimes overall spec quality argues that not everyone can be happy. 
Having compromises where everyone "can live with it" means that the 
overall quality is lower for everyone. Then we all lose.

-- 
Ian Hickson   U+1047E)\._.,--,'``.fL
http://ln.hixie.ch/   U+263A/,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

Re: Selectors API naming

[Bjoern Hoehrmann]

* Anne van Kesteren wrote:
>[...]

I would like to point out that there exists a valid technical reason for
using different method names than the ones in the current draft. One of
reasons why the DOM uses longer, more descriptive names is to avoid name
clashes. The current draft essentially reserves the names 'matchAll' and
'matchSingle' for attributes and methods on all specialized Document and
Element interfaces. This implies, among other things, that you cannot
make a markup language where you have

  These names would also be slightly confusing as they would not take a  
>selector but rather a group of selectors. I suppose the group in favor of  
>these methods find that acceptable. I wonder if they find the  
>inconsistency with the other DOM methods to be acceptable as well.  

I do not think that properties of return values such as liveness should
influence naming, so I do not really see how picking such a name would
introduce any new inconsistency. As for selector groups, you could just
use getElementsBySelectors(...) or getElementsByCssQuery(...) or just
cssQuery(...). I'd be fine with 'cssQuery' and 'cssQueryOne' instead of
the current methods; these names happen to be exactly as long, would not
have either of the problems mentioned above, and are already well-known
among developers if

  http://www.google.com/search?q=matchall+css
  http://www.google.com/search?q=cssquery+css

counts as "evidence". We already broke the getElementsBy... convention
with the .selectNodes(...) and .selectSingleNode(...) methods, we have
plenty of experience that this is not too big an issue. I'd be fine with
the getElementsBy... versions above though of course.

>It seems that libraries find there's a need to provide shortcuts for the  
>several of the above mentioned methods (notably document.getElementById  
>and document.getElementsByTagName). Several authors have argued that they  
>don't see a need for such a thing but no "evidence" has been provided. No  
>evidence to the contrary either, though.

These libraries typically do not simply set up some alias for a feature
like the Selectors API, they would add code to detect whether the user
agent supports the feature, might switch to an alternate pure-script im-
plementation in case it does not, they might have work arounds for known
issues, they might have a pre-defined namespace resolver so you have the
prefixes for all the common namespaces available, they might add some
tracing code for debugging purposes, and they might add other features.

Further, no name can remove the `document.` you have to put in front of
it, and if you can have document.matchAll(...) or cssQ(...), you'd pick
the latter. As such I do not think the argument, if we pick a short name
the library designers won't write wrapper functions, holds at all. If I
were to make considerable use of the API, I would certainly write one,
if only so I can use BH.cssQuery(...) instead of document.matchAll(...,
BH.stdNamespaceResolver).
-- 
Björn Höhrmann · mailto:[EMAIL PROTECTED] · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/ 

Re: Selectors API naming

[Doug Schepers]

Hi, Anne-

Anne van Kesteren wrote:


Currently the following methods exist:

 * document.getElementsByTagName()
 * document.getElementsByName() (HTML only)
 * document.getElementById()

The following method is proposed by the WHATWG:

 * document.getElementsByClassName()


I'd really like to use that.  It's very useful.


These four methods all return a _live_ NodeList meaning that when 
something in the DOM is changed the variable that holds the NodeList is 
changed accordingly, if needed.


document.getElementById() returns an element, not a nodeList [0].  It 
doesn't seem that it's live.




If we would name the new pair as follows:

 * document.getElementBySelector()
 * document.getElementsBySelector()

They would not be consistent with the previous four mentioned methods as 
they would not return a live NodeList but a StaticNodeList. Which means 
that when an attribute value changes the StaticNodeList does not need to 
be updated for a group of selectors that uses an attribute selector 
somewhere.


document.getElementBySelector() should return an element, not a nodeList 
(live or static); it's like document.getElementById().


In practical terms, regardless of whether the list is live or not, the 
same accessor, looping, and assignation mechanisms would still work for 
both.


Personally, the liveness has always struck me as more of a bug than a 
feature.  Thus my code always strives to avoid the negative aspects of a 
live nodeList, and I suspect that others code the same way.  I don't see 
a negative impact in my current methodology of the list being static.



These names would also be slightly confusing as they would not take a 
selector but rather a group of selectors. I suppose the group in favor 
of these methods find that acceptable. I wonder if they find the 
inconsistency with the other DOM methods to be acceptable as well. 
Personally I don't really like that.


Again, I don't care if the names are different, to reflect this (minor) 
difference.  For example, I'd be happy with:


 * document.getNodeBySelector()
 * document.getNodelistBySelector()

or something similar.

It seems that libraries find there's a need to provide shortcuts for the 
several of the above mentioned methods (notably document.getElementById 
and document.getElementsByTagName). Several authors have argued that 
they don't see a need for such a thing but no "evidence" has been 
provided. No evidence to the contrary either, though.


As has been stated, there may be reasons for using method aliases that 
are unrelated to the length of the method.  Even if that is one of the 
reasons, I don't think that it's a compelling argument, certainly not 
proof of "failure".  It might be better not to assume that these 
alias-happy authors are doing it for the reasons you maintain.


My colleagues who do use aliases, for example, do so to abstract out the 
 framework that they use (dojo, as it happens) in order to add 
functionality and to future-proof their own code against underlying 
changes, not merely to make shorter names.  BTW, they do hundreds and 
thousands of lines of code, and they prefer the longer names, as well.


Consider that the aliasing may be done because the library wants to 
achieve cross-platform compatibility, and they use the shorter name 
because the more descriptive name is already taken.  Have we solicited



I'm personally not really convinced by the autocomplete argument. I 
don't really think it's good language design to assume there's such a 
thing.


I don't use autocomplete, and I don't mind the slightly longer names.


I'm still leaning towards not changing the draft with regard to naming 
for reasons mentioned above, but if someone can tackle the problems 
mentioned above I'm willing to reconsider.


I don't see the problem you're talking about.

The clear majority of individuals and arguments in this thread favor 
longer descriptive naming conventions (including others from your own 
company).  Further, I haven't seen counterarguments against most of the 
points in favor of this stance.  No offense, but your conviction does 
sound more ideological than logical.



[0] http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-getElBId

Regards-
-Doug

Re: NSResolver Re: Selectors API naming

[Anne van Kesteren]

On Thu, 21 Dec 2006 23:19:09 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:

So even a quirksmode document is in the xhtml namespace?


I think that's the plan, yes. That all documents parsed with an HTML  
parser will return a DOM with namespaced element nodes. (There's still an  
open question as to whether quirks mode will have a different parsing mode  
or not. I hope it won't, because it doesn't seem to needed.)


(Again, this is already the case for CSS.)


--
Anne van Kesteren

RE: NSResolver Re: Selectors API naming

[Chris Wilson]

So even a quirksmode document is in the xhtml namespace?

-Original Message-
From: Anne van Kesteren [mailto:[EMAIL PROTECTED] 
Sent: Thursday, December 21, 2006 2:15 PM
To: Chris Wilson; Charles McCathieNevile; Dave Massy; Web API WG (public)
Cc: Tina Duff
Subject: Re: NSResolver Re: Selectors API naming

On Thu, 21 Dec 2006 23:09:46 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
> Sorry.  I should be saying "what namespace URI is an HTML document in?"

As I said before, currently implementations set the namespaceURI attribute  
of elements to null for documents parsed with an HTML parser. The HTML5  
proposal says that it should be http://www.w3.org/1999/xhtml instead.


For the purposes of CSS elements from documents parsed with an HTML parser  
are already in the http://www.w3.org/1999/xhtml namespace in Opera,  
Mozilla and I think Safari too. It would only make sense if this was done  
for the DOM too.


-- 
Anne van Kesteren

Re: NSResolver Re: Selectors API naming

[Anne van Kesteren]

On Thu, 21 Dec 2006 23:09:46 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:

Sorry.  I should be saying "what namespace URI is an HTML document in?"


As I said before, currently implementations set the namespaceURI attribute  
of elements to null for documents parsed with an HTML parser. The HTML5  
proposal says that it should be http://www.w3.org/1999/xhtml instead.



For the purposes of CSS elements from documents parsed with an HTML parser  
are already in the http://www.w3.org/1999/xhtml namespace in Opera,  
Mozilla and I think Safari too. It would only make sense if this was done  
for the DOM too.



--
Anne van Kesteren

RE: NSResolver Re: Selectors API naming

[Chris Wilson]

Sorry.  I should be saying "what namespace URI is an HTML document in?"

-Original Message-
From: Anne van Kesteren [mailto:[EMAIL PROTECTED] 
Sent: Thursday, December 21, 2006 2:07 PM
To: Chris Wilson; Charles McCathieNevile; Dave Massy; Web API WG (public)
Cc: Tina Duff
Subject: Re: NSResolver Re: Selectors API naming

On Thu, 21 Dec 2006 22:57:55 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
> Whose job is it in the W3C?  (This isn't "how you transform HTML into a  
> DOM" - it's "what doctype do you presume when it's not there?")

DOCTYPEs? DOCTYPEs have two use cases on the web as far as I know:

   1. In HTML they provide a way for the author to pick between
  "quirks mode", "almost standards mode" (in some browsers)
  and "standards mode". What these modes imply varies among
  implementations at the moment. In general they affect
  rendering. In some implementations they affect parsing
  too.

   2. In XML some "known DOCTYPEs" tell the user agent to
  support a set of "named entities".

(Note that I said "the web" above.)


If something is HTML or not depends on the media type, mostly. text/html  
-> HTML (except when you're fetching something like a feed). I think Ian  
Hickson is doing some research on this.


-- 
Anne van Kesteren

Re: NSResolver Re: Selectors API naming

[Anne van Kesteren]

On Thu, 21 Dec 2006 22:57:55 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
Whose job is it in the W3C?  (This isn't "how you transform HTML into a  
DOM" - it's "what doctype do you presume when it's not there?")


DOCTYPEs? DOCTYPEs have two use cases on the web as far as I know:

  1. In HTML they provide a way for the author to pick between
 "quirks mode", "almost standards mode" (in some browsers)
 and "standards mode". What these modes imply varies among
 implementations at the moment. In general they affect
 rendering. In some implementations they affect parsing
 too.

  2. In XML some "known DOCTYPEs" tell the user agent to
 support a set of "named entities".

(Note that I said "the web" above.)


If something is HTML or not depends on the media type, mostly. text/html  
-> HTML (except when you're fetching something like a feed). I think Ian  
Hickson is doing some research on this.



--
Anne van Kesteren

RE: NSResolver Re: Selectors API naming

[Chris Wilson]

Whose job is it in the W3C?  (This isn't "how you transform HTML into a DOM" - 
it's "what doctype do you presume when it's not there?")

-Original Message-
From: Anne van Kesteren [mailto:[EMAIL PROTECTED] 
Sent: Thursday, December 21, 2006 1:35 PM
To: Chris Wilson; Charles McCathieNevile; Dave Massy; Web API WG (public)
Cc: Tina Duff
Subject: Re: NSResolver Re: Selectors API naming

On Thu, 21 Dec 2006 22:25:11 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
> I don't care about the particular conclusion.  For the purposes of  
> interoperability across implementations (and that IS the point of  
> creating a standard, right?) I believe it absolutely should be defined,  
> and is the issue of the WebAPI WG - unless you don't really care about  
> interoperability, in which case I'm not sure I see the point of having a  
> standard to begin with.

Euhmmm... I care about interoperability, a lot. It's sort of my day job to  
care about that. I'm just saying it's not our issue. It depends on HTML is  
reflected in the DOM. That requires someone to specify how you transform  
HTML into a DOM. I explained that the HTML5 proposal did that and how it  
did that. I think it's out of scope of the Selectors API specification to  
define how you convert a string of HTML into a DOM. (The methods from the  
Selectors API operate on a DOM.)


In general you don't need to use the namespaces by the way. Certainly not  
for HTML. You would just do:

   document.matchAll("div.example, div.examples")

which will match the  element in any namespace with either a class  
"example" or "examples" which is fine for HTML.


> Look, I've been involved in developing a lot of the W3C standards that  
> the web development community relies on today - HTML, DOM, CSS, XSL -  
> and I can say without reservation the biggest lesson I've learned about  
> building a durable standard on which multiple interoperable  
> implementations can be built is that you must think about the edge cases  
> and capture them in the standard as early as possible.  Otherwise you  
> end up with a debacle[1] like CSS, where the original version is so  
> loosely defined that it can be interpreted in many different ways, and  
> you progressively introduce detail into later versions of the spec (or  
> have wildly incompatible implementations), screwing the early  
> implementers and adopters along the way (hi there).

Yeah, I think every reasonable person agrees with this :-)


> A very senior person in IE's development in the past repeatedly stated  
> to me that he didn't believe that there would ever be truly  
> interoperable DOM implementations, because (e.g.) getting the event  
> timing perfectly the same was nearly impossible - there would always be  
> timing differences or whatever.  Let's prove him wrong.  Designing loose  
> standards doesn't help.

And with this too!


-- 
Anne van Kesteren

Re: NSResolver Re: Selectors API naming

[Anne van Kesteren]

On Thu, 21 Dec 2006 22:25:11 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
I don't care about the particular conclusion.  For the purposes of  
interoperability across implementations (and that IS the point of  
creating a standard, right?) I believe it absolutely should be defined,  
and is the issue of the WebAPI WG - unless you don't really care about  
interoperability, in which case I'm not sure I see the point of having a  
standard to begin with.


Euhmmm... I care about interoperability, a lot. It's sort of my day job to  
care about that. I'm just saying it's not our issue. It depends on HTML is  
reflected in the DOM. That requires someone to specify how you transform  
HTML into a DOM. I explained that the HTML5 proposal did that and how it  
did that. I think it's out of scope of the Selectors API specification to  
define how you convert a string of HTML into a DOM. (The methods from the  
Selectors API operate on a DOM.)



In general you don't need to use the namespaces by the way. Certainly not  
for HTML. You would just do:


  document.matchAll("div.example, div.examples")

which will match the  element in any namespace with either a class  
"example" or "examples" which is fine for HTML.



Look, I've been involved in developing a lot of the W3C standards that  
the web development community relies on today - HTML, DOM, CSS, XSL -  
and I can say without reservation the biggest lesson I've learned about  
building a durable standard on which multiple interoperable  
implementations can be built is that you must think about the edge cases  
and capture them in the standard as early as possible.  Otherwise you  
end up with a debacle[1] like CSS, where the original version is so  
loosely defined that it can be interpreted in many different ways, and  
you progressively introduce detail into later versions of the spec (or  
have wildly incompatible implementations), screwing the early  
implementers and adopters along the way (hi there).


Yeah, I think every reasonable person agrees with this :-)


A very senior person in IE's development in the past repeatedly stated  
to me that he didn't believe that there would ever be truly  
interoperable DOM implementations, because (e.g.) getting the event  
timing perfectly the same was nearly impossible - there would always be  
timing differences or whatever.  Let's prove him wrong.  Designing loose  
standards doesn't help.


And with this too!


--
Anne van Kesteren

RE: NSResolver Re: Selectors API naming

[Chris Wilson]

I don't care about the particular conclusion.  For the purposes of 
interoperability across implementations (and that IS the point of creating a 
standard, right?) I believe it absolutely should be defined, and is the issue 
of the WebAPI WG - unless you don't really care about interoperability, in 
which case I'm not sure I see the point of having a standard to begin with.

Look, I've been involved in developing a lot of the W3C standards that the web 
development community relies on today - HTML, DOM, CSS, XSL - and I can say 
without reservation the biggest lesson I've learned about building a durable 
standard on which multiple interoperable implementations can be built is that 
you must think about the edge cases and capture them in the standard as early 
as possible.  Otherwise you end up with a debacle[1] like CSS, where the 
original version is so loosely defined that it can be interpreted in many 
different ways, and you progressively introduce detail into later versions of 
the spec (or have wildly incompatible implementations), screwing the early 
implementers and adopters along the way (hi there).

A very senior person in IE's development in the past repeatedly stated to me 
that he didn't believe that there would ever be truly interoperable DOM 
implementations, because (e.g.) getting the event timing perfectly the same was 
nearly impossible - there would always be timing differences or whatever.  
Let's prove him wrong.  Designing loose standards doesn't help.

-Chris

[1] I'm not saying CSS as a whole is a debacle - I consider getting an initial 
implementation of CSS into IE3 to be one of the proudest and most 
industry-affecting single moments of my career in retrospect - but I do believe 
the progressive-refinement process it's been going through for the last ten 
years is.

-Original Message-
From: Anne van Kesteren [mailto:[EMAIL PROTECTED] 
Sent: Thursday, December 21, 2006 12:36 PM
To: Chris Wilson; Charles McCathieNevile; Dave Massy; Web API WG (public)
Cc: Tina Duff
Subject: Re: NSResolver Re: Selectors API naming

On Thu, 21 Dec 2006 19:47:58 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
> Nope, that's what I meant.  The spec should give more examples,  
> particularly in the simplistic cases.  The one case I wanted a  
> definition for was if there is no doctype given on an HTML document, and  
> there is a specific namespace given for XHTML (or whatever), does it  
> match?  (e.g. is there a presumed doctype default for HTML in browsers,  
> and if so what is it.  I would prefer not, BTW.)

How HTML documents end up in the DOM is an issue of the HTML WG / WHATWG.  
The HTML5 proposal puts HTML elemenets in the http://www.w3.org/1999/xhtml  
namespace during parsing. I don't think that's implemented in any user  
agent yet. What is implemented is that HTML elements are assumed to be in  
that namespace for the purposes of CSS. Anyway, not our issue in my  
opinion. You're free however to provide more examples for inclusion in the  
specification.


-- 
Anne van Kesteren

Re: Selectors API naming

[Anne van Kesteren]

Currently the following methods exist:

 * document.getElementsByTagName()
 * document.getElementsByName() (HTML only)
 * document.getElementById()

The following method is proposed by the WHATWG:

 * document.getElementsByClassName()

These four methods all return a _live_ NodeList meaning that when  
something in the DOM is changed the variable that holds the NodeList is  
changed accordingly, if needed.


If we would name the new pair as follows:

 * document.getElementBySelector()
 * document.getElementsBySelector()

They would not be consistent with the previous four mentioned methods as  
they would not return a live NodeList but a StaticNodeList. Which means  
that when an attribute value changes the StaticNodeList does not need to  
be updated for a group of selectors that uses an attribute selector  
somewhere.


These names would also be slightly confusing as they would not take a  
selector but rather a group of selectors. I suppose the group in favor of  
these methods find that acceptable. I wonder if they find the  
inconsistency with the other DOM methods to be acceptable as well.  
Personally I don't really like that.



It seems that libraries find there's a need to provide shortcuts for the  
several of the above mentioned methods (notably document.getElementById  
and document.getElementsByTagName). Several authors have argued that they  
don't see a need for such a thing but no "evidence" has been provided. No  
evidence to the contrary either, though.



I'm personally not really convinced by the autocomplete argument. I don't  
really think it's good language design to assume there's such a thing.



I'm still leaning towards not changing the draft with regard to naming for  
reasons mentioned above, but if someone can tackle the problems mentioned  
above I'm willing to reconsider.



--
Anne van Kesteren

Re: NSResolver Re: Selectors API naming

[Anne van Kesteren]

On Thu, 21 Dec 2006 19:47:58 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:
Nope, that's what I meant.  The spec should give more examples,  
particularly in the simplistic cases.  The one case I wanted a  
definition for was if there is no doctype given on an HTML document, and  
there is a specific namespace given for XHTML (or whatever), does it  
match?  (e.g. is there a presumed doctype default for HTML in browsers,  
and if so what is it.  I would prefer not, BTW.)


How HTML documents end up in the DOM is an issue of the HTML WG / WHATWG.  
The HTML5 proposal puts HTML elemenets in the http://www.w3.org/1999/xhtml  
namespace during parsing. I don't think that's implemented in any user  
agent yet. What is implemented is that HTML elements are assumed to be in  
that namespace for the purposes of CSS. Anyway, not our issue in my  
opinion. You're free however to provide more examples for inclusion in the  
specification.



--
Anne van Kesteren

Re: ProgressEvent Re: Liason statement from JSR 280

[Charles McCathieNevile]

On Fri, 15 Dec 2006 16:37:38 +0100, Ellen Siegel <[EMAIL PROTECTED]>  
wrote:


I will put your current draft version into the upcoming 280 Proposed  
Final Draft

spec that we plan to publish in early January.

The main issue remaining, then is to determine when this interface can be
considered final from the W3C point of view. JSR 280 currently plans to  
go to Final Approval Ballot (frozen spec) in the beginning of April, but

we would depend on having the W3C API we depend on be frozen as well or
we risk future incompatibility. Do you have any idea when you plan to go
to your public review, and when it would close?


Hi Ellen,

At this stage our plan would mean it is difficult to go to Last Call  
before April, and it would close after all comments have been  
satisfactorily dealt with - so a minimum would be about 6 weeks if the  
spec is already perfect.


I can attempt to bring forward the publication schedule somewhat, but I am  
not sure how much I can manage there.


cheers

Chaals



2. ProgressEvent
...

Hi Ellen, Nandini, Vincent,

I have published a first editor's draft [1] of a Progress event roughly  
based on

the specification in SVG 1.2 [2]. Comments are most welcome

[1]  
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html

[2] http://www.w3.org/TR/SVGMobile12/svgudom.html#events__ProgressEvent





--
  Charles McCathieNevile, Opera Software: Standards Group
  hablo español  -  je parle français  -  jeg lærer norsk
[EMAIL PROTECTED]  Try Opera 9 now! http://opera.com

RE: NSResolver Re: Selectors API naming

[Chris Wilson]

Nope, that's what I meant.  The spec should give more examples, particularly in 
the simplistic cases.  The one case I wanted a definition for was if there is 
no doctype given on an HTML document, and there is a specific namespace given 
for XHTML (or whatever), does it match?  (e.g. is there a presumed doctype 
default for HTML in browsers, and if so what is it.  I would prefer not, BTW.)

-Original Message-
From: Charles McCathieNevile [mailto:[EMAIL PROTECTED] 
Sent: Thursday, December 21, 2006 10:42 AM
To: Chris Wilson; Dave Massy; Web API public
Cc: Anne van Kesteren; Tina Duff
Subject: Re: NSResolver Re: Selectors API naming

On Thu, 21 Dec 2006 19:09:17 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:

> Wow, sorry, a bunch of messages got caught in spam filter temporarily.
>
> I think the point was overcommunicating how this works in the spec would  
> be a really good idea, not "this doesn't work well."

Not quite sure I follow you, but If you mean "We should explain this in  
more detail" then I am with you (doubly so if you have proposed text and  
examples for the spec ;) ). If you mean something else, I am confused...

cheers

Chaals

> -Original Message-
> From: Charles McCathieNevile [mailto:[EMAIL PROTECTED]
> Sent: Tuesday, December 19, 2006 12:59 PM
> To: Dave Massy; Web API public
> Cc: Chris Wilson; Anne van Kesteren; Tina Duff
> Subject: NSResolver Re: Selectors API naming
>
> On Tue, 19 Dec 2006 21:35:17 +0100, Dave Massy <[EMAIL PROTECTED]>
> wrote:
>
>> It'd be great to have more detail and scenario on NSResolver. It appears
>> to allow elements within the document to have different prefixes than
>> things in the style sheet. For example if we map html as the prefix for
>> XHTML in our document then we’d write it like:
>>  
>> But then we can write a selector such as:
>>  “h|table > h|tr > h|td”
>> With a NSResolver that maps h to the same namespace as the html in the
>> primary document. This seems potentially confusing.
>
> Hmm. This seems blindingly obvious to me, as something that if anyone  
> ever
> forces me to hand-code I automatically do. This is how namespaces work in
> general. Admittedly, if you are sharing code snippets amongst people who
> have no shared understanding and are not really aware of what namespace
> prefixes provide (a shorthand for a simple URI-based disambiguation
> scheme), then using this feature can be confusing. I don't see that as a
> reason to disallow the use case of simplifying my half of some code,  
> since
> there is no obvious technical problem here.
>
> cheers
>
> Chaals
>



-- 
   Charles McCathieNevile, Opera Software: Standards Group
   hablo español  -  je parle français  -  jeg lærer norsk
[EMAIL PROTECTED]  Try Opera 9 now! http://opera.com

Re: NSResolver Re: Selectors API naming

[Charles McCathieNevile]

On Thu, 21 Dec 2006 19:09:17 +0100, Chris Wilson  
<[EMAIL PROTECTED]> wrote:



Wow, sorry, a bunch of messages got caught in spam filter temporarily.

I think the point was overcommunicating how this works in the spec would  
be a really good idea, not "this doesn't work well."


Not quite sure I follow you, but If you mean "We should explain this in  
more detail" then I am with you (doubly so if you have proposed text and  
examples for the spec ;) ). If you mean something else, I am confused...


cheers

Chaals


-Original Message-
From: Charles McCathieNevile [mailto:[EMAIL PROTECTED]
Sent: Tuesday, December 19, 2006 12:59 PM
To: Dave Massy; Web API public
Cc: Chris Wilson; Anne van Kesteren; Tina Duff
Subject: NSResolver Re: Selectors API naming

On Tue, 19 Dec 2006 21:35:17 +0100, Dave Massy <[EMAIL PROTECTED]>
wrote:


It'd be great to have more detail and scenario on NSResolver. It appears
to allow elements within the document to have different prefixes than
things in the style sheet. For example if we map html as the prefix for
XHTML in our document then we’d write it like:

But then we can write a selector such as:
“h|table > h|tr > h|td”
With a NSResolver that maps h to the same namespace as the html in the
primary document. This seems potentially confusing.


Hmm. This seems blindingly obvious to me, as something that if anyone  
ever

forces me to hand-code I automatically do. This is how namespaces work in
general. Admittedly, if you are sharing code snippets amongst people who
have no shared understanding and are not really aware of what namespace
prefixes provide (a shorthand for a simple URI-based disambiguation
scheme), then using this feature can be confusing. I don't see that as a
reason to disallow the use case of simplifying my half of some code,  
since

there is no obvious technical problem here.

cheers

Chaals





--
  Charles McCathieNevile, Opera Software: Standards Group
  hablo español  -  je parle français  -  jeg lærer norsk
[EMAIL PROTECTED]  Try Opera 9 now! http://opera.com

RE: NSResolver Re: Selectors API naming

[Chris Wilson]

Wow, sorry, a bunch of messages got caught in spam filter temporarily.

I think the point was overcommunicating how this works in the spec would be a 
really good idea, not "this doesn't work well."

-Original Message-
From: Charles McCathieNevile [mailto:[EMAIL PROTECTED] 
Sent: Tuesday, December 19, 2006 12:59 PM
To: Dave Massy; Web API public
Cc: Chris Wilson; Anne van Kesteren; Tina Duff
Subject: NSResolver Re: Selectors API naming

On Tue, 19 Dec 2006 21:35:17 +0100, Dave Massy <[EMAIL PROTECTED]>  
wrote:

> It'd be great to have more detail and scenario on NSResolver. It appears  
> to allow elements within the document to have different prefixes than  
> things in the style sheet. For example if we map html as the prefix for  
> XHTML in our document then we’d write it like:
>   
> But then we can write a selector such as:
>   “h|table > h|tr > h|td”
> With a NSResolver that maps h to the same namespace as the html in the  
> primary document. This seems potentially confusing.

Hmm. This seems blindingly obvious to me, as something that if anyone ever  
forces me to hand-code I automatically do. This is how namespaces work in  
general. Admittedly, if you are sharing code snippets amongst people who  
have no shared understanding and are not really aware of what namespace  
prefixes provide (a shorthand for a simple URI-based disambiguation  
scheme), then using this feature can be confusing. I don't see that as a  
reason to disallow the use case of simplifying my half of some code, since  
there is no obvious technical problem here.

cheers

Chaals

-- 
   Charles McCathieNevile, Opera Software: Standards Group
   hablo español  -  je parle français  -  jeg lærer norsk
[EMAIL PROTECTED]  Try Opera 9 now! http://opera.com

Re: Selectors API naming

[Christophe Jolif]

Martijn wrote:


On 12/20/06, Anne van Kesteren <[EMAIL PROTECTED]> wrote:
One of the arguments that was made was also that the existing methods 
have

failed, which would make #3 the odd one out and probably #2 as well. "I
don't really care what the final name, but it should match the first
principle..."



I don't think the existing methods have failed.


Yes, I might be the only one, but I use getElementById every day without 
feeling like I need a shortcut (IDEs auto-completion is your friend)!



--
Christophe

Re: Selectors API naming

[Hallvord R. M. Steen]

On Tue, 19 Dec 2006 21:50:44 +0100, Anne van Kesteren <[EMAIL PROTECTED]>  
wrote:


getElementBySelector/getElementsBySelector is the only proposal we  
think is acceptable.


But it's not accurate. This also creates the problem Ian Hickson pointed  
out a few times. That people will map it to $$ or something which makes  
it even less useful.


People will do that anyway for obfuscation/convenience/wrapper function  
features/compatibility layers and similar reasons. I don't really see that  
as a problem.


"getElementsByTagName" is annoying but it's mostly because of that extra  
capitalised N. My vote would be consistency with the other DOM functions  
and thus getElement(s)BySelector .


--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience