bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi

[Eli Zaretskii]

> 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?