From: Alan Mackenzie <acm@muc.de>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 22101@debbugs.gnu.org
Subject: bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi
Date: Sun, 6 Dec 2015 21:41:42 +0000 [thread overview]
Message-ID: <20151206214142.GA2703@acm.fritz.box> (raw)
In-Reply-To: <83vb8bef6p.fsf@gnu.org>
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).
next prev parent reply other threads:[~2015-12-06 21:41 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-12-06 10:26 bug#22101: Emacs-25: inaccuracy in documentation of `mapconcat' in .../lispref/functions.texi Alan Mackenzie
2015-12-06 16:04 ` Eli Zaretskii
2015-12-06 21:41 ` Alan Mackenzie [this message]
2015-12-07 10:54 ` Alan Mackenzie
2015-12-07 15:51 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20151206214142.GA2703@acm.fritz.box \
--to=acm@muc.de \
--cc=22101@debbugs.gnu.org \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).