From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#24014: 24.5; doc string of `cl-reduce' Date: Sun, 17 Jul 2016 21:41:42 -0700 (PDT) Message-ID: References: <18e97f8d-f6f8-4b4c-9d4c-20eb8664483e@default> <87zipgmf51.fsf@web.de> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1468817391 16511 80.91.229.3 (18 Jul 2016 04:49:51 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Jul 2016 04:49:51 +0000 (UTC) Cc: 24014@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jul 18 06:49:38 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bP0Ur-0007si-B0 for geb-bug-gnu-emacs@m.gmane.org; Mon, 18 Jul 2016 06:49:37 +0200 Original-Received: from localhost ([::1]:44305 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bP0Uq-0001io-4g for geb-bug-gnu-emacs@m.gmane.org; Mon, 18 Jul 2016 00:49:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48673) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bP0Nd-0008Kt-3i for bug-gnu-emacs@gnu.org; Mon, 18 Jul 2016 00:42:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bP0NX-0006Hz-2S for bug-gnu-emacs@gnu.org; Mon, 18 Jul 2016 00:42:08 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:42660) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bP0NW-0006Hr-V7 for bug-gnu-emacs@gnu.org; Mon, 18 Jul 2016 00:42:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bP0NW-0000Vf-BH for bug-gnu-emacs@gnu.org; Mon, 18 Jul 2016 00:42:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Jul 2016 04:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24014 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24014-submit@debbugs.gnu.org id=B24014.14688169131942 (code B ref 24014); Mon, 18 Jul 2016 04:42:02 +0000 Original-Received: (at 24014) by debbugs.gnu.org; 18 Jul 2016 04:41:53 +0000 Original-Received: from localhost ([127.0.0.1]:54997 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bP0NM-0000VF-M9 for submit@debbugs.gnu.org; Mon, 18 Jul 2016 00:41:52 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:19460) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bP0NL-0000V3-3p for 24014@debbugs.gnu.org; Mon, 18 Jul 2016 00:41:51 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u6I4figa000393 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 18 Jul 2016 04:41:44 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0021.oracle.com (8.13.8/8.13.8) with ESMTP id u6I4fhJ3006779 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 18 Jul 2016 04:41:44 GMT Original-Received: from abhmp0011.oracle.com (abhmp0011.oracle.com [141.146.116.17]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id u6I4fh3Z026126; Mon, 18 Jul 2016 04:41:43 GMT In-Reply-To: <87zipgmf51.fsf@web.de> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6744.5000 (x86)] X-Source-IP: userv0021.oracle.com [156.151.31.71] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:121208 Archived-At: > > Please state in the doc string what the function does. IOW, > > explain/describe/specify what "reduce" means. Do not suppose that Emac= s > > Lisp users are all familiar with functional programming etc. > > > > If _you_ understand it, you should be able to describe it in a couple o= f > > sentences. It's not a complicated thing, but just repeating the word > > "reduce" from the function name is not sufficient - not helpful. >=20 > I also find the explanation in the manual confusing: >=20 > "This function combines the elements of SEQ using an associative > binary operation." >=20 > The function does _not_ need to be associative. The sentence later: >=20 > "If =E2=80=98:from-end=E2=80=99 is true, the reduction is right-associa= tive instead > of left-associative." >=20 > 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.