[COMMIT] Avoid calling various macros "special operators" in the manuals.

APPROVE COMMIT NOTE: This patch has been committed. # HG changeset patch # User Aidan Kehoe <kehoea(a)parhasard.net&gt; # 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&gt; * 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&gt; + + * 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&gt; * 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