[Emacs-diffs] /srv/bzr/emacs/trunk r110711: * doc/misc/cl.texi (Organization): More details on cl-lib.el versus cl.el.

[Glenn Morris]

------------------------------------------------------------
revno: 110711
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2012-10-28 18:06:13 -0700
message:
  * doc/misc/cl.texi (Organization): More details on cl-lib.el versus cl.el.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-10-28 02:34:36 +0000
+++ b/doc/misc/ChangeLog        2012-10-29 01:06:13 +0000
@@ -1,3 +1,7 @@
+2012-10-29  Glenn Morris  <address@hidden>
+
+       * cl.texi (Organization): More details on cl-lib.el versus cl.el.
+
 2012-10-28  Glenn Morris  <address@hidden>
 
        * cl.texi (Multiple Values, Common Lisp Compatibility):

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-10-28 02:34:36 +0000
+++ b/doc/misc/cl.texi  2012-10-29 01:06:13 +0000
@@ -182,17 +182,30 @@
 will take care of pulling in the other files when they are
 needed.
 
-There is another file, @file{cl.el}, which was the main entry point
-to the CL package prior to Emacs 24.3.  Nowadays, it is replaced
-by @file{cl-lib.el}.  The two provide the same features, but use
-different function names (in fact, @file{cl.el} just defines aliases
-to the @file{cl-lib.el} definitions).  In particular, the old @file{cl.el}
-does not use a clean namespace.  For this reason, Emacs has a policy
-that packages distributed with Emacs must not load @code{cl} at run time.
-(It is ok for them to load @code{cl} at @emph{compile} time, with
address@hidden, and use the macros it provides.)  There is
-no such restriction on the use of @code{cl-lib}.  New code should use
address@hidden rather than @code{cl}.  @xref{Naming Conventions}.
+There is another file, @file{cl.el}, which was the main entry point to
+the CL package prior to Emacs 24.3.  Nowadays, it is replaced by
address@hidden  The two provide the same features (in most cases),
+but use different function names (in fact, @file{cl.el} mainly just
+defines aliases to the @file{cl-lib.el} definitions).  Where
address@hidden defines a function called, for example,
address@hidden, @file{cl.el} uses the same name but without the
address@hidden prefix, e.g. @code{incf} in this example.  There are a few
+exceptions to this.  First, functions such as @code{cl-defun} where
+the unprefixed version was already used for a standard Emacs Lisp
+function.  In such cases, the @file{cl.el} version adds a @samp{*}
+suffix, e.g. @code{defun*}.  Second, there are some obsolete features
+that are only implemented in @file{cl.el}, not in @file{cl-lib.el},
+because they are replaced by other standard Emacs Lisp features.
+Finally, in a very few cases the old @file{cl.el} versions do not
+behave in exactly the same way as the @file{cl-lib.el} versions.
address@hidden Features}.
+
+Since the old @file{cl.el} does not use a clean namespace, Emacs has a
+policy that packages distributed with Emacs must not load @code{cl} at
+run time.  (It is ok for them to load @code{cl} at @emph{compile}
+time, with @code{eval-when-compile}, and use the macros it provides.)
+There is no such restriction on the use of @code{cl-lib}.  New code
+should use @code{cl-lib} rather than @code{cl}.
 
 There is one more file, @file{cl-compat.el}, which defines some
 routines from the older Quiroz CL package that are not otherwise
@@ -4666,13 +4679,6 @@
 Following is a list of all known incompatibilities between this
 package and Common Lisp as documented in Steele (2nd edition).
 
address@hidden
-Certain function names, such as @code{member}, @code{assoc}, and
address@hidden, were already taken by (incompatible) Emacs Lisp
-functions; this package appends @samp{*} to the names of its
-Common Lisp versions of these functions.
address@hidden ignore
-
 The word @code{cl-defun} is required instead of @code{defun} in order
 to use extended Common Lisp argument lists in a function.  Likewise,
 @code{cl-defmacro} and @code{cl-function} are versions of those forms
@@ -4684,6 +4690,7 @@
 between IEEE floating-point plus and minus zero.  The @code{cl-equalp}
 predicate has several differences with Common Lisp; @pxref{Predicates}.
 
address@hidden FIXME no longer provided by cl.
 The @code{setf} mechanism is entirely compatible, except that
 setf-methods return a list of five values rather than five
 values directly.  Also, the new address@hidden function'' concept