- From: Michael Dyck and/or June Harman <jmdyck@netcom.ca>
- Date: Mon, 31 Aug 1998 02:22:36 -0400 (EDT)
- To: <www-dom@w3.org>
Comments on PR-DOM-Level-1-19980818 (just the Core)
A lot of my suggested changes are editorial (fixing typos, making the
presentation more consistent, and increasing the clarity), but a few are
substantive. If you'd prefer these to be separated, I can do so and resubmit,
but I'm guessing you don't mind.
I haven't always justified my suggestions, as it's often obvious.
In case it isn't, I'll be happy to elucidate.
When I say a word or phrase is unnecessary, I mean that it has been elided in
similar contexts elsewhere in the spec.
------------------
throughout:
Inconsistent format of qualified names for attributes and methods, e.g.,
"Element:getElementsByTagName", referred to in 1.1.1
"Element.normalize()", referred to in 1.3 CDATASection
(1) Should the connector be a colon or a period?
(2) Should the parentheses appear or not?
(3) Should it be delimited by "<code></code>"?
"On setting a <someException> is raised..."
Insert comma after "setting".
Similarly with "On retrieval a ..."
------------------
What is the Document Object Model?
Introduction
3rd para: "Various other IDLs could have been used.."
Remove extra period.
Where the Document Object Model came from
"provide an APIs"
Change to "provide an API" or "provide APIs".
------------------
Chapter 1: Document Object Model (Core) Level 1
1.1.2 Memory Management
"from language platforms do not expose"
Insert "that" before "do".
1.2 Fundamental Interfaces
DocumentFragment
3rd para: "<code>DocumentFragment</code> do not need"
Insert "nodes" before "do".
Document:createEntityReference
Document:getElementsByTagName
Shouldn't these methods raise INVALID_NAME_ERR if the entity name or
tag name is invalid?
Document:getElementsByTagName
'If the string "*" is given, this method returns ...'
This mixes "Return Value" information into "Parameter" information
more than is usual. Perhaps change to:
'The special value "*" matches all tags.'
"all the <code>Elements</code>"
Insert "matched" after "the".
Node:nodeType
"the type of the underlying object's type"
Remove either "the type of" or "'s type".
Node:childNodes
"object that enumerate"
Change "enumerate" to "enumerates" (or maybe just "contains").
Node:previousSibling
"<code>null</code> is returned."
Change to "this returns <code>null</code>" (as with neighbouring
attributes).
Node:attributes,
Node:ownerDocument
"Provides access to"
This phrase is unnecessary.
Node:insertBefore
"The node to insert"
Append period.
Node:insertBefore,
Node:replaceChild,
Node:appendChild
Shouldn't the DOM raise an exception if 'newChild' is:
'refChild'/'oldChild',
"this" node, or
one of this node's ancestors?
Node:removeChild
"The node being removed"
Append period.
NodeList:item
"null is returned."
Change "null" to "<code>null</code>".
"Index into the collection"
Append period.
"The node at the <code>index</code> position"
Add "th" after "</code>".
NamedNodeMap
"DOM implementations should, when possible, preserve the ordering of
objects
in a namedNodeMap...":
My guess is that, in most such implementations, setNamedItem would add
the node at the "high" end of the map, so that its index immediately
thereafter would be length-1. However, one could also preserve order
by
always adding the node at the "low" end (index=0) of the map.
If you don't want to allow this alternative, you should clarify what
"preserving the order" means.
In the method descriptions, references to "list" should perhaps be changed
to "map" (or "collection"?).
NamedNodeMap:getNamedItem
NamedNodeMap:removeNamedItem
Shouldn't these methods raise INVALID_NAME_ERR if the attribute name is
invalid?
NamedNodeMap:setNamedItem
"null is returned."
Change "null" to "<code>null</code>".
"INUSE_ATTRIBUTE_ERR: ... that is already attribute"
Insert "an" before "attribute".
NamedNodeMap:removeNamedItem
"The name of a node to remove"
Append period.
NamedNodeMap:item
"Index into the collection"
Append period.
"The node at the <code>index</code> position"
Add "th" after "</code>".
CharacterData
"uses these attributes and methods for clarity"
Move "for clarity" to start of sentence?
CharacterData:data
"data data"
Too much data.
"Attempts ... causes [an exception] to be raised."
Change to "Attempts" to "An attempt" or "Attempting".
CharacterData:substringData,
CharacterData:deleteData,
CharacterData:replaceData
"and if the specified count is negative"
Change "and" to "or".
CharacterData:substringData
"Start offset of substring to extract"
Append period.
"This method returns"
This phrase is unnecessary?
CharacterData:insertData
"The character offset at which to insert"
Append period.
"The <code>wstring</code> to insert"
Append period.
CharacterData:deleteData
'"No_MODIFICATION_ALLOWED_ERR'
Remove extraneous double-quote.
Attribute
"having a separate identity separate from"
Too much separation.
"associated with element nodes"
Change "element" to "<code>Element</code>".
"In XML,"
Change to "For XML documents,".
"the value of an attribute is represented"
Insert "also" after "is"?
Or change the sentence to (something like):
"In XML, the value of an attribute can contain entity references.
In the corresponding Attribute:value furnished by the DOM, these
entity references are replaced with their values. However, the
child nodes of the Attribute node provide a representation in which
entity references are not expanded."
"Thus, attributes which contain entity references will have a child
list..."
So attributes which *don't* contain entity references *won't* have any
children? Or the DOM implementation might provide it, but need not?
"tokenised attribute values"
The XML spec spells it "tokenized".
Attribute:specified
"the specified flag"
"specified == <code>false</code>"
Put "specified" in <code>.
"and <code>specified</code> is <code>true</code>, the value is ..."
Change "and" to "then", and insert "and" before "the value".
Attribute:value
"the Value" (twice)
Use lowercase "v".
"an Attribute"
Use lowercase "a".
"creates a Text node"
Put "Text" in <code>.
Element
"(apart from text) of objects"
Change to "of objects (apart from text)".
'the top node is "elementExample"'
Insert "an <code>Element</code> node for" after "is".
"directly an Attribute value"
Change to "an Attribute value directly", or just remove "directly".
"Attribute objects should be retrieved in XML, ..."
Change sentence to (something like):
"In XML, an attribute value may contain entity references, perhaps
involving a fairly complex tree of entity references and text.
In the DOM, when the value of such an attribute is retrieved by the
Element:getAttribute method, the returned string has every entity
reference replaced by its value (and so on recursively). If, instead,
you want access to the value without expansion, you should retrieve
the Attribute object with the Element:getAttributeNode method [and
examine the children of the <code>Attribute</code> node]."
Element:getAttribute
"The name of the attribute to retrieve"
Append period.
Element:getAttribute
Element:removeAttribute
Element:getAttributeNode
Element:getElementsByTagName
Shouldn't these methods raise INVALID_NAME_ERR if the attribute/tag name is
invalid?
Element:getAttribute
"The name of the attribute to retrieve"
Append period.
Element:setAttribute
"Name of an attribute"
Append period.
Maybe change to "The name of the attribute to create or alter.",
for general consistency.
"Value to set in string form"
Append period.
Element:removeAttribute
"The name of the attribute to remove"
Append period.
'"NO_MODIFICATION_ALLOWED_ERR:'
Remove extraneous double-quote.
Element:getAttributeNode
"an attribute node"
"The attribute node"
Change "attribute" to "<code>Attribute</code>".
"The name of the attribute to retrieve"
Append period.
Element:setAttributeNode
"The attribute node to add to the attribute list"
Change "attribute" to "<code>Attribute</code>".
Append period.
"null is returned."
Put "null" in <code>.
Element:removeAttributeNode
"Returns"
This word is unnecessary.
"the Attribute node"
Put "Attribute" in <code>.
Element:getElementsByTagName
"all descendant element of with"
Insert something ("this node"?) after "of".
"with a given tag name"
Insert a comma after "name".
'If the string "*" is given, ...'
(As for Document:getElementsByTagName,) change to:
'The special value "*" matches all tags.'
"This method returns"
This phrase is unnecessary.
"element nodes that have the specified tag name"
Change to "matching <code>Element</code> nodes".
Element:normalize
"adjacent Text nodes"
Put "Text" in <code>.
"the DOM view"
Change to "the DOM's structural model"?
"how it would look if"
At first glance, this phrase appears to be talking about the graphic
*presentation* of a document, which is presumably not the intent.
Maybe change "identical to how it would look if" to "the same as if it
were".
Also, the sentence talks about saving and reloading, which are concepts
that are not described elsewhere in the spec. Maybe that's okay.
Text
"The <code>text</code> interface"
Change "text" to "Text".
"that is the child of the element"
Insert "only" before "child".
"of the text nodes"
"text node children"
Change "text" to "<code>Text</code>".
"child elements that are siblings of the text nodes on either side of it"
Does this imply that every Element node has a Text node on either side?
(Possibly with no character data.)
"made available to the DOM"
Change "to" to "via" or "through"?
"only one Text node"
"adjacent Text nodes"
"adjacent Text objects"
Put "Text" in <code>.
Text:splitText
"Breaks a text node into two text nodes"
Change "text" to "<code>Text</code>" twice.
"This method returns"
This phrase is unnecessary.
"the new text node"
Change "text" to "<code>Text</code>".
Comment
"i.e."
Insert comma afterward.
ProcessingInstruction:data
Is a 'TextDecl' represented as a ProcessingInstruction node?
"from from"
Too much from.
1.3 Extended Interfaces
CDATASection
"CDATA Section" (4 times in first paragraph)
Change to "CDATA section" (as in second paragraph and the XML spec).
"The CDATA Section inherits"
Change to "The <code>CDATASection</code> interface inherits"
"CharacterData"
"Text"
Put in <code>.
"Adjacent CDATA Sections"
Change to "Adjacent <code>CDATASection</code> nodes"
DocumentType
first sentence
Change to (something like):
"Each <code>Document</code> has a <code>doctype</code> attribute
whose value is either <code>null</code> or a <code>DocumentType</code>
object."
"class"
Change to "interface".
"Level 1 core"
Use uppercase "C".
DocumentType:name
"The <code>name</code> attribute is"
This phrase is unnecessary.
DocumentType:entities
"This is"
This phrase is unnecessary.
"All objects supporting the <code>Node</code> interface that are accessed
through this attribute, also support the <code>Entity</code> interface."
This suggests that there are objects *not* supporting the Node
interface
that can be accessed through this attribute, which I believe is not the
case: a NamedNodeMap is a collection of nodes. Change to: "Each node
in
this map also implements the <code>Entity</code>interface." (as phrased
under DocumentType:notations)
"For HTML, this is always <code>null</code>."
Start a new paragraph and change to:
"For an HTML document, the value of this attribute is always
<code>null</code>."
On second thought, Document:doctype is always null for an HTML
document,
so how would you get a DocumentType object for an HTML document?
DocumentType:notations
"This is"
This phrase is unnecessary.
Notation
Maybe change the name of the interface from "Notation" to "NotationDecl".
"represents a notation declared in"
Change to "represents a notation decalaration in"
"A notation declares"
Change "notation" to "notation declaration".
"The nodeName attribute inherited from Node"
Put "nodeName" and "Node" in <code>.
Entity
"Note that this models the entity itself not the entity declaration. Entity
declaration modelling has been left for a later Level of the DOM
specification."
It seems to me that this interface *does* model the entity declaration
(or at least, the general entity declaration, which is all that
DocumentType:entities contains). That is, it associates a name with
some internal entity (represented by the children of the node) or
external entity (identified by the publicId, systemId, and/or
notationName attributes of the node). How does this *not* model entity
declarations?
Is it the fact that the children of the node represent the entity's
'replacement text' (i.e., after replacement of character references
and parameter-entity references) rather than its 'literal entity
value'?
Perhaps the nodeValue attribute inherited from Node should contain the
literal entity value.
So I suggest renaming this interface as EntityDecl or
GeneralEntityDecl.
"no entity references"
Change to "no <code>EntityReference</code> nodes".
"The structure of the child list is exactly the same as the structure of
the
child list for an EntityReference with the same nodeName value."
This seems backward.
Moreover, the EntityReference section says:
"The replacement value of the referenced <code>Entity</code>, if
available, appears in the child list of the EntityReference object."
This seems circular.
I suggest replacing the above sentence ("The structure...") with
--- The paragraph beginning "XML does not mandate" from the
EntityReference section, moved here, maybe with "replacement value"
changed to "replacement text", as that is the formal term from the
XML spec.
--- Followed by (something like) the sentence:
"When the replacement text is available, the corresponding
<code>Entity</code> node's child list represents the structure of
that replacement text. Otherwise, the child list is empty."
Also, something like the "lazy evaluation" paragraph from the
EntityReference section presumably applies here too.
"editing <code>Entity</code> declarations;"
Change "declarations" to "nodes".
Append "all descendants of the <code>Entity</code> node are readonly.",
as reinforcement of the lack of editing facilities.
"the EntityReference node"
Change to "every <code>EntityReference</code> that refers to the
Entity". (or "... that represents a reference to the Entity")
"by a clone of the Entity's contents"
Add "and then the desired changes must be made to each of those clones
instead".
"All the nodes beneath the entity reference are readonly."
Move this sentence to the EntityReference section.
Change "the nodes beneath" to "descendants of".
Change "the entity reference" to "an <code>EntityReference</code>".
EntityReference
"The replacement value of the referenced <code>Entity</code>, ...
Alternatively, ..."
(See above under Entity.)
Change these two sentences to something like:
"Moreover, the XML processor may completely expand all references to
entities ..., instead of providing <code>EntityReference</code>
objects.
If it does provide such objects, then for a given
<code>EntityReference</code> node, it may be that there is no
<code>Entity</code> node representing the referenced entity;
but if such an <code>Entity</code> exists, then the child list of the
<code>EntityReference</code> node is the same as that of the
<code>Entity</code> node. As with the <code>Entity</code> node, all
descendants of the <code>EntityReference</code> are readonly.
Thus, a DOM implementation is free to use the same underlying objects
for the two structures."
3rd para: "the <code>EntityReference</code> Node"
Use lowercase "n".
End of comments on the DOM Core Level 1.
-Michael Dyck
jmdyck@netcom.ca
Received on Friday, 25 September 1998 11:07:33 UTC