bug#4433: 23.1; dolist vs dolist

bug#4433: 23.1; dolist vs dolist

[Drew Adams]

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

bug#4433: 23.1; dolist vs dolist

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

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

If you have a definition of `return-from', then you have the cl.el
`dolist', so I don't really see the point.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#4433: 23.1; dolist vs dolist

[Drew Adams]

> From: Drew Adams  Sent: Wednesday, July 13, 2011 6:30 AM
> 
> > If you have a definition of `return-from', then you have the cl.el
> > `dolist', so I don't really see the point.
> 
> I don't see _your_ point.  There is no need to check 
> `return-from'.  `C-h f' also tells you which you have, by 
> referring to the source file.
> 
> That's not the point.
> 
> These two macros have the same name.
> These two macros have the same doc.
> 
> These two macros have different behavior.
> 
> This difference, with no corresponding difference in doc or 
> name, is a proven source of confusion.
> 
> It's probably too late to make the names different and 
> correct the bad design.
> 
> The doc should distinguish them, carefully and clearly, even 
> explicitly averting users to the possible confusion (gotcha).

bug#4433: 23.1; dolist vs dolist

[Lars Magne Ingebrigtsen]

I've now mentioned the block in the cl-macs dolist.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/