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

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

[Alan Mackenzie]

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
-@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.
 
 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).

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?

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

[Alan Mackenzie]

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 <acm@muc.de>

[ .... ]

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

I like very much the way the omission of a comma in "or a vector or list
of characters" attaches the "of characters" to both  "vector" and "list".
:-)

I have an uneasy feeling that the two paragraphs might be a bit dense for
a newish Lisp programmer, who's just come across `mapconcat' for the
first time, and needs to know what it does.  I have an urge to insert a
"(@pxref{Sequence Type})" somewhere, but can't really see where - maybe
right at the end - or maybe at the end of the first paragraph.  The
problem is "string" is concrete and means what it means, but "sequence"
is a rather vague sounding abstract word (even though Emacs gives it a
precise meaning).

Yes, I think "(@pxref{Sequence Type}) should be inserted at the end of
the first paragraph.

What do you think of that?

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Alan Mackenzie]

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 <acm@muc.de>

[ .... ]

> 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).

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

[Eli Zaretskii]

> Date: Mon, 7 Dec 2015 10:54:58 +0000
> Cc: 22101-done@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > 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

Such an impatience...

Did you forget to push?

> with two changes: I have added @xref{Sequences Arrays Vectors}
> at the end of the first paragraph.

It should be way up in the text preceding this @defun, because the
section talks about sequences much earlier, and it makes no sense to
have the cross-reference so late in the text.

Thanks.