Subject: bug#15021: 24.3.50; `CL' manual: describe differences from Common Lisp, everywhere

From: Drew Adams <[email-masked]>
Date: Sun, 4 Aug 2013 10:52:54 -0700 (PDT)

In general, some description is provided for the Emacs-Lisp versions of
CL things.  But there is little or no info about how the Emacs version
of the thing differs from the CL version.

That missing info is one of the most important things to be documented.

Example of where we do point out a difference: In (cl) `Structures' we
say:

"In true Common Lisp, each structure type is a new type distinct from
 all existing Lisp types.  Since the underlying Emacs Lisp system
 provides no way to create new distinct types, this package implements
 structures as vectors (or lists upon request) with a special "tag"
 symbol to identify them."

And there is more info about this type tag.

(Drop "true", BTW.)

But there are many more differences between what CL offers and what
package cl-lib provides.  There needs to be much more documentation to
explain the differences.  Otherwise, Emacs-Lisp users are forced to
examine the (dense and confusing) cl-lib.el code itself and guess what
the actual behavior is and how it differs from CL.

CL itself is specified rigorously and pretty completely.  What is
missing is good Emacs-Lisp doc of just how cl-lib diverges from the CL
spec.  Many (nearly all?) cl-lib functions, macros, whatever differ in
some way from CL, but little is said about these differences.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-02 on ODIEONE
Bzr revision: 113660 [email-masked]
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'