--- Begin Message ---
|
Subject: |
Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi |
|
Date: |
Sun, 6 Dec 2015 10:26:22 +0000 |
|
User-agent: |
Mutt/1.5.23 (2014-03-12) |
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
address@hidden: the results, which must be strings, are concatenated.
-Between each pair of result strings, @code{mapconcat} inserts the string
address@hidden: 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).
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi |
|
Date: |
Mon, 7 Dec 2015 10:54:58 +0000 |
|
User-agent: |
Mutt/1.5.23 (2014-03-12) |
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 <address@hidden>
[ .... ]
> 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).
--- End Message ---