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

Hi Ian,

Thanks for your comments.

On Mar 27, 2006, at 7:41 PM, Ian Hickson wrote:

> 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.

This is badly worded, but the intent is to say, "you don't have to be  
a traditional browser-style visual interactive HTML user agent for  
this stuff to be useful." Can you suggest a better wording? If not,  
maybe I'll just drop this sentence.

> 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.

Agreed, it shouldn't say "the main purpose". I'll reword this to say  
that is one feature of the Window object (the spec will actually  
require that it be implemented by the ECMAScript global scope for in- 
page script execution such as <script> elements or event listener  
markup) and put it last, since that aspect is not language-independent.

> 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.)

Should I move the definition to before the first use? Any use of  
"window object" is a mistake. "Window Object 1.0" is the title of the  
specification, I try to use it only with the version number. "Window  
object" is "an object that implements the Window interface", so I  
don't have to keep writing the 7-word phrase. "Window interface" is  
the interface as defined.

> Is the Introduction meant to be normative?

No, I should mark it non-normative.

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

I'll change it to "in addition".

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

Will fix.

> 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".

I agree, I'll change ReSpec to handle this and apply it.

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

Agreed.

> | 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.

Works for me.

> 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.

I suppose that depends on how much you reify the abstraction. I'm not  
sure it is good to define it as just the set of views, but maybe that  
works.


>
> "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.

I need to think about this. I think removing this requirement would  
make some of the conformance criteria either inconsistent with this  
possibility or untestable.

For instance I intend to require that the default view for all  
documents in the sequence must be the same object, since this  
behavior is interoperably implemented and depended on by some  
content. This would not be consistent with the same browsing context  
presenting multiple documents given the requirement that the document  
property of the Window object must be the document being presented.

I think it would be better to say that if you are presenting multiple  
documents at once, you have multiple browsing contexts, even if they  
are tied together in some way.

Can you think of a particular UI innovation, however crazy, that  
would benefit from a single browsing context presenting multiple  
documents from its sequence at once?


> "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.

Yes, the detail is planned for the Navigation section. I intended  
this to ultimately be a link to the definition of "navigate". Do you  
think it would be better to omit it here?

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

Will fix.

> "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").

I'll strike the first clause.

> 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?

I would have to compare the latest WHATWG text to evaluate this  
possibility.

> "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.

OK, I'll take this suggestion. DocumentWindow needs the same treatment.

> "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.

I'll do one of those (need to check the context).

>
>
>     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.

The behavior of replaceable attributes will be described in the  
(forthcoming) ECMAScript appendix, along with behavior when  
attempting to assign or delete readonly attributes, delete non-read- 
only attributes, shadow attributes with a var declaration, etc.

> 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.

I'll make the definitions the same but keep a clarifying statement of  
fact on the "self", does that sound ok?


> : 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.

I agree with you that it is more important, but I think it helps  
clarity to leave language-specific issues to separate sections. Let's  
revisit this once the appendix actually exists, so we can see how the  
spec reads that way.


> "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.

Nothing forbids documents not being presented in a browsing context  
from implementing the DocumentView or DocumentWindow interface, and  
it may be more convenient for implementations that have both  
presented and non-presented documents to use a single implementation  
for both. But maybe it's not our business to say how such documents  
behave, so I'll strike this.

> 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.

Yep, still a work in progress.

> 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 didn't actually look at the WHATWG spec for this interface yet, the  
bits of it that I wrote were based on reading docs and/or  
implementation code for Safari, Firefox and IE. I will make sure to  
look at the WHATWG spec when fleshing out this section.

> 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.)

Anne wrote this section, using the terminology from CDRF, I plan to  
take a pass at it to define things in terms of browsing contexts as  
you suggest (I believe there is an editor's note to that effect).

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

Examples are supposed to be in grey boxes, but unfortunately so is  
IDL. Normative requirements are distiguished by the use of an RFC2119  
keyword, these are in small caps. Terms being defined are bold with a  
green background. Informative notes are not specially distinguished  
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 purpose of this section is so that CDF doesn't have to duplicate  
the relevant de facto functionality. I don't think it will be hard to  
get it specced out in more detail.

> "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.

I agree, I'll review this in context.

> "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.

Well, the spec could normatively require the standard web security  
model for prevention of cross-site scripting exploits, but I have two  
main concerns with this:

1) This might not be appropriate for all classes of implementations.

2) It is possible that there is some as yet unknown flaw in the  
standard model, I would not want the spec to normatively require it  
if it were discovered to be insecure. As an example of a recent  
improvement in understanding, until recently browsers allowed any  
frame to target a navigation to any named frame or top-level window,  
since assigning to location on any window object is allowed in the  
standard model. But this was discovered to be possibly exploitable  
for phishing / pharming attacks, so now browsers restrict what frames  
are visible by name. Maybe we should just bite the bullet and accept  
the need for spec errata if flaws are discovered. I'll raise this as  
an issue.


> "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 spec will end up defining the way "name" relates to specific HTML  
elements, I don't think it makes sense to leave it vague and does no  
harm for the non-HTML case.


> 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.

It will be rewritten to be organized like the earlier sections.

> 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.

I'll raise an issue on this. I have come to the conclusion that for  
timers we need to either invent a new feature that can reasonably be  
specified in a language-neutral way (while maintaining setTimeout,  
etc as ECMAScript-specific interfaces), or specify timers only for  
ECMAScript and allow other languages to depend on language-specific  
facilities. However, I don't know enough about Java or how in- 
document Java scripting for SVG works to know if Java-native timer  
facilities will work in a web context. In many languages such  
facilities depend on running some sort of event loop, and for web  
documents the browser controls the event loop.

> I hope this review helped.

It was helpful, thanks. Although it will take me a while to apply all  
the suggested improvements.

> 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.

Sounds good.

Regards,
Maciej

Received on Tuesday, 28 March 2006 05:50:19 UTC