DOM reference documentation tracking bug



18 years ago
6 years ago


(Reporter: oeschger, Assigned: sheppy)




(Whiteboard: u=webdev p=0 c=DOM, )


(3 attachments)



18 years ago
Need a place to keep track of additions, errors, versions, etc.
Hope you guys don't mind me sticking you on here.


18 years ago

Comment 1

18 years ago
Just posted an updated doc at Waiting to see about changes. Will post there when it's ready. Also talking with Fabian
Guisset about integrating some of the introductory material he has into the
intro section of this doc.

Updating URL (for now).

Comment 2

18 years ago
I'm here :-) My email is I can't currently answer your
mails because Mozilla is in a crashing mood today when composing mails
(smoketest blocker). I'll do it asap though.
And thanks for filing this bug :-)

Comment 3

18 years ago
a few nitpicks:
When moving the doc from brownhen to, remove the link
in the footer.
I have no idea how you generate those pages, but I am always picking on 
linking to #names, when you intend to just link to then page. You get a cut
off header, which always puzzles me, and I have to find out where the heck I am.
(docbook + dssl stylesheets? you gotta love rewriting that rule)

Should have a list of -moz


Comment 4

18 years ago
Just moved these docs over to (without yet removing
the link to, Axel--but I will do so, probably take my name out of
there too :) and posted to n.p.m.dom and

I agree completely: the anchors near the tops of pages just suck. I am using
Framemaker->WebWorks->HTML, a pretty common one-two punch in the tech writing
biz, and while it has its advantages, it doesn't exactly encourage collaboration
or simple HTML source, and it does annoying things like this. 

I will add the -moz properties right away. Thanks for the suggestions, Axel

Comment 5

18 years ago
I think it's a good idea to at least have your name somewhere in there, unless
you want me to be held responsible for all the blah blah's ;-) (just kidding)

Comment 6

18 years ago
Having the examples as live pages would be cool.

And do some line wrappings on the examples, they're hard to read with such
long lines.


Comment 7

18 years ago
Hi, I was wondering what the chances of a zipped version were. For those of us
without broadband, a local copy would be really useful..


Comment 8

18 years ago
A zipped version would be good. I want to take a couple more passes at it and
integrate as much of the feedback, suggestions and examples as I can. It's
pretty drafty right now. Gimme a few days more on it and I will put a
down in that project directory. Thanks!

Comment 9

18 years ago
Just updated the introduction and preface to the domref. Still working on these

Comment 10

18 years ago
I changed the URL from brownhen to, so it's easier to find.


how about rephrasing the second paragraph in the preface section 
"Who Should Read This Guide", I had to read it twice to find out that it's legal
english ;-)
The last paragraph in "What's Gecko" does not only stop rather suddenly (;-)),
but it looks like the UI would be part of the content DOM. Those hierarchies
*should* be separate. No idea how to word that more precisely though.
API syntax has the return type of a return type :-(. I miss a few XXX there, 

example 4 misses a }, and some indention.

so much for this comment

Comment 11

18 years ago

There's a Web page that explains how to make WWP do the right thing with anchors:
The examples are from the Dynamic HTML template, I believe, but the XHTML
template should be extremely similar.

Comment 12

18 years ago
Just checked in some Element API updates: the namespace-related methods
(getAttributeNS, et cetera), a couple of other ones I was missing. Thanks a lot
for those, Fabian. Haven't started on any of the DOM3 stuff yet. Will soon.

Looking at Jeff's suggestion about the anchor->top stuff now. 
I guess I also better create a document history, at least a text file for the
cvs log. 


Comment 13

18 years ago
What does getElementsByTagName() mean on the element? Does it get all the
elements in the document to which the element belongs, or does it return the
child elements or what? tanks.

Comment 14

18 years ago
Just checked in a simple history file (history.txt, linked from TOC), added the
getElementsByTagName() method to the element reference, fooled with the template
a little.

Working on DOM3 reference stuff now. 
Not sure what to do about the HTML-only element stuff, given how things are set
up. Will stop spamming so much here. :^/

Comment 15

18 years ago
Anyone want to help out on element.innerHTML? I have a bunch of blah blahs where
I hoped to put examples and some explanation of this property's usefulness, but
I'm not really familiar with it.

If you send me stuff in whatever form I'll push it into the docs. thanks!

Comment 16

18 years ago
Just updated the domref again: pulled the not implemented stuff out of window,
added a few there, cleaned it up, and indexed that chapter as well. Also made a
new and called it

Working on these today:


Comment 17

18 years ago
Just added style reference section to the DOM book. This new chapter includes
the interfaces for the style, stylesheet, and cssRule objects, as well as the
DOM CSS properties list that I moved over from the elements chapter. 

Comment 18

18 years ago
I think you should add in the style reference that the only rules accessible 
via are the inline styles.

Comment 19

18 years ago
I think I've got all the window stuff in there now, albeit in a pretty spare
way. Also figured out how to get the titles of the pages set correctly--all of
the regular API pages were titled "Syntax", which was bad. Have a little
post-process script now that sets the right title in the HTML.

No..wait..still don't know what window.updateCommands() does. Can anyone give me
a description of this method? thanks -i.

Comment 20

18 years ago
Ok first it is a XUL-only method. It calls the updateCommands() method of the
XUL command dispatcher. I think it updates all the widgets that rely on a
<command> element whose id is passed in as argument to updateCommands().
You might want to verify this with someone like hyatt though.

Comment 21

18 years ago
A couple of little nits about the window object:
* window.Components: we should link to from

* Returns the pkcs11 object , which can be used to install drivers other
software associated with the pkcs11 protocol.
(Grammar error in "drivers other software"?)

Apart from that, it's excellent!! Thank you so much for doing this work.


Comment 22

18 years ago
Just checked in another update: have a little script that actually linkifies the
pointers to the specs at the bottom of each page (which were just sitting there
inert because I am using Framemaker->WebWorks in a not very savvy way); also
added an events chapter, which is still pretty stubby, but which I am adding to

Also added a couple more examples in the examples chapter and in some of the
document APIs (e.g., addEventListener, which is so key for the event object
stuff I've just added).

Time for a new zipfile and a PDF:
Bug in Event interface docs:

This is supposed to be the target property, which designates where the Event
object is heading.  Instead, it tells me target means a boolean on whether the
ALT key is depressed... :)

Likewise, all such dom_event_refXX.html links reflect that information.

I'll be seeking info in at #mozilla and #mozillazine for a
little while.  Would appreciate assistance (trying to complete my book; I'm on
the Events chapter).

Comment 24

18 years ago
Million more small updates. Got a great example of DOM event constants into the
Examples chapter, made lots of additions and changes to the dom_events chapter
per his last comment, including the documentation for those event.init methods,
and created a new zipped version at:


Comment 25

18 years ago
Woops. Meant to say "Got a great example of DOM event constants *from Alex
Vincent* into the Examples chapter," whence the reference to "his last comment"
later in that same sentence. ajvincent is the possessive pronoun antecedent
there. Ahem...

Comment 26

18 years ago
More updates! Added the form and table element interfaces in a new chapter
called the DOM HTML Elements Reference. Fabian and I did these and are working
on the other specialized HTML element interfaces. I expect this chapter will be
long and manifold, but not as well-thumbed as the set that's there already: doc,
window, element, et al. Heading into the minutiae of DOM reference material.

Also did some more in the introductory chapter. Have a better list there of
"core" APIs for DOM programmers, an "Interfaces versus Objects" section, and
some general cleanup.

Comment 27

18 years ago
Fixed a typo in the replaceChild() params: it's not replaceChild(oldChild,
newChild), as I had it, but the reverse. Ought to see the update on the site
within the hour.

Comment 28

18 years ago
has no documentation, only dummy text.

Comment 29

18 years ago
Checked in an update of the domref: new, somewhat clearer information about the
CSS properties list and the use of the style property. Also some minor
formatting changes: bug link now called "tracking bug", link to
becomes link to the DOM project itself.

Updated the DOM project page: reference to domref now includes links to zipped
HTML and PDF versions per requests. Hope you don't mind, Fabian. Most recent
zipped HTML will always be linked simply as

Blocks: 57237

Comment 30

18 years ago
IMHO the "HTML" bullet is not necessary because it points to the same place as
the larger title. I try to keep the main page as short as possible. The other
two bullets are fine with me though. It helps newcomers see that it is the most
important part of the DOM content.

Comment 31

18 years ago
Hey Ian, I just got a mail saying the "Zipped HTML" link at docs/dom is broken.
And indeed it is. It will be annoying to update that link everytime you update
the zip name. Perhaps set a redirect? Have you got any solution? And btw, what's
the current zip name? I can't find it.

Comment 32

18 years ago
Shoot-y-boots! I forgot to cvs add the I just made. Fabian, I am
going to always call the latest zip as, so I won't need to do any
versioning on the front end. 

Just committed the domref and removed the extraneous domref->HTML link from the
project page. Also updating the domref.pdf right now, which was a few months behind

Comment 33

18 years ago
There is a problem with the "document" object documentation. I'll post more
details in npm.dom/documentation and CC you, Ian. Also the "appendChild()"
method is bogus in the "Element" object reference. It should say "element"
instead of "document", everywhere it's used.

Comment 34

18 years ago
typo at iframe.contentDocument:

working_title = src_doc.tile; 
should probably be 
working_title = src_doc.title;

Comment 35

18 years ago
*** Bug 119668 has been marked as a duplicate of this bug. ***

Comment 36

18 years ago
Just made an update. 

The tile->title typo is fixed in the frame doc, the appendChild doc->el is also
fixed, so is the formatting of the title in the TOC.

Comment 37

18 years ago
needs new title (bookmarking matters!)

is: Chapter 0 Table of Contents
ought: Gecko DOM Reference

Comment 38

18 years ago
Bugs relating to the DOM Event Reference:

- Summary is missing for charCode, pageX/Y, layerX/Y
- The detail page for pageX/Y and layerX/Y needs to be fixed
- Please clarify how charCode is different from keyCode in the detail page for
both properties.
- Please describe how the secondaryTarget property is actually implemented
instead of quoting the W3C spec (which may or may not actually correspond to the
Mozilla reality)
- I can't find a description of how to get the event coordinates relative to the
target element anywhere (is this layerX/Y or something?).

Comment 39

18 years ago
*cringe* I can't believe I'm even suggesting this since I use IE, but you might
want to check to make sure your CSS styles look good on NS/Mozilla.  For
example, check out on IE
and then on Mozilla.  The IE styles are great, but Mozilla is barely readable. 
(The fonts are way too small, and aren't sans-serif, like they are on IE).

Comment 40

18 years ago
More issues ...
- It would be really nice to have a comprehensive list of event handlers,
something akin to
- There's no documentation for the 'oncontextmenu' event handler, even though
it's supported.

Comment 41

18 years ago
I have been working on getting some of Rober Kieffer's excellent suggestions and
good spots into the domref. Just posted a new version that has the fix for the
minor problem addressed in comment #37, has most of the issues in #38 addressed
(including an example of relatedTarget I cribbed from LXR), and takes a stab at
the list he suggests in #40 with a new section in dom_event_ref, DOM Event
Handler List. 

For this last one, I grabbed stuff from DOMEvent.h and began to write little
summaries of the related properties. Not done yet. Some of them are missing and
some are almost certainly inaccurate. But I am not averse to publishing blatant
inaccuracies and blah blahs to stimulate assistance, as you will know if you've
read through the domref. :)

Take a look at the new section and give me a hand if you have a minute. Just
need to describe what each of the events are for which these guys are handlers,
and may want to add more information if we have it.

Robert also suggested creating new bugs for some of the more important issues in
the reference. If you do this, please create them in Documentation->Web
Developer and also create a dependency here to the new bug. Thanks a lot!

Comment 42

17 years ago
Jasper du Pont noticed this: hasChildNodes is not a boolean property but a
method that returns a boolean. Had it wrong in the domref. Fixed now (locally,
though not on check-in coming soon).

Comment 43

17 years ago
cols documentation is
fixed locally. checking in an update with this and a few other things very soon.

Comment 44

17 years ago
Suggestion from
"How about adding a link, or a search box, to a script reference?  For example,
if someone is looking for details on using 'this' to provide a self-reference,
it would be helpful to start on  your Index page."

I think we should do something like this to make JS info as readily available as
possible. Which reference should we be referring to in this case?


Comment 45

17 years ago
fixed nodeValue description (and closed bug 122741), hasChildNodes syntax, and
FRAMESET.cols documentation. Thanks all.

Comment 46

17 years ago
A few things:* You should add body.vLink, .aLink etc.* In document.vlinkColor (and friends) you should note that it is deprecated from the DOM2 spec and now "redirects" to its body correspondent.

Comment 48

17 years ago
Ah, yes. Very sharp. Just testing you, of course, doron: _I know_ insertBefore
takes two is another sighting from jst:
"There is no focus() method on document, so the page is incorrect."

I will get both of these updates in tout de suite. thanks both of you.
another thing.  Some pages have:


param is a something.

in them when the entity in question has no parameter. Example is

Comment 50

17 years ago
I've tested (Mozilla RC3) the example of replaceChild()

but it doesn't work. I got only a 

Error: uncaught exception: [Exception... "Node was not found"  code: "8" 
nsresult: "0x80530008 (NS_ERROR_DOM_NOT_FOUND_ERR)"  
location: "file:///T:/EMS/ContentManagement/Allgemein/Georg%20He%
DFmann/Sonstiges/CSS%20Werbung%20Test/replace-doc.html Line: 10"]

<div id="top" align="left"> 
  <div id="in">in</div> 

d1 = document.getElementById("top"); 
d_new = document.createElement("p"); 
d1.replaceChild(d_new, d1); 

See bug #56758 for the replaceChild issue

Comment 52

17 years ago
The problem is the example.

d1.replaceChild(d_new, d1); 

is incorrect. The second argument should the node to be replaced. Also, the
alert won't work because of #text node which is the first child.

Comment 53

17 years ago
updated the replaceChild example in the HTML. Will fix the source (my Framemaker
documents) as soon as I can get to them. Thanks, Bob, Goerg, Kinger.

Comment 54

17 years ago
The reference for is incorrect:


documentFragment = element.createDocumentFragment 

Element does not support createDocumentFragment, Document does however. It is
also missing the ending (). It should read

documentFragment = document.createDocumentFragment();

The Example

frag = document.createDocumentFragment(); 
frag.write("<div>Moveable Div</div>"); 

is incorrect. a DocumentFragment is a Node and does not support a method called

It should read:

frag = document.createDocumentFragment();
elm  = frag.appendChild( document.createElement('foo') );

Comment 55

17 years ago
I'd like to help out by working on the docs for the Range.  I have working
knowledge of the DOM 2 Range interfaces, as well as examples for most that I
have used in exposing bugs in it over the past two years.  I have a real need
for the specs so I'm sure others do too.  So what do I need to do to get
involved in this?

Comment 56

17 years ago
You're on, Dylan. Dylan has sent me great docs for the Range APIs and I am
integrating them into the book this week. Also working on noting the APIs in the
domref that are frozen.

Comment 57

17 years ago
Just checked in Dylan's Schiemann's Range interface docs. Also regenerating and domref.pdf for your viewing pleasure. Thanks, Dylan!

Comment 58

17 years ago
Properties, methods, events should be listed in alphabetical order (see
HTMLFormElement Interface: ).

In the frame page (
), replace the 2nd name by noresize and edit the link accordingly if the page is

General comments:

Definitions given in reference pages should always correspond to the definition
in detail pages. E.g.: "clientX :Returns the horizontal position of the event"
does not correspond to "clientX: Returns the horizontal coordinate of the event
within the DOM client area".

"Parameters" in detail pages should be only used for methods. Mentioning
parameters makes no sense when defining object and properties. It's an misuse of

Inconsistant choice of identifiers in definition pages: e.g.: the syntax refers
to event.screenX but the example uses e.screenX. I personally have a problem
with the use of  the object's identifier "event" since this is known to be the
event object as a property of the window object under MSIE. This is also bad for
people learning javascript, DOM as it confuses matters. Most programmers use evt
to identify to Netscape's event object.

Some examples simply cannot work (too many mistakes). E.g.: event.screenX ( ).

Some definitions are simply wrong: window.screenX/Y to name one.
( )
window.screenY returns the vertical distance of the top border of the user's
browser from the top side of the screen.

Some methods are missing (e.g. method addEventListener not listed in window and

The format of the Specification section should be standardized and always be a
link to the precise url defining the standard. E.g.: Specification DOM level 2
Style module -- deleteRule

The Notes section should always include a default value if there is one (mostly

I agree with R. Kieffer's comment #38 entirely.

I'm sorry if I appear nitpicking and harsh here but I personnally feel that MSDN
has a much better reference site with interactive demo examples: it is more
useful, more complete, more structured. I understand that the Gecko DOM
reference is in development and Ian Oeschger might be overloaded.

Specific points:
window.screen.availTop: Returns the first available pixel from the top of the
screen available to the browser.
window.screen.availHeight : Returns the amount of vertical space available to
the window on the screen.

The operative word here is available. I believe people will not understand what
that means. It's true that this property is very rarely used. Nevertheless I
think there should be a better definition for these 2 properties. How about:

Specifies the y-coordinate of the first pixel that is not allocated to permanent
or semipermanent user interface features.

Specifies the height of the screen, in pixels, minus permanent or semipermanent
user interface features displayed by the operating system, such as the Taskbar
on Windows.

as given by Client-Side JavaScript Reference v1.3 at

One can see the effect of these properties when you move the windows taskbar
around the screen (at top and left sides of the monitor video display).


I think you should redo the detail page of event.clientX/Y and event.layerX/Y
entirely. I can help you on this.

The definition of pageX/Y "looks" awkward or wrong. PageX/Y return the
horizontal/vertical coordinate of the event relative to the whole width/height
of the document. "visible page" as stated in the definition is very misleading:
I am sure some people would think this is the client area, the rendering area.

window.onresize and window.onscroll are DOM level 2 Events module spec:


Comment 59

17 years ago
Added a first batch of methods from Dylan Schiemann to the Range object APIs at:
Not sure it's up on the server quite yet, and it's not complete, but the
remainder are coming shortly. Selection interfaces also coming soon!

Dr. Unclear--thanks for the comments. As you suggest, I can't always spend as
much time on the domref as it wants--certainly not as much as the _army of MS
employees_ do on their corresponding reference materials--but I welcome your
suggestions. I will try to address some of the issues you bring up, and I have
already in fact begun some updates based upon the more specific comments (e.g.,
ambiguity of availHeight, availWidth, etc.). Robert Kieffer--haven't forgotten
about your very useful suggestions either.

Comment 60

17 years ago
DOM Elements Interface

offsetLeft, offsetTop, offsetWidth and offsetHeight

offsetLeft, offsetTop, offsetWidth and offsetHeight are all referenced/related
to a system of coordinates created by the closest (nearest in the containment
hierarchy) positioned containing element. If the element is non-positioned, the
root element (html in standards compliant mode; body in quirks rendering mode)
is the offsetParent.

So, in the definition of these 4 properties, you can safely replace the last 2
words "parent element" by "offsetParent node"

"offsetParent returns a reference to the object in which the current element is
offset (i.e., the parent element)."

can be changed to

"offsetParent returns a reference to the object which is the closest (nearest in
the containment hierarchy) positioned containing element. If the element is
non-positioned, the root element (html in standards compliant mode; body in
quirks rendering mode) is the offsetParent.

N.B.: Only 1 item needs to be checked/verified for sure about this definition:
if the root element is actually the html node in standards compliant rendering
mode and if the body node is the root element in quirks/compatible rendering
mode. I'm pretty sure it is like that.

Comment 61

17 years ago
Re: comment #59

"I can't always spend as much time on the domref as it wants--certainly not as
much as the _army of MS employees_ do on their corresponding reference materials

I understand. I'm willing to help. I consider myself as very good at testing and
creating good test cases or examples.

Comment 62

17 years ago
DOM window Interface

The window.title property does not exist. The document and element object has
the title property, but not the window.

Comment 63

17 years ago
Removed window.title interface. 

Thinking now we ought to make new bugs (like 120589 133932 and others, which I
am creating dependencies for now in this bug) for these specific issues. Then I
can have the pleasure of closing them as I fix them. :)

An update later today to the domref will resolve a few of these.
Depends on: 120589, 120592, 122580, 133932, 147444

Comment 64

17 years ago
docs on element offset properties updated per comment #60. yeah, dr. unclear!

Comment 65

17 years ago
Here's a working and more complete example for evt.screenX/Y. The notes about
the routing of event is also covered in this example. Finally, removing the <p
id="idP"> node and leaving the red, yellow and green image serving as a client
image map (that would better fit the meaning of the function name) is up to you. 

In the "Notes" section, please change

"When you trap events on the window, document, or other roomy elements, "


"When you trap events on the window, document or other elements," 

I'm not sure that "trap" is the best verb. Maybe capture or "When events are
fired on the ...". Just my opinion here.

How do I upload an image in bugzilla? I.e.: RedYellowGreenClickMap.png


<html lang="en-us">


<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Style-Type" content="text/css">
<meta http-equiv="Content-Script-Type" content="text/javascript">

<title>evt.screenX (dom_event_ref21.html)</title>

<script type="text/javascript">
function checkClickMap(evt)
	if (evt.screenX < 60)
	if (evt.screenX >= 60 && evt.screenX < 110)
	if (evt.screenX >= 110)

function doRedButton(RoutingEvtForRed)
{alert("red was clicked at: " + RoutingEvtForRed.screenX);}

function doYellowButton(RoutingEvtForYellow)
{alert("yellow was clicked at: " + RoutingEvtForYellow.screenX);}

function doGreenButton(RoutingEvtForGreen)
{alert("green was clicked at: " + RoutingEvtForGreen.screenX);}

function init()
document.getElementsByTagName("body").item(0).addEventListener("click" ,
checkClickMap , true);

/* document.getElementsByTagName("body")[0].addEventListener("click" ,
checkClickMap , true);
also works without a problem */

<style type="text/css">
body {margin:7px; color:black; background-color:white; border:3px solid silver;}
p#idP {color:white; background-color:black;}


<body onload="init();">

<p id="idP">The body node is within the silver bordered box.</p>
<p><img src="RedYellowGreenClickMap.png" style="width:200px; height:50px;"
alt="A red, yellow and green image"></p>


Comment 66

17 years ago
A red, yellow and green image

Comment 67

17 years ago
In the index file
I would use a bigger font-size for the A - B - C - ... - X - Y - Z links. 
Regarding the long list of links to files, did you consider spacing a bit each
line and wrapping the text into an anchor? I would find this more convenient
than having to click on a single number, which is rather narrow... You have/use
big letters for delimiting subsection but rather "little" font for clickable
links. Just my opinion here.

pageXOffset is missing in that file;
title 2 should be removed and also window.title .


17 years ago
Depends on: 157610


17 years ago
Depends on: 159849
This is a request for more detail in the Gecko DOM Reference.  I see other
similar comments in this bug, so I think this is the right place.

navigator.platform -- some known values are listed, but apparently incorrect --
"win32" seems to be the value used for all Win9x/WinNT systems.  I'd like to
see the Windows 3.1 value, in particular; additional Linux/Unix strings, if
known, would also be helpful.

navigator.oscpu -- no field values are listed; listing the known ones would be
useful, along with a note about the less-specific (i.e. Unix) values. I would
like to know, for instance, that the string "OS X" appears in the Mac OSX
version, since that string apparently does not appear in the 'platform' field.

navigator.userAgent -- could a link be added from here to:
... and, could that linked document be updated as well, with full documentation
for the Mac cases, and additional Linux/Unix info?
Is it guaranteed that, barring spoofing, the 'oscpu' field will appear verbatim
in the userAgent?  (It is not the case that the 'platform' field appears
verbatim in the userAgent.)

Attached is a list of userAgent strings I grep'd out of an enormous list from
someone's website.  If the 'oscpu' field does normally appear verbatim in the
userAgent string, then the data there can be used to flesh out the oscpu list
of values.

Comment 69

17 years ago
Just updated the domref html and pdf: now has Dylan's Mozilla Range interface
extensions in the dom_range chapter.


17 years ago
Depends on: 137555


17 years ago
Depends on: 165739


17 years ago
Depends on: 172820, 185813, 187342


16 years ago
Depends on: 198645

Comment 70

16 years ago
*** Bug 193270 has been marked as a duplicate of this bug. ***


16 years ago
Depends on: 195867


16 years ago
Depends on: 194646
Keywords: meta


16 years ago
Depends on: 194587

Comment 71

16 years ago
>I can't always spend as much time on the domref as it wants--certainly not as
>much as the _army of MS employees_ do on their corresponding reference materials

Yes, that is true, Ian. Maintaining the messy source code requires extra effort
--I know from experience. 

Ian has decided that using inline styling is the way to go. lots of: <span
style="color:#000000;  font-style: normal; font-weight: normal;
text-decoration: none; text-transform: none; vertical-align: baseline...
When I speak of messy source code, this is a big part of the problem.

This bug should be marked INVALID. What little progress is made here is futile
and in vain. Bug 193270, marked a duplicate of this, more clearly addresses the
problem: The documentation needs to be rewritten.

The dom refs docs are 90% wrong. Since the docs have messy source code, it would
be more efficient and even easier to bag the current project and start over with
a carefully thought-out plan. 

I strongly encourage anyone who is contributing to the domref docs to stop and
think about the usefulness of your efforts. Could your efforts be more
efficiently used? If so, in what scenario?

I have already made an offer to work on rewriting the docs and I provided a
sample document, attachment 114391 [details]. It documents interfaces as interfaces and
objects as objects, never confusing the two as the current docs do. 

The sample document has a few minor technical difficulties (misspelling
"hierarchy" and says "implements modules" instead of "supports modules"). The
sample doc is also short on links. Each property needs to be linked, and this is
a TODO. I stand by the structure of my sample and the completeness of its approach.


16 years ago
Depends on: 196463, 196779


16 years ago
Depends on: 196786


16 years ago
Depends on: 211382

Comment 72

16 years ago
I posted a message in netscape.public.mozilla.documentation a few min. ago
(Subject line is "Gecko DOM reference: problems and suggestions. (bug 93108, bug
193210, bug 157610)"). I hope people from and netscape (DevEdge)
will read it with an open-mind and try to establish a roadmap, agree on a plan,
a new design, some new protocols to best use efficiently the time and efforts of
volunteers willing to update the Gecko DOM reference and upgrade its
functionalities, content, etc.. I know that others tried a few years ago.

The cost involved by incorrect, weak, flawed, unusable, counter-productive,
inconsequent documentation is immense and it affects all who use it .. or avoid
it deliberately. Just this window.innerWidth issue is a good example of how much
time, efforts is lost, redundantly lost, repeatedly from duplicate bugfiles to
INVALID ones. Bug 57700 is another good example.

I wish one day I can post a reply in a web programming newsgroup and confidently
recommend the Gecko DOM reference without shame, without hesitation, without
guilt. I tried like many others to do a difference and I hope others will
succeed where I have failed.

I have nothing personal against Ian Oeschger, J. Rudman or B. Clary.

Comment 73

16 years ago
The document is written in FrameMaker and then exported to HTML. Ian Oeschger
said he would convert the doc to DocBook so other people can contribute. Before
that happens, DOM ref is still a one-man effort :-(

Comment 74

16 years ago
In #c72, I was referring to bug 193270.

> Ian Oeschger said he would convert the doc to DocBook so other people can
Even if this is done, Gecko DOM reference will still need to address many
issues, organize a roadmap, a plan of some sort, protocols, etc.. As it is, the
Gecko DOM reference is not recommendable and the organization to contribute to
it is impractical, too much time-consuming and too much effort consuming and
involves duplicated efforts. Am I fair and square here?

>Before that happens, DOM ref is still a one-man effort :-(
The Gecko DOM ref never should have been a one-man effort. Just by reading this
bugfile, I think it never was either. Maybe Ian O. has been the main person
behind this bugfile and Gecko DOM reference (GDR) edition but that's the nr 1
issue to address. Mozilla never was and never should be a 1 person organization.
By saying this, I'm not condemning Ian's personal efforts into this bugfile or
GDR. Nobody can't reproach Ian for not being omniscient or for not being an
impeccable robot. 

But I'll definitively point my finger toward so many webpages
inviting people to contribute to documentation when trying to do so is so
frustrating, counter-productive (blatant incoherences) and a big waste of
volunteer time. That's how I feel about this issue.

This documentation issue makes lots of other people (in bugzilla bugfile and
elsewhere) lose time also: that's just one major consequence of the GDR
documentation state.


16 years ago
Depends on: 215921

Comment 75

16 years ago
moving stuff over to an outside-the-firewall email for the time being, looking
for people to pick these Help and doc bugs up for me.
Assignee: oeschger → oeschger
Ian, I would be interested in maintaining it, just need to get cvs access to it :)

Comment 77

16 years ago
reassigning to doron. Doron, the original source files are in Framemaker. I
checked them into a src subdir of that domref dir on mozilla. Can talk to you
about maintenance. Thanks! 
Assignee: oeschger → doronr


16 years ago
Depends on: 216733


16 years ago
Depends on: 212507


16 years ago
Depends on: 223806


16 years ago
Depends on: 209398


16 years ago
Depends on: 215080


16 years ago
Depends on: 228494, 228497


16 years ago
Depends on: 233213


15 years ago
Depends on: 243630


15 years ago
Depends on: 273123
The reference is in process of being migrated to dev.m.o wiki, updated URL.


14 years ago
Depends on: 302538


10 years ago
Assignee: doronr → nobody
Component: Web Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
QA Contact: rudman → doc-request


7 years ago
Depends on: 722760
Component: Documentation Requests → Documentation
Product: Mozilla Developer Network → Mozilla Developer Network
Automatically closing all bugs that have not been updated in a while. Please reopen if this is still important to you and has not yet been corrected.
Last Resolved: 7 years ago
Resolution: --- → INVALID
Reopening for review by Sheppy.
Assignee: nobody → eshepherd
Resolution: INVALID → ---
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation


6 years ago
Whiteboard: u=webdev p=0


6 years ago
Whiteboard: u=webdev p=0 → u=webdev p=0 c=DOM

Comment 81

6 years ago
Now that we have "Developer Documentation::DOM" as component/product pair, I don't think this tracking bug is necessary any longer. Closing. Feel free to reopen if it serves a different purpose than "Developer Documentation::DOM"
Last Resolved: 7 years ago6 years ago
Resolution: --- → INVALID
You need to log in before you can comment on or make changes to this bug.