bug#4433: 23.1; dolist vs dolist

["Drew Adams" <drew.adams@oracle.com>]

The doc strings for the `dolist' defined in emacs -Q and the `dolist'
defined in cl-macs.el are the same. However, the two `dolist's are not
the same.
 
At the very least, the doc string for the CL version should mention
`return-from' and any other features that it offers and which are not
available for the vanilla `dolist'. And the doc string for the vanilla
`dolist' should mention that it is not the same as the `dolist' of
Common Lisp.
 
Even more important is to document this in the Elisp manual. State
clearly that `dolist' (the one provided by Emacs, without cl.el) is
not the same as the `dolist' of Common Lisp or the `dolist' of cl.el,
both of which support `return-from', and so on.
 
The use of the same name by Emacs for a very different function
(macro) is confusing and error prone. The least we can do is point
this out in the doc.

Note that we do say this in node Catch and Throw:

"Common Lisp note: Most other versions of Lisp, including Common
 Lisp, have several ways of transferring control nonsequentially:
 `return', `return-from', and `go', for example.  Emacs Lisp has
 only `throw'."

A similar note is called for wherever Emacs has a function or macro with the
same name as one from Common Lisp, whenever there is a significant difference in
behavior.
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'