Hi,
the SXPath documentation in the Guile manual is rather sparse. To
figure out how to use SXPath functions I had to look up the source code
at module/sxml/upstream/SXPath-old.scm. When I did, I noticed that
there are lots of useful comments that really should be part of the
documentation.
Attached is a patch that takes the comments from the sources and adds
them to the Texinfo sources. I chose to rewrite a few comments to make
them a little clearer and added some Texinfo markup, but most of the
documentation is unchanged from Oleg's comments in the source.
While these changes don't result in great SXML documentation on par
with the rest of the Guile documentation, I do think they make the
SXPath section a lot more useful.
This is the first time I wrote Texinfo documentation (it's not even
close to being the obstacle to contributing that some people on another
mailing list make it out to be), so I'm not sure I chose the most
appropriate markup in all cases.
There is also one instance where I think I did the right thing but the
results are wrong: I added a link to an example further down the page
but in my compiled version of the manual I end up far from the anchor
when I follow the link.
This is the section containing the reference:
Similarly to XPath, SXPath defines full and abbreviated notations for
location paths. In both cases, the abbreviated notation can be
mechanically expanded into the full form by simple rewriting rules. In
case of SXPath the corresponding rules are given in the documentation of
the @code{sxpath} procedure. @xref{sxpath-procedure-docs,,SXPath
procedure documentation}.
...
And here's the anchor:
@anchor{sxpath-procedure-docs}
@deffn {Scheme Procedure} sxpath path
Evaluate an abbreviated SXPath.
...
I would appreciate it if you could take a look at my changes and suggest
improvements.
Cheers,
rekado
0001-doc-Add-SXPath-documentation-from-sources.patch
Description: Text Data
--- End Message ---