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

On Tue, 2004-02-24 at 02:22, Susan Lesch wrote:
> 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?

That would be certainly nice but I don't think that someone is willing
to take the entire document and search for those. Document and
DOMImplementation are not linked because there are part of the Core and
the scripts don't generate automatic link between DOM modules.

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

Fixed.

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

Yes. The sentence you mentioned is just after the table of contents and
before the sub sections. I don't think changes are needed.

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

DOM specifications never used the RFC 2119 explicitly and this is
unfortunate The Manual of Style was published a long time after the
publication of the publication of DOM Level 2.

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

The conformance section for DOM Level 3 modules is included in the
introduction of DOM Level 3 Core, as noted in the introduction of
section 1.3. There is no need to repeat it across all DOM Modules.

> 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.
>
> [...]

done.

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

Not done, since a complete document is not a fragment. I kept the
current wording.

Philippe

Received on Tuesday, 24 February 2004 14:43:01 UTC