From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: ludo@gnu.org (Ludovic =?UTF-8?Q?Court=C3=A8s?=) Newsgroups: gmane.lisp.guile.bugs Subject: bug#19478: [PATCH] Improve SXPath documentation Date: Wed, 04 Mar 2015 10:23:28 +0100 Message-ID: <87mw3tnmjz.fsf@gnu.org> References: <87fvbv7op7.fsf@mango.localdomain> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1425461062 15300 80.91.229.3 (4 Mar 2015 09:24:22 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 4 Mar 2015 09:24:22 +0000 (UTC) Cc: 19478@debbugs.gnu.org To: rekado Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Wed Mar 04 10:24:11 2015 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1YT5XF-0006jB-OM for guile-bugs@m.gmane.org; Wed, 04 Mar 2015 10:24:09 +0100 Original-Received: from localhost ([::1]:42836 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YT5XE-0001yI-JN for guile-bugs@m.gmane.org; Wed, 04 Mar 2015 04:24:08 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40235) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YT5XA-0001yC-72 for bug-guile@gnu.org; Wed, 04 Mar 2015 04:24:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YT5X8-00020g-Ue for bug-guile@gnu.org; Wed, 04 Mar 2015 04:24:04 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:35987) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YT5X8-00020Z-R6 for bug-guile@gnu.org; Wed, 04 Mar 2015 04:24:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1YT5X8-00031J-EQ for bug-guile@gnu.org; Wed, 04 Mar 2015 04:24:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: ludo@gnu.org (Ludovic =?UTF-8?Q?Court=C3=A8s?=) Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Wed, 04 Mar 2015 09:24:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 19478 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Original-Received: via spool by 19478-submit@debbugs.gnu.org id=B19478.142546101511571 (code B ref 19478); Wed, 04 Mar 2015 09:24:02 +0000 Original-Received: (at 19478) by debbugs.gnu.org; 4 Mar 2015 09:23:35 +0000 Original-Received: from localhost ([127.0.0.1]:34555 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YT5Wg-00030Z-Cn for submit@debbugs.gnu.org; Wed, 04 Mar 2015 04:23:34 -0500 Original-Received: from fencepost.gnu.org ([208.118.235.10]:53512 ident=Debian-exim) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YT5We-00030L-3V for 19478@debbugs.gnu.org; Wed, 04 Mar 2015 04:23:33 -0500 Original-Received: from reverse-83.fdn.fr ([80.67.176.83]:50679 helo=pluto) by fencepost.gnu.org with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1YT5Wd-0000lB-6m; Wed, 04 Mar 2015 04:23:31 -0500 In-Reply-To: <87fvbv7op7.fsf@mango.localdomain> (rekado@elephly.net's message of "Wed, 31 Dec 2014 17:45:40 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4 (gnu/linux) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:7742 Archived-At: rekado skribis: > 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. Nice! > 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) Good to hear. ;-) > 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 just tried and this seems to be a bug in the Emacs Info reader. The standalone Info reader brings you to the right place, and the HTML and PDF outputs are OK. Could you report it? Some superficial comments follow. I realize some of these may be present in the original SXPath source, but it seems best to fix them anyway. BTW, I think we should add a sentence at the beginning of the =E2=80=9CSXPa= th=E2=80=9D section saying that the material is taken from the SXPath source by Oleg et al. > mechanically expanded into the full form by simple rewriting rules. In > -case of SXPath the corresponding rules are given as comments to a sxpath > -function, below. The regression test suite at the end of this file shows > -a representative sample of SXPaths in both notations, juxtaposed with > -the corresponding XPath expressions. Most of the samples are borrowed > +case of SXPath the corresponding rules are given in the documentation of Missing =E2=80=9Cthe=E2=80=9D (=E2=80=9CIn the case of SXPath=E2=80=9D.) > +The regression test suite at the end of the file SXPATH-old.scm shows a @file{SXPATH-old.scm} > +representative sample of SXPaths in both notations, juxtaposed with the > +corresponding XPath expressions. Most of the samples are borrowed > literally from the XPath specification, while the others are adjusted > -for our running example, tree1. > +for our running example, @code{tree1}. The issue was already there, but apparently =E2=80=98tree1=E2=80=99 is not = used elsewhere in the documentation. Perhaps it=E2=80=99s best to remove it? > +@subsubsection Basic converters and applicators Capital C and capital A. > +A converter is a function mapping a nodeset (or a single node) to another > +nodeset. Its type can be represented like this: > + > +@smallexample > + type Converter =3D Node|Nodeset -> Nodeset > +@end smallexample Rather @example (@smallexample means small typeface) and no space before =E2=80=98type=E2=80=99 (same for the other examples below.) > @deffn {Scheme Procedure} node-typeof? crit > +This function implements a 'Node test' as defined in Sec. 2.3 of XPath > +document. A node test is one of the components of a location step. It Missing =E2=80=9Cthe=E2=80=9D (=E2=80=9Cof the XPath document=E2=80=9D.) > +@subsubsection Converter combinators Capital C. > +Combinators are higher-order functions that transmogrify a converter or > +glue a sequence of converters into a single, non-trivial converter. The > +goal is to arrive at converters that correspond to XPath location paths. > + > +From a different point of view, a combinator is a fixed, named > +@emph{pattern} of applying converters. Given below is a complete set of When introducing a term, use @dfn; so @dfn{pattern}. > +@smallexample > +(define (node-closure f) > + (node-or > + (select-kids f) > + (node-reduce (select-kids (node-typeof? '*)) (node-closure f)))) Align below the =E2=80=98e=E2=80=99 of =E2=80=98define=E2=80=99. Could you send an updated patch? Thanks! Ludo=E2=80=99.