From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi Date: Sun, 06 Dec 2015 18:04:46 +0200 Message-ID: <83vb8bef6p.fsf@gnu.org> References: <20151206102622.GA2113@acm.fritz.box> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1449417991 1692 80.91.229.3 (6 Dec 2015 16:06:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 6 Dec 2015 16:06:31 +0000 (UTC) Cc: 22101@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Dec 06 17:06:12 2015 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 1a5bpD-0002fQ-Iu for geb-bug-gnu-emacs@m.gmane.org; Sun, 06 Dec 2015 17:06:11 +0100 Original-Received: from localhost ([::1]:50220 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a5bpC-0007qW-Pp for geb-bug-gnu-emacs@m.gmane.org; Sun, 06 Dec 2015 11:06:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51157) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a5bp8-0007qO-6P for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 11:06:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a5bp4-0005Jp-Or for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 11:06:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:51203) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a5bp4-0005Ji-LT for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 11:06:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1a5bp4-0002XC-3x for bug-gnu-emacs@gnu.org; Sun, 06 Dec 2015 11:06:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 06 Dec 2015 16:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 22101 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 22101-submit@debbugs.gnu.org id=B22101.14494179169682 (code B ref 22101); Sun, 06 Dec 2015 16:06:02 +0000 Original-Received: (at 22101) by debbugs.gnu.org; 6 Dec 2015 16:05:16 +0000 Original-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 Original-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 Original-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) Original-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) In-reply-to: <20151206102622.GA2113@acm.fritz.box> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x 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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:109690 Archived-At: > 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?