Re: [XBL] Editorial: xblSetInsertionPoint()

* Ian Hickson wrote:
>On Thu, 5 Oct 2006, Anne van Kesteren wrote:
>> In http://www.w3.org/TR/2006/WD-xbl-20060907/#xblsetinsertionpoint the 
>> xblSetInsertionPoint() method is defined as taking a Node though the 
>> prose suggests it only takes an Element...

>> A somewhat clear description of what it does, or pointer to the 
>> appropriate section, wouldn't hurt either (I've seen the example added 
>> in CVS, didn't help much).
>
>I don't really understand why the current definition is unclear, but maybe 
>I've spent too much time nose-first in the spec to really have a clear 
>view. Any suggestions?

Let's have a look:

  xblSetInsertionPoint 

    The xblSetInsertionPoint method must check that the given node is
    a child of the same bound element as the shadow tree is itself
    associated with, and, if it is, must check that the node matches
    this content element, and, if it does, must assign the node to this
    content element instead of whatever previous content element it was
    assigned to.

This is complete gibberish, I cannot even parse "the same bound element
as the shadow tree is itself associated with" and it certainly does not
say what the method does. That aside, I approached the problem as
follows:

  1. the name suggests the method sets an insertion point, so I
     searched the document for the definition of this term. It
     seems there is none.

  2. ignoring the unparsable text, we have "node matches content
     element". I then searched the document for the definition
     of when a node matches a content element. The term "match"
     occurs first in

       If the includes attribute successfully matches against
       children of the bound element ...

     ... so, presumably, a node matches a content element if
     the includes attribute "successfully matches". When is
     that the case?

       The includes attribute can be used to indicate that only
       certain content should be placed at the content element.
       Its value is a selector. (See: processing content elements.)

     Amazed how it would make sense to anyone to define the
     processing of an element way outside the introduction
     of the element, I followed the link and found the term
     again in this "sentence":

       The explicit children of an element are the nodes that
       are listed in the element's childNodes array, with the
       exception that any content elements in that array are
       instead replaced by whatever nodes they currently have
       assigned to them, or, if no nodes match that content
       element, by the child nodes of that content element.

     So the document uses the term "node matches content
     element" long before it attempts to define it. Then we
     have:

       If no includes attribute is specified, a content element
       is considered generic and will match on all content,
       including text nodes, CDATA nodes, comments, and so on.

     "Something will match on something" sounds more like a non-
     normative description of a process than a definition of when
     a node matches a content element, but I chose to take this
     to mean: any node matches a content element if the content
     element has no includes attribute -- even though that contra-
     dicts my earlier assumption.

     Then:

       If the includes attribute is specified, it must be
       interpreted as a selector, and only elements that match the
       selector apply to that insertion point. If the selector is
       invalid, the content element does not match any nodes.
       Matching of the elements to the selector is done without
       taking into account the shadow tree in which the insertion
       point itself is found.

     Here I can add to the earlier definition: no node matches a
     content element if it has a includes attribute and its value
     is invalid. The first part does not define when a node matches
     a content element and it uses the term "insertion point" for
     which I could not find a definition. Ignoring that, I chose to
     add to my definition: any node that matches the selector
     specified in the includes attribute matches a content element.

     This is about all information I could find regarding when a
     node matches a content element.

  3. Then let's go back to the unparsable text "must check that the
     given node is a child of the same bound element as the shadow
     tree is itself associated with". Silly as I am, I tried to use
     the preceding text to read meaning into this. The section starts
     out with:

       The XBLContentElement interface is implemented by content
       elements that are inside shadow template trees. It can be
       obtained using binding-specific casting methods on the Element
       interface.

     Okay, so the content elements we are looking at are in shadow
     template trees. What is a shadow template tree? Well, this is
     the only occurance of "template tree" in the document, so maybe
     "tree" is redunant with "shadow template". Looking for this term,
     I found it in two examples, and in this part of the document. So,
     doh, this text doesn't really help me.

     Okay, then the next bit of text:

       xblChildNodes of type NodeList, readonly

         The xblChildNodes attribute must return a NodeList containing
         a live list of all the nodes that are currently assigned to
         that insertion point.

     "that"? Perhaps "this"? If that were so, some content elements
     would be "insertion points". I then grepped for this term again:

       The content element is used inside shadow content to specify
       insertion points ...

       The inherited element represents an insertion point ...

       ...

       The explicit children must be processed in order, so if two nodes
       match an insertion point, their order in the insertion point is
       the same as their relative order in the explicit children list.

     Uhm, that me confused again; so nodes can match insertion points,
     and a inherited element represents an insertion point. Then what
     does the document say about that?

       The inherited element represents an insertion point for the next
       inherited shadow tree. If the binding is the base binding (and
       thus has no inherited bindings) or if none of the bindings it
       inherits from have shadow trees, or if this is not the first
       inherited element in the binding's shadow tree, then the contents
       of the inherited element (if any) are used instead.

     The second sentence is "If a, or b, or c, then x are used instead".
     Instead of what? For what? "Foo represents bar; if baz, then x is
     used instead"?? The document then goes on

       (See: rules for shadow content generation.)

     In the referenced section, the 'inherited' element is not mentioned
     at all, neither are insertion points. I don't really see how that
     section helps me understand the 'inherited' element.

     ...

     Back to "must check that the given node is a child of the same
     bound element as the shadow tree is itself associated with". Okay,
     the node must be a child. Of a bound element. There is a shadow
     tree. And there is a relationship bound element <=> shadow tree.

     I do not understand why the text says "same". I do not understand
     which "shadow tree" is being referred to, or, alternatively, which
     bound element is being referred to. So let's go back and check what
     a "shadow tree" is...

     That's turns out to be difficult, the definition of the term refers
     to as many as three different terms which are introduced only much
     later in the document, and then refers to a fourth section for more
     information. In the Introduction. Long before discussing, say, the
     "Relationship to XBL1" and the "Relationship to XSLT".

     I then tried to read the example in the section under discussion.
     It's not well-formed, lacks an example bound document, uses not
     widely known ECMAScript extensions, complicated features like
     closures returned from inline Function objects and 'with', and
     then, eventually, points out that a corresponding real-world
     example would be considerably more complex.

     So I give up here.

An author will read this section of the document asking "What is this
for, what does it do". There is not a single bit of information con-
cerning these questions, there is only some text detailing how to im-
plement the feature. It seems quite natural that Anne is having trouble
to understand what the method does.
-- 
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

Received on Friday, 6 October 2006 18:12:28 UTC