Steven, your explanation text looks excellent - clear and some useful examples.
I had only a couple of minor comments - the line "strings in the form like above" is perhaps a bit awkward. Maybe it would be better to just give an example, i.e.: strings in the form "prefix:href" Also, both of the questions you pose should have a question mark at the end, i.e.: * How do I match nodes that use the default namespace prefix? * How do I match particular nodes within any namespace? I hope these comments are useful, and apologies for not sending them in the form of a proper patch, but I'm labouring under the threat of a rapidly approaching deadline. -- sam On 21/01/2008, Steven Parkes <[EMAIL PROTECTED]> wrote: > > > 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 > [email protected] > http://rubyforge.org/mailman/listinfo/libxml-devel >
_______________________________________________ libxml-devel mailing list [email protected] http://rubyforge.org/mailman/listinfo/libxml-devel
