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