Re: Further update to Window Object 1.0, I think it's ready for first Working Draft

On Mon, 27 Mar 2006, Maciej Stachowiak wrote:
>
> http://dev.w3.org/cvsweb/~checkout~/2006/webapi/Window/publish/Window.html

"With this specification, it is recommended for all implementations that 
present documents to the user or provide the equivalent of a browsing 
context." makes no sense.


I don't think I agree with:

   The main purpose of the Window object is to provide the global 
   namespace for script execution.

That's the purpose of the global scope object, which is an ECMAScript 
concept. As specced, the Window interface (it's not an object) is just 
something that the global scope object implements.


You inconsistently refer to the "window object", "Window object", "Window 
interface", etc, in a way that is a bit subtle for me. In particular, 
speaking of the Window object in the singular and with that capitalisation 
seems a bit odd to me. (later note: It seems this may be because you 
define "Window object" after you first use it.)


Is the Introduction meant to be normative?


Starting a sentence with "And finally" is poor form.


You have "this section is informative" twice in" 1.2. Not in This 
Specification".


I personally have issue with the word "informative" used as an antonym to 
the word "normative". I've often read specs that say "this section is 
informative" and gotten very confused and thought "no it isn't, it's 
highly uninformative". I recommend using the term "non-normative".


"MUST, REQUIRED and SHALL level criteria" should be "MUST-, 
REQUIRED- and SHALL-level criteria".


| Need to define the term "document"?

If you do, I'd define it as "A document is an object that implements the 
Document interface" or some such.


I'd like to make the WHATWG and W3C definitions of "browsing context" 
identical. The following comments are related to trying to get these 
definitions closer together. They are all "nits" except for the fact that 
they are the cause of differences between these specs.

"A browsing context is a place where a user agent presents a document"

I don't think this is true. A browsing context isn't a place, it's a set 
of views.

"Only one document of this sequence is presented at a time."

This is a statement of fact, and as such is incorrect. There is no 
technical reason why a UA couldn't show multiple documents from a browsing 
context at once; the WHATWG spec goes to some lengths to not preclude 
crazy UI "innovations" and I think the Window spec should likewise avoid 
limiting allowed UI unnecessarily.

"A browsing context is said to navigate when it changes from presenting 
one document to another, for example by following a hyperlink. More is 
specified about navigation behavior in the Navigation section."

This is not enough detail, and I remove moving that entire quote to a 
later section where navigation of browsing contexts can be considered 
separately.

"An visual user" is a typo ("a").

"In a conforming implementation, an object that implements the Document 
interface [DOM3Core] and is presented in a browsing context MUST also 
implement the DocumentWindow interface."

The first four words of that sentence are redundant (given your earlier 
definitions of "conforming" and "must").

Overall, would you consider using the WHATWG text instead of the current 
Window text? What is it about the WHATWG text that would need to change in 
order to make that possible?


"The Window interface is fully specified in IDL in the IDL Definitions 
Appendix. To better organize this specification, it is described in prose 
in mulitple IDL fragments."

I find it really useful to have one place, in the spec itself, which 
hyperlinks all the various parts of the interface together. If it would be 
possible to have one interface at the top of the Window section that would 
be great, even if parts of it are then later duplicated.


"In addition to the DocumentView interface, the Document MUST implement 
the Document and DocumentWindow interfaces."

This is redundant. You already required this. Either drop it or make it a 
statement of fact.


    readonly attribute Window window;
    readonly attribute Window self;

It seems that while "window" is readonly, "self" is replaceable in 
Mozilla (at least). The spec doesn't currently mention anything like this.


I think it's confusing that you have different definitions for "self" and 
"window". I also think it's confusing that you have two MUST requirements 
for what "self" should be -- if you can't just use the same definition, 
you should at least make one of those two definitions a statement of fact.


: 2.1.2. Use in scripting
:
: The Window object also has a special role as the global scope for 
: scripts in the document in languages such as ECMAScript [ECMAScript]. 
: Such use is specified by individual language bindings. For ECMAScript it 
: is specified in the ECMAScript Language Binding Appendix.

Given that the ECMAScript binding is far more important than the others, 
I'd like to request that things that affect that binding be moved into the 
main prose instead of being relegated to an appendix.


"For documents not being presented in a browsing context, the value of the 
defaultView attribute MUST be null."

There is no requirement in the spec that such documents even implement 
this interface, so that seems wrong. Indeed the spec is clear that it is 
documents that _are_ in browsing contexts that implement this.

So I would request that this be removed. Documents not being presented in 
a browsing context wouldn't even have the defaultView attribute.


Sections "3.1. The Window Interface, Location Attributes" and "3.2. The 
DocumentWindow Interface, Location Attributes" are woefully inadequate 
right now so I've not looked at them in detail.


Section "3.3. The Location Interface" duplicates the definitions in the 
WHATWG spec. Is there any way we can just use the text from the WHATWG 
spec here? The WHATWG spec is equally incomplete, but I'd like to not have 
to fork here.

I haven't looked at the rest of section 3 in any more detail since this 
section is very incomplete right now.


"When a document has no embedding element that points to it the document 
is a root document."

Any chance we could use the WHATWG terminology here? ("top-level browsing 
context document") It avoids the word "root" which I think is overloaded 
enough already. (You actually use the term "top-level browsing context" in 
the spec already, though without defining it.)


I'd like the spec to make clearer typographic distinctions between 
normative text, "informative" notes, and examples. It's a little confusing 
right now.


"4. Embedding: Compound Documents by Reference" doesn't seem to have an 
associated IDL (it does, it just comes afterwards instead of before, like 
the previous sections). The section in general feels unsure about what it 
is defining; should it be left up to CDF?


"The name attribute of a Window object MUST be the name assigned by the 
embedding element, the empty string if there is no such element or a value 
set by the script author." makes not as much sense as it should.


"Security should probably be taken care of in a separate part of the 
specification."

Please don't relegate security to an after-thought. It should IMHO be 
defined right there in the part the implementors are going to read, and 
the separate security section should be a set of statements of fact 
explaining the reasons for various requirements in the prose.


"does it make sense to spec this without being html-specific or defining 
open?"

I don't understand the problem with being HTML-specific here. Pragmatism 
should win over theoretical purity.


The "4.1. The Window Interface, Embedding Attributes" section "defines" 
("informatively") the bits that are actually normative defined in the 
earlier block of text. This is inconsistent with how the earlier part of 
the spec is organised.


The "5.1. The Window Interface, Timer Attributes" section is woefully 
inadequate. See the WHATWG spec.


Notwithstanding the fact that the WHATWG spec makes the same mistake, 
the "5.2. The TimerListener Interface" section should IMHO be dropped. The 
setTimeout(), etc, APIs are ECMAScript-specific, and it makes no sense to 
make them available to other languages. In fact in other languages there 
are bound to be much better ways of doing timeouts than using DOM APIs.


Thanks for the acknowledgement.


I hope this review helped. I look forward to reviewing a more substantial 
version of this spec in due course, and hope we can work closely in 
aligning this spec with the WHATWG spec to avoid contradictions and keep 
the overlap at a minimum going forward.

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

Received on Tuesday, 28 March 2006 03:41:47 UTC