GNU bug report logs - #11262
help text fro sorted? predicate is wrong/misleading.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 11262 in the body.
You can then email your comments to 11262 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Alexei Matveev <alexei.matveev <at> gmail.com>
To: bug-guile <at> gnu.org
Subject: help text fro sorted? predicate is wrong/misleading.
Date: Tue, 17 Apr 2012 12:07:56 +0200

Hi, Guilers,

I seem to have almost convinced at least one another person that
the docstring of sorted? predicate is at least misleading:

guile> (sorted? '(0 0) <)
#t

guile> (help sorted?)
`sorted?' is a primitive procedure in the (guile) module.

 -- Scheme Procedure: sorted? items less
     Return `#t' iff ITEMS is a list or a vector such that for all 1 <=
     i <= m, the predicate LESS returns true when applied to all
     elements i - 1 and i

My suggestion for the docstring is below (feel free to improve my broken
english).

Alexei

diff --git a/libguile/sort.c b/libguile/sort.c
index ecadd82..b71d101 100644
--- 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.")
 #define FUNC_NAME s_scm_sorted_p
 {
   long len, j;                 /* list/vector length, temp j */

Message #8 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: Noah Lavine <noah.b.lavine <at> gmail.com>
To: Alexei Matveev <alexei.matveev <at> gmail.com>
Cc: 11262 <at> debbugs.gnu.org, guile-devel <guile-devel <at> gnu.org>
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Wed, 18 Apr 2012 21:14:10 -0400

It looks like you're right, and strangely enough there's a comment in
sort.c right above the definition of sorted? that has the correct
documentation.

I hope other people will correct me if I'm wrong, but I believe the
ideal thing for you to do now is submit a patch created with git
format-patch. That way you can write a git log entry, and your name
will be associated with the patch. You can see other recent log
entries for the standard guile format.

If you don't want to do this, I can do it for you, but I think it's
nicer if you are listed as the author since you did the work.

Thank you very much for reporting this,
Noah

On Tue, Apr 17, 2012 at 6:07 AM, Alexei Matveev
<alexei.matveev <at> gmail.com> wrote:
> Hi, Guilers,
>
> I seem to have almost convinced at least one another person that
> the docstring of sorted? predicate is at least misleading:
>
> guile> (sorted? '(0 0) <)
> #t
>
> guile> (help sorted?)
> `sorted?' is a primitive procedure in the (guile) module.
>
>  -- Scheme Procedure: sorted? items less
>     Return `#t' iff ITEMS is a list or a vector such that for all 1 <=
>     i <= m, the predicate LESS returns true when applied to all
>     elements i - 1 and i
>
> My suggestion for the docstring is below (feel free to improve my broken
> english).
>
> Alexei
>
> diff --git a/libguile/sort.c b/libguile/sort.c
> index ecadd82..b71d101 100644
> --- 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.")
>  #define FUNC_NAME s_scm_sorted_p
>  {
>   long len, j;                 /* list/vector length, temp j */
>
>
>

Message #11 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: Alexei Matveev <alexei.matveev <at> gmail.com>
To: Noah Lavine <noah.b.lavine <at> gmail.com>
Cc: 11262 <at> debbugs.gnu.org, guile-devel <guile-devel <at> gnu.org>
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Fri, 20 Apr 2012 12:20:29 +0200

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

Hi, Noah, Hi Guilers,

On Thu, Apr 19, 2012 at 3:14 AM, Noah Lavine <noah.b.lavine <at> gmail.com> wrote:
> It looks like you're right, and strangely enough there's a comment in
> sort.c right above the definition of sorted? that has the correct
> documentation.

Yes, that added me some confidence.

> I hope other people will correct me if I'm wrong, but I believe the
> ideal thing for you to do now is submit a patch created with git
> format-patch.

Attachment contains a patch created by "git format-patch origin".
The patch does exactly the same as the diff sent earlier.

Alexei

[0001-Reformulate-misleading-output-of-help-sorted.patch (application/octet-stream, attachment)]

Message #14 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: ludo <at> gnu.org (Ludovic Courtès)
To: Alexei Matveev <alexei.matveev <at> gmail.com>
Cc: Noah Lavine <noah.b.lavine <at> gmail.com>, 11262 <at> debbugs.gnu.org
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Sun, 22 Apr 2012 01:38:33 +0200

Hi Alexei,

(Removing Cc: guile-devel.)

Thanks for the patch!

Alexei Matveev <alexei.matveev <at> 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?

Thanks,
Ludo’.

Message #17 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ian Hulin <ian <at> hulin.org.uk>
To: bug-guile <at> gnu.org
Cc: 11262 <at> debbugs.gnu.org, Alexei Matveev <alexei.matveev <at> gmail.com>
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Sun, 22 Apr 2012 11:29:23 +0100

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 <at> 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

Message #23 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: ludo <at> gnu.org (Ludovic Courtès)
To: Ian Hulin <ian <at> hulin.org.uk>
Cc: 11262 <at> debbugs.gnu.org, Alexei Matveev <alexei.matveev <at> gmail.com>
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Sun, 22 Apr 2012 12:36:47 +0200

Hi,

Ian Hulin <ian <at> hulin.org.uk> skribis:

> Please spell out iff, which I presume means "if-and-only-if".

I think it’s fine: it’s used consistently in the manual, and it’s
documented (info "(guile) Typographical Conventions").

Ludo’.

Message #26 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: Alexei Matveev <alexei.matveev <at> gmail.com>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: Ian Hulin <ian <at> hulin.org.uk>, Noah Lavine <noah.b.lavine <at> gmail.com>,
	11262 <at> debbugs.gnu.org
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Sun, 22 Apr 2012 12:53:10 +0200

>> 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.

Yes, "m" should not be mentioned. But I think you got it backwards again:

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{y} @var{x})} returns @code{#f}.

Note the order of x and y in (less? y x) in the last line.

Alexei

Message #31 received at 11262-done <at> debbugs.gnu.org (full text, mbox):

From: ludo <at> gnu.org (Ludovic Courtès)
To: Alexei Matveev <alexei.matveev <at> gmail.com>
Cc: Ian Hulin <ian <at> hulin.org.uk>, Noah Lavine <noah.b.lavine <at> gmail.com>,
	11262-done <at> debbugs.gnu.org
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Sun, 22 Apr 2012 14:53:56 +0200

Hi Alexei,

Alexei Matveev <alexei.matveev <at> gmail.com> skribis:

>>> 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.
>
> Yes, "m" should not be mentioned. But I think you got it backwards again:
>
> 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{y} @var{x})} returns @code{#f}.
>
> Note the order of x and y in (less? y x) in the last line.

Oops, indeed.

Pushed in commit fd07759b7d4c9d631090b04855ab81b6a2109e9e.

Thanks for the report, patch, and review!

Ludo’.

Message #34 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: Marijn <hkBst <at> gentoo.org>
To: 11262 <at> debbugs.gnu.org, ludo <at> gnu.org
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Thu, 26 Apr 2012 09:31:09 +0200

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 22-04-12 14:53, Ludovic Courtès wrote:
> Hi Alexei,
> 
> Alexei Matveev <alexei.matveev <at> gmail.com> skribis:
> 
>>>> 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.
>> 
>> Yes, "m" should not be mentioned. But I think you got it
>> backwards again:
>> 
>> 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{y} @var{x})} returns
>> @code{#f}.
>> 
>> Note the order of x and y in (less? y x) in the last line.
> 
> Oops, indeed.
> 
> Pushed in commit fd07759b7d4c9d631090b04855ab81b6a2109e9e.
> 
> Thanks for the report, patch, and review!

So it seems the rewording was about whether a list like '(2 2) is
sorted or not. IIUC the rewording makes it a sorted list according to
<, because (not (< 2 2)) is #f.

Is that really what is wanted?

Marijn
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk+Y+b0ACgkQp/VmCx0OL2zB1wCfZ9Zp5JpJw4frqfpXOnCp2xvM
75kAnjJi/CpmNvh7M9sqQTbFzj7pTniN
=6xtZ
-----END PGP SIGNATURE-----

Message #37 received at 11262 <at> debbugs.gnu.org (full text, mbox):

From: Noah Lavine <noah.b.lavine <at> gmail.com>
To: Marijn <hkBst <at> gentoo.org>
Cc: ludo <at> gnu.org, 11262 <at> debbugs.gnu.org
Subject: Re: bug#11262: help text fro sorted? predicate is wrong/misleading.
Date: Thu, 26 Apr 2012 22:34:21 -0400

Well, I wanted to reply to you by seeing how sorted? was used. But
looking at the Guile source code, it appears that there are no uses of
sorted? at all! However, I think it needs to stay like it is, because
other code may depend on it.

Noah

On Thu, Apr 26, 2012 at 3:31 AM, Marijn <hkBst <at> gentoo.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 22-04-12 14:53, Ludovic Courtès wrote:
>> Hi Alexei,
>>
>> Alexei Matveev <alexei.matveev <at> gmail.com> skribis:
>>
>>>>> 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.
>>>
>>> Yes, "m" should not be mentioned. But I think you got it
>>> backwards again:
>>>
>>> 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{y} @var{x})} returns
>>> @code{#f}.
>>>
>>> Note the order of x and y in (less? y x) in the last line.
>>
>> Oops, indeed.
>>
>> Pushed in commit fd07759b7d4c9d631090b04855ab81b6a2109e9e.
>>
>> Thanks for the report, patch, and review!
>
> So it seems the rewording was about whether a list like '(2 2) is
> sorted or not. IIUC the rewording makes it a sorted list according to
> <, because (not (< 2 2)) is #f.
>
> Is that really what is wanted?
>
> Marijn
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.19 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAk+Y+b0ACgkQp/VmCx0OL2zB1wCfZ9Zp5JpJw4frqfpXOnCp2xvM
> 75kAnjJi/CpmNvh7M9sqQTbFzj7pTniN
> =6xtZ
> -----END PGP SIGNATURE-----
>
>
>

Previous Next

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