APPROVE COMMIT
NOTE: This patch has been committed.
# HG changeset patch
# User Aidan Kehoe <kehoea(a)parhasard.net>
# Date 1312906664 -3600
# Node ID a46c5c8d65648803e334ca73b5a306092557334b
# Parent d54278e74d71b8fbd47829e91cb129376fc709ea
Avoid calling various macros "special operators" in the manuals.
2011-08-09 Aidan Kehoe <kehoea(a)parhasard.net>
* cl.texi (Argument Lists):
* cl.texi (Time of Evaluation):
* cl.texi (Type Predicates):
* cl.texi (Assignment):
* cl.texi (Basic Setf):
* cl.texi (Modify Macros):
* cl.texi (Customizing Setf):
* cl.texi (Dynamic Bindings):
* cl.texi (Lexical Bindings):
* cl.texi (Function Bindings):
* cl.texi (Macro Bindings):
* cl.texi (Conditionals):
* cl.texi (Blocks and Exits):
* cl.texi (Iteration):
* cl.texi (Loop Basics):
* cl.texi (Macros):
* cl.texi (Declarations):
* cl.texi (Property Lists):
* cl.texi (Structures):
* cl.texi (Assertions):
* cl.texi (Efficiency Concerns):
* lispref/compile.texi (Eval During Compile):
* lispref/compile.texi (Compiled-Function Objects):
* lispref/eval.texi (Multiple values):
* lispref/frames.texi (Input Focus):
* lispref/internationalization.texi (Level 3 Primitives):
* lispref/positions.texi (Excursions):
* lispref/positions.texi (Narrowing):
* lispref/searching.texi (Saving Match Data):
* lispref/specifiers.texi (Adding Specifications):
* lispref/windows.texi:
Correct the manuals to avoid using the term "special operator" when
#'special-operator-p would give nil.
diff -r d54278e74d71 -r a46c5c8d6564 man/ChangeLog
--- a/man/ChangeLog Mon Aug 08 23:10:47 2011 +0900
+++ b/man/ChangeLog Tue Aug 09 17:17:44 2011 +0100
@@ -1,3 +1,39 @@
+2011-08-09 Aidan Kehoe <kehoea(a)parhasard.net>
+
+ * cl.texi (Argument Lists):
+ * cl.texi (Time of Evaluation):
+ * cl.texi (Type Predicates):
+ * cl.texi (Assignment):
+ * cl.texi (Basic Setf):
+ * cl.texi (Modify Macros):
+ * cl.texi (Customizing Setf):
+ * cl.texi (Dynamic Bindings):
+ * cl.texi (Lexical Bindings):
+ * cl.texi (Function Bindings):
+ * cl.texi (Macro Bindings):
+ * cl.texi (Conditionals):
+ * cl.texi (Blocks and Exits):
+ * cl.texi (Iteration):
+ * cl.texi (Loop Basics):
+ * cl.texi (Macros):
+ * cl.texi (Declarations):
+ * cl.texi (Property Lists):
+ * cl.texi (Structures):
+ * cl.texi (Assertions):
+ * cl.texi (Efficiency Concerns):
+ * lispref/compile.texi (Eval During Compile):
+ * lispref/compile.texi (Compiled-Function Objects):
+ * lispref/eval.texi (Multiple values):
+ * lispref/frames.texi (Input Focus):
+ * lispref/internationalization.texi (Level 3 Primitives):
+ * lispref/positions.texi (Excursions):
+ * lispref/positions.texi (Narrowing):
+ * lispref/searching.texi (Saving Match Data):
+ * lispref/specifiers.texi (Adding Specifications):
+ * lispref/windows.texi:
+ Correct the manuals to avoid using the term "special operator" when
+ #'special-operator-p would give nil.
+
2011-08-08 Stephen J. Turnbull <stephen(a)xemacs.org>
* internals/internals.texi (Mercurial Techniques): New.
diff -r d54278e74d71 -r a46c5c8d6564 man/cl.texi
--- a/man/cl.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/cl.texi Tue Aug 09 17:17:44 2011 +0100
@@ -381,14 +381,14 @@
Instead, this package defines alternates for several Lisp forms
which you must use if you need Common Lisp argument lists.
-@deffn {Special Operator} defun* name arglist body...
+@defmac defun* name arglist body...
This form is identical to the regular @code{defun} form, except
that @var{arglist} is allowed to be a full Common Lisp argument
list. Also, the function body is enclosed in an implicit block
called @var{name}; @pxref{Blocks and Exits}.
-@end deffn
-
-@deffn {Special Operator} defsubst* name arglist body...
+@end defmac
+
+@defmac defsubst* name arglist body...
This is just like @code{defun*}, except that the function that
is defined is automatically proclaimed @code{inline}, i.e.,
calls to it may be expanded into in-line code by the byte compiler.
@@ -398,9 +398,9 @@
efficient inline expansions. In particular, @code{defsubst*}
arranges for the processing of keyword arguments, default values,
etc., to be done at compile-time whenever possible.
-@end deffn
-
-@deffn {Special Operator} defmacro* name arglist body...
+@end defmac
+
+@defmac defmacro* name arglist body...
This is identical to the regular @code{defmacro} form,
except that @var{arglist} is allowed to be a full Common Lisp
argument list. The @code{&environment} keyword is supported as
@@ -409,13 +409,13 @@
cannot be implemented with the current Emacs Lisp interpreter.
The macro expander body is enclosed in an implicit block called
@var{name}.
-@end deffn
-
-@deffn {Special Operator} function* symbol-or-lambda
+@end defmac
+
+@defmac function* symbol-or-lambda
This is identical to the regular @code{function} form,
except that if the argument is a @code{lambda} form then that
form may use a full Common Lisp argument list.
-@end deffn
+@end defmac
Also, all forms (such as @code{defsetf} and @code{flet}) defined
in this package that include @var{arglist}s in their syntax allow
@@ -606,7 +606,7 @@
at compile-time so that later parts of the file can refer to the
macros that are defined.
-@deffn {Special Operator} eval-when (situations...) forms...
+@defmac eval-when (situations...) forms...
This form controls when the body @var{forms} are evaluated.
The @var{situations} list may contain any set of the symbols
@code{compile}, @code{load}, and @code{eval} (or their long-winded
@@ -678,7 +678,7 @@
certain top-level forms, like @code{defmacro} (sort-of) and
@code{require}, as if they were wrapped in @code{(eval-when
(compile load eval) @dots{})}.
-@end deffn
+@end defmac
Emacs 19 includes two special operators related to @code{eval-when}.
One of these, @code{eval-when-compile}, is not quite equivalent to
@@ -690,7 +690,7 @@
equivalent to @samp{(eval-when (compile load eval) @dots{})} and
so is not itself defined by this package.
-@deffn {Special Operator} eval-when-compile forms...
+@defmac eval-when-compile forms...
The @var{forms} are evaluated at compile-time; at execution time,
this form acts like a quoted constant of the resulting value. Used
at top-level, @code{eval-when-compile} is just like @samp{eval-when
@@ -699,9 +699,9 @@
or other reasons.
This form is similar to the @samp{#.} syntax of true Common Lisp.
-@end deffn
-
-@deffn {Special Operator} load-time-value form
+@end defmac
+
+@defmac load-time-value form
The @var{form} is evaluated at load-time; at execution time,
this form acts like a quoted constant of the resulting value.
@@ -742,7 +742,7 @@
", and loaded on: "
--temp--))
@end example
-@end deffn
+@end defmac
@node Function Aliases, , Time of Evaluation, Program Structure
@section Function Aliases
@@ -869,7 +869,7 @@
error.
@end defun
-@deffn {Special Operator} deftype name arglist forms...
+@defmac deftype name arglist forms...
This macro defines a new type called @var{name}. It is similar
to @code{defmacro} in many ways; when @var{name} is encountered
as a type name, the body @var{forms} are evaluated and should
@@ -897,7 +897,7 @@
The last example shows how the Common Lisp @code{unsigned-byte}
type specifier could be implemented if desired; this package does
not implement @code{unsigned-byte} by default.
-@end deffn
+@end defmac
The @code{typecase} and @code{check-type} macros also use type
names. @xref{Conditionals}. @xref{Assertions}. The @code{map},
@@ -989,7 +989,7 @@
The @code{psetq} form is just like @code{setq}, except that multiple
assignments are done in parallel rather than sequentially.
-@deffn {Special Operator} psetq [symbol form]@dots{}
+@defmac psetq [symbol form]@dots{}
This macro is used to assign to several
variables simultaneously. Given only one @var{symbol} and @var{form},
it has the same effect as @code{setq}. Given several @var{symbol}
@@ -1017,7 +1017,7 @@
@pxref{Modify Macros}.)
@code{psetq} always returns @code{nil}.
-@end deffn
+@end defmac
@node Generalized Variables, Variable Bindings, Assignment, Control Structure
@section Generalized Variables
@@ -1055,7 +1055,7 @@
The @code{setf} macro is the most basic way to operate on generalized
variables.
-@deffn {Special Operator} setf [place form]@dots{}
+@defmac setf [place form]@dots{}
This macro evaluates @var{form} and stores it in @var{place}, which
must be a valid generalized variable form. If there are several
@var{place} and @var{form} pairs, the assignments are done sequentially
@@ -1218,7 +1218,7 @@
the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
evaluate @var{b} first, then @var{a}, just as in an actual call
to @code{wrong-order}.
-@end deffn
+@end defmac
@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
@subsection Modify Macros
@@ -1228,15 +1228,15 @@
that operate on generalized variables. Many are interesting and
useful even when the @var{place} is just a variable name.
-@deffn {Special Operator} psetf [place form]@dots{}
+@defmac psetf [place form]@dots{}
This macro is to @code{setf} what @code{psetq} is to @code{setq}:
When several @var{place}s and @var{form}s are involved, the
assignments take place in parallel rather than sequentially.
Specifically, all subforms are evaluated from left to right, then
all the assignments are done (in an undefined order).
-@end deffn
-
-@deffn {Special Operator} incf place &optional x
+@end defmac
+
+@defmac incf place &optional x
This macro increments the number stored in @var{place} by one, or
by @var{x} if specified. The incremented value is returned. For
example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
@@ -1274,35 +1274,35 @@
As a more Emacs-specific example of @code{incf}, the expression
@code{(incf (point) @var{n})} is essentially equivalent to
@code{(forward-char @var{n})}.
-@end deffn
-
-@deffn {Special Operator} decf place &optional x
+@end defmac
+
+@defmac decf place &optional x
This macro decrements the number stored in @var{place} by one, or
by @var{x} if specified.
-@end deffn
-
-@deffn {Special Operator} pop place
+@end defmac
+
+@defmac pop place
This macro removes and returns the first element of the list stored
in @var{place}. It is analogous to @code{(prog1 (car @var{place})
(setf @var{place} (cdr @var{place})))}, except that it takes care
to evaluate all subforms only once.
-@end deffn
-
-@deffn {Special Operator} push x place
+@end defmac
+
+@defmac push x place
This macro inserts @var{x} at the front of the list stored in
@var{place}. It is analogous to @code{(setf @var{place} (cons
@var{x} @var{place}))}, except for evaluation of the subforms.
-@end deffn
-
-@deffn {Special Operator} pushnew x place @t{&key :test :test-not :key}
+@end defmac
+
+@defmac pushnew x place @t{&key :test :test-not :key}
This macro inserts @var{x} at the front of the list stored in
@var{place}, but only if @var{x} was not @code{eql} to any
existing element of the list. The optional keyword arguments
are interpreted in the same way as for @code{adjoin}.
@xref{Lists as Sets}.
-@end deffn
-
-@deffn {Special Operator} shiftf place@dots{} newvalue
+@end defmac
+
+@defmac shiftf place@dots{} newvalue
This macro shifts the @var{place}s left by one, shifting in the
value of @var{newvalue} (which may be any Lisp expression, not just
a generalized variable), and returning the value shifted out of
@@ -1320,9 +1320,9 @@
@noindent
except that the subforms of @var{a}, @var{b}, and @var{c} are actually
evaluated only once each and in the apparent order.
-@end deffn
-
-@deffn {Special Operator} rotatef place@dots{}
+@end defmac
+
+@defmac rotatef place@dots{}
This macro rotates the @var{place}s left by one in circular fashion.
Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
@@ -1337,12 +1337,12 @@
except for the evaluation of subforms. @code{rotatef} always
returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
conveniently exchanges @var{a} and @var{b}.
-@end deffn
+@end defmac
The following macros were invented for this package; they have no
analogues in Common Lisp.
-@deffn {Special Operator} letf (bindings@dots{}) forms@dots{}
+@defmac letf (bindings@dots{}) forms@dots{}
This macro is analogous to @code{let}, but for generalized variables
rather than just symbols. Each @var{binding} should be of the form
@code{(@var{place} @var{value})}; the original contents of the
@@ -1392,14 +1392,14 @@
variables and calls to @code{symbol-value} and @code{symbol-function}.
If the symbol is not bound on entry, it is simply made unbound by
@code{makunbound} or @code{fmakunbound} on exit.
-@end deffn
-
-@deffn {Special Operator} letf* (bindings@dots{}) forms@dots{}
+@end defmac
+
+@defmac letf* (bindings@dots{}) forms@dots{}
This macro is to @code{letf} what @code{let*} is to @code{let}:
It does the bindings in sequential rather than parallel order.
-@end deffn
-
-@deffn {Special Operator} callf @var{function} @var{place} @var{args}@dots{}
+@end defmac
+
+@defmac callf @var{function} @var{place} @var{args}@dots{}
This is the ``generic'' modify macro. It calls @var{function},
which should be an unquoted function name, macro name, or lambda.
It passes @var{place} and @var{args} as arguments, and assigns the
@@ -1416,14 +1416,14 @@
@xref{Customizing Setf}, for @code{define-modify-macro}, a way
to create even more concise notations for modify macros. Note
again that @code{callf} is an extension to standard Common Lisp.
-@end deffn
-
-@deffn {Special Operator} callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
+@end defmac
+
+@defmac callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
This macro is like @code{callf}, except that @var{place} is
the @emph{second} argument of @var{function} rather than the
first. For example, @code{(push @var{x} @var{place})} is
equivalent to @code{(callf2 cons @var{x} @var{place})}.
-@end deffn
+@end defmac
The @code{callf} and @code{callf2} macros serve as building
blocks for other macros like @code{incf}, @code{pushnew}, and
@@ -1439,7 +1439,7 @@
@code{defsetf}, and @code{define-setf-method}, that allow the
user to extend generalized variables in various ways.
-@deffn {Special Operator} define-modify-macro name arglist function [doc-string]
+@defmac define-modify-macro name arglist function [doc-string]
This macro defines a ``read-modify-write'' macro similar to
@code{incf} and @code{decf}. The macro @var{name} is defined
to take a @var{place} argument followed by additional arguments
@@ -1480,9 +1480,9 @@
using @code{get-setf-method}, or consult the source file
@file{cl-macs.el} to see how to use the internal @code{setf}
building blocks.
-@end deffn
-
-@deffn {Special Operator} defsetf access-fn update-fn
+@end defmac
+
+@defmac defsetf access-fn update-fn
This is the simpler of two @code{defsetf} forms. Where
@var{access-fn} is the name of a function which accesses a place,
this declares @var{update-fn} to be the corresponding store
@@ -1525,9 +1525,9 @@
(defsetf symbol-value set)
(defsetf buffer-name rename-buffer t)
@end example
-@end deffn
-
-@deffn {Special Operator} defsetf access-fn arglist (store-var) forms@dots{}
+@end defmac
+
+@defmac defsetf access-fn arglist (store-var) forms@dots{}
This is the second, more complex, form of @code{defsetf}. It is
rather like @code{defmacro} except for the additional @var{store-var}
argument. The @var{forms} should return a Lisp form which stores
@@ -1556,9 +1556,9 @@
(defsetf nth (n x) (store)
(list 'setcar (list 'nthcdr n x) store))
@end example
-@end deffn
-
-@deffn {Special Operator} define-setf-method access-fn arglist forms@dots{}
+@end defmac
+
+@defmac define-setf-method access-fn arglist forms@dots{}
This is the most general way to create new place forms. When
a @code{setf} to @var{access-fn} with arguments described by
@var{arglist} is expanded, the @var{forms} are evaluated and
@@ -1603,7 +1603,7 @@
use this setf-method will optimize away most temporaries that
turn out to be unnecessary, so there is little reason for the
setf-method itself to optimize.
-@end deffn
+@end defmac
@defun get-setf-method place &optional env
This function returns the setf-method for @var{place}, by
@@ -1669,7 +1669,7 @@
at compile-time. The @code{progv} form provides an easy way to
bind variables whose names are computed at run-time.
-@deffn {Special Operator} progv symbols values forms@dots{}
+@defmac progv symbols values forms@dots{}
This form establishes @code{let}-style variable bindings on a
set of variables computed at run-time. The expressions
@var{symbols} and @var{values} are evaluated, and must return lists
@@ -1679,7 +1679,7 @@
are made unbound (as if by @code{makunbound}) inside the body.
If @var{symbols} is shorter than @var{values}, the excess values
are ignored.
-@end deffn
+@end defmac
@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
@subsection Lexical Bindings
@@ -1688,7 +1688,7 @@
The @dfn{CL} package defines the following macro which
more closely follows the Common Lisp @code{let} form:
-@deffn {Special Operator} lexical-let (bindings@dots{}) forms@dots{}
+@defmac lexical-let (bindings@dots{}) forms@dots{}
This form is exactly like @code{let} except that the bindings it
establishes are purely lexical. Lexical bindings are similar to
local variables in a language like C: Only the code physically
@@ -1788,12 +1788,12 @@
The @code{lexical-let} form is an extension to Common Lisp. In
true Common Lisp, all bindings are lexical unless declared otherwise.
-@end deffn
-
-@deffn {Special Operator} lexical-let* (bindings@dots{}) forms@dots{}
+@end defmac
+
+@defmac lexical-let* (bindings@dots{}) forms@dots{}
This form is just like @code{lexical-let}, except that the bindings
are made sequentially in the manner of @code{let*}.
-@end deffn
+@end defmac
@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
@subsection Function Bindings
@@ -1802,7 +1802,7 @@
These forms make @code{let}-like bindings to functions instead
of variables.
-@deffn {Special Operator} flet (bindings@dots{}) forms@dots{}
+@defmac flet (bindings@dots{}) forms@dots{}
This form establishes @code{let}-style bindings on the function
cells of symbols rather than on the value cells. Each @var{binding}
must be a list of the form @samp{(@var{name} @var{arglist}
@@ -1841,14 +1841,14 @@
argument notation supported by @code{defun*}; also, the function
body is enclosed in an implicit block as if by @code{defun*}.
@xref{Program Structure}.
-@end deffn
-
-@deffn {Special Operator} labels (bindings@dots{}) forms@dots{}
+@end defmac
+
+@defmac labels (bindings@dots{}) forms@dots{}
The @code{labels} form is a synonym for @code{flet}. (In Common
Lisp, @code{labels} and @code{flet} differ in ways that depend on
their lexical scoping; these distinctions vanish in dynamically
scoped Emacs Lisp.)
-@end deffn
+@end defmac
@node Macro Bindings, , Function Bindings, Variable Bindings
@subsection Macro Bindings
@@ -1856,7 +1856,7 @@
@noindent
These forms create local macros and ``symbol macros.''
-@deffn {Special Operator} macrolet (bindings@dots{}) forms@dots{}
+@defmac macrolet (bindings@dots{}) forms@dots{}
This form is analogous to @code{flet}, but for macros instead of
functions. Each @var{binding} is a list of the same form as the
arguments to @code{defmacro*} (i.e., a macro name, argument list,
@@ -1868,9 +1868,9 @@
affect only calls that appear physically within the body
@var{forms}, possibly after expansion of other macros in the
body.
-@end deffn
-
-@deffn {Special Operator} symbol-macrolet (bindings@dots{}) forms@dots{}
+@end defmac
+
+@defmac symbol-macrolet (bindings@dots{}) forms@dots{}
This form creates @dfn{symbol macros}, which are macros that look
like variable references rather than function calls. Each
@var{binding} is a list @samp{(@var{var} @var{expansion})};
@@ -1935,7 +1935,7 @@
@xref{Loop Facility}, for a description of the @code{loop} macro.
This package defines a nonstandard @code{in-ref} loop clause that
works much like @code{my-dolist}.
-@end deffn
+@end defmac
@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
@section Conditionals
@@ -1944,7 +1944,7 @@
These conditional forms augment Emacs Lisp's simple @code{if},
@code{and}, @code{or}, and @code{cond} forms.
-@deffn {Special Operator} when test forms@dots{}
+@defmac when test forms@dots{}
This is a variant of @code{if} where there are no ``else'' forms,
and possibly several ``then'' forms. In particular,
@@ -1958,9 +1958,9 @@
@example
(if @var{test} (progn @var{a} @var{b} @var{c}) nil)
@end example
-@end deffn
-
-@deffn {Special Operator} unless test forms@dots{}
+@end defmac
+
+@defmac unless test forms@dots{}
This is a variant of @code{if} where there are no ``then'' forms,
and possibly several ``else'' forms:
@@ -1974,9 +1974,9 @@
@example
(when (not @var{test}) @var{a} @var{b} @var{c})
@end example
-@end deffn
-
-@deffn {Special Operator} case keyform clause@dots{}
+@end defmac
+
+@defmac case keyform clause@dots{}
This macro evaluates @var{keyform}, then compares it with the key
values listed in the various @var{clause}s. Whichever clause matches
the key is executed; comparison is done by @code{eql}. If no clause
@@ -2010,15 +2010,15 @@
((?\r ?\n) (do-ret-thing))
(t (do-other-thing)))
@end example
-@end deffn
-
-@deffn {Special Operator} ecase keyform clause@dots{}
+@end defmac
+
+@defmac ecase keyform clause@dots{}
This macro is just like @code{case}, except that if the key does
not match any of the clauses, an error is signalled rather than
simply returning @code{nil}.
-@end deffn
-
-@deffn {Special Operator} typecase keyform clause@dots{}
+@end defmac
+
+@defmac typecase keyform clause@dots{}
This macro is a version of @code{case} that checks for types
rather than values. Each @var{clause} is of the form
@samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
@@ -2035,13 +2035,13 @@
The type specifier @code{t} matches any type of object; the word
@code{otherwise} is also allowed. To make one clause match any of
several types, use an @code{(or ...)} type specifier.
-@end deffn
-
-@deffn {Special Operator} etypecase keyform clause@dots{}
+@end defmac
+
+@defmac etypecase keyform clause@dots{}
This macro is just like @code{typecase}, except that if the key does
not match any of the clauses, an error is signalled rather than
simply returning @code{nil}.
-@end deffn
+@end defmac
@node Blocks and Exits, Iteration, Conditionals, Control Structure
@section Blocks and Exits
@@ -2054,7 +2054,7 @@
optimizing byte-compiler to omit the costly @code{catch} step if the
body of the block does not actually @code{return-from} the block.
-@deffn {Special Operator} block name forms@dots{}
+@defmac block name forms@dots{}
The @var{forms} are evaluated as if by a @code{progn}. However,
if any of the @var{forms} execute @code{(return-from @var{name})},
they will jump out and return directly from the @code{block} form.
@@ -2093,20 +2093,20 @@
that jump to it. This means that @code{do} loops and @code{defun*}
functions which don't use @code{return} don't pay the overhead to
support it.
-@end deffn
-
-@deffn {Special Operator} return-from name [result]
+@end defmac
+
+@defmac return-from name [result]
This macro returns from the block named @var{name}, which must be
an (unevaluated) symbol. If a @var{result} form is specified, it
is evaluated to produce the result returned from the @code{block}.
Otherwise, @code{nil} is returned.
-@end deffn
-
-@deffn {Special Operator} return [result]
+@end defmac
+
+@defmac return [result]
This macro is exactly like @code{(return-from nil @var{result})}.
Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
themselves in @code{nil} blocks.
-@end deffn
+@end defmac
@node Iteration, Loop Facility, Blocks and Exits, Control Structure
@section Iteration
@@ -2116,7 +2116,7 @@
looping constructs to complement Emacs Lisp's basic @code{while}
loop.
-@deffn {Special Operator} loop forms@dots{}
+@defmac loop forms@dots{}
The @dfn{CL} package supports both the simple, old-style meaning of
@code{loop} and the extremely powerful and flexible feature known as
the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
@@ -2144,9 +2144,9 @@
(This is not a restriction in practice, since a plain symbol
in the above notation would simply access and throw away the
value of a variable.)
-@end deffn
-
-@deffn {Special Operator} do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
+@end defmac
+
+@defmac do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
This macro creates a general iterative loop. Each @var{spec} is
of the form
@@ -2192,9 +2192,9 @@
((or (null x) (null y))
(nreverse z)))
@end example
-@end deffn
-
-@deffn {Special Operator} do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
+@end defmac
+
+@defmac do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
This is to @code{do} what @code{let*} is to @code{let}. In
particular, the initial values are bound as if by @code{let*}
rather than @code{let}, and the steps are assigned as if by
@@ -2212,18 +2212,18 @@
(nreverse z))
(push (f x y) z))
@end example
-@end deffn
-
-@deffn {Special Operator} dolist (var list [result]) forms@dots{}
+@end defmac
+
+@defmac dolist (var list [result]) forms@dots{}
This is a more specialized loop which iterates across the elements
of a list. @var{list} should evaluate to a list; the body @var{forms}
are executed with @var{var} bound to each element of the list in
turn. Finally, the @var{result} form (or @code{nil}) is evaluated
with @var{var} bound to @code{nil} to produce the result returned by
the loop. The loop is surrounded by an implicit @code{nil} block.
-@end deffn
-
-@deffn {Special Operator} dotimes (var count [result]) forms@dots{}
+@end defmac
+
+@defmac dotimes (var count [result]) forms@dots{}
This is a more specialized loop which iterates a specified number
of times. The body is executed with @var{var} bound to the integers
from zero (inclusive) to @var{count} (exclusive), in turn. Then
@@ -2231,9 +2231,9 @@
number of iterations that were done (i.e., @code{(max 0 @var{count})})
to get the return value for the loop form. The loop is surrounded
by an implicit @code{nil} block.
-@end deffn
-
-@deffn {Special Operator} do-symbols (var [obarray [result]]) forms@dots{}
+@end defmac
+
+@defmac do-symbols (var [obarray [result]]) forms@dots{}
This loop iterates over all interned symbols. If @var{obarray}
is specified and is not @code{nil}, it loops over all symbols in
that obarray. For each symbol, the body @var{forms} are evaluated
@@ -2241,12 +2241,12 @@
an unspecified order. Afterward the @var{result} form, if any,
is evaluated (with @var{var} bound to @code{nil}) to get the return
value. The loop is surrounded by an implicit @code{nil} block.
-@end deffn
-
-@deffn {Special Operator} do-all-symbols (var [result]) forms@dots{}
+@end defmac
+
+@defmac do-all-symbols (var [result]) forms@dots{}
This is identical to @code{do-symbols} except that the @var{obarray}
argument is omitted; it always iterates over the default obarray.
-@end deffn
+@end defmac
@xref{Mapping over Sequences}, for some more functions for
iterating over vectors or lists.
@@ -2286,7 +2286,7 @@
takes place at byte-compile time; compiled @code{loop}s are just
as efficient as the equivalent @code{while} loops written longhand.
-@deffn {Special Operator} loop clauses@dots{}
+@defmac loop clauses@dots{}
A loop construct consists of a series of @var{clause}s, each
introduced by a symbol like @code{for} or @code{do}. Clauses
are simply strung together in the argument list of @code{loop},
@@ -2325,7 +2325,7 @@
(Because the loop body is enclosed in an implicit block, you can
also use regular Lisp @code{return} or @code{return-from} to
break out of the loop.)
-@end deffn
+@end defmac
The following sections give some examples of the Loop Macro in
action, and describe the particular loop clauses in great detail.
@@ -3003,7 +3003,7 @@
Destructuring is made available to the user by way of the
following macro:
-@deffn {Special Operator} destructuring-bind arglist expr forms@dots{}
+@defmac destructuring-bind arglist expr forms@dots{}
This macro expands to code which executes @var{forms}, with
the variables in @var{arglist} bound to the list of values
returned by @var{expr}. The @var{arglist} can include all
@@ -3012,13 +3012,13 @@
is not allowed.) The macro expansion will signal an error
if @var{expr} returns a list of the wrong number of arguments
or with incorrect keyword arguments.
-@end deffn
+@end defmac
This package also includes the Common Lisp @code{define-compiler-macro}
facility, which allows you to define compile-time expansions and
optimizations for your functions.
-@deffn {Special Operator} define-compiler-macro name arglist forms@dots{}
+@defmac define-compiler-macro name arglist forms@dots{}
This form is similar to @code{defmacro}, except that it only expands
calls to @var{name} at compile-time; calls processed by the Lisp
interpreter are not expanded, nor are they expanded by the
@@ -3052,7 +3052,7 @@
@code{member*} call is left intact. (The actual compiler macro
for @code{member*} optimizes a number of other cases, including
common @code{:test} predicates.)
-@end deffn
+@end defmac
@defun compiler-macroexpand form
This function is analogous to @code{macroexpand}, except that it
@@ -3094,7 +3094,7 @@
is evaluated and thus should normally be quoted.
@end defun
-@deffn {Special Operator} declaim decl-specs@dots{}
+@defmac declaim decl-specs@dots{}
This macro is like @code{proclaim}, except that it takes any number
of @var{decl-spec} arguments, and the arguments are unevaluated and
unquoted. The @code{declaim} macro also puts an @code{(eval-when
@@ -3103,22 +3103,22 @@
since normally the declarations are meant to influence the way the
compiler treats the rest of the file that contains the @code{declaim}
form.)
-@end deffn
-
-@deffn {Special Operator} declare decl-specs@dots{}
+@end defmac
+
+@defmac declare decl-specs@dots{}
This macro is used to make declarations within functions and other
code. Common Lisp allows declarations in various locations, generally
at the beginning of any of the many ``implicit @code{progn}s''
throughout Lisp syntax, such as function bodies, @code{let} bodies,
etc. Currently the only declaration understood by @code{declare}
is @code{special}.
-@end deffn
-
-@deffn {Special Operator} locally declarations@dots{} forms@dots{}
+@end defmac
+
+@defmac locally declarations@dots{} forms@dots{}
In this package, @code{locally} is no different from @code{progn}.
-@end deffn
-
-@deffn {Special Operator} the type form
+@end defmac
+
+@defmac the type form
Type information provided by @code{the} is ignored in this package;
in other words, @code{(the @var{type} @var{form})} is equivalent
to @var{form}. Future versions of the optimizing byte-compiler may
@@ -3131,7 +3131,7 @@
compiler would have enough information to expand the loop in-line.
For now, Emacs Lisp will treat the above code as exactly equivalent
to @code{(mapcar 'car foo)}.
-@end deffn
+@end defmac
Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
@code{declare} should be a list beginning with a symbol that says
@@ -3313,7 +3313,7 @@
expression.
@end defun
-@deffn {Special Operator} remf place property
+@defmac remf place property
This macro removes the property-value pair for @var{property} from
the property list stored at @var{place}, which is any @code{setf}-able
place expression. It returns true if the property was found. Note
@@ -3321,7 +3321,7 @@
effectively do a @code{(setf @var{place} (cddr @var{place}))},
whereas if it occurs later, this simply uses @code{setcdr} to splice
out the property and value cells.
-@end deffn
+@end defmac
@iftex
@secno=2
@@ -4677,7 +4677,7 @@
implements structures as vectors (or lists upon request) with a
special ``tag'' symbol to identify them.
-@deffn {Special Operator} defstruct name slots@dots{}
+@defmac defstruct name slots@dots{}
The @code{defstruct} form defines a new structure type called
@var{name}, with the specified @var{slots}. (The @var{slots}
may begin with a string which documents the structure type.)
@@ -4984,7 +4984,7 @@
specifies a number of slots to be skipped between the last slot
of the included type and the first new slot.
@end table
-@end deffn
+@end defmac
Except as noted, the @code{defstruct} facility of this package is
entirely compatible with that of Common Lisp.
@@ -5007,7 +5007,7 @@
away the following assertions. Because assertions might be optimized
away, it is a bad idea for them to include side-effects.
-@deffn {Special Operator} assert test-form [show-args string args@dots{}]
+@defmac assert test-form [show-args string args@dots{}]
This form verifies that @var{test-form} is true (i.e., evaluates to
a non-@code{nil} value). If so, it returns @code{nil}. If the test
is not satisfied, @code{assert} signals an error.
@@ -5030,9 +5030,9 @@
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.
-@end deffn
-
-@deffn {Special Operator} check-type place type &optional string
+@end defmac
+
+@defmac check-type place type &optional string
This form verifies that @var{place} evaluates to a value of type
@var{type}. If so, it returns @code{nil}. If not, @code{check-type}
signals a continuable @code{wrong-type-argument} error. The default
@@ -5051,18 +5051,18 @@
should 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}, most simply by returning a value from the debugger.
-@end deffn
+@end defmac
The following error-related macro is also defined:
-@deffn {Special Operator} ignore-errors forms@dots{}
+@defmac ignore-errors forms@dots{}
This executes @var{forms} exactly like a @code{progn}, except that
errors are ignored during the @var{forms}. More precisely, if
an error is signalled then @code{ignore-errors} immediately
aborts execution of the @var{forms} and returns @code{nil}.
If the @var{forms} complete successfully, @code{ignore-errors}
returns the result of the last @var{form}.
-@end deffn
+@end defmac
@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
@appendix Efficiency Concerns
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/compile.texi
--- a/man/lispref/compile.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/compile.texi Tue Aug 09 17:17:44 2011 +0100
@@ -691,7 +691,7 @@
These features permit you to write code to be evaluated during
compilation of a program.
-@deffn {Special Operator} eval-and-compile body
+@defmac eval-and-compile body
This form marks @var{body} to be evaluated both when you compile the
containing code and when you run it (whether compiled or not).
@@ -699,9 +699,9 @@
and referring to that file with @code{require}. Using @code{require} is
preferable if there is a substantial amount of code to be executed in
this way.
-@end deffn
+@end defmac
-@deffn {Special Operator} eval-when-compile body
+@defmac eval-when-compile body
This form marks @var{body} to be evaluated at compile time and not when
the compiled program is loaded. The result of evaluation by the
compiler becomes a constant which appears in the compiled program. When
@@ -712,7 +712,7 @@
@code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
@samp{#.} reader macro (but not when interpreting) is closer to what
@code{eval-when-compile} does.
-@end deffn
+@end defmac
@node Compiled-Function Objects
@section Compiled-Function Objects
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/eval.texi
--- a/man/lispref/eval.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/eval.texi Tue Aug 09 17:17:44 2011 +0100
@@ -743,21 +743,21 @@
values.
@end defun
-@deffn {Special Operator} multiple-value-bind (var@dots{}) values-form forms@dots{}
-This special operator evaluates @var{values-form}, which may return
+@defmac multiple-value-bind (var@dots{}) values-form forms@dots{}
+This macro evaluates @var{values-form}, which may return
multiple values. It then binds the @var{var}s to these respective values,
as if by @code{let}, and then executes the body @var{forms}.
If there are more @var{var}s than values, the extra @var{var}s
are bound to @code{nil}. If there are fewer @var{var}s than
values, the excess values are ignored.
-@end deffn
+@end defmac
-@deffn {Special Operator} multiple-value-setq (var@dots{}) form
-This special operator evaluates @var{form}, which may return multiple
+@defmac multiple-value-setq (var@dots{}) form
+This macro evaluates @var{form}, which may return multiple
values. It then sets the @var{var}s to these respective values, as if by
@code{setq}. Extra @var{var}s or values are treated the same as
in @code{multiple-value-bind}.
-@end deffn
+@end defmac
@deffn {Special Operator} multiple-value-call function forms@dots{}
This special operator evaluates function, discarding any multiple
@@ -767,10 +767,10 @@
infrastructure, treating multiple values as intercalated lists.
@end deffn
-@deffn {Special Operator} multiple-value-list form
-This special operator evaluates @var{form} and returns a list of the
+@defmac multiple-value-list form
+This macro evaluates @var{form} and returns a list of the
multiple values given by it.
-@end deffn
+@end defmac
@deffn {Special Operator} multiple-value-prog1 first body@dots{}
This special operator evaluates the form @var{first}, then the
@@ -779,12 +779,12 @@
@code{prog1} always discards multiple values.
@end deffn
-@deffn {Special Operator} nth-value n form
-This special operator evaluates @var{form} and returns the @var{n}th
+@defmac nth-value n form
+This macro evaluates @var{form} and returns the @var{n}th
value it gave. @var{n} must be an integer of value zero or more.
If @var{form} gave insufficient multiple values, @code{nth-value}
returns @code{nil}.
-@end deffn
+@end defmac
@defvar multiple-values-limit
This constant describes the exclusive upper bound on the number of
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/frames.texi
--- a/man/lispref/frames.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/frames.texi Tue Aug 09 17:17:44 2011 +0100
@@ -785,18 +785,18 @@
@code{focus-follows-mouse}.
@end defun
-@deffn {Special Operator} save-selected-frame forms@dots{}
-This special operator records the selected frame, executes @var{forms} in
+@defmac save-selected-frame forms@dots{}
+This macro records the selected frame, executes @var{forms} in
sequence, then restores the earlier selected frame. The value returned
is the value of the last form.
-@end deffn
+@end defmac
-@deffn {Special Operator} with-selected-frame frame forms@dots{}
-This special operator records the selected frame, then selects @var{frame}
+@defmac with-selected-frame frame forms@dots{}
+This macro records the selected frame, then selects @var{frame}
and executes @var{forms} in sequence. After the last form is finished,
the earlier selected frame is restored. The value returned is the value
of the last form.
-@end deffn
+@end defmac
@ignore (FSF Emacs, continued from defun select-frame)
XEmacs cooperates with the X server and the window managers by arranging
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/internationalization.texi
--- a/man/lispref/internationalization.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/internationalization.texi Tue Aug 09 17:17:44 2011 +0100
@@ -83,8 +83,8 @@
nothing.
@end defun
-@deffn {Special Operator} domain string
-This function specifies the text domain used for translating documentation
+@defmac domain string
+This macro specifies the text domain used for translating documentation
strings and interactive prompts of a function. For example, write:
@example
@@ -94,7 +94,7 @@
to specify @code{emacs-foo} as the text domain of the function @code{foo}.
The ``call'' to @code{domain} is actually a declaration rather than a
function; when actually called, @code{domain} just returns @code{nil}.
-@end deffn
+@end defmac
@defun domain-of function
This function returns the text domain of @var{function}; it returns
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/positions.texi
--- a/man/lispref/positions.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/positions.texi Tue Aug 09 17:17:44 2011 +0100
@@ -818,21 +818,21 @@
@code{save-current-buffer} is a primitive.
@end deffn
-@deffn {Special Operator} with-current-buffer buffer forms@dots{}
+@defmac with-current-buffer buffer forms@dots{}
This macro evaluates @var{forms} with @var{buffer} as the current
buffer. It returns the value of the last form.
-@end deffn
+@end defmac
-@deffn {Special Operator} with-temp-file filename forms@dots{}
+@defmac with-temp-file filename forms@dots{}
This macro creates a new buffer, evaluates @var{forms} there, and
writes the buffer to @var{filename}. It returns the value of the last form
evaluated.
-@end deffn
+@end defmac
-@deffn {Special Operator} save-selected-window forms@dots{}
+@defmac save-selected-window forms@dots{}
This macro is similar to @code{save-excursion} but it saves and
restores the selected window and nothing else.
-@end deffn
+@end defmac
@node Narrowing
@section Narrowing
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/searching.texi
--- a/man/lispref/searching.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/searching.texi Tue Aug 09 17:17:44 2011 +0100
@@ -1458,10 +1458,10 @@
You can save and restore the match data with @code{save-match-data}:
-@deffn {Special Operator} save-match-data body@dots{}
-This special operator executes @var{body}, saving and restoring the match
+@defmac save-match-data body@dots{}
+This macro executes @var{body}, saving and restoring the match
data around it.
-@end deffn
+@end defmac
Emacs automatically saves and restores the match data when it runs
process filter functions (@pxref{Filter Functions}) and process
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/specifiers.texi
--- a/man/lispref/specifiers.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/specifiers.texi Tue Aug 09 17:17:44 2011 +0100
@@ -875,7 +875,7 @@
@code{add-spec-list-to-specifier}.
@end defun
-@deffn {Special Operator} let-specifier specifier-list &rest body
+@defmac let-specifier specifier-list &rest body
This macro temporarily adds specifications to specifiers,
evaluates forms in @var{body} and restores the specifiers to their
previous states. The specifiers and their temporary specifications are
@@ -912,7 +912,7 @@
(let-specifier ((modeline-shadow-thickness 0 (selected-window)))
(sit-for 1))
@end example
-@end deffn
+@end defmac
@defun set-specifier specifier value &optional locale tag-set how-to-add
This function adds some specifications to @var{specifier}. @var{value}
diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/windows.texi
--- a/man/lispref/windows.texi Mon Aug 08 23:10:47 2011 +0900
+++ b/man/lispref/windows.texi Tue Aug 09 17:17:44 2011 +0100
@@ -442,12 +442,12 @@
@end example
@end defun
-@deffn {Special Operator} save-selected-window forms@dots{}
+@defmac save-selected-window forms@dots{}
This macro records the selected window, executes @var{forms} in
sequence, then restores the earlier selected window. It does not save
or restore anything about the sizes, arrangement or contents of windows;
therefore, if the @var{forms} change them, the changes are permanent.
-@end deffn
+@end defmac
@cindex finding windows
The following functions choose one of the windows on the screen,
@@ -1969,7 +1969,7 @@
@end example
@end defun
-@deffn {Special Operator} save-window-excursion forms@dots{}
+@defmac save-window-excursion forms@dots{}
This macro records the window configuration, executes @var{forms}
in sequence, then restores the earlier window configuration. The window
configuration includes the value of point and the portion of the buffer
@@ -2005,7 +2005,7 @@
;; @r{The frame is now split again.}
@end group
@end example
-@end deffn
+@end defmac
@defun window-configuration-p object
This function returns @code{t} if @var{object} is a window configuration.
--
‘Iodine deficiency was endemic in parts of the UK until, through what has been
described as “an unplanned and accidental public health triumph”, iodine was
added to cattle feed to improve milk production in the 1930s.’
(EN Pearce, Lancet, June 2011)
_______________________________________________
XEmacs-Patches mailing list
XEmacs-Patches(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-patches