Closed Bug 93108 Opened 23 years ago Closed 11 years ago

DOM reference documentation tracking bug

Categories

(Developer Documentation Graveyard :: General, defect)

x86
Other
defect
Not set
normal

Tracking

(Not tracked)

RESOLVED INVALID

People

(Reporter: oeschger, Assigned: sheppy)

References

()

Details

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

Attachments

(3 files)

Need a place to keep track of additions, errors, versions, etc.
Hope you guys don't mind me sticking you on here.
Status: NEW → ASSIGNED
Just posted an updated doc at www.brownhen.com/domref. Waiting to see about
mozilla.org 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).
I'm here :-) My email is hidday@geocities.com. 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 :-)
a few nitpicks:
When moving the doc from brownhen to mozilla.org, remove the mozilla.org 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 http://www.brownhen.com/domref/dom_el_ref66.html have a list of -moz
properties?

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

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

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

David
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 domref.zip
down in that project directory. Thanks!
Just updated the introduction and preface to the domref. Still working on these
files.
I changed the URL from brownhen to mozilla.org, so it's easier to find.

And:

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

example 4 misses a }, and some indention.

so much for this comment
Ian,

There's a Web page that explains how to make WWP do the right thing with anchors:

http://www.frameexpert.com/tips/capstudio/wwp_bettertitlejump.html
The examples are from the Dynamic HTML template, I believe, but the XHTML
template should be extremely similar.
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. 

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.
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. :^/
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!
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 domref.zip and called it domref09192001.zip.

Working on these today:
window.scrollX
window.scrollY
window.scrollTo()
window.scrollBy()
window.scrollByLines()
window.scrollByPages()
window.directories
window.controllers
window.prompter
window.pkcs11
window.updateCommands()

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. 
I think you should add in the style reference that the only rules accessible 
via element.style are the inline styles.
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.
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.
A couple of little nits about the window object:
* window.Components: we should link to  
http://www.mozilla.org/scriptable/components_object.html from
http://mozilla.org/docs/dom/domref/dom_window_ref11.html#999999

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


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

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:
docs/dom/domref10102001.zip
docs/dom/domref.PDF
Bug in Event interface docs:

http://www.mozilla.org/docs/dom/domref/dom_event_ref24.html#999930

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 irc.mozilla.org at #mozilla and #mozillazine for a
little while.  Would appreciate assistance (trying to complete my book; I'm on
the Events chapter).
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:

mozilla-org/html/docs/dom/domref10192001.zip
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...
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.
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.
window.updateCommands()
has no documentation, only dummy text.
http://www.mozilla.org/docs/dom/domref/dom_window_ref126.html#1000361
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 mozilla.org
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 domref.zip.

Blocks: 57237
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.
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.
Shoot-y-boots! I forgot to cvs add the domref.zip I just made. Fabian, I am
going to always call the latest zip as domref.zip, 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
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.
typo at iframe.contentDocument:

working_title = src_doc.tile; 
should probably be 
working_title = src_doc.title;
*** Bug 119668 has been marked as a duplicate of this bug. ***
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.
needs new title (bookmarking matters!)

is: Chapter 0 Table of Contents
ought: Gecko DOM Reference
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?).
*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 http://www.mozilla.org/docs/dom/domref/dom_el_ref.html 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).
More issues ...
- It would be really nice to have a comprehensive list of event handlers,
something akin to
http://msdn.microsoft.com/workshop/author/dhtml/reference/events.asp
- There's no documentation for the 'oncontextmenu' event handler, even though
it's supported.
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!
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 mozilla.org. check-in coming soon).
cols documentation is
wrong:http://www.mozilla.org/docs/dom/domref/dom_frame_ref3.html
fixed locally. checking in an update with this and a few other things very soon.
Suggestion from bill@fastpitchcentral.com:
"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?


 
fixed nodeValue description (and closed bug 122741), hasChildNodes syntax, and
FRAMESET.cols documentation. Thanks all.
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.
Ah, yes. Very sharp. Just testing you, of course, doron: _I know_ insertBefore
takes two arguments...Ahem...here is another sighting from jst:
 
"There is no focus() method on document, so the page
http://www.mozilla.org/docs/dom/domref/dom_doc_ref48.html is incorrect."

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

Parameters

param is a something.

in them when the entity in question has no parameter. Example is
http://www.mozilla.org/docs/dom/domref/dom_event_ref7.html#999325
I've tested (Mozilla RC3) the example of replaceChild()

http://www.mozilla.org/docs/dom/domref/dom_el_ref56.html

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

--example--
<html>
<body>
<div id="top" align="left"> 
  <div id="in">in</div> 
</div> 

<script>
d1 = document.getElementById("top"); 
d_new = document.createElement("p"); 
d1.replaceChild(d_new, d1); 
alert(d1.childNodes[0].tagName) 
</script>

</body>
</html>
--/example--
See bug #56758 for the replaceChild issue
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.
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.
The reference for
http://www.mozilla.org/docs/dom/domref/dom_doc_ref45.html#1004304 is incorrect:

Syntax

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
write. http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html#ID-B63ED1A3

It should read:

frag = document.createDocumentFragment();
elm  = frag.appendChild( document.createElement('foo') );
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?
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.
Just checked in Dylan's Schiemann's Range interface docs. Also regenerating
domref.zip and domref.pdf for your viewing pleasure. Thanks, Dylan!
Properties, methods, events should be listed in alphabetical order (see
HTMLFormElement Interface:
http://www.mozilla.org/docs/dom/domref/dom_html_ref2.html ).

In the frame page ( http://www.mozilla.org/docs/dom/domref/dom_frame_ref5.html
), replace the 2nd name by noresize and edit the link accordingly if the page is
done.

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

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 (
http://www.mozilla.org/docs/dom/domref/dom_event_ref21.html#999877 ).

Some definitions are simply wrong: window.screenX/Y to name one.
( http://www.mozilla.org/docs/dom/domref/dom_window_ref103.html#1000288 )
window.screenY returns the vertical distance of the top border of the user's
browser from the top side of the screen.
http://developer.netscape.com/docs/technote/javascript/window/images/display_screen.gif

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

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

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

http://www.mozilla.org/docs/dom/domref/dom_window_ref95.html
window.screen.availTop: Returns the first available pixel from the top of the
screen available to the browser.

http://www.mozilla.org/docs/dom/domref/dom_window_ref93.html#1000258
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:

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

availHeight
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
http://developer.netscape.com/docs/manuals/js/client/jsref/screen.htm#1193206

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:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents

Added a first batch of methods from Dylan Schiemann to the Range object APIs at:
http://www.mozilla.org/docs/dom/domref/dom_range_ref.html.
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.

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

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.
DOM window Interface
====================

The window.title property does not exist. The document and element object has
the title property, but not the window.
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
docs on element offset properties updated per comment #60. yeah, dr. unclear!
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, "

for

"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

-------

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
        "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en-us">

<head>

<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)
		doRedButton(evt);
	if (evt.screenX >= 60 && evt.screenX < 110)
		doYellowButton(evt);
	if (evt.screenX >= 110)
		doGreenButton(evt);
}

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 */
}
-->
</script>

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

</head>

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

</body></html>

A red, yellow and green image
In the index file
http://www.mozilla.org/docs/dom/domref/dom_shortIX.html
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 .
Depends on: 157610
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:
   http://www.mozilla.org/build/revised-user-agent-strings.html
... 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.
Just updated the domref html and pdf: now has Dylan's Mozilla Range interface
extensions in the dom_range chapter.
Depends on: 137555
Depends on: 165739
Depends on: 172820, 185813, 187342
Depends on: 198645
*** Bug 193270 has been marked as a duplicate of this bug. ***
Depends on: 195867
Depends on: 194646
Keywords: meta
Depends on: 194587
>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.
Depends on: 196463, 196779
Depends on: 196786
Depends on: 211382
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 mozilla.org 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.
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 :-(
In #c72, I was referring to bug 193270.

> Ian Oeschger said he would convert the doc to DocBook so other people can
contribute.
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 Mozilla.org 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.
Depends on: 215921
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
Status: ASSIGNED → NEW
Ian, I would be interested in maintaining it, just need to get cvs access to it :)
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
Depends on: 216733
Depends on: 212507
Depends on: 223806
Depends on: 209398
Depends on: 215080
Depends on: 228494, 228497
Depends on: 233213
Depends on: 243630
Depends on: 273123
The reference is in process of being migrated to dev.m.o wiki, updated URL.
Depends on: 302538
Assignee: doronr → nobody
Component: Web Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
QA Contact: rudman → doc-request
Depends on: 722760
Component: Documentation Requests → Documentation
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.
Status: NEW → RESOLVED
Closed: 12 years ago
Resolution: --- → INVALID
Reopening for review by Sheppy.
Assignee: nobody → eshepherd
Status: RESOLVED → REOPENED
Resolution: INVALID → ---
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation
Whiteboard: u=webdev p=0
Whiteboard: u=webdev p=0 → u=webdev p=0 c=DOM
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"
Status: REOPENED → RESOLVED
Closed: 12 years ago11 years ago
Resolution: --- → INVALID
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: