Hi Ludo,
my apologies for not responding to your comments for so long.
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 “SXPath”
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 “the” (“In the case of SXPath”.)
Fixed.
+The regression test suite at the end of the file SXPATH-old.scm shows a
@file{SXPATH-old.scm}
Ok.
+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 ‘tree1’ is not used
elsewhere in the documentation. Perhaps it’s best to remove it?
I removed the last sentence as it doesn’t make any sense unless the
example is added to the documentation. Maybe I’ll add additional
examples in a later patch.
+@subsubsection Basic converters and applicators
Capital C and capital A.
Oh, I forgot that the default is American English. I also changed the
other headings I added.
+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 = Node|Nodeset - Nodeset
+@end smallexample
Rather @example (@smallexample means small typeface) and no space before
‘type’ (same for the other examples below.)
Good to know. I fixed all of these type summaries to use “@example” and
without indentation.
@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 “the” (“of the XPath document”.)
Added.
+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}.
Okay.
+@smallexample
+(define (node-closure f)
+ (node-or
+ (select-kids f)
+ (node-reduce (select-kids (node-typeof? '*)) (node-closure f
Align below the ‘e’ of ‘define’.
Done.
Could you send an updated patch?
Attached is an updated patch.
After all this time I noticed that even after this patch, the SXPath
documentation is still not clear enough. I again found myself looking
up the sources to see actual examples. In a later patch I’d like to add
general examples as well as some examples for specific functions, if
that’s okay.
~~ Ricardo
From 302fd7dd9d293ca1e88a39c255704ccd173caed4 Mon Sep 17 00:00:00 2001
From: Ricardo Wurmus rek...@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.
---
doc/ref/sxml.texi | 298 +++---
1 file changed, 263 insertions(+), 35 deletions(-)
diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi
index 75867f3..75ebedc 100644
--- a/doc/ref/sxml.texi
+++ b/doc/ref/sxml.texi
@@ -250,8 +250,8 @@ internal and external parsed entities, user-controlled handling of
whitespace, and validation. This module therefore is intended to be a
framework, a set of ``Lego blocks'' you can use to build a parser
following any discipline and performing validation to any degree. As an
-example of the parser construction, this file includes a semi-validating
-SXML parser.
+example of the parser construction, the source file includes a
+semi-validating SXML parser.
SSAX has a ``sequential'' feel of SAX yet a ``functional style'' of DOM.
Like a SAX parser, the framework scans the document only once and
@@ -725,95 +725,323 @@ location path is a relative path applied to the root node.
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 as comments to a sxpath
-function, below. The regression test suite at
