GNU bug report logs - #19478
[PATCH] Improve SXPath documentation

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: ludo <at> gnu.org (Ludovic Courtès)
Cc: tracker <at> debbugs.gnu.org
Subject: bug#19478: closed ([PATCH] Improve SXPath documentation)
Date: Sat, 05 Sep 2015 16:54:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Sat, 05 Sep 2015 18:53:45 +0200
with message-id <87wpw4dcyu.fsf <at> gnu.org>
and subject line Re: bug#19478: [PATCH] Improve SXPath documentation
has caused the debbugs.gnu.org bug report #19478,
regarding [PATCH] Improve SXPath documentation
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
19478: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19478
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: rekado <rekado <at> elephly.net>
To: bug-guile <at> gnu.org
Subject: [PATCH] Improve SXPath documentation
Date: Wed, 31 Dec 2014 17:45:40 +0100

[Message part 3 (text/plain, inline)]

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 (text/x-patch, attachment)]

[Message part 5 (message/rfc822, inline)]

From: ludo <at> gnu.org (Ludovic Courtès)
To: Ricardo Wurmus <rekado <at> elephly.net>
Cc: 19478-done <at> debbugs.gnu.org
Subject: Re: bug#19478: [PATCH] Improve SXPath documentation
Date: Sat, 05 Sep 2015 18:53:45 +0200

Ricardo Wurmus <rekado <at> elephly.net> skribis:

>>> From 302fd7dd9d293ca1e88a39c255704ccd173caed4 Mon Sep 17 00:00:00 2001
>>> From: Ricardo Wurmus <rekado <at> elephly.net>
>>> Date: Sun, 30 Aug 2015 10:58:42 +0200
>>> Subject: [PATCH] doc: Add SXPath documentation from sources
>>>
>>> * doc/ref/sxml.texi (SXPath): Add procedure documentation from sources.
>>
>> Pushed.  I added a note at the top of the file that this is from
>> SXPath.scm, which is public-domain.
>
> Actually, my patch included these lines near the end of the first
> section:
>
>> +Much of the following material is taken from the SXPath sources by Oleg
>> +Kiselyov et al.
>
> Putting a note at the top also seems appropriate.

Yes, that’s what I thought; it makes it easier to see at a glance where
the material comes from and what its copyright status is.

>> Should this bug be closed now?  Your call.
>
> Yes, it can be closed now.  For future SXML documentation updates should
> I just send patches to guile-devel or open a bug report?

Either way is fine; it’s easier not to lose track of bugs, though.

Thanks!

Ludo’.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.