Monkey see, monkey do

In this item I said, incorrectly, that I was unable to use Mozilla's DOM 3 XPath implementation to query document subtrees. Wrong. I was merely unable to read the documentation. The XPath implementation can, of course, query subtrees. You can see an example of both whole-document and partial-document queries in this revised version of the Greasemonkey script that adds next channel links to Bloglines' "river of news" view.

I know I'm not alone in this failing, but it is a failing: I learn poorly from API documentation, and rely almost exclusively on examples. According to the pattern I've internalized from other XPath implementations, including libxml, the query method attaches to what's called the context node -- your current spot in the document. So if this query produces a DIV node:

div = document.query(_, _, _)

p = div.query(_, _, _)

But in Mozilla's implementation of DOM 3 XPath, the query always attaches to the document, and the context node is a parameter, so:

div = document.query(_, document, _)
  
p = document.query(_, div, _)

This is clearly spelled out in the documentation, which I had read -- or rather, looked at -- but my API documentation dyslexia, coupled with past conditioning to expect a different pattern, prevented me from seeing it. A (friendly) dope slap from Mozillans Brendan Eich and Peter Van der Beken finally set me straight.

When I went back and looked at another piece of documentation I'd also referred to -- one that does include examples -- I noted this comment:

For example, XXX - want an example with add and remove nodes and probably also with contextNode != document

Ironically the whole purpose of this exercise was to enhance a feature of Bloglines -- its "river of news" view -- which, judging by blog and email comments about this item, is typically not discovered by Bloglines users. In the tree pane, clicking on an individual feed loads that feed's items into the viewing pane, and that's apparently how most folks operate. Clicking on the top-level folder loads everything into the viewing pane, thus creating the "river of news" view. This is logically consistent, though it would be more discoverable if, when hovering over the link, the popup message read Load all unread items into viewer rather than 52 updated feeds (253 hidden). But I suspect that the light bulb still wouldn't really click on for a lot of people until they saw it happen -- which is why I've come to see screencasts as such a powerful and necessary tool.

We have the power of reason. But when we learn things, a lot of the time, it's monkey see, monkey do.

Former URL: http://weblog.infoworld.com/udell/2005/10/04.html#a1314