+If the optional second argument @var{show-args} is @code{t} instead
+of @code{nil}, then the error message (with or without @var{string})
+will also include all non-constant arguments of the top-level
+@var{form}. For example:
+
+@example
+(cl-assert (> x 10) t "x is too small: %d")
+@end example
+
+This usage of @var{show-args} is an extension to Common Lisp. In
+true Common Lisp, the second argument gives a list of @var{places}
+which can be @code{setf}'d by the user before continuing from the
+error. Since Emacs Lisp does not support continuable errors, it
+makes no sense to specify @var{places}.
+@end defmac
+
+@defmac cl-check-type form type [string]
+This form verifies that @var{form} evaluates to a value of type
+@var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
+signals a @code{wrong-type-argument} error. The default error message
+lists the erroneous value along with @var{type} and @var{form}
+themselves. If @var{string} is specified, it is included in the
+error message in place of @var{type}. For example:
+
+@example
+(cl-check-type x (integer 1 *) "a positive integer")
+@end example
+
+@xref{Type Predicates}, for a description of the type specifiers
+that may be used for @var{type}.
+
+Note that in Common Lisp, the first argument to @code{check-type}
+must be a @var{place} suitable for use by @code{setf}, because
+@code{check-type} signals a continuable error that allows the
+user to modify @var{place}.
+@end defmac
+
+@node Efficiency Concerns
+@appendix Efficiency Concerns
+
+@appendixsec Macros
+
+@noindent
+Many of the advanced features of this package, such as @code{cl-defun},
+@code{cl-loop}, etc., are implemented as Lisp macros. In
+byte-compiled code, these complex notations will be expanded into
+equivalent Lisp code which is simple and efficient. For example,
+the form
+
+@example
+(cl-incf i n)
+@end example
+
+@noindent
+is expanded at compile-time to the Lisp form
+
+@example
+(setq i (+ i n))
+@end example
+
+@noindent
+which is the most efficient ways of doing this operation
+in Lisp. Thus, there is no performance penalty for using the more
+readable @code{cl-incf} form in your compiled code.
+
+@emph{Interpreted} code, on the other hand, must expand these macros
+every time they are executed. For this reason it is strongly
+recommended that code making heavy use of macros be compiled.
+A loop using @code{cl-incf} a hundred times will execute considerably
+faster if compiled, and will also garbage-collect less because the
+macro expansion will not have to be generated, used, and thrown away a
+hundred times.
+
+You can find out how a macro expands by using the
+@code{cl-prettyexpand} function.
+
+@defun cl-prettyexpand form &optional full
+This function takes a single Lisp form as an argument and inserts
+a nicely formatted copy of it in the current buffer (which must be
+in Lisp mode so that indentation works properly). It also expands
+all Lisp macros that appear in the form. The easiest way to use
+this function is to go to the @file{*scratch*} buffer and type, say,
+
+@example
+(cl-prettyexpand '(cl-loop for x below 10 collect x))
+@end example
+
+@noindent
+and type @kbd{C-x C-e} immediately after the closing parenthesis;
+an expansion similar to:
+
+@example
+(cl-block nil
+ (let* ((x 0)
+ (G1004 nil))
+ (while (< x 10)
+ (setq G1004 (cons x G1004))
+ (setq x (+ x 1)))
+ (nreverse G1004)))
+@end example
+
+@noindent
+will be inserted into the buffer. (The @code{cl-block} macro is
+expanded differently in the interpreter and compiler, so
+@code{cl-prettyexpand} just leaves it alone. The temporary
+variable @code{G1004} was created by @code{cl-gensym}.)
+
+If the optional argument @var{full} is true, then @emph{all}
+macros are expanded, including @code{cl-block}, @code{cl-eval-when},
+and compiler macros. Expansion is done as if @var{form} were
+a top-level form in a file being compiled.
+
+@c FIXME none of these examples are still applicable.
+@ignore
+For example,
+
+@example
+(cl-prettyexpand '(cl-pushnew 'x list))
+ @print{} (setq list (cl-adjoin 'x list))
+(cl-prettyexpand '(cl-pushnew 'x list) t)
+ @print{} (setq list (if (memq 'x list) list (cons 'x list)))
+(cl-prettyexpand '(caddr (cl-member 'a list)) t)
+ @print{} (car (cdr (cdr (memq 'a list))))
+@end example
+@end ignore
+
+Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
+have built-in compiler macros to optimize them in common cases.
+@end defun
+
+@appendixsec Error Checking
+
+@noindent
+Common Lisp compliance has in general not been sacrificed for the
+sake of efficiency. A few exceptions have been made for cases
+where substantial gains were possible at the expense of marginal
+incompatibility.
+
+The Common Lisp standard (as embodied in Steele's book) uses the
+phrase ``it is an error if'' to indicate a situation that is not
+supposed to arise in complying programs; implementations are strongly
+encouraged but not required to signal an error in these situations.
+This package sometimes omits such error checking in the interest of
+compactness and efficiency. For example, @code{cl-do} variable
+specifiers are supposed to be lists of one, two, or three forms;
+extra forms are ignored by this package rather than signaling a
+syntax error. The @code{cl-endp} function is simply a synonym for
+@code{null} in this package. Functions taking keyword arguments
+will accept an odd number of arguments, treating the trailing
+keyword as if it were followed by the value @code{nil}.
+
+Argument lists (as processed by @code{cl-defun} and friends)
+@emph{are} checked rigorously except for the minor point just
+mentioned; in particular, keyword arguments are checked for
+validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
+are fully implemented. Keyword validity checking is slightly
+time consuming (though not too bad in byte-compiled code);
+you can use @code{&allow-other-keys} to omit this check. Functions
+defined in this package such as @code{cl-find} and @code{cl-member}
+do check their keyword arguments for validity.
+
+@appendixsec Compiler Optimizations
+
+@noindent
+Changing the value of @code{byte-optimize} from the default @code{t}
+is highly discouraged; many of the Common
+Lisp macros emit
+code that can be improved by optimization. In particular,
+@code{cl-block}s (whether explicit or implicit in constructs like
+@code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
+byte-compiler removes @code{cl-block}s that are not actually
+referenced by @code{cl-return} or @code{cl-return-from} inside the block.
+
+@node Common Lisp Compatibility
+@appendix Common Lisp Compatibility
+
+@noindent
+The following is a list of all known incompatibilities between this
+package and Common Lisp as documented in Steele (2nd edition).
+
+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
+which understand full-featured argument lists. The @code{&whole}
+keyword does not work in @code{cl-defmacro} argument lists (except
+inside recursive argument lists).
+
+The @code{equal} predicate does not distinguish
+between IEEE floating-point plus and minus zero. The @code{cl-equalp}
+predicate has several differences with Common Lisp; @pxref{Predicates}.
+
+The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
+with no @var{obarray} argument. In Common Lisp, this form would
+iterate over all symbols in all packages. Since Emacs obarrays
+are not a first-class package mechanism, there is no way for
+@code{cl-do-all-symbols} to locate any but the default obarray.
+
+The @code{cl-loop} macro is complete except that @code{loop-finish}
+and type specifiers are unimplemented.
+
+The multiple-value return facility treats lists as multiple
+values, since Emacs Lisp cannot support multiple return values
+directly. The macros will be compatible with Common Lisp if
+@code{cl-values} or @code{cl-values-list} is always used to return to
+a @code{cl-multiple-value-bind} or other multiple-value receiver;
+if @code{cl-values} is used without @code{cl-multiple-value-@dots{}}
+or vice-versa the effect will be different from Common Lisp.
+
+Many Common Lisp declarations are ignored, and others match
+the Common Lisp standard in concept but not in detail. For
+example, local @code{special} declarations, which are purely
+advisory in Emacs Lisp, do not rigorously obey the scoping rules
+set down in Steele's book.
+
+The variable @code{cl--gensym-counter} starts out with a pseudo-random
+value rather than with zero. This is to cope with the fact that
+generated symbols become interned when they are written to and
+loaded back from a file.
+
+The @code{cl-defstruct} facility is compatible, except that structures
+are of type @code{:type vector :named} by default rather than some
+special, distinct type. Also, the @code{:type} slot option is ignored.
+
+The second argument of @code{cl-check-type} is treated differently.
+
+@node Porting Common Lisp
+@appendix Porting Common Lisp
+
+@noindent
+This package is meant to be used as an extension to Emacs Lisp,
+not as an Emacs implementation of true Common Lisp. Some of the
+remaining differences between Emacs Lisp and Common Lisp make it
+difficult to port large Common Lisp applications to Emacs. For
+one, some of the features in this package are not fully compliant
+with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
+are also quite a few features that this package does not provide
+at all. Here are some major omissions that you will want to watch out
+for when bringing Common Lisp code into Emacs.
+
+@itemize @bullet
+@item
+Case-insensitivity. Symbols in Common Lisp are case-insensitive
+by default. Some programs refer to a function or variable as
+@code{foo} in one place and @code{Foo} or @code{FOO} in another.
+Emacs Lisp will treat these as three distinct symbols.
+
+Some Common Lisp code is written entirely in upper case. While Emacs
+is happy to let the program's own functions and variables use
+this convention, calls to Lisp builtins like @code{if} and
+@code{defun} will have to be changed to lower case.
+
+@item
+Lexical scoping. In Common Lisp, function arguments and @code{let}
+bindings apply only to references physically within their bodies (or
+within macro expansions in their bodies). Traditionally, Emacs Lisp
+uses @dfn{dynamic scoping} wherein a binding to a variable is visible
+even inside functions called from the body.
+@xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
+Lexical binding is available since Emacs 24.1, so be sure to set
+@code{lexical-binding} to @code{t} if you need to emulate this aspect
+of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
+
+Here is an example of a Common Lisp code fragment that would fail in
+Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
+
+@example
+(defun map-odd-elements (func list)
+ (loop for x in list
+ for flag = t then (not flag)
+ collect (if flag x (funcall func x))))
+
+(defun add-odd-elements (list x)
+ (map-odd-elements (lambda (a) (+ a x)) list))
+@end example
+
+@noindent
+With lexical binding, the two functions' usages of @code{x} are
+completely independent. With dynamic binding, the binding to @code{x}
+made by @code{add-odd-elements} will have been hidden by the binding
+in @code{map-odd-elements} by the time the @code{(+ a x)} function is
+called.
+
+Internally, this package uses lexical binding so that such problems do
+not occur. @xref{Obsolete Lexical Binding}, for a description of the obsolete
+@code{lexical-let} form that emulates a Common Lisp-style lexical
+binding when dynamic binding is in use.
+
+@item
+Reader macros. Common Lisp includes a second type of macro that
+works at the level of individual characters. For example, Common
+Lisp implements the quote notation by a reader macro called @code{'},
+whereas Emacs Lisp's parser just treats quote as a special case.
+Some Lisp packages use reader macros to create special syntaxes
+for themselves, which the Emacs parser is incapable of reading.
+
+@item
+Other syntactic features. Common Lisp provides a number of
+notations beginning with @code{#} that the Emacs Lisp parser
+won't understand. For example, @samp{#| @dots{} |#} is an
+alternate comment notation, and @samp{#+lucid (foo)} tells
+the parser to ignore the @code{(foo)} except in Lucid Common
+Lisp.
+
+@item
+Packages. In Common Lisp, symbols are divided into @dfn{packages}.
+Symbols that are Lisp built-ins are typically stored in one package;
+symbols that are vendor extensions are put in another, and each
+application program would have a package for its own symbols.
+Certain symbols are ``exported'' by a package and others are
+internal; certain packages ``use'' or import the exported symbols
+of other packages. To access symbols that would not normally be
+visible due to this importing and exporting, Common Lisp provides
+a syntax like @code{package:symbol} or @code{package::symbol}.
+
+Emacs Lisp has a single namespace for all interned symbols, and
+then uses a naming convention of putting a prefix like @code{cl-}
+in front of the name. Some Emacs packages adopt the Common Lisp-like
+convention of using @code{cl:} or @code{cl::} as the prefix.
+However, the Emacs parser does not understand colons and just
+treats them as part of the symbol name. Thus, while @code{mapcar}
+and @code{lisp:mapcar} may refer to the same symbol in Common
+Lisp, they are totally distinct in Emacs Lisp. Common Lisp
+programs that refer to a symbol by the full name sometimes
+and the short name other times will not port cleanly to Emacs.
+
+Emacs Lisp does have a concept of ``obarrays'', which are
+package-like collections of symbols, but this feature is not
+strong enough to be used as a true package mechanism.
+
+@item
+The @code{format} function is quite different between Common
+Lisp and Emacs Lisp. It takes an additional ``destination''
+argument before the format string. A destination of @code{nil}
+means to format to a string as in Emacs Lisp; a destination
+of @code{t} means to write to the terminal (similar to
+@code{message} in Emacs). Also, format control strings are
+utterly different; @code{~} is used instead of @code{%} to
+introduce format codes, and the set of available codes is
+much richer. There are no notations like @code{\n} for
+string literals; instead, @code{format} is used with the
+``newline'' format code, @code{~%}. More advanced formatting
+codes provide such features as paragraph filling, case
+conversion, and even loops and conditionals.
+
+While it would have been possible to implement most of Common
+Lisp @code{format} in this package (under the name @code{cl-format},
+of course), it was not deemed worthwhile. It would have required
+a huge amount of code to implement even a decent subset of
+@code{format}, yet the functionality it would provide over
+Emacs Lisp's @code{format} would rarely be useful.
+
+@item
+Vector constants use square brackets in Emacs Lisp, but
+@code{#(a b c)} notation in Common Lisp. To further complicate
+matters, Emacs has its own @code{#(} notation for
+something entirely different---strings with properties.
+
+@item
+Characters are distinct from integers in Common Lisp. The notation
+for character constants is also different: @code{#\A} in Common Lisp
+where Emacs Lisp uses @code{?A}. Also, @code{string=} and
+@code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
+case-insensitive in Common Lisp.
+
+@item
+Data types. Some Common Lisp data types do not exist in Emacs
+Lisp. Rational numbers and complex numbers are not present,
+nor are large integers (all integers are ``fixnums''). All
+arrays are one-dimensional. There are no readtables or pathnames;
+streams are a set of existing data types rather than a new data
+type of their own. Hash tables, random-states, structures, and
+packages (obarrays) are built from Lisp vectors or lists rather
+than being distinct types.
+
+@item
+The Common Lisp Object System (CLOS) is not implemented,
+nor is the Common Lisp Condition System. However, the EIEIO package
+(@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
+CLOS functionality.
+
+@item
+Common Lisp features that are completely redundant with Emacs
+Lisp features of a different name generally have not been
+implemented. For example, Common Lisp writes @code{defconstant}
+where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
+takes its arguments in different ways in the two Lisps but does
+exactly the same thing, so this package has not bothered to
+implement a Common Lisp-style @code{make-list}.
+
+@item
+A few more notable Common Lisp features not included in this
+package: @code{compiler-let}, @code{tagbody}, @code{prog},
+@code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
+
+@item
+Recursion. While recursion works in Emacs Lisp just like it
+does in Common Lisp, various details of the Emacs Lisp system
+and compiler make recursion much less efficient than it is in
+most Lisps. Some schools of thought prefer to use recursion
+in Lisp over other techniques; they would sum a list of
+numbers using something like