bug#11262: help text fro sorted? predicate is wrong/misleading.

[Ian Hulin <ian@hulin.org.uk>]

Hi Ludo, Alexei,
Please avoid C-speak in documentation if possible.
(See below)

On 22/04/12 00:38, Ludovic Courtès wrote:
> Hi Alexei,
> 
> (Removing Cc: guile-devel.)
> 
> Thanks for the patch!
> 
> Alexei Matveev <alexei.matveev@gmail.com> skribis:
> 
>> --- a/libguile/sort.c +++ b/libguile/sort.c @@ -101,9 +101,10 @@
>> SCM_DEFINE (scm_restricted_vector_sort_x,
>> "restricted-vector-sort!", 4, 0, 0, * (not (less? (list-ref list
>> i) (list-ref list (- i 1)))). */ SCM_DEFINE (scm_sorted_p,
>> "sorted?", 2, 0, 0, (SCM items, SCM less), -	    "Return
>> @code{#t} iff @var{items} is a list or a vector such that\n" -
>> "for all 1 <= i <= m, the predicate @var{less} returns true
>> when\n" -	    "applied to all elements i - 1 and i") +
>> "Return @code{#t} iff @var{items} is  a list or a vector such\n" 
>> +	    "that for all  1 <= i <= m,  the predicate @var{less}
>> returns\n" +	    "@code{#f} when comparing element i to the
>> preceeding element\n" +	    "i - 1.")
> 
> How about this:
> 
> Return @code{#t} iff @var{items} is a list or vector such that, for
> each element @var{x} and the next element @var{y} of @var{items}, 
> @code{(@var{less} @var{x} @var{y})} returns @code{#f}.
> 
> This avoids use of ‘m’, which would need to be defined, and makes
> it clear what “comparing element i to the preceeding element”
> means.
> 
> What do you think?
> 

Please spell out iff, which I presume means "if-and-only-if".  The
reason is that on first reading it looks ambiguous to old dinosaurs
like me who may have experience of programming languages using iff as
a token for "if-false" back in the Jurassic period.

Or maybe say:

Return @code{#t} when @var{items} is a list or vector such that,
   for each element @var{x} and the next element @var{y} of @var{items},
   @code{(@var{less} @var{x} @var{y})} returns @code{#f}.


Cheers,
Ian Hulin