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

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

[Noah Lavine]

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@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 */
>
>
>

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

[Alexei Matveev]

[-- Attachment #1: Type: text/plain, Size: 582 bytes --]

Hi, Noah, Hi Guilers,

On Thu, Apr 19, 2012 at 3:14 AM, Noah Lavine <noah.b.lavine@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

[-- Attachment #2: 0001-Reformulate-misleading-output-of-help-sorted.patch --]
[-- Type: application/octet-stream, Size: 1300 bytes --]

From 3ba571b35031aaff074d7d634e59a2a869fa2339 Mon Sep 17 00:00:00 2001
From: Alexei Matveev <matveev@theochem.tu-muenchen.de>
Date: Fri, 20 Apr 2012 12:06:52 +0200
Subject: [PATCH] Reformulate misleading output of (help sorted?).

Fixes <http://bugs.gnu.org/11262>.

* libguile/sort.c (scm_sorted_p): changed strings only
---
 libguile/sort.c |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

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 */
-- 
1.5.6.5