Please send me a documentation paragraph that I can add to .find
which
makes this more explicit and understandable. Hopefully this will
eliminate future confusion over the usage.
There is a little bit of documentation, but it's in the XPath class, which
takes a little tracking down. It doesn't help the the XPath rdocs are messed
up: the doc for .find ends up in XML::XPath::InvalidPath for reasons I
haven't been able to ferret out.
Here's a patch that tries to explain things, as applied to the XPath file.
(I haven't looked too hard into why this is getting put in the wrong place,
though I guess I could.) This could be moved in whole to the Node class if
desired or a pointer from the Node class to the XPath class.
Index: ext/libxml/ruby_xml_xpath.c
===================================================================
--- ext/libxml/ruby_xml_xpath.c (revision 242)
+++ ext/libxml/ruby_xml_xpath.c (working copy)
@@ -99,8 +99,8 @@
* call-seq:
* XML::XPath.find(path, namespaces = [any]) => xpath
*
- * Find nodes matching the specified xpath (and optionally any of the
- * supplied namespaces) and return as an XML::Node::Set.
+ * Find nodes matching the specified xpath and return as an
+ * XML::Node::Set.
*
* The optional namespaces argument may take one of
* two forms:
@@ -109,9 +109,33 @@
* * An array of:
* * strings in the form like above
* * arrays in the form of ['prefix','uri']
- *
- * If not specified, matching nodes from any namespace
- * will be included.
+ *
+ * For example, to match the <p> elements in the XHTML document
+ * <html xmlns="http://www.w3.org/1999/xhtml";>
+ * <p />
+ * <p />
+ * </html>
+ * you could write
+ * doc.find "//x:p", "x:http://www.w3.org/1999/xhtml";
+ *
+ * Two very commonly asked questions are:
+ *
+ * * How do I match nodes that use the default namespace prefix
+
+ * The example shows how to do this. Even though the default namespace
+ * prefix is used in the document, the xpath expression must
+ * explicitly identify the namespace. The only nodes that a pattern
+ * without a namespace will match are nodes that do not have a
+ * namespace, neither explicit nor from a default prefix.
+ *
+ * * How do I match particular nodes within any namespace
+ *
+ * It is possible to match all nodes with the star pattern, e.g.,
+ * <tt>//*</tt>, and it is possible to match all nodes within an
+ * individual namespace, e.g., <tt>//ns:*</tt>, but it is not possible
+ * to match individual nodes from any namespace: <tt>//*:p</tt> is
+ * invalid.
+ *
*/
VALUE
ruby_xml_xpath_find(VALUE class, VALUE anode, VALUE xpath_expr, VALUE
nslist) {
_______________________________________________
libxml-devel mailing list
libxml-devel@rubyforge.org
http://rubyforge.org/mailman/listinfo/libxml-devel
