bug#35710: 26.1; incomplete mapconcat description string

bug#35710: 26.1; incomplete mapconcat description string

[phs]

In my v26.1, the description string for mapconcat is

   mapconcat is a built-in function in ‘src/fns.c’.

   (mapconcat FUNCTION SEQUENCE SEPARATOR)

   Apply FUNCTION to each element of SEQUENCE, and concat the results as
strings.
   In between each pair of results, stick in SEPARATOR.  Thus, " " as
   SEPARATOR results in spaces between the values returned by FUNCTION.
   SEQUENCE may be a list, a vector, a bool-vector, or a string.

The description does not say what is accepted for SEPARATOR, it only
gives an example.

By playing around a bit, it turns out that SEPARATOR can be a string
(obviously), a list of chars, a vector of chars, the empty bool-vector
but not any other bool-vector.

It is not clear why these possibilities are offered while some are not
(e.g., why not make SEPARATOR optional?). This is one more reason to
make the description string explicit about what is allowed.
-- 
Philippe SCHNOEBELEN,       	
"Algebraic symbols are used when you do not know what you are talking about"

bug#35710: 26.1; incomplete mapconcat description string

[Noam Postavsky]

phs <phs@lsv.fr> writes:

> In my v26.1, the description string for mapconcat is
>
>    mapconcat is a built-in function in ‘src/fns.c’.
>
>    (mapconcat FUNCTION SEQUENCE SEPARATOR)
>
>    Apply FUNCTION to each element of SEQUENCE, and concat the results as
> strings.
>    In between each pair of results, stick in SEPARATOR.  Thus, " " as
>    SEPARATOR results in spaces between the values returned by FUNCTION.
>    SEQUENCE may be a list, a vector, a bool-vector, or a string.
>
> The description does not say what is accepted for SEPARATOR, it only
> gives an example.

It mentions concat, which is what determines what is acceptable.  I
agree it could be made more explicit though.

bug#35710: 26.1; incomplete mapconcat description string

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Mon, 13 May 2019 08:02:44 -0400
> Cc: 35710@debbugs.gnu.org
> 
> >    (mapconcat FUNCTION SEQUENCE SEPARATOR)
> >
> >    Apply FUNCTION to each element of SEQUENCE, and concat the results as
> > strings.
> >    In between each pair of results, stick in SEPARATOR.  Thus, " " as
> >    SEPARATOR results in spaces between the values returned by FUNCTION.
> >    SEQUENCE may be a list, a vector, a bool-vector, or a string.
> >
> > The description does not say what is accepted for SEPARATOR, it only
> > gives an example.
> 
> It mentions concat, which is what determines what is acceptable.  I
> agree it could be made more explicit though.

The manual does spell that out, we could simply add that to the doc
string.

bug#35710: Acknowledgement (26.1; incomplete mapconcat description string)

[phs]

[-- Attachment #1: Type: text/plain, Size: 588 bytes --]

Thanks for the explanations, I never realized that concat was so
versatile (and I'm an emacs lover since 1983). Live and learn ...

Here is a suggested replacement for the documentation string (patch
attached). It produces

	Apply FUNCTION to each element of SEQUENCE, and concat the results as
strings.
	In between each pair of results, stick in SEPARATOR.  Thus, " " as
	SEPARATOR results in spaces between the values returned by FUNCTION.
	SEQUENCE may be a list, a vector, etc. see ‘mapcar’.
	SEPARATOR and all values returned by FUNCTION must be accepted by ‘concat’.

--phs

[-- Attachment #2: mapconcat-descr.patch --]
[-- Type: text/plain, Size: 709 bytes --]

diff --git a/src/fns.c b/src/fns.c
index c3202495da..f5e2584587 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -2668,7 +2668,8 @@ DEFUN ("mapconcat", Fmapconcat, Smapconcat, 3, 3, 0,
        doc: /* Apply FUNCTION to each element of SEQUENCE, and concat the results as strings.
 In between each pair of results, stick in SEPARATOR.  Thus, " " as
 SEPARATOR results in spaces between the values returned by FUNCTION.
-SEQUENCE may be a list, a vector, a bool-vector, or a string.  */)
+SEQUENCE may be a list, a vector, etc. see `mapcar'.
+SEPARATOR and all values returned by FUNCTION must be accepted by `concat'.  */)
   (Lisp_Object function, Lisp_Object sequence, Lisp_Object separator)
 {
   USE_SAFE_ALLOCA;

bug#35710: Acknowledgement (26.1; incomplete mapconcat description string)

[Eli Zaretskii]

> From: phs <phs@lsv.fr>
> Date: Tue, 14 May 2019 10:14:02 +0200
> 
> Thanks for the explanations, I never realized that concat was so
> versatile (and I'm an emacs lover since 1983). Live and learn ...
> 
> Here is a suggested replacement for the documentation string (patch
> attached). It produces
> 
> 	Apply FUNCTION to each element of SEQUENCE, and concat the results as
> strings.
> 	In between each pair of results, stick in SEPARATOR.  Thus, " " as
> 	SEPARATOR results in spaces between the values returned by FUNCTION.
> 	SEQUENCE may be a list, a vector, etc. see ‘mapcar’.
> 	SEPARATOR and all values returned by FUNCTION must be accepted by ‘concat’.

Thanks, I fixed the doc string in a slightly different way.  The fix
will be in Emacs 26.3.  I'm therefore marking this bug done.