Re: L3 Core Document comments

Philippe Le Hegaret wrote:

>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.
>
I assume that you meant "adequate" in the first sentence in the previous 
paragraph and I would disagree since I could not find anything is the 
spec like the second sentence in the previous paragraph.  Is there some 
other recommendation that already uses the term "actual encoding" in the 
manner?

If that is your intention, I think that "initialEncoding" is clearer.

>config: Using an abbreviation is unusual.
>  
>
>
>We do have some abbreviation, such as "Attr", "id", "doctype". We choose
>to keep config for the moment.
>  
>

OK

>  
>
>>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.
>  
>
OK.  Wanted to clarify that URI/IRI checking was intentionally omitted 
instead of overlooked.  So an implementation would be non-conformant if 
it raised an exception on a malformed URI?

>  
>
>>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.
>
I think that "lastEncoding" or "saveEncoding" is clearer.

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

It would be good if the first sentences in each description were 
parallel.  For example, adopt could say:

Attempts to adopt a node from another document to this document.  [...]  
If supported, the source node is  removed from the original document 
and  altered changing the ownerDocument of the node and any descendants,,,


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

Is it an opening for an implementation to not attempt to adopt a node 
under any circumstances?  That is

class DocumentImpl implements Document
   public Node adoptNode(Node node) {
       //   i'm not even going to try
       return null;
    }
}

There should be some statement of allowable changes to the source node 
in the event of a null return.  Could an adoptNode implementation detach 
the source node from its parent and then fail to add it to the target 
document?

A Node return type was appropriate for importNode since it would create 
a new Node.  For adoptNode, only acceptible return values appear to be 
the source node or null.  The return value is just an expensive boolean.

>  
>
>>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 norma
>
>izeDocument method
>does not generate fatal errors, as well as does not raise exceptions
>(specified by the IDL).
>

This was discussed earlier.  I was interpreting "fatal error" in the 
panic error (System.exit(-1)) sense.

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

Received on Friday, 29 August 2003 01:56:34 UTC