bug#19478: [PATCH] Improve SXPath documentation

[rekado]

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