Need a place to keep track of additions, errors, versions, etc. Hope you guys don't mind me sticking you on here.
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 email@example.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.
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 firstname.lastname@example.org: "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.
http://www.mozilla.org/docs/dom/domref/dom_el_ref47.html#1019733 is wrong, insertBefore needs 2 arguments.
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.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!
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.
docs on element offset properties updated per comment #60. yeah, dr. unclear!
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 .
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.
*** Bug 193270 has been marked as a duplicate of this bug. ***
>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.
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.
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
The reference is in process of being migrated to dev.m.o wiki, updated URL.
Assignee: doronr → nobody
Component: Web Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
QA Contact: rudman → doc-request
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.
Status: NEW → RESOLVED
Last Resolved: 6 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 → 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
Last Resolved: 6 years ago → 6 years ago
Resolution: --- → INVALID
You need to log in before you can comment on or make changes to this bug.