Sync NEWS with the documentation

* etc/NEWS: Mark entries according to documentation.

* doc/lispref/functions.texi (Mapping Functions): Document 'mapcan'.

1 files changed, 25 insertions, 5 deletions

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 06de2e2f730..0d407ab966b 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -930,11 +930,11 @@ the @code{call-interactively} function.  @xref{Interactive Call}.
   A @dfn{mapping function} applies a given function (@emph{not} a
 special form or macro) to each element of a list or other collection.
 Emacs Lisp has several such functions; this section describes
-@code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a
-list.  @xref{Definition of mapatoms}, for the function @code{mapatoms}
-which maps over the symbols in an obarray.  @xref{Definition of
-maphash}, for the function @code{maphash} which maps over key/value
-associations in a hash table.
+@code{mapcar}, @code{mapc}, @code{mapconcat}, and @code{mapcan}, which
+map over a list.  @xref{Definition of mapatoms}, for the function
+@code{mapatoms} which maps over the symbols in an obarray.
+@xref{Definition of maphash}, for the function @code{maphash} which
+maps over key/value associations in a hash table.
 
   These mapping functions do not allow char-tables because a char-table
 is a sparse array whose nominal range of indices is very large.  To map
@@ -986,6 +986,26 @@ Return the list of results."
 @end example
 @end defun
 
+@defun mapcan function sequence
+This function applies @var{function} to each element of
+@var{sequence}, like @code{mapcar}, but instead of collecting the
+results into a list, it returns a single list with all the elements of
+the results (which must be lists), by altering the results (using
+@code{nconc}; @pxref{Rearrangement}).  Like with @code{mapcar},
+@var{sequence} can be of any type except a char-table.
+
+@group
+@example
+;; @r{Contrast this:}
+(mapcar 'list '(a b c d))
+     @result{} ((a) (b) (c) (d))
+;; @r{with this:}
+(mapcan 'list '(a b c d))
+     @result{} (a b c d)
+@end example
+@end group
+@end defun
+
 @defun mapc function sequence
 @code{mapc} is like @code{mapcar} except that @var{function} is used for
 side-effects only---the values it returns are ignored, not collected