[Fwd: Re: Document element]
Boris Zbarsky
-------- Original Message --------
Subject: Re: Document element
Date: Tue, 09 May 2006 11:04:51 -0500
From: Boris Zbarsky <bzba...@mit.edu>
Christian Biesinger wrote:
> They are contained on other interfaces, such as nsIDOMNSDocument,
> nsIDOMHTMLDocument, etc.
But the page [1] doesn't make that clear. What's worse is that it tries and
fails -- for example, it claims that document.designMode is not HTML-specific,
and same for document.write and company.
The page also includes document.contentWindow, which isn't even a property in
Gecko; I have no idea how it ended up with an entry here AND a page of its own.
Both should be removed.
This whole page really needs a thorough read-through and redesign, especially
since non-HTML documents are popular now (with XMLHTTPRequest and company) and
they have methods and properties that are not on either Document or HTMLDocument....
-Boris
Martijn
On 5/10/06, Boris Zbarsky <bzba...@mit.edu> wrote:
>
> -------- Original Message --------
> Subject: Re: Document element
> Date: Tue, 09 May 2006 11:04:51 -0500
> From: Boris Zbarsky <bzba...@mit.edu>
>
> Christian Biesinger wrote:
> > They are contained on other interfaces, such as nsIDOMNSDocument,
> > nsIDOMHTMLDocument, etc.
>
> But the page [1] doesn't make that clear. What's worse is that it tries and
> fails -- for example, it claims that document.designMode is not HTML-specific,
> and same for document.write and company.
I've added a remark that document.designMode is HTML specific. It
seems to me a lot more properties on that page are HTML specific.
Maybe things need to be split out in a Document and a HTMLDocument, etc?
Maybe even splitting stuff out in all the stuff that can be found in
the document.idl files:
http://lxr.mozilla.org/seamonkey/find?string=document.idl
(the inheritance graph of lxr doesn't seem to work)
> The page also includes document.contentWindow, which isn't even a property in
> Gecko; I have no idea how it ended up with an entry here AND a page of its own.
> Both should be removed.
I removed the document.contentWindow reference.
I tried to remove
http://developer.mozilla.org/en/docs/DOM:document.contentWindow , but
it seems I only removed the contents, how can I remove it totally?
Does somebody know how to do that?
And I see also a mention of document.width and document.height. I
don't think those exist in Mozilla, so I think those can also be
removed.
Regards,
Martijn
> This whole page really needs a thorough read-through and redesign, especially
> since non-HTML documents are popular now (with XMLHTTPRequest and company) and
> they have methods and properties that are not on either Document or HTMLDocument....
>
> -Boris
>
> [1] http://developer.mozilla.org/en/docs/DOM:document
> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
>
L. David Baron
> >Christian Biesinger wrote:
> >> They are contained on other interfaces, such as nsIDOMNSDocument,
> >> nsIDOMHTMLDocument, etc.
> >
> >But the page [1] doesn't make that clear. What's worse is that it tries
> >and
> >fails -- for example, it claims that document.designMode is not
> >HTML-specific,
> >and same for document.write and company.
> >[1] http://developer.mozilla.org/en/docs/DOM:document
I think the DOM Reference needs a major reorganization if it's to be
both accurate and useful. For my thoughts on what needs to happen, see:
https://mail.mozilla.org/pipermail/devmo-general/2006-January/000656.html
(and also the followups in that thread).
Tweaking pages bit by bit isn't going to fix the fundamental
organizational problems.
-David
--
L. David Baron <URL: http://dbaron.org/ >
Technical Lead, Layout & CSS, Mozilla Corporation
Nickolay Ponomarev
> I tried to remove
> http://developer.mozilla.org/en/docs/DOM:document.contentWindow , but
> it seems I only removed the contents, how can I remove it totally?
> Does somebody know how to do that?
I deleted it, you need special privs for that. Next time, please
either ask in #devmo or mark the page as [[Category:Junk]] instead of
simply blanking it.
Nickolay
Boris Zbarsky
> Maybe things need to be split out in a Document and a HTMLDocument, etc?
> Maybe even splitting stuff out in all the stuff that can be found in
> the document.idl files:
> http://lxr.mozilla.org/seamonkey/find?string=document.idl
> (the inheritance graph of lxr doesn't seem to work)
It makes sense to split out by concrete class, but not by interface. For
example, all our Documents implement nsIDOMNSDocumentXBL.
Also, some HTMLDocument stuff is not supported in XHTML (e.g. document.write),
while other parts are.
> And I see also a mention of document.width and document.height. I
> don't think those exist in Mozilla, so I think those can also be
> removed.
Yeah, indeed.
Thanks for dealing with this!
-Boris
Nickolay Ponomarev
> Martijn wrote:
> > And I see also a mention of document.width and document.height. I
> > don't think those exist in Mozilla, so I think those can also be
> > removed.
>
> Yeah, indeed.
>
their docs should be updated, I don't know.
http://landfill.mozilla.org/mxr-test/mozilla/source/dom/public/idl/html/nsIDOMNSHTMLDocument.idl#45
Nickolay
Nickolay Ponomarev
> I think the DOM Reference needs a major reorganization if it's to be
> both accurate and useful. For my thoughts on what needs to happen, see:
> https://mail.mozilla.org/pipermail/devmo-general/2006-January/000656.html
> (and also the followups in that thread).
>
> Tweaking pages bit by bit isn't going to fix the fundamental
> organizational problems.
>
the individual pages, so the little improvements that are being made
over time are not a waste of resources.
I think everyone familiar with our DOM reference agrees it needs to be
organized differently. The problem is that it's quite a bit of work
and nobody has volunteered to do the reorganization.
Nickolay
Justin Wood (Callek)
> I think everyone familiar with our DOM reference agrees it needs to be
> organized differently. The problem is that it's quite a bit of work
> and nobody has volunteered to do the reorganization.
>
This implies a particular plan is allready established, if so; where?
And if not placed somewhere, why?
And lastly, if there is no plan, we need it first before anyone would
volunteer (imho).
I would gladly help with the re-org if a clear-cut plan was
established, where, without knowing all the finer details of the DOM,
I could still contribute to the work.
~Justin Wood (Callek)
Nickolay Ponomarev
> On 8/27/06, Nickolay Ponomarev <asqu...@gmail.com> wrote:
> > I think everyone familiar with our DOM reference agrees it needs to be
> > organized differently. The problem is that it's quite a bit of work
> > and nobody has volunteered to do the reorganization.
> >
>
> This implies a particular plan is allready established, if so; where?
>
> And if not placed somewhere, why?
>
> And lastly, if there is no plan, we need it first before anyone would
> volunteer (imho).
>
the reference and plan the required changes appropriately.
David's post has many good points, but it's still not a comprehensive plan.
Nickolay
Martijn
Ah yeah, sorry, now I remember it again. document.width and
document.height return document.body.offsetWidth and
document.body.offsetHeight (at least it did that, last time I tested
it).
I looked at those properties some time ago, hoping they would return
the real document width and height, but I had to use window.innerWidth
+ window.scrollMaxX instead (similar for the height).
Regards,
Martijn
> Nickolay
>
Martijn
> either ask in #devmo or mark the page as [[Category:Junk]] instead of
> simply blanking it.
Sorry, about that, I was acting too hasty, I see now where that is written down:
http://developer.mozilla.org/en/docs/MDC:Getting_started#Requesting_page_deletions
Regards,
Martijn
> Nickolay
>
Martijn
> > Maybe even splitting stuff out in all the stuff that can be found in
> > the document.idl files:
> > http://lxr.mozilla.org/seamonkey/find?string=document.idl
> > (the inheritance graph of lxr doesn't seem to work)
>
> It makes sense to split out by concrete class, but not by interface. For
> example, all our Documents implement nsIDOMNSDocumentXBL.
I'm not sure what you mean by concrete class, you mean a certain
subset of interfaces?
So I would like to document that as:
http://developer.mozilla.org/en/docs/DOM:nsIDOMNSDocumentXBL
http://developer.mozilla.org/en/docs/DOM:nsIDOMNSDocumentXBL.getAnonymousNodes
But that's not something you like? Why not?
> Thanks for dealing with this!
Heh, well, I wasn't promising anything. I was just struck by the fact
that nothing has been done since your first mail. But as I understand
now, that's because it's not really certain how to organize the DOM
reference. Justin and Nickolay certainly seem to be willing to
contribute.
David made a lot of good suggestions in his mail (
https://mail.mozilla.org/pipermail/devmo-general/2006-January/000656.html
)
I think I prefer the [DOM:interface.property] naming scheme, so it's
organized like the .idl files.
But if a different naming scheme is decided, that's fine for me too.
It seems to me there are 3 different naming schemes that can be chosen
(this is from David's mail):
[DOM:object.property]
[DOM:property]
[DOM:interface.property]
I prefer the last one, because I think this will prevent naming
conflicts and will prevent duplicate documentation.
Regards,
Martijn
> -Boris
Andreas Wuest
On 8/28/06, Martijn <martijn...@gmail.com> wrote:
> On 8/27/06, Boris Zbarsky <bzba...@mit.edu> wrote:
> > Martijn wrote:
> > > Maybe things need to be split out in a Document and a HTMLDocument, etc?
> > > Maybe even splitting stuff out in all the stuff that can be found in
> > > the document.idl files:
> > > http://lxr.mozilla.org/seamonkey/find?string=document.idl
> > > (the inheritance graph of lxr doesn't seem to work)
> >
> > It makes sense to split out by concrete class, but not by interface. For
> > example, all our Documents implement nsIDOMNSDocumentXBL.
>
> I'm not sure what you mean by concrete class, you mean a certain
> subset of interfaces?
> So I would like to document that as:
> http://developer.mozilla.org/en/docs/DOM:nsIDOMNSDocumentXBL
> http://developer.mozilla.org/en/docs/DOM:nsIDOMNSDocumentXBL.getAnonymousNodes
> But that's not something you like? Why not?
Note that I, from the POV of an extensions developer, do not have any
objections against organising things like this.
But thinking about web developers, who want to access the DOM using
embedded JavaScript, I don't know if that makes sense for them. I
don't know if they know, or even care, about the Mozilla interfaces
which are used to access which properties, methods, etc. It might even
confuse them. I guess it would be better if you told them, well, if
you have an HTML document, then you can access this and this stuff, if
you have an XHTML document, then you can do this and that, etc.
Of course, you could also argue that they should simply look at what
is there, and just not get confused by the interfaces information.
The point I want to get across is, that we should think about the
target audience: do they know the concept of interfaces, and do they
know how this translates into their world, or are we targeting
extension developers who access the DOM programmatically through
XPCOM.
--
Kind regards,
Andi
Nickolay Ponomarev
> On 8/28/06, Martijn <martijn...@gmail.com> wrote:
> > So I would like to document that as:
> > http://developer.mozilla.org/en/docs/DOM:nsIDOMNSDocumentXBL
> > http://developer.mozilla.org/en/docs/DOM:nsIDOMNSDocumentXBL.getAnonymousNodes
> > But that's not something you like? Why not?
>
> Note that I, from the POV of an extensions developer, do not have any
> objections against organising things like this.
>
> But thinking about web developers, who want to access the DOM using
> embedded JavaScript, I don't know if that makes sense for them. I
> don't know if they know, or even care, about the Mozilla interfaces
> which are used to access which properties, methods, etc. It might even
> confuse them.
Yes, that's why the reference originally didn't mention interfaces at
all and documented NodeList.length at DOM:element.length. It just
didn't work out.
We have to mention interfaces if we are to be technically correct. And
I think it's not a big problem if we also provide an object-focused
view (i.e. pages that list all properties of a particular object from
all interfaces it implements) as I suggested in my other mail.
Nickolay
Boris Zbarsky
> I'm not sure what you mean by concrete class, you mean a certain
> subset of interfaces?
Sure, you could think of it that way.
I guess what I feel is more important to authors is what properties are
available for an HTML document than what precise properties are available for
each of the numerous interfaces an HTML document implements. Just listing the
scriptable ones:
Applicable to all documents:
nsIDOMDocument
nsIDOM3Document (DOM3 stuff added to nsIDOMDocument; authors
shouldn't have to know it exists)
nsIDOMNSDocument
nsIDOMDocumentEvent
nsIDOM3DocumentEvent (DOM3 stuff added to nsIDOMDocumentEvent)
nsIDOMDocumentStyle
nsIDOMNSDocumentStyle
nsIDOMDocumentView
nsIDOMDocumentRange
nsIDOMDocumentTraversal
nsIDOMDocumentXBL
nsIDOMEventTarget
nsIDOM3EventTarget (DOM3 stuff added to nsIDOMEventTarget)
nsIDOMNSEventTarget
nsIDOMNode
nsIDOMXPathEvaluator
HTML document only:
nsIDOMHTMLDocument
nsIDOMNSHTMLDocument
I guess it's fine to describe some things in terms of interfaces, but then we
need something that lists which interfaces a given object implements.
> I think I prefer the [DOM:interface.property] naming scheme, so it's
> organized like the .idl files.
The problem is that this doesn't match the W3C naming scheme well, due to the
nsIDOM3 stuff. Would it make sense to use the W3C interface names for W3C stuff
and our own names for our stuff?
-Boris