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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 22101 in the body.
You can then email your comments to 22101 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Emacs-25: inaccuracy in documentation of `mapconcat' in
 .../lispref/functions.texi
Date: Sun, 6 Dec 2015 10:26:22 +0000

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

Message #8 received at 22101 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 22101 <at> debbugs.gnu.org
Subject: Re: 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 <at> 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?

Message #11 received at 22101 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 22101 <at> debbugs.gnu.org
Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat'
 in	.../lispref/functions.texi
Date: Sun, 6 Dec 2015 21:41:42 +0000

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

Message #16 received at 22101-done <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 22101-done <at> debbugs.gnu.org
Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat'
 in	.../lispref/functions.texi
Date: Mon, 7 Dec 2015 10:54:58 +0000

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

Message #19 received at 22101 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 22101 <at> debbugs.gnu.org
Subject: Re: bug#22101: Emacs-25: inaccuracy in documentation of
 `mapconcat'	in	.../lispref/functions.texi
Date: Mon, 07 Dec 2015 17:51:24 +0200

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.