[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../l
From: |
Eli Zaretskii |
Subject: |
bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi |
Date: |
Sun, 06 Dec 2015 18:04:46 +0200 |
> Date: Sun, 6 Dec 2015 10:26:22 +0000
> From: Alan Mackenzie <acm@muc.de>
>
> 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?