GNU bug report logs - #24014
24.5; doc string of `cl-reduce'

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 24014 in the body.
You can then email your comments to 24014 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: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; doc string of `cl-reduce'
Date: Sun, 17 Jul 2016 07:55:07 -0700 (PDT)

Please state in the doc string what the function does.  IOW,
explain/describe/specify what "reduce" means.  Do not suppose that Emacs
Lisp users are all familiar with functional programming etc.

If _you_ understand it, you should be able to describe it in a couple of
sentences.  It's not a complicated thing, but just repeating the word
"reduce" from the function name is not sufficient - not helpful.

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24014 <at> debbugs.gnu.org
Subject: Re: bug#24014: 24.5; doc string of `cl-reduce'
Date: Sun, 17 Jul 2016 17:57:14 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> Please state in the doc string what the function does.  IOW,
> explain/describe/specify what "reduce" means.  Do not suppose that Emacs
> Lisp users are all familiar with functional programming etc.
>
> If _you_ understand it, you should be able to describe it in a couple of
> sentences.  It's not a complicated thing, but just repeating the word
> "reduce" from the function name is not sufficient - not helpful.

I also find the explanation in the manual confusing:

  "This function combines the elements of SEQ using an associative
  binary operation."

The function does _not_ need to be associative.  The sentence later:

  "If ‘:from-end’ is true, the reduction is right-associative instead
  of left-associative."

makes sense, of course, but above, the word "associative" does not mean
more than "any", and without reading the later text, it can easily be
misunderstood.


Michael.

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

From: Nicolas Petton <nicolas <at> petton.fr>
To: Michael Heerdegen <michael_heerdegen <at> web.de>,
 Drew Adams <drew.adams <at> oracle.com>
Cc: 24014 <at> debbugs.gnu.org
Subject: Re: bug#24014: 24.5; doc string of `cl-reduce'
Date: Sun, 17 Jul 2016 23:18:12 +0200

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

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> Drew Adams <drew.adams <at> oracle.com> writes:
>
>> Please state in the doc string what the function does.  IOW,
>> explain/describe/specify what "reduce" means.  Do not suppose that Emacs
>> Lisp users are all familiar with functional programming etc.

The documentation of `seq-reduce' is probably not perfect, but at least
it tries to explain what reducing means:

    Return the result of calling FUNCTION with INITIAL-VALUE and the
    first element of SEQUENCE, then calling FUNCTION with that result and
    the second element of SEQUENCE, then with that result and the third
    element of SEQUENCE, etc.

    If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called.

Nico

[signature.asc (application/pgp-signature, inline)]

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 24014 <at> debbugs.gnu.org
Subject: RE: bug#24014: 24.5; doc string of `cl-reduce'
Date: Sun, 17 Jul 2016 21:41:42 -0700 (PDT)

> > Please state in the doc string what the function does.  IOW,
> > explain/describe/specify what "reduce" means.  Do not suppose that Emacs
> > Lisp users are all familiar with functional programming etc.
> >
> > If _you_ understand it, you should be able to describe it in a couple of
> > sentences.  It's not a complicated thing, but just repeating the word
> > "reduce" from the function name is not sufficient - not helpful.
> 
> I also find the explanation in the manual confusing:
> 
>   "This function combines the elements of SEQ using an associative
>   binary operation."
> 
> The function does _not_ need to be associative.  The sentence later:
> 
>   "If ‘:from-end’ is true, the reduction is right-associative instead
>   of left-associative."
> 
> makes sense, of course, but above, the word "associative" does not mean
> more than "any", and without reading the later text, it can easily be
> misunderstood.

Yes, and even when such text is corrected, it is not necessarily
understandable by many users.  We should not assume that users
are math majors.

Even providing a functional-programming definition of `reduce' is
better than just describing it in abstract terms, if we can't come
up with a more down-to-earth description.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Nicolas Petton <nicolas <at> petton.fr>, Michael Heerdegen
 <michael_heerdegen <at> web.de>
Cc: 24014 <at> debbugs.gnu.org
Subject: RE: bug#24014: 24.5; doc string of `cl-reduce'
Date: Sun, 17 Jul 2016 21:44:50 -0700 (PDT)

> >> Please state in the doc string what the function does.  IOW,
> >> explain/describe/specify what "reduce" means.  Do not suppose that Emacs
> >> Lisp users are all familiar with functional programming etc.
> 
> The documentation of `seq-reduce' is probably not perfect, but at least
> it tries to explain what reducing means:
> 
>     Return the result of calling FUNCTION with INITIAL-VALUE and the
>     first element of SEQUENCE, then calling FUNCTION with that result and
>     the second element of SEQUENCE, then with that result and the third
>     element of SEQUENCE, etc.
> 
>     If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called.

Much better, yes.  This is the right level at which to describe what
it does for most programmers, IMO.

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

From: Clément Pit--Claudel <clement.pit <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#24014: 24.5; doc string of `cl-reduce'
Date: Mon, 18 Jul 2016 10:54:21 +0200

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

On 2016-07-18 06:41, Drew Adams wrote:
> Even providing a functional-programming definition of `reduce' is
> better than just describing it in abstract terms, if we can't come
> up with a more down-to-earth description.

What about adding a few examples? Something like this maybe?

    (cl-reduce f '(1 2 3 4 5))
      ↔ (f (f (f (f 1 2) 3) 4) 5)

    (cl-reduce f '(1 2 3 4 5) :initial-value 0)
      ↔ (f (f (f (f (f 0 1) 2) 3) 4) 5)

    (cl-reduce f '(1 2 3 4 5) :from-end t)
      ↔ (f 1 (f 2 (f 3 (f 4 5))))

    (cl-reduce f '(1 2 3 4 5) :from-end t :initial-value 0)
      ↔ (f 1 (f 2 (f 3 (f 4 (f 5 0)))))

[signature.asc (application/pgp-signature, attachment)]

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

From: Nicolas Petton <nicolas <at> petton.fr>
To: Drew Adams <drew.adams <at> oracle.com>,
 Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 24014 <at> debbugs.gnu.org
Subject: RE: bug#24014: 24.5; doc string of `cl-reduce'
Date: Mon, 18 Jul 2016 14:19:01 +0200

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

Drew Adams <drew.adams <at> oracle.com> writes:

> Much better, yes.  This is the right level at which to describe what
> it does for most programmers, IMO.

I pushed a commit in master (I haven't done anything WRT the texinfo
file).

Nico

[signature.asc (application/pgp-signature, inline)]

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Clément Pit--Claudel <clement.pit <at> gmail.com>,
 24014 <at> debbugs.gnu.org
Subject: RE: bug#24014: 24.5; doc string of `cl-reduce'
Date: Mon, 18 Jul 2016 07:02:30 -0700 (PDT)

> > Even providing a functional-programming definition of `reduce' is
> > better than just describing it in abstract terms, if we can't come
> > up with a more down-to-earth description.
> 
> What about adding a few examples? Something like this maybe?
> 
>     (cl-reduce f '(1 2 3 4 5))
>       ↔ (f (f (f (f 1 2) 3) 4) 5)
> 
>     (cl-reduce f '(1 2 3 4 5) :initial-value 0)
>       ↔ (f (f (f (f (f 0 1) 2) 3) 4) 5)
> 
>     (cl-reduce f '(1 2 3 4 5) :from-end t)
>       ↔ (f 1 (f 2 (f 3 (f 4 5))))
> 
>     (cl-reduce f '(1 2 3 4 5) :from-end t :initial-value 0)
>       ↔ (f 1 (f 2 (f 3 (f 4 (f 5 0)))))

LGTM - except that f should be quoted as an arg to `cl-reduce'.
E.g. (cl-reduce 'f '(1 2 3)).

And a shorter list makes things a tiny bit simpler: (1 2 3).

(And I'm not crazy about the too-short double arrow, personally.)

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

From: Clément Pit--Claudel <clement.pit <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 24014 <at> debbugs.gnu.org
Subject: Re: bug#24014: 24.5; doc string of `cl-reduce'
Date: Mon, 18 Jul 2016 18:03:00 +0200

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

On 2016-07-18 16:02, Drew Adams wrote:
>>> Even providing a functional-programming definition of `reduce' is
>>> better than just describing it in abstract terms, if we can't come
>>> up with a more down-to-earth description.
>>
>> What about adding a few examples? Something like this maybe?
>>
>>     (cl-reduce f '(1 2 3 4 5))
>>       ↔ (f (f (f (f 1 2) 3) 4) 5)
>>
>>     (cl-reduce f '(1 2 3 4 5) :initial-value 0)
>>       ↔ (f (f (f (f (f 0 1) 2) 3) 4) 5)
>>
>>     (cl-reduce f '(1 2 3 4 5) :from-end t)
>>       ↔ (f 1 (f 2 (f 3 (f 4 5))))
>>
>>     (cl-reduce f '(1 2 3 4 5) :from-end t :initial-value 0)
>>       ↔ (f 1 (f 2 (f 3 (f 4 (f 5 0)))))
> 
> LGTM - except that f should be quoted as an arg to `cl-reduce'.
> E.g. (cl-reduce 'f '(1 2 3)).
> 
> And a shorter list makes things a tiny bit simpler: (1 2 3).
> 
> (And I'm not crazy about the too-short double arrow, personally.)

I wasn't sure about the sort list; I actually found things more confusing that way.  Should this go in the ELisp manual, or in the docstring?
No strong feelings about the double arrow, and fine with me for quoting f.

[signature.asc (application/pgp-signature, attachment)]

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Clément Pit--Claudel <clement.pit <at> gmail.com>,
 24014 <at> debbugs.gnu.org
Subject: RE: bug#24014: 24.5; doc string of `cl-reduce'
Date: Mon, 18 Jul 2016 10:28:44 -0700 (PDT)

> I wasn't sure about the s[h]ort list; I actually found things more
> confusing that way.

I wonder why?  But OK by me not to shorten.

> Should this go in the ELisp manual, or in the docstring?

Doesn't matter to me.  Maybe the manual is better.

And isn't the CL manual the proper manual, not the Elisp manual?

IMHO, it would help if manual entries for Common-Lisp emulation
stuff had links to the most relevant CLTL2 sections that specify it.

E.g., in this case, our CL manual would point here:
https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node143.html.

It is appropriate for our CL doc to both (1) point to the Common-Lisp
spec for the corresponding thingy and (2) point out any differences
between our emulation and the thing it emulates.

IMHO, not doing this is not doing our job properly, not helping
Emacs-Lisp users use our CL emulation.

> No strong feelings about the double arrow, and fine with me for quoting f.
 
Not quoting f is not an option.  If f is a variable bound to a function
then (f a b c) raises an error.  (This is not Scheme.)

  (setq b #'car)
  (b '(1 2 3))
  Symbol's function definition is void: b

If b is an fboundp symbol then (b '(1 2 3)) => 1.

When you pass a function-valued argument to `cl-reduce' it is the
boundp value of that _variable_ (symbol arg) that is passed, not
the fboundp value of the symbol arg.

The only thing that works a bit like what a Scheme user might
expect in this regard is the use of a lambda at the head of the
list:

((lambda (xs) (car xs)) '(1 2 3)) = 1.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>,
 Nicolas Petton <nicolas <at> petton.fr>, 24014 <at> debbugs.gnu.org
Subject: Re: bug#24014: 24.5; doc string of `cl-reduce'
Date: Sat, 23 Oct 2021 10:32:31 -0700

close 24014 28.1
thanks

Drew Adams <drew.adams <at> oracle.com> writes:

>> >> Please state in the doc string what the function does.  IOW,
>> >> explain/describe/specify what "reduce" means.  Do not suppose that Emacs
>> >> Lisp users are all familiar with functional programming etc.
>>
>> The documentation of `seq-reduce' is probably not perfect, but at least
>> it tries to explain what reducing means:
>>
>>     Return the result of calling FUNCTION with INITIAL-VALUE and the
>>     first element of SEQUENCE, then calling FUNCTION with that result and
>>     the second element of SEQUENCE, then with that result and the third
>>     element of SEQUENCE, etc.
>>
>>     If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called.
>
> Much better, yes.  This is the right level at which to describe what
> it does for most programmers, IMO.

Nicolas updated the docstring, and I have now done the same change in
cl.texi on the emacs-28 branch (commit 43914ab01f).

It is the same text as above, just formatted for texinfo, so it should
be understandable to us mere programmers.

I'm consequently closing this bug report.

Previous Next

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