Re: XML::LibXML::DocumentFragment

On Feb 24, 2011, at 00:31 , Tom Metro wrote:
> Robin Berjon wrote:
>> No offense, but for someone who only a few hours ago did not know
>> what a DocumentFragment was, I think that you're a little bit quick
>> to criticise the standard. 
> 
> I said it was unusual, not wrong, though I suppose I did imply that. My
> point was to seek insight. Is there a good reason why they broke from
> convention and took that approach?

Could you clarify what convention you are referring to? I can find many quirks in the DOM, and many things that I think could be improved, but I've been using DFs for an awful long time and this never struck me as even slightly odd.

> And yeah, I take some offense. DOM and related standards comprise a
> large ecosystem. I've been using the DOM API to some degree for
> something like a decade, but that doesn't mean I'm familiar with every
> corner of it.

I never said that you should be familiar with every corner of it, nor that you should like it — it's perfectly fine as a user to only know what you need. Simply that before implying that something is poorly designed a little bit of research and further thinking into the issue might be warranted.

> It also means I don't need to be intimately familiar with
> DocumentFragment to spot an inconsistency in how it is specified in
> comparison to other W3C and Internet standards.

Well I have some degree of familiarity with "other W3C and Internet standards" and I don't see the inconsistency, so it would be appreciated if you could clarify your point here.

>> The Document objects has a rather central role in the way in which
>> the DOM is architected, moving nodes between documents certainly has
>> implications that moving them into a DocumentFragment does not. But more
>> importantly, a Document can quite logically only have one child element
>> node. DocumentFragments don't have this limitation.
> 
> OK, that's a better explanation for why a DocumentFragment isn't a
> trivial subclass of a Document object, but it still doesn't explain why
> many of the Document-specific methods that should be equally applicable
> to a DocumentFragment aren't supported (createElement() being the
> example I previously mentioned).

What I don't understand is why you think that those methods should be available on DF and not on, say, pretty much any node. By you word processor analogy below, given that an element can contain other elements it should expose createElement as well, right? In fact, it could expose all the create* methods except createDocument and createDocumentType. I guess by the same design Attr nodes would expose a more limited set, comprising createTextNode and createEntityReference.

That could work. It would create (no pun intended) a larger API surface though, with lots of duplicate functionality (since these additional create* methods would do very much the same thing that they do on Document, except that they'd have to be implemented differently). This in turn means more tests, more potential for bugs, etc. In general, that's considered bad API design.

Implementation-wise it wouldn't change much. Several of those methods need to hit to the Document object because they need information for which it is the logical holder. For instance, when you call createElement it looks at the DocumentType object — which is a natural property of Document — to check whether any attributes should be defaulted. If you made createElement available on other interfaces, it would still need to talk to the Document (which every Node has a pointer to) to do its work.

> If you don't know, that's fine. The other poster answered my original
> question by referencing the spec, which showed that XML::LibXML's
> behavior was consistent with the spec. Beyond that I'm just pondering
> why the spec is the way it is.

I hope that the explanation above helps. It probably requires a little bit of spec exegesis and some implementation experience to come up with it. But there are other, more obvious reasons. For instance, if DF were a trivial subclass of Document, it would inherit all sorts of things that would be misplaced, borderline meaningless, or potentially harmful such as xmlVersion, xmlEncoding, doctype, domConfig, etc. That's already to a lesser degree the case with Node, a limitation due to the DOM being specified also for languages like Java that can't do OO, but it's manageable. Making it worse for no obvious functionality gain (df.createElement isn't all that better than df.ownerDocument.createElement) does not seem like a good idea.

> Lets stick to rational analogies.

I'm not sure it's possible for reasoning by analogy to be rational :)

> If a word processor edits documents, and a mythical "paragraph
> processor" edits paragraphs, which you'd likely agree are a fragment of
> a document, then logically I'd expect to be able to use a paragraph
> processor to add/remove words (elements), just as I would with a word
> processor.

No, I probably wouldn't. API design is not like UI design. For users, convenience and affordance primes. For APIs, it's generally a better idea to strictly limit functionality (and add convenience at another layer). For standardised APIs I think that's even more the case. You really want to expose just the bare bones that are needed for everyone to work, and then you can let projects like jQuery make things easy.

In your example, if there were an API I would expect the document to be a clearinghouse for things that I can insert in a paragraph. For instance, the document is likely where a set of styles are held. When inserting something, I probably want to hit against that.

> What I expect it can't do are things that are document specific. (Say
> creating a title page, or footnotes, or setting page margins, or
> whatever aspects you'd attribute to the document at large.)

Well, in that case it shouldn't inherit from document!

-- 
Robin Berjon - http://berjon.com/



_______________________________________________
Perl-XML mailing list
[email protected]
To unsubscribe: http://listserv.ActiveState.com/mailman/mysubs