Comments for PR-DOM-Level-3-LS-20040205

Hello,

These are comments for your DOM 3 Load and Save Proposed
Recommendation [1] to use as you see fit.

The document would benefit from adherence to a markup plan. Why
for example is "read only node" a link twice in one paragraph? Why in
LSParserFilter are Document and DOMImplementation not links (or marked
up) in "the owner Document and DOMImplementation objects exist"? Why is
Node marked up and capitalized sometimes and plain text others? Why is
External XML Entity capitalized and not marked up?

---

Load and Save section 1.3 says "The interface within this section
is considered fundamental, and must be fully implemented by all
conforming implementations of the DOM Load and Save module." Do you
mean all of the "interfaces" (a typo) within section 1.3? If you do,
then why does the introduction to section 1 say, "The functionality
specified in this section (the Load and Save functionality) is
sufficient to allow software developers and web script authors to load
and save XML content inside conforming products." Do you mean all of
the functionality specified in all of section 1?

Section 1.3 says a DOM application may or must do some things. If the
words may and must are meant in the RFC 2119 sense, then the document
should state so. Further, it should credit the RFC and make it a
normative reference. The Manual of Style has example markup [2]. If may
and must aren't used this way, then I would write an explanation of
what you do mean by them.

Statements like the following state requirements in different ways:
"is," "will be," "are expected to." So, I can't search for conformance
keywords (and really shouldn't have to). Maybe no one else would notice
but I think this is worth mentioning to see what you think.

- For all other types of nodes the serialized form is implementation
   dependent.
- any occurrence of a character that cannot be represented in the output
   character encoding is reported as a DOMError fatal error
- If inconsistencies are found, the serialized form of the document will
   be altered to remove them.
- implementations are expected to raise implementation specific errors and
   warnings

Maybe a section named "Conformance" would help Load and Save?

---

The rest of this note is minor editorial.

s/DOM Working Group members/DOM Working Group participants/
s/paramter/parameter/
s/web/Web/
s/The list of interfaces involved with the Loading and Saving of
XML documents is:/The interfaces involved with the loading and saving of
XML documents are:/
s/LSReader is NOT bound/LSReader is <em>not</em> bound/
s/therefore as no recommended meaning/therefore has no recommended meaning/
s/parameters recognized in on/parameters recognized in/ (or on)
s/URN's/URNs/

In the TOCs and headings I would capitalize Interfaces and References.

These sentences were pretty long and could be shortened something like:

     This specification does not attempt to define exactly when progress
     events should be dispatched. That is intentionally left as
     implementation-dependent. Here is one example of how an application
     might dispatch progress events: Once the parser starts receiving
     data, a progress event is dispatched to indicate that the parsing
     starts. From there on, a progress event is dispatched for every
     4096 bytes of data that is received and processed.

Same here:

     This DOMConfiguration is specific to the parse operation. No
     parameter values from this DOMConfiguration object are passed
     automatically to the DOMConfiguration object on the Document that
     is created, or used, by the parse operation.

     The source document must be an XML fragment. A fragment is anything
     except a complete XML document, a DOCTYPE (internal subset), entity
     declaration(s), notation declaration(s), or XML or text
     declaration(s). Note that a complete XML document with context node
     of type DOCUMENT_NODE and action ACTION_REPLACE_CHILDREN is a
     fragment.

     The system identifier is optional if there is a byte stream, a
     character stream, or string data. It is still useful to provide
     one, since the application will use it to resolve any relative URIs
     and can include it in error messages and warnings. (The LSParser
     will only attempt to fetch the resource identified by the URI
     reference if there is no other input available in the input
     source.)

     For XML [XML 1.0] resources (i.e. entities), applications must use
     the value "http://www.w3.org/TR/REC-xml". For XML Schema [XML
     Schema Part 1], applications must use the value
     "http://www.w3.org/2001/XMLSchema".

     The constants SHOW_ATTRIBUTE, SHOW_DOCUMENT, SHOW_DOCUMENT_TYPE,
     SHOW_NOTATION, SHOW_ENTITY, and SHOW_DOCUMENT_FRAGMENT are
     meaningless here. Those nodes will never be passed to
     LSParserFilter.acceptNode.

[1] http://www.w3.org/TR/2004/PR-DOM-Level-3-LS-20040205/
[2] http://www.w3.org/2001/06/manual/#RFC

Best wishes for your project,
-- 
Susan Lesch           http://www.w3.org/People/Lesch/
mailto:lesch@w3.org               tel:+1.858.483.4819
World Wide Web Consortium (W3C)    http://www.w3.org/

Received on Tuesday, 24 February 2004 02:22:36 UTC