- From: Susan Lesch <susan@textet.com>
- Date: Wed, 16 Feb 2000 14:44:02 -0500 (EST)
- To: www-dom@w3.org
- Cc: w3t-comm@w3.org
Based on one reading, here is a list of possible minor improvements
for the DOM2 Candidate Recommendation [1]. These comments are mainly
microscopic editorial suggestions. Please feel free to ignore them if
they are of no use to you.
General Comments
----------------
Contractions, in core.html and especially in css.html, seem
colloquial in a formal specification. For example, "doesn't" could
read "does not", and "can't" could read "cannot."
I did not point out the many references to "HTML 4.0" that may need
to change to "HTML 4.01."
The markup is meticulous and beautifully done. Time on this was well
spent. (I have never seen a specification before with so many
cross-referenced links and CODE sections that looks this good.)
7.1.3. uses n to denote an integer. 8.2.1. par. 7 uses #. Maybe they
could match.
The rest of this mail is organized in this order:
Page
Section number (if any)
Interface (if any) (attribute or method)
Paragraph number (if any)
Quote, followed by a suggestion. Comments are in brackets [].
cover.html
----------
TOC
1.1.4. Inheritance vs Flattened
1.1.4. Inheritance vs. Flattened
copyright-notice.html
---------------------
W3C Document Copyright par. 3
Copyright (c)
Copyright ©
[As far as I know (c) has no legal standing.]
"...The pre-existing copyright notice of the original author,
if it doesn't exist, a notice of the form:"
could read:
The pre-existing copyright notice of the original author,
or if it doesn't exist, a notice of the form:
derived).
derived.)
introduction.html
-----------------
Introduction par. 3
OMG IDL
[Ungainly as it may look, I would link to a reference, or spell out
these acronyms here when they are first used.]
Object Management Group (OMG) Interface Definition Language (IDL)
introduction.html - What the Document Object Model is par. 2
"...In the DOM, documents have a logical structure which is
very much like a tree; to be more precise, it is like a
"forest" or "grove", which can contain more than one tree."
[What is "it"? The DOM, a document, or a structure? I would replace
"it" with a noun (probably document).]
methods (this does not include attributes).
methods; (this does not include attributes).
"...This should not be taken as meaning that the DOM must be
implemented as a tree structure."
[I believe this was already said in this paragraph and so can be omitted here.]
What the Document Object Model is not - list item 3
data structures, it is an object model
data structures; it is an object model
Entities and the DOM Core par. 1
or the SCRIPT and STYLE elements in HTML
or in the SCRIPT and STYLE elements in HTML
the Level 1 specification
[For this first mention, you might say "DOM Level 1" and link to [DOM1].]
Compliance par. 3
table (strings are case-insensitive):
table; (strings are case-insensitive):
DOM Interfaces and DOM Implementations - list item 3
can not
cannot
core.html
---------
1.1.1. par. 2
"live", that is,
"live"; that is,
1.1.2 par. 1
an actual implementation
an implementation
not actually implement
not implement
1.1.2 par. 2
; actual DOM implementations
. DOM implementations
1.1.2 par. 3
not the DOM WG.
not the DOM Working Group.
[or omit this phrase]
1.1.3 par. 1
that makes it difficult
that make it difficult
1.1.4. Inheritance vs Flattened
1.1.4. Inheritance vs. Flattened
1.1.4 par. 1
document; one
document: one
1.1.4 par. 2
one).
one.)
1.1.7 par. 2
naively.
natively.
1.1.7 par. 3
Also, because in the DOM nodes
Also, because, in the DOM, nodes
1.2. Exception DOMException par. 1
in ordinary processing situation
in ordinary processing situations
or:
in an ordinary processing situation
1.2 Definition group ExceptionCode line 2, and Definition group NodeType line 2
reserved to W3C
reserved for [or by] W3C
INUSE_ATTRIBUTE_ERR
inuse
in use
INVALID_STATE_ERR
is not, or no longer
is not, or is no longer
1.2 Document - createElement and Interface Element - tagName
canonical uppercase form
[I'm not certain uppercase is ever canonical.]
Document - createProcessingInstruction - NOT_SUPPORTED_ERR
[I believe HTML can include the style PI.]
createEntityReference
unbound (its namespaceURI is null).
unbound; (its namespaceURI is null).
importNode
no parent (parentNode is null).
no parent; (parentNode is null).
ELEMENT_NODE
If importNode deep parameter
If the importNode deep parameter
ENTITY_NODE
the descendants of the the source Entity is
the descendants of the source Entity are
NOTATION_NODE
the publicId, and systemId
the publicId and systemId
Interface Node - ELEMENT_NODE
The node is a Element.
The node is an Element.
Attributes - prefix
an attribute, that is known to have a default value, does not
an attribute that is known to have a default value does not
Methods - replaceChild - Exceptions
or it the node
or if the node
cloneNode
has no parent (parentNode returns null.).
has no parent; (parentNode returns null).
supports - feature
name that which can be
name which can be
Interface NodeList - removeNamedItem and removeNamedItemNS
[This sentence makes sense but it is too long.]
"...When this NamedNodeMap contains the attributes attached
to an element, as returned by the attributes attribute of
the Node interface, if the removed attribute is known to
have a default value, an attribute immediately appears
containing the default value as well as the corresponding
namespace URI, local name, and prefix when applicable."
could be two sentences and read:
A removed attribute may be known to have a default value
when this NamedNodeMap contains the attributes attached
to an element, as returned by the attributes attribute of
the Node Interface. If so, an attribute immediately appears
containing the default value as well as the corresponding
namespace URI, local name, and prefix when applicable.
setNamedItemNS
"...If a node with those namespace URI and local name is
already present in the map, it is replaced by the new one."
could read:
If a node with that namespace URI and that local name is
already present in the map, it is replaced by the new one.
Interface CharacterData - replaceData
replaced (i.e., the effect is
replaced; (i.e., the effect is
Interface Element - setAttribute
simple string, it is not parsed
simple string; it is not parsed
setAttributeNS
string, it is
string; it is
setAttributeNodeNS
If an attribute with that local name and namespace URI
[not sure here]
If an attribute with the same local name and namespace URI
Interface Text - splitText
And a new node
A new node
starting from p0.
starting from 0.
1.3 Interface CDATASection par. 1
can not
cannot
The primary purpose is for including material
Their primary purpose is to include material
par 4 Note
CDATA Section
CDATA section [or CDATASection?]
making the task of ensuring data is not corrupted
making the task of ensuring that data is not corrupted
Interface Notation par. 1
Processing Instruction
processing instruction [or ProcessingInstruction?]
Interface Entity - Note par. 7
And the same is true
The same is true
Interface EntityReference par. 1
"...If it does provide such objects, then for a given
EntityReference node, it may be that there is no Entity
node representing the referenced entity; but if such an
Entity exists, then the child list of the EntityReference
node is in general the same as that of the Entity node."
[Can that be broken into two sentences?]
If it does provide such objects, then for a given
EntityReference node, it may be that there is no Entity
node representing the referenced entity. If such an
Entity exists, then the child list of the EntityReference
node is in general the same as that of the Entity node.
html.html
---------
2.4.
Interface HTMLDocument par. 1
Beside providing
Besides providing
body
returns the BODY element, and in frameset documents,
returns the BODY element. In frameset documents,
2.5.1. par. 1
The name of the exposed property always uses the naming conventions,
could read:
The DOM naming conventions always determine the name of the exposed property,
or maybe:
The name of the exposed property is always formed by the DOM's naming
conventions,
2.5.2. par. 1
name-space
namespace
2.5.5
Interface HTMLBaseElement - href
The base URI See
The base URI. See
Interface HTMLStyleElement - type
The style sheet language (Internet media type).
The content type of the style sheet language.
Interface HTMLInputElement par. 1
Depending upon the environment the page is being viewed,
Depending upon the environment in which the page is being viewed,
checked
"...Changes to this attribute changes the state of the form
control, but does not change the value..."
could read:
Changes to this attribute change the state of the form
control, but do not change the value...
readOnly
This control is read-only. When type has the value "text" or "password" only.
[Sorry I got lost here. Could read:]
This control is read-only. True when type has the value "Text" or "Password"?
Interface HTMLLIElement - value
in OL See
in OL. See
Interface HTMLQuoteElement - cite
A URI designating a document that designates a source document or message.
A URI designating a source document or message.
Interface HTMLTableElement - summary
Supplementary description about the purpose or structure of a table.
[This is a WAI priority 3 authoring guideline; I suggest it is more
essential than supplementary.]
Description of the purpose or structure of a table.
views.html
----------
3.1 par. 1
e.g: a computed view
e.g., a computed view
(e.g HTML Frame)
(e.g., HTML Frame)
3.2
Interface AbstractView - document
The source DocumentView for which, this is an AbstractView of.
The source DocumentView for which this is an AbstractView.
or:
The source DocumentView of which this is an AbstractView.
stylesheets.html
----------------
DOM Level 2 Style Sheet interfaces
DOM Level 2 StyleSheet interfaces
[I'd use a compound capitalized word when talking DOM, two words otherwise.]
4.2
Interface MediaList par. 1
a list that contains the medium "all".
a list that contains media all.
item
Returns the indexth in the list.
Returns the indexth medium in the list.
css.html
--------
5.1 par. 1
(specifically CSS level two
(specifically CSS Level 2
5.1 par. 2
the Style Sheets chapter of the DOM Level 2
the StyleSheets chapter of the DOM Level 2
or:
the style sheets chapter of the DOM Level 2
5.2
CSSStyleSheet par. 1
a CSS style sheet i.e. a style sheet whose
a CSS style sheet, i.e., a style sheet whose
Interface CSSMediaRule - insertRule - Exceptions
at the specified index. e.g. if
at the specified index, e.g., if
Interface CSSPrimitiveValue par. 2
"...Conversions are allowed between absolute values (from
millimeters to centimeters, from degrees to radians, and
so on) but not between relative values (for example, a
pixel value can't be converted to a centimeter value)."
[This works as two sentences:]
Conversions are allowed between absolute values (from
millimeters to centimeters, from degrees to radians, and
so on) but not between relative values. (For example, a
pixel value cannot be converted to a centimeter value.)
"...There is one exception with color percentage values;
since a color percentage value is relative to the range
0-255, a color percentage value can be converted to a
number (see also the RGBColor interface)."
[minor punctuation change:]
"...There is one exception for color percentage values:
since a color percentage value is relative to the range
0-255, a color percentage value can be converted to a
number; (see also the RGBColor interface)."
CSSPrimitiveValue - Defined Constants - CSS_EMS, CSS_EXS, CSS_PX,
CSS_CM, CSS_MM, CSS_IN, and CSS_PT
The value is length (<length>).
The value is a length (<length>).
[CSS_PC is fine.]
Interface CSSValueList - length
For
[a text fragment or artifact]
5.2.1.
Interface DocumentCSS par. 2
stylesheets [twice]
style sheets
over author style sheet
over author style sheets
"...Both override and user style sheets may contain
"!important" declarations, and user "!important" rules
take precedence over override "!important" rules. Both
author and override style sheets may contain "!important"
declarations, and override "!important" rules takes
precedence over author "!important" rules."
[could be:]
Override, author, and user style sheets all may contain
"!important" declarations. User "!important" rules take
precedence over both override and author "!important"
rules, and override "!important" rules take precedence
over author "!important" rules.
getOverrideStyle
pseudo element
pseudo-element
5.2.2.
DOMImplementationCSS - createCSSStyleSheet
Style Sheet Interfaces [twice]
StyleSheet Interfaces
5.3. par. 2
"...can be cast down, using binding-specific casting methods,
to the specific derived interface."
[This paragraph has a few "specifies" and "specifics." Can one be cut:]
can be cast down, using binding-specific casting methods,
to the derived interface.
Interface CSS2Azimuth - setAngleValue
any previously set identifiers values.
[not sure:]
any previously set identifier value.
Interface CSS2BackgroundPosition - horizontalType
It would be one
It would be one of
setPositionIdentifier
set to his default value
set to its [or this?] default value
Raised if the identifiers have a syntax error and is unparsable.
Raised if the identifiers have a syntax error and are unparsable.
or:
Raised if the identifier has a syntax error and is unparsable.
Interface CSS2CounterIncrement - increment
The increment (default value is 1).
could read:
The increment. (Default value is 1.)
Interface CSS2PlayDuring - playDuringType
as define in CSSvalue.
as defined in CSSvalue.
Interface CSS2TextShadow - color
Specified the color of the text shadow.
Specifies the color of the text shadow.
Interface CSS2FontFaceWidths - Table
margin,right
margin-right
Interface CSS2Properties - par. 5
"...suffices (the normals are initial values, and are implied
by use of the longhand property)."
[new sentence here:]
suffices. (The normals are initial values, and are implied
by use of the longhand property.)
par 7
should be used, i.e.,
should be used; i.e.,
events.html
-----------
[On this page, "event listeners" is sometimes two words. You may or
may not want to make them all <a
href='events.html#Events-EventListener'><code>EventListeners</code></a
>. If you are going to have this many links in running text, I think
this would make the net effect more readable. On the other hand,
maybe this was by design.]
6.2. par. 1
through which the an event
through which an event
6.2.1. par. 1
"...Although all EventListeners on the EventTarget are
guaranteed to be triggered by any event which is received
by that EventTarget, no specification is made as to the
order in which they will receive the event with regards
to the other EventListeners on the EventTarget."
could read:
Although all EventListeners on the EventTarget are
guaranteed to be triggered by any event which is received
by that EventTarget, no specification is made as to the
order in which those EventListeners will receive the event.
6.2.2. par. 2
"...An EventListener being registered on an EventTarget may
choose to have that EventListener capture events by
specifying the useCapture parameter of the
addEventListener method to be true."
could read:
An EventListener registered on an EventTarget may
choose to capture events by specifying the useCapture
parameter of the addEventListener method to be true.
6.2.2. par. 4
for a single EventTarget, it is specified for
for a single EventTarget; it is specified for
6.2.4. par. 1
to active that hyperlink.
to activate that hyperlink.
6.4.
Interface Event - preventDefault
"...If, during any stage of event flow, the preventDefault
method is called the event is canceled. Any default
action associated with the event will not occur. Calling
this method for a non-cancelable event has no effect.
Once preventDefault has been called it will remain in
effect throughout the remainder of the event's
propagation. This method may be used during any stage of
event flow."
could read:
During any stage of event flow, the preventDefault method
may be called, and the event is canceled. Any default
action associated with the event will not occur. Calling
this method for a non-cancelable event has no effect.
Once preventDefault has been called, it will remain in
effect throughout the remainder of the event's
propagation.
initEvent
are modified, all other properties are left unchanged.
are modified; all other properties are left unchanged.
initEvent - Parameters - eventTypeArg
event type..
event type.
6.5.
Interface DocumentEvent par. 1
"...The DocumentEvent interface provides a mechanism by which
the user can create an Event of a type supported by the
implementation. It is expected that the DocumentEvent
interface will be implemented on the same object which
implements the Document interface in an implementation
which supports the Event model."
[Too many "implements"? Not sure if a synonym exists:]
The DocumentEvent interface provides a mechanism by which
the user can create an Event supported by the environment.
In environments which support the Event model, the
DocumentEvent interface is implemented on the same object
which implements the Document interface.
6.6.2
Interface MouseEvent - mouseover and mouseout
metaKey, relatedNode
metaKey. relatedNode
mouseout
for most elements..
for most elements.
6.6.4 par. 1
including attr and text modifications.
including <code>Attr</code> and text modifications.
or:
including attribute and text modifications.
Interface MutationEvent - relatedNode
If an event is instead dispatch to
If an event is instead dispatched to
6.6.5. - error
for OBJECT elements, BODY elements, and FRAMESET element.
for OBJECT, BODY, and FRAMESET elements.
6.6.5 - change
for INPUT, SELECT, and TEXTAREA. element.
for INPUT, SELECT, and TEXTAREA elements.
traversal.html
--------------
[This page has fewer CODE and anchors to other parts of the spec,
which follows some people's ideal for good Web design, but in the
overall DOM2 context, looks like a departure. I wonder if it would
help to add minimal markup to section 7.2. -- for Node, NodeType,
NodeFilter, and null, for example. For DocumentTraversal, could there
be a link for "iterator" in the sentence "See the description of
iterator for the set of possible values."?]
7.1.1.3. par. 2
lower case
lowercase
7.1.2.3. par. 1
can not
cannot
7.1.3.1. par. 2
response to these change is
response to these changes is
over, TreeWalkers
over, TreeWalker's
range.html
----------
8.5 par. 2
an boundary-point
a boundary-point
8.5 par. 5, 6, and 7
"...In the second case a child C of the container of A is an
ancestor container of B. In this case, A is before B if
the offset of A is less than or equal to the index of the
child C and A is after B otherwise."
could read:
In the second case, a child C of the container of A is an
ancestor container of B. A is before B if the offset of A
is less than or equal to the index of the child C.
Otherwise, A is after B.
"...In the third case a child C of the container of B is an
ancestor container of A. In this case, A is before B if
the index of the child C is less than the offset of B and
A is after B otherwise."
could read:
In the third case, a child C of the container of B is an
ancestor container of A. A is before B if the index of the
child C is less than the offset of B. Otherwise, A is after B.
"...In the fourth case, none of three other cases hold: the
containers of A and B are siblings or descendants of
sibling nodes. In this case, A is before B if the
container of A is before the container of B in a
pre-order traversal of the Ranges' context tree and A is
after B otherwise."
could read:
In the fourth case, none of three other cases hold: the
containers of A and B are siblings or descendants of
sibling nodes. A is before B if the container of A is
before the container of B in a pre-order traversal of the
Ranges' context tree. Otherwise, A is after B.
8.12. par. 1
unless it is fixed up in some way.
[seems colloquial]
unless it is amended [or revised?].
changes.html
------------
A.1.2: - CSS, Events, and Traversal
the following interfaces
the following interfaces:
idl-definitions.html
--------------------
C.4: Document Object Model Stylesheets
C.4: Document Object Model StyleSheets
java-binding.html
-----------------
Stylesheets
StyleSheets
D.4: Document Object Model Stylesheets
D.4: Document Object Model StyleSheets
ecma-script-binding.html
------------------------
Appendix E par. 1
Stylesheets
StyleSheets
E.1 - createAttribute, createAttributeNS, getAttributeNode,
setAttributeNode, removeAttributeNode, getAttributeNodeNS,
setAttributeNodeNS,
This method returns a Attr.
This method returns an Attr.
E.1 - createEntityReference
This method returns a EntityReference.
This method returns an EntityReference.
E.1 - createElementNS, getElementById
This method returns a Element.
This method returns an Element.
Object Comment, Object CDATASection, and Object EntityReference say
"as well as the properties and methods defined below" but none are
defined below.
E.2 - Object HTMLTableElement - createTHead, createTFoot,
createCaption, and deleteRow, and E.2 - Object
HTMLTableSectionElement - insertRow, and E.2 Object
HTMLTableRowElement - insertCell
This method returns a HTMLElement.
This method returns an HTMLElement.
E.5 - Object CSSMediaRule - insertRule
This method returns a unsigned long.
This method returns an unsigned long.
E.5 - Object CSSPrimitiveValue - getRGBColorValue
This method returns a RGBColor.
This method returns an RGBColor.
E.6 - Object DocumentEvent - createEvent
This method returns a Event.
This method returns an Event.
acknowledgments.html
--------------------
[last line]
Postscript
PostScript
glossary.html
-------------
equivalence
then collection of attribute names
the collection of attribute names
"...Two nodes are deeply equivalent if they are equivalent,
the child node lists are equivalent are equivalent as
NodeList objects, and the pairs of equivalent attributes
must in fact be deeply equivalent."
[Too many "equivalents"? Not sure, but could read:]
Two nodes are deeply equivalent if they are equivalent,
the child node lists are equivalent NodeList objects, and
the pairs of attributes are equivalent.
XML
"...Extensible Markup Language (XML) is an extremely simple
dialect of SGML which is completely described in this
document."
["this document" might be confused with DOM]
Extensible Markup Language (XML) is a simple dialect of SGML.
XML name
([XML]).
[XML].
reference.html
--------------
[The CORBA link moved to <http://www.omg.org/library/c2indx.html>.]
Reference:
[1] http://www.w3.org/TR/1999/CR-DOM-Level-2-19991210/
Thank you for your time, and good luck with your project.
--
Susan Lesch
susan@textet.com
http://www.textet.com/
Received on Wednesday, 16 February 2000 15:00:05 UTC