From debbugs-submit-bounces@debbugs.gnu.org Sun Dec 06 05:24:42 2015 Received: (at submit) by debbugs.gnu.org; 6 Dec 2015 10:24:43 +0000 Received: from localhost ([127.0.0.1]:40336 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5WUk-0000sS-GB for submit@debbugs.gnu.org; Sun, 06 Dec 2015 05:24:42 -0500 Received: from eggs.gnu.org ([208.118.235.92]:55543) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5WUQ-0000rz-AP for submit@debbugs.gnu.org; Sun, 06 Dec 2015 05:24:40 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a5WUO-0002ze-UE for submit@debbugs.gnu.org; Sun, 06 Dec 2015 05:24:22 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:49499) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a5WUO-0002zY-Qk for submit@debbugs.gnu.org; Sun, 06 Dec 2015 05:24:20 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:37298) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a5WUN-0008AD-La for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 05:24:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a5WUK-0002yg-J2 for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 05:24:19 -0500 Received: from mail.muc.de ([193.149.48.3]:39815) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a5WUK-0002yY-98 for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 05:24:16 -0500 Received: (qmail 41762 invoked by uid 3782); 6 Dec 2015 10:24:14 -0000 Received: from acm.muc.de (p548A54DA.dip0.t-ipconnect.de [84.138.84.218]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 06 Dec 2015 11:24:14 +0100 Received: (qmail 2196 invoked by uid 1000); 6 Dec 2015 10:26:22 -0000 Date: Sun, 6 Dec 2015 10:26:22 +0000 To: bug-gnu-emacs@gnu.org Subject: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi Message-ID: <20151206102622.GA2113@acm.fritz.box> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.23 (2014-03-12) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.3 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.3 (----) Hello, Emacs. In the elisp manual, mapconcat is described thusly: `mapconcat' applies FUNCTION to each element of SEQUENCE: the results, which must be strings, are concatenated. Between each ^^^^^^^^^^^^^^^^^^^^^ pair of result strings, `mapconcat' inserts the string SEPARATOR. ^^^^^^^^^^ Usually SEPARATOR contains a space or comma or other suitable punctuation. The results returned by FUNCTION need not be strings; they may be of any sequence type acceptable to `concat'. The same applies to SEPARATOR. Either the code or the documentation is wrong. I strongly believe it's the documentation. Here's a patch to fix it. I will apply this patch to the emacs-25 branch soon, if I don't hear any objections. diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 8835667..1b949f2 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -861,13 +861,15 @@ Mapping Functions @defun mapconcat function sequence separator @code{mapconcat} applies @var{function} to each element of -@var{sequence}: the results, which must be strings, are concatenated. -Between each pair of result strings, @code{mapconcat} inserts the string +@var{sequence}: the results, which must be sequences, are +concatenated. These result sequences are usually strings, but may +also be lists of numbers or vectors of numbers. Between each pair of +result sequences, @code{mapconcat} inserts the sequence @var{separator}. Usually @var{separator} contains a space or comma or other suitable punctuation. The argument @var{function} must be a function that can take one -argument and return a string. The argument @var{sequence} can be any +argument and return a sequence. The argument @var{sequence} can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Sun Dec 06 11:05:16 2015 Received: (at 22101) by debbugs.gnu.org; 6 Dec 2015 16:05:16 +0000 Received: from localhost ([127.0.0.1]:40911 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5boJ-0002W4-7v for submit@debbugs.gnu.org; Sun, 06 Dec 2015 11:05:15 -0500 Received: from mtaout24.012.net.il ([80.179.55.180]:52211) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5bny-0002V8-G9 for 22101@debbugs.gnu.org; Sun, 06 Dec 2015 11:05:14 -0500 Received: from conversion-daemon.mtaout24.012.net.il by mtaout24.012.net.il (HyperSendmail v2007.08) id <0NYY007001BUWE00@mtaout24.012.net.il> for 22101@debbugs.gnu.org; Sun, 06 Dec 2015 17:57:41 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.94.185.246]) by mtaout24.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NYY006MN1O4L020@mtaout24.012.net.il>; Sun, 06 Dec 2015 17:57:41 +0200 (IST) Date: Sun, 06 Dec 2015 18:04:46 +0200 From: Eli Zaretskii Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi In-reply-to: <20151206102622.GA2113@acm.fritz.box> X-012-Sender: halo1@inter.net.il To: Alan Mackenzie Message-id: <83vb8bef6p.fsf@gnu.org> References: <20151206102622.GA2113@acm.fritz.box> X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: 22101 Cc: 22101@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: Eli Zaretskii List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.9 (/) > Date: Sun, 6 Dec 2015 10:26:22 +0000 > From: Alan Mackenzie > > In the elisp manual, mapconcat is described thusly: > > `mapconcat' applies FUNCTION to each element of SEQUENCE: the > results, which must be strings, are concatenated. Between each > ^^^^^^^^^^^^^^^^^^^^^ > pair of result strings, `mapconcat' inserts the string SEPARATOR. > ^^^^^^^^^^ > Usually SEPARATOR contains a space or comma or other suitable > punctuation. > > The results returned by FUNCTION need not be strings; they may be of any > sequence type acceptable to `concat'. The same applies to SEPARATOR. Indeed. > Either the code or the documentation is wrong. I strongly believe it's > the documentation. Yes, I agree. > Here's a patch to fix it. I will apply this patch to the emacs-25 branch > soon, if I don't hear any objections. > > > > diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi > index 8835667..1b949f2 100644 > --- a/doc/lispref/functions.texi > +++ b/doc/lispref/functions.texi > @@ -861,13 +861,15 @@ Mapping Functions > > @defun mapconcat function sequence separator > @code{mapconcat} applies @var{function} to each element of > -@var{sequence}: the results, which must be strings, are concatenated. > -Between each pair of result strings, @code{mapconcat} inserts the string > +@var{sequence}: the results, which must be sequences, are > +concatenated. These result sequences are usually strings, but may > +also be lists of numbers or vectors of numbers. Between each pair of > +result sequences, @code{mapconcat} inserts the sequence > @var{separator}. Usually @var{separator} contains a space or comma or > other suitable punctuation. IMO, this errs on the other side: it seems to allow sequences that will be rejected by mapconcat or by concat that it calls. I suggest the following alternative wording: @code{mapconcat} applies @var{function} to each element of @var{sequence}; the results, which must be sequences of characters (strings, vectors, or lists), are concatenated into a single string return value. Between each pair of result sequences, @code{mapconcat} inserts the characters from @var{separator}, which also must be a string, or a vector or list of characters. The argument @var{function} must be a function that can take one argument and return a sequence of characters: a string, a vector, or a list. The argument @var{sequence} can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. WDYT? From debbugs-submit-bounces@debbugs.gnu.org Sun Dec 06 16:39:38 2015 Received: (at 22101) by debbugs.gnu.org; 6 Dec 2015 21:39:38 +0000 Received: from localhost ([127.0.0.1]:41046 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5h1u-0002Hv-7m for submit@debbugs.gnu.org; Sun, 06 Dec 2015 16:39:38 -0500 Received: from mail.muc.de ([193.149.48.3]:55062) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5h1r-0002Hm-Qw for 22101@debbugs.gnu.org; Sun, 06 Dec 2015 16:39:36 -0500 Received: (qmail 54672 invoked by uid 3782); 6 Dec 2015 21:39:34 -0000 Received: from acm.muc.de (p579E9725.dip0.t-ipconnect.de [87.158.151.37]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 06 Dec 2015 22:39:33 +0100 Received: (qmail 2793 invoked by uid 1000); 6 Dec 2015 21:41:42 -0000 Date: Sun, 6 Dec 2015 21:41:42 +0000 To: Eli Zaretskii Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi Message-ID: <20151206214142.GA2703@acm.fritz.box> References: <20151206102622.GA2113@acm.fritz.box> <83vb8bef6p.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83vb8bef6p.fsf@gnu.org> User-Agent: Mutt/1.5.23 (2014-03-12) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 22101 Cc: 22101@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) Hello, Eli. On Sun, Dec 06, 2015 at 06:04:46PM +0200, Eli Zaretskii wrote: > > Date: Sun, 6 Dec 2015 10:26:22 +0000 > > From: Alan Mackenzie [ .... ] > > diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi > > index 8835667..1b949f2 100644 > > --- a/doc/lispref/functions.texi > > +++ b/doc/lispref/functions.texi > > @@ -861,13 +861,15 @@ Mapping Functions > > @defun mapconcat function sequence separator > > @code{mapconcat} applies @var{function} to each element of > > -@var{sequence}: the results, which must be strings, are concatenated. > > -Between each pair of result strings, @code{mapconcat} inserts the string > > +@var{sequence}: the results, which must be sequences, are > > +concatenated. These result sequences are usually strings, but may > > +also be lists of numbers or vectors of numbers. Between each pair of > > +result sequences, @code{mapconcat} inserts the sequence > > @var{separator}. Usually @var{separator} contains a space or comma or > > other suitable punctuation. > IMO, this errs on the other side: it seems to allow sequences that > will be rejected by mapconcat or by concat that it calls. I suggest > the following alternative wording: > @code{mapconcat} applies @var{function} to each element of > @var{sequence}; the results, which must be sequences of characters > (strings, vectors, or lists), are concatenated into a single string > return value. Between each pair of result sequences, > @code{mapconcat} inserts the characters from @var{separator}, which > also must be a string, or a vector or list of characters. > The argument @var{function} must be a function that can take one > argument and return a sequence of characters: a string, a vector, or > a list. The argument @var{sequence} can be any kind of sequence > except a char-table; that is, a list, a vector, a bool-vector, or a > string. > WDYT? I like very much the way the omission of a comma in "or a vector or list of characters" attaches the "of characters" to both "vector" and "list". :-) I have an uneasy feeling that the two paragraphs might be a bit dense for a newish Lisp programmer, who's just come across `mapconcat' for the first time, and needs to know what it does. I have an urge to insert a "(@pxref{Sequence Type})" somewhere, but can't really see where - maybe right at the end - or maybe at the end of the first paragraph. The problem is "string" is concrete and means what it means, but "sequence" is a rather vague sounding abstract word (even though Emacs gives it a precise meaning). Yes, I think "(@pxref{Sequence Type}) should be inserted at the end of the first paragraph. What do you think of that? -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Mon Dec 07 05:52:54 2015 Received: (at 22101-done) by debbugs.gnu.org; 7 Dec 2015 10:52:54 +0000 Received: from localhost ([127.0.0.1]:41345 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5tPZ-0005tB-OV for submit@debbugs.gnu.org; Mon, 07 Dec 2015 05:52:54 -0500 Received: from mail.muc.de ([193.149.48.3]:38059) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5tPX-0005t3-Mc for 22101-done@debbugs.gnu.org; Mon, 07 Dec 2015 05:52:52 -0500 Received: (qmail 11415 invoked by uid 3782); 7 Dec 2015 10:52:50 -0000 Received: from acm.muc.de (p5B1463E7.dip0.t-ipconnect.de [91.20.99.231]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 07 Dec 2015 11:52:49 +0100 Received: (qmail 2669 invoked by uid 1000); 7 Dec 2015 10:54:58 -0000 Date: Mon, 7 Dec 2015 10:54:58 +0000 To: Eli Zaretskii Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi Message-ID: <20151207105457.GA1904@acm.fritz.box> References: <20151206102622.GA2113@acm.fritz.box> <83vb8bef6p.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83vb8bef6p.fsf@gnu.org> User-Agent: Mutt/1.5.23 (2014-03-12) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 22101-done Cc: 22101-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) Hello, Eli. On Sun, Dec 06, 2015 at 06:04:46PM +0200, Eli Zaretskii wrote: > > Date: Sun, 6 Dec 2015 10:26:22 +0000 > > From: Alan Mackenzie [ .... ] > IMO, this errs on the other side: it seems to allow sequences that > will be rejected by mapconcat or by concat that it calls. I suggest > the following alternative wording: > @code{mapconcat} applies @var{function} to each element of > @var{sequence}; the results, which must be sequences of characters > (strings, vectors, or lists), are concatenated into a single string > return value. Between each pair of result sequences, > @code{mapconcat} inserts the characters from @var{separator}, which > also must be a string, or a vector or list of characters. > The argument @var{function} must be a function that can take one > argument and return a sequence of characters: a string, a vector, or > a list. The argument @var{sequence} can be any kind of sequence > except a char-table; that is, a list, a vector, a bool-vector, or a > string. > WDYT? I think it's good. I have just taken the liberty of committing your version, with two changes: I have added @xref{Sequences Arrays Vectors} at the end of the first paragraph. I have changed "return" to "returns" to indicate that the "returning" is mandatory, and not a subclause of the "can" bit. (A small point, but I think it's more correct.) -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Mon Dec 07 10:51:52 2015 Received: (at 22101) by debbugs.gnu.org; 7 Dec 2015 15:51:52 +0000 Received: from localhost ([127.0.0.1]:41862 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5y4u-0005u5-DI for submit@debbugs.gnu.org; Mon, 07 Dec 2015 10:51:52 -0500 Received: from mtaout23.012.net.il ([80.179.55.175]:35483) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1a5y4Z-0005te-51 for 22101@debbugs.gnu.org; Mon, 07 Dec 2015 10:51:51 -0500 Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0NYZ00A00VQSFJ00@a-mtaout23.012.net.il> for 22101@debbugs.gnu.org; Mon, 07 Dec 2015 17:51:29 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.94.185.246]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NYZ00AC6W1SAD90@a-mtaout23.012.net.il>; Mon, 07 Dec 2015 17:51:28 +0200 (IST) Date: Mon, 07 Dec 2015 17:51:24 +0200 From: Eli Zaretskii Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi In-reply-to: <20151207105457.GA1904@acm.fritz.box> X-012-Sender: halo1@inter.net.il To: Alan Mackenzie Message-id: <83fuzedzpf.fsf@gnu.org> References: <20151206102622.GA2113@acm.fritz.box> <83vb8bef6p.fsf@gnu.org> <20151207105457.GA1904@acm.fritz.box> X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: 22101 Cc: 22101@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: Eli Zaretskii List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.9 (/) > Date: Mon, 7 Dec 2015 10:54:58 +0000 > Cc: 22101-done@debbugs.gnu.org > From: Alan Mackenzie > > > IMO, this errs on the other side: it seems to allow sequences that > > will be rejected by mapconcat or by concat that it calls. I suggest > > the following alternative wording: > > > @code{mapconcat} applies @var{function} to each element of > > @var{sequence}; the results, which must be sequences of characters > > (strings, vectors, or lists), are concatenated into a single string > > return value. Between each pair of result sequences, > > @code{mapconcat} inserts the characters from @var{separator}, which > > also must be a string, or a vector or list of characters. > > > The argument @var{function} must be a function that can take one > > argument and return a sequence of characters: a string, a vector, or > > a list. The argument @var{sequence} can be any kind of sequence > > except a char-table; that is, a list, a vector, a bool-vector, or a > > string. > > > WDYT? > > I think it's good. I have just taken the liberty of committing your > version Such an impatience... Did you forget to push? > with two changes: I have added @xref{Sequences Arrays Vectors} > at the end of the first paragraph. It should be way up in the text preceding this @defun, because the section talks about sequences much earlier, and it makes no sense to have the cross-reference so late in the text. Thanks. From unknown Fri Jun 13 11:11:48 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 05 Jan 2016 12:24:03 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator