Re: L3 Core Document comments

On Wed, 2003-07-30 at 00:44, Curt Arnold wrote:
> actualEncoding:  Not adequately explained.  Is this the encoding at the 
> time of parsing?  Do subsequent saves change the value?  initialEncoding 
> might be better.

We believe that the description is accurate. It is the encoding used
while loading the document. The value is read-only and cannot be
changed, including the LS module. write* operations in LS don't never
modify the document.

> config: Using an abbreviation is unusual.

We do have some abbreviation, such as "Attr", "id", "doctype". We choose
to keep config for the moment.

> documentURI: Should it be possible (or required) for an implementation 
> to raise an exception if a new value is set that is not a valid URI.

We didn't want to go into the issue of URI/IRI checking, so no exception
or error if you set to an invalid one. I clarified that no lexical
checking was done when setting documentURI. baseURI will return null if
an absolute URI cannot be determined. Note that we don't check the
xml:base attributes either.

> xmlEncoding: Can an implementation raise an exception if it does not 
> recognize the encoding on setting?  How is this affected by saves?   
> Does this affect saves (which would be in the L/S spec)?  Maybe it is 
> cleaner just to allow the encoding to be specified on the save request.

xmlEncoding has been changed to read-only, in order to simplify the
computation of the encoding used at save time (i.e. only
DOMOutput.encoding could be changed). Save defines an
"unsupported-encoding" error if the encoding is not supported.

> xmlStandalone: What occurs when this attribute is set to true and the 
> document does not satisify the requirements for standalone="yes".

normalizeDocument and the DOMSerializer will catch it, as defined by the
XML specification: this is a validity constraint. I added for that
effect in the description of xmlStandalone.

> adoptNode:
> The difference between adoptNode and importNode is not immediately 
> obvious. 

We think that the current description is clear enough. Here are some
excerpts from the first paragraphs of the 2 methods:

adoptNode:
[[
When possible, changes the ownerDocument of a node, its children, as
well as the attached attribute nodes if there are any.
]]

importNode:
[[
Imports a node from another document to this document. [...] The source
node is not altered or removed from the original document; this method
creates a new copy of the source node.
]]

> "from its parent child list" should be "from its parent's child list" or 
> better "from the child list of its parent"

done.

> "or null if the operation fails, such as when the source node comes from 
> a different implementation".  This seems to be a opening for an 
> implementation to always return null.  The expected failure scenarios 
> should be enumerated as exceptions.

Correct, it is indeed an opening for an implementation to refuse to
adopt a node from one document to an other. Several failure scenarios
can happen, predictable or implementation dependent ones, so any list
would be incomplete.

> getElementsByTagName:  "The special value "*" ... For XML, this is is 
> case-sensitive"
> "this is" should be "the tagname parameter" or the sentences should be 
> rearranged.

fixed.

> normalizeDocument: "Note that this method does not generate fatal errors"
>
> Should this be "does not raise exceptions"

No, the current description is correct. The normalizeDocument method
does not generate fatal errors, as well as does not raise exceptions
(specified by the IDL).

> renameNode:  What is the behavior when attempting to change the 
> attribute name to the name of an attribute that already exists on the 
> element.

The current description says:
[[
 When the node being renamed is an Attr that is attached to an
 Element, the node is first removed from the Element attributes map.
Then, once renamed, either by modifying the existing node or creating a
new one as described above, it is put back.
]]

i.e. it will replace the old attribute node, since it is equivalent to
the removal of the Attr node, then set it back using setAttributeNode.

Philippe

Received on Thursday, 28 August 2003 14:39:08 UTC