Reorganizing the DOM reference [was Fwd: Re: Document element]
Nickolay Ponomarev
> [...]
> 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.
I too prefer DOM:interface.property naming for pages. However, since
distinction between interfaces is seldom useful to authors, I think we
should also maintain pages listing all properties of an *object* (i.e.
something akin to DOM:element, but with different pages for different
objects). The duplication of property summaries is avoided through the
use of <includeonly>, like we do in the XUL reference.
There are many small questions here, that need to be answered before
starting making changes, e.g.:
- do we want to create a separate page for all kinds of objects (such
as HTMLBRElement) with majority of content - common properties listing
- duplicated, or try to fit everything on one page like DOM:element
while making it clear what object each property applies to.
- what properties and in what order are included on the interface and
object pages
- what object and interface names do we use when making up names for
the pages. We do have names for some of them in Gecko, but I'd rather
not expose the authors to internal nsIDOMNS* interfaces.
There are problems with our events documentation:
http://groups.google.com/group/mozilla.dev.mdc/browse_thread/thread/18cc2670c315506f/2b23f419ba61157f?lnk=gst&q=dom+reference&rnum=8#2b23f419ba61157f
..as well as DOM style docs as discussed earlier, see for example
http://developer.mozilla.org/en/docs/DOM:style which got better since
dbaron's mail, but still needs lots of fixes.
We still need someone to volunteer to write up a reorganization
proposal, but I figured it may help to have a list of problems to
solve.
Nickolay
Martijn
> I too prefer DOM:interface.property naming for pages. However, since
> distinction between interfaces is seldom useful to authors, I think we
> should also maintain pages listing all properties of an *object* (i.e.
> something akin to DOM:element, but with different pages for different
> objects). The duplication of property summaries is avoided through the
> use of <includeonly>, like we do in the XUL reference.
Ok, sounds like a good idea to me.
> There are many small questions here, that need to be answered before
> starting making changes, e.g.:
> - do we want to create a separate page for all kinds of objects (such
> as HTMLBRElement) with majority of content - common properties listing
> - duplicated, or try to fit everything on one page like DOM:element
> while making it clear what object each property applies to.
I think I prefer creating a separate page for all kinds of objects.
> - what properties and in what order are included on the interface and
> object pages
Alphabetical?
> - what object and interface names do we use when making up names for
> the pages. We do have names for some of them in Gecko, but I'd rather
> not expose the authors to internal nsIDOMNS* interfaces.
Just strip that part out? So instead of nsIDOMNSHTMLHRElement, use
HTMLHRElement?
> There are problems with our events documentation:
> http://groups.google.com/group/mozilla.dev.mdc/browse_thread/thread/18cc2670c315506f/2b23f419ba61157f?lnk=gst&q=dom+reference&rnum=8#2b23f419ba61157f
Yes, those need fixing too, it seems to me they can have the same kind
of idl style naming scheme, not?
So something like [[DOM:Events:DOMMouseEvent:mouseover]] for example?
Regards,
Martijn
Nickolay Ponomarev
> > There are many small questions here, that need to be answered before
> > starting making changes, e.g.:
> > - do we want to create a separate page for all kinds of objects (such
> > as HTMLBRElement) with majority of content - common properties listing
> > - duplicated, or try to fit everything on one page like DOM:element
> > while making it clear what object each property applies to.
>
> I think I prefer creating a separate page for all kinds of objects.
>
> > - what properties and in what order are included on the interface and
> > object pages
>
> Alphabetical?
>
multiple pages, and there's no way we can alleviate this via templates
due to alphabetical sort order.
> > - what object and interface names do we use when making up names for
> > the pages. We do have names for some of them in Gecko, but I'd rather
> > not expose the authors to internal nsIDOMNS* interfaces.
>
> Just strip that part out? So instead of nsIDOMNSHTMLHRElement, use
> HTMLHRElement?
>
Which is the name of the object itself too. Do we want such
element-specific interfaces have both an interface and an object page
or maybe we can just have a single object page with element-specific
properties separated from DOM Core ones. This solution seems nice to
me, but it means we're not 100% consistent.
> > There are problems with our events documentation:
> > http://groups.google.com/group/mozilla.dev.mdc/browse_thread/thread/18cc2670c315506f/2b23f419ba61157f?lnk=gst&q=dom+reference&rnum=8#2b23f419ba61157f
>
> Yes, those need fixing too, it seems to me they can have the same kind
> of idl style naming scheme, not?
> So something like [[DOM:Events:DOMMouseEvent:mouseover]] for example?
>
Yeah, probably. Someone needs to look carefully at the event-related
information we want to document and write up a proposal.
Nickolay
Martijn
> > > - do we want to create a separate page for all kinds of objects (such
> > > as HTMLBRElement) with majority of content - common properties listing
> > > - duplicated, or try to fit everything on one page like DOM:element
> > > while making it clear what object each property applies to.
> >
> > I think I prefer creating a separate page for all kinds of objects.
> >
> > > - what properties and in what order are included on the interface and
> > > object pages
> >
> > Alphabetical?
> >
> It means the long list of common properties will be duplicated across
> multiple pages, and there's no way we can alleviate this via templates
> due to alphabetical sort order.
Ah, I see the problem. Well, an alphabetical sort order would be nice
to have, but is not a must (for me at least).
Regards,
Martijn
Nickolay Ponomarev
I think there needs to be a detailed and carefully thought out plan
for a skeleton structure of how the newly re-organised DOM
documentation will be organised. This would give the contributors some
sort of guidelines and framework to code in. Something like a top down
tree structure - similar to a detailed list of contents should do.
This could start at the MDC homepage and then cover all of the
documentation.
As far as interfaces go, for someone learning web development, they
don't mean alot to me, although they are probably quite important to
others. I'm far more concerned about what DOM objects are available,
and what properties, methods and events they offer a web designer
interested in DHTML. All I need is a simple example to illustrate how
a particular property, method, or event can be used in my website
code. Quote from http://www.w3schools.com, "Never increase, beyond
what is necessary, the number of entities required to explain
anything" -- William of Ockham (1285-1349).
The DOM:style documentation is a bit vague to say the least, and I'm
not even sure if this is actually needed. I'm trying to think of a way
to document the CSS style properties, without having multiple
instances of the documents under different titles.
For non-javascripters that want to use CSS stylesheets statically,
there obviously needs to be a CSS reference for their use.
For others that want to manipulate style values through the DOM
dynamically with DHTML, maybe some sort of introducion on how to
manipulate a page element's style values would be helpfull.
This could also cover the following objects:
* style element object - which represents the <style> tag in an
(x)html document.
* styleSheet object - a member of the styleSheets array
* cssRule object - a member of the cssRules array
* style object - a property of an (x)html element
Then, for the full list of properties that can be manipulated via an
element's style object, just point them to the static CSS properties
reference. There also needs to be a note concerning javascript's
non-use of the '-' character, and that for each style property
mentioned in the static CSS reference, the '-' character needs to be
removed, and the character following the '-' upper-cased, with a few
examples as well.
Regarding a replacement for the talk system, you might want to look
at: http://newsboard.unclassified.de/ this is open-source GPL'd forum
software, that uses php and mysql. The forum markup is very similar to
MDC wikki markup.
Jabez
gmgj
http://developer.mozilla.org/en/docs/Talk:DOM:event.initKeyboardEvent.
I do not know what to do next? What I have done in the past is
identify developers actively changing the code in question and just
bring it to their attention. I could enter a bug in buzilla and ask
for clarification on what the developers want to do. I could try and
track down the mozilla folks on the DOM3 events committee. I could
post to mozillazine and / or google groups.
My goal is get the right folks to comment on this so that we could
update the documentation.
Please advise?