commit: Change "special form" to "special operator" in the manuals, too

ClamAV 0.96 changeset: 5361:62b9ef1ed4ac parent: 5359:f5a5501814f5 user: Aidan Kehoe <kehoea(a)parhasard.net&gt; date: Tue Mar 01 14:18:45 2011 +0000 files: man/ChangeLog man/cl.texi man/lispref/commands.texi man/lispref/compile.texi man/lispref/control.texi man/lispref/display.texi man/lispref/eval.texi man/lispref/frames.texi man/lispref/functions.texi man/lispref/internationalization.texi man/lispref/intro.texi man/lispref/lists.texi man/lispref/macros.texi man/lispref/positions.texi man/lispref/searching.texi man/lispref/sequences.texi man/lispref/specifiers.texi man/lispref/variables.texi man/lispref/windows.texi description: Change "special form" to "special operator" in the manuals, too 2011-03-01 Aidan Kehoe <kehoea(a)parhasard.net&gt; * lispref/commands.texi (Using Interactive): * lispref/compile.texi (Eval During Compile): * lispref/compile.texi (Compiled-Function Objects): * lispref/control.texi (Sequencing): * lispref/control.texi (Conditionals): * lispref/control.texi (Combining Conditions): * lispref/control.texi (Iteration): * lispref/control.texi (Catch and Throw): * lispref/control.texi (Handling Errors): * lispref/control.texi (Cleanups): * lispref/display.texi (Temporary Displays): * lispref/eval.texi (Quoting): * lispref/eval.texi (Multiple values): * lispref/frames.texi (Input Focus): * lispref/functions.texi (Argument List): * lispref/functions.texi (Defining Functions): * lispref/functions.texi (Anonymous Functions): * lispref/internationalization.texi (Level 3 Primitives): * lispref/internationalization.texi (Domain Specification): * lispref/intro.texi (A Sample Function Description): * lispref/intro.texi (A Sample Variable Description): * lispref/lists.texi (Sets And Lists): * lispref/macros.texi (Defining Macros): * lispref/macros.texi (Backquote): * lispref/positions.texi (Excursions): * lispref/positions.texi (Narrowing): * lispref/searching.texi (Saving Match Data): * lispref/sequences.texi (Sequence Functions): * lispref/sequences.texi (Array Functions): * lispref/specifiers.texi (Adding Specifications): * lispref/variables.texi (Local Variables): * lispref/variables.texi (Defining Variables): * lispref/variables.texi (Setting Variables): * lispref/variables.texi (Default Value): * lispref/windows.texi (Selecting Windows): * lispref/windows.texi (Window Configurations): No longer use ＠defspec, since we no longer use the term "special form"; instead use ＠deffn {Special Operator}. Unfortunately there's no way in texinfo to redefine ＠defspec in one place. diff -r f5a5501814f5 -r 62b9ef1ed4ac man/ChangeLog --- a/man/ChangeLog Sat Feb 19 11:03:46 2011 +0000 +++ b/man/ChangeLog Tue Mar 01 14:18:45 2011 +0000 ＠＠ -1,3 +1,69 ＠＠ +2011-03-01 Aidan Kehoe <kehoea(a)parhasard.net&gt; + + * lispref/commands.texi (Using Interactive): + * lispref/compile.texi (Eval During Compile): + * lispref/compile.texi (Compiled-Function Objects): + * lispref/control.texi (Sequencing): + * lispref/control.texi (Conditionals): + * lispref/control.texi (Combining Conditions): + * lispref/control.texi (Iteration): + * lispref/control.texi (Catch and Throw): + * lispref/control.texi (Handling Errors): + * lispref/control.texi (Cleanups): + * lispref/display.texi (Temporary Displays): + * lispref/eval.texi (Quoting): + * lispref/eval.texi (Multiple values): + * lispref/frames.texi (Input Focus): + * lispref/functions.texi (Argument List): + * lispref/functions.texi (Defining Functions): + * lispref/functions.texi (Anonymous Functions): + * lispref/internationalization.texi (Level 3 Primitives): + * lispref/internationalization.texi (Domain Specification): + * lispref/intro.texi (A Sample Function Description): + * lispref/intro.texi (A Sample Variable Description): + * lispref/lists.texi (Sets And Lists): + * lispref/macros.texi (Defining Macros): + * lispref/macros.texi (Backquote): + * lispref/positions.texi (Excursions): + * lispref/positions.texi (Narrowing): + * lispref/searching.texi (Saving Match Data): + * lispref/sequences.texi (Sequence Functions): + * lispref/sequences.texi (Array Functions): + * lispref/specifiers.texi (Adding Specifications): + * lispref/variables.texi (Local Variables): + * lispref/variables.texi (Defining Variables): + * lispref/variables.texi (Setting Variables): + * lispref/variables.texi (Default Value): + * lispref/windows.texi (Selecting Windows): + * lispref/windows.texi (Window Configurations): + No longer use ＠defspec, since we no longer use the term "special + form"; instead use ＠deffn {Special Operator}. Unfortunately + there's no way in texinfo to redefine ＠defspec in one place. + +2011-03-01 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): + 2011-02-19 Aidan Kehoe <kehoea(a)parhasard.net&gt; * lispref/lists.texi (Sets And Lists): diff -r f5a5501814f5 -r 62b9ef1ed4ac man/cl.texi --- a/man/cl.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/cl.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -381,14 +381,14 ＠＠ Instead, this package defines alternates for several Lisp forms which you must use if you need Common Lisp argument lists. -＠defspec defun* name arglist body... +＠deffn {Special Operator} 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 defspec - -＠defspec defsubst* name arglist body... +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec defmacro* name arglist body... +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec function* symbol-or-lambda +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn 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. -＠defspec eval-when (situations...) forms... +＠deffn {Special Operator} 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 defspec +＠end deffn 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. -＠defspec eval-when-compile forms... +＠deffn {Special Operator} 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 defspec - -＠defspec load-time-value form +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠node Function Aliases, , Time of Evaluation, Program Structure ＠section Function Aliases ＠＠ -869,7 +869,7 ＠＠ error. ＠end defun -＠defspec deftype name arglist forms... +＠deffn {Special Operator} 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 defspec +＠end deffn 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. -＠defspec psetq [symbol form]＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec setf [place form]＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec psetf [place form]＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec incf place &optional x +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec decf place &optional x +＠end deffn + +＠deffn {Special Operator} decf place &optional x This macro decrements the number stored in ＠var{place} by one, or by ＠var{x} if specified. -＠end defspec - -＠defspec pop place +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec push x place +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec pushnew x place ＠t{&key :test :test-not :key} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec shiftf place＠dots{} newvalue +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec rotatef place＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn The following macros were invented for this package; they have no analogues in Common Lisp. -＠defspec letf (bindings＠dots{}) forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec letf* (bindings＠dots{}) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec callf ＠var{function} ＠var{place} ＠var{args}＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec callf2 ＠var{function} ＠var{arg1} ＠var{place} ＠var{args}＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn 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. -＠defspec define-modify-macro name arglist function [doc-string] +＠deffn {Special Operator} 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 defspec - -＠defspec defsetf access-fn update-fn +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec defsetf access-fn arglist (store-var) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec define-setf-method access-fn arglist forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec progv symbols values forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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: -＠defspec lexical-let (bindings＠dots{}) forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec lexical-let* (bindings＠dots{}) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec flet (bindings＠dots{}) forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec labels (bindings＠dots{}) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠node Macro Bindings, , Function Bindings, Variable Bindings ＠subsection Macro Bindings ＠＠ -1856,7 +1856,7 ＠＠ ＠noindent These forms create local macros and ``symbol macros.'' -＠defspec macrolet (bindings＠dots{}) forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec symbol-macrolet (bindings＠dots{}) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec when test forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec unless test forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec case keyform clause＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec ecase keyform clause＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec typecase keyform clause＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec etypecase keyform clause＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec block name forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec return-from name [result] +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec return [result] +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec loop forms＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec do (spec＠dots{}) (end-test [result＠dots{}]) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec do* (spec＠dots{}) (end-test [result＠dots{}]) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec dolist (var list [result]) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec dotimes (var count [result]) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec do-symbols (var [obarray [result]]) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec do-all-symbols (var [result]) forms＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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. -＠defspec loop clauses＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn 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: -＠defspec destructuring-bind arglist expr forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn 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. -＠defspec define-compiler-macro name arglist forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠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 -＠defspec declaim decl-specs＠dots{} +＠deffn {Special Operator} 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 defspec - -＠defspec declare decl-specs＠dots{} +＠end deffn + +＠deffn {Special Operator} 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 defspec - -＠defspec locally declarations＠dots{} forms＠dots{} +＠end deffn + +＠deffn {Special Operator} locally declarations＠dots{} forms＠dots{} In this package, ＠code{locally} is no different from ＠code{progn}. -＠end defspec - -＠defspec the type form +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn 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 -＠defspec remf place property +＠deffn {Special Operator} 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 defspec +＠end deffn ＠iftex ＠secno=2 ＠＠ -4677,7 +4677,7 ＠＠ implements structures as vectors (or lists upon request) with a special ``tag'' symbol to identify them. -＠defspec defstruct name slots＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn 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. -＠defspec assert test-form [show-args string args＠dots{}] +＠deffn {Special Operator} 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 defspec - -＠defspec check-type place type &optional string +＠end deffn + +＠deffn {Special Operator} 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 defspec +＠end deffn The following error-related macro is also defined: -＠defspec ignore-errors forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top ＠appendix Efficiency Concerns diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/commands.texi --- a/man/lispref/commands.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/commands.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -120,7 +120,7 ＠＠ This section describes how to write the ＠code{interactive} form that makes a Lisp function an interactively-callable command. -＠defspec interactive arg-descriptor +＠deffn {Special Operator} interactive arg-descriptor ＠cindex argument descriptors This special operator declares that the function in which it appears is a command, and that it may therefore be called interactively (via ＠＠ -139,7 +139,7 ＠＠ ＠code{interactive} form are executed, but at this time ＠code{interactive} simply returns ＠code{nil} without even evaluating its argument. -＠end defspec +＠end deffn There are three possibilities for the argument ＠var{arg-descriptor}: diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/compile.texi --- a/man/lispref/compile.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/compile.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -691,7 +691,7 ＠＠ These features permit you to write code to be evaluated during compilation of a program. -＠defspec eval-and-compile body +＠deffn {Special Operator} 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 defspec +＠end deffn -＠defspec eval-when-compile body +＠deffn {Special Operator} 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 defspec +＠end deffn ＠node Compiled-Function Objects ＠section Compiled-Function Objects diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/control.texi --- a/man/lispref/control.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/control.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -76,7 +76,7 ＠＠ needed now most often inside an ＠code{unwind-protect}, ＠code{and}, ＠code{or}, or in the ＠var{then}-part of an ＠code{if}. -＠defspec progn forms＠dots{} +＠deffn {Special Operator} progn forms＠dots{} This special operator evaluates all of the ＠var{forms}, in textual order, returning the result of the final form. ＠＠ -91,12 +91,12 ＠＠ ＠result{} "The third form" ＠end group ＠end example -＠end defspec +＠end deffn Two other control constructs likewise evaluate a series of forms but return a different value: -＠defspec prog1 form1 forms＠dots{} +＠deffn {Special Operator} prog1 form1 forms＠dots{} This special operator evaluates ＠var{form1} and all of the ＠var{forms}, in textual order, returning the result of ＠var{form1}. ＠＠ -118,9 +118,9 ＠＠ ＠example (prog1 (car x) (setq x (cdr x))) ＠end example -＠end defspec +＠end deffn -＠defspec prog2 form1 form2 forms＠dots{} +＠deffn {Special Operator} prog2 form1 form2 forms＠dots{} This special operator evaluates ＠var{form1}, ＠var{form2}, and all of the following ＠var{forms}, in textual order, returning the result of ＠var{form2}. ＠＠ -136,7 +136,7 ＠＠ ＠result{} "The second form" ＠end group ＠end example -＠end defspec +＠end deffn ＠node Conditionals ＠section Conditionals ＠＠ -146,7 +146,7 ＠＠ has two conditional forms: ＠code{if}, which is much the same as in other languages, and ＠code{cond}, which is a generalized case statement. -＠defspec if condition then-form else-forms＠dots{} +＠deffn {Special Operator} if condition then-form else-forms＠dots{} ＠code{if} chooses between the ＠var{then-form} and the ＠var{else-forms} based on the value of ＠var{condition}. If the evaluated ＠var{condition} is non-＠code{nil}, ＠var{then-form} is evaluated and the result returned. ＠＠ -169,9 +169,9 ＠＠ ＠result{} very-false ＠end group ＠end example -＠end defspec +＠end deffn -＠defspec cond clause＠dots{} +＠deffn {Special Operator} cond clause＠dots{} ＠code{cond} chooses among an arbitrary number of alternatives. Each ＠var{clause} in the ＠code{cond} must be a list. The ＠sc{car} of this list is the ＠var{condition}; the remaining elements, if any, the ＠＠ -239,7 +239,7 ＠＠ ＠noindent This expression is a ＠code{cond} which returns ＠code{foo} if the value of ＠code{a} is 1, and returns the string ＠code{"default"} otherwise. -＠end defspec +＠end deffn Any conditional construct can be expressed with ＠code{cond} or with ＠code{if}. Therefore, the choice between them is a matter of style. ＠＠ -268,7 +268,7 ＠＠ using the name ＠code{null} if you are testing for an empty list. ＠end defun -＠defspec and conditions＠dots{} +＠deffn {Special Operator} and conditions＠dots{} The ＠code{and} special operator tests whether all the ＠var{conditions} are true. It works by evaluating the ＠var{conditions} one by one in the order written. ＠＠ -320,9 +320,9 ＠＠ (cond (＠var{arg1} (cond (＠var{arg2} ＠var{arg3})))) ＠end group ＠end example -＠end defspec +＠end deffn -＠defspec or conditions＠dots{} +＠deffn {Special Operator} or conditions＠dots{} The ＠code{or} special operator tests whether at least one of the ＠var{conditions} is true. It works by evaluating all the ＠var{conditions} one by one in the order written. ＠＠ -369,7 +369,7 ＠＠ This is not completely equivalent because it can evaluate ＠var{arg1} or ＠var{arg2} twice. By contrast, ＠code{(or ＠var{arg1} ＠var{arg2} ＠var{arg3})} never evaluates any argument more than once. -＠end defspec +＠end deffn ＠node Iteration ＠section Iteration ＠＠ -381,7 +381,7 ＠＠ of a list, or once for each integer from 0 to ＠var{n}. You can do this in XEmacs Lisp with the special operator ＠code{while}: -＠defspec while condition forms＠dots{} +＠deffn {Special Operator} while condition forms＠dots{} ＠code{while} first evaluates ＠var{condition}. If the result is non-＠code{nil}, it evaluates ＠var{forms} in textual order. Then it reevaluates ＠var{condition}, and if the result is non-＠code{nil}, it ＠＠ -427,7 +427,7 ＠＠ This moves forward one line and continues moving by lines until it reaches an empty. It is unusual in that the ＠code{while} has no body, just the end test (which also does the real work of moving point). -＠end defspec +＠end deffn ＠node Nonlocal Exits ＠section Nonlocal Exits ＠＠ -499,15 +499,7 ＠＠ ＠code{throw} can be used in commands such as ＠code{exit-recursive-edit} that throw back to the editor command loop (＠pxref{Recursive Editing}). -＠cindex CL note---only ＠code{throw} in Emacs -＠quotation -＠b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, -have several ways of transferring control nonsequentially: ＠code{return}, -＠code{return-from}, and ＠code{go}, for example. XEmacs Lisp has only -＠code{throw}. -＠end quotation - -＠defspec catch tag body＠dots{} +＠deffn {Special Operator} catch tag body＠dots{} ＠cindex tag on run time stack ＠code{catch} establishes a return point for the ＠code{throw} function. The return point is distinguished from other such return points by ＠var{tag}, ＠＠ -522,7 +514,7 ＠＠ If a ＠code{throw} is done within ＠var{body} specifying the same value ＠var{tag}, the ＠code{catch} exits immediately; the value it returns is whatever was specified as the second argument of ＠code{throw}. -＠end defspec +＠end deffn ＠defun throw tag value The purpose of ＠code{throw} is to return from a return point previously ＠＠ -1028,7 +1020,7 ＠＠ by an error handler (though using ＠code{throw} when there is no suitable ＠code{catch} signals an error that can be handled). -＠defspec condition-case var protected-form handlers＠dots{} +＠deffn {Special Operator} condition-case var protected-form handlers＠dots{} This special operator establishes the error handlers ＠var{handlers} around the execution of ＠var{protected-form}. If ＠var{protected-form} executes without error, the value it returns becomes the value of the ＠＠ -1077,7 +1069,7 ＠＠ If ＠var{var} is ＠code{nil}, that means no variable is bound. Then the error symbol and associated data are not available to the handler. -＠end defspec +＠end deffn ＠cindex ＠code{arith-error} example Here is an example of using ＠code{condition-case} to handle the error ＠＠ -1252,7 +1244,7 ＠＠ temporarily put a data structure in an inconsistent state; it permits you to ensure the data are consistent in the event of an error or throw. -＠defspec unwind-protect body cleanup-forms＠dots{} +＠deffn {Special Operator} unwind-protect body cleanup-forms＠dots{} ＠cindex cleanup forms ＠cindex protected forms ＠cindex error cleanup ＠＠ -1278,7 +1270,7 ＠＠ The number of currently active ＠code{unwind-protect} forms counts, together with the number of local variable bindings, against the limit ＠code{max-specpdl-size} (＠pxref{Local Variables}). -＠end defspec +＠end deffn For example, here we make an invisible buffer for temporary use, and make sure to kill it before finishing: diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/display.texi --- a/man/lispref/display.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/display.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -720,7 +720,7 ＠＠ and then present it to the user for perusal rather than for editing. Many of the help commands use this feature. -＠defspec with-output-to-temp-buffer buffer-name forms＠dots{} +＠deffn {Special Operator} with-output-to-temp-buffer buffer-name forms＠dots{} This function executes ＠var{forms} while arranging to insert any output they print into the buffer named ＠var{buffer-name}. The buffer is then shown in some window for viewing, displayed but not selected. ＠＠ -760,7 +760,7 ＠＠ ---------- Buffer: foo ---------- ＠end group ＠end example -＠end defspec +＠end deffn ＠defvar temp-buffer-show-function If this variable is non-＠code{nil}, ＠code{with-output-to-temp-buffer} diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/eval.texi --- a/man/lispref/eval.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/eval.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -663,9 +663,9 ＠＠ not necessary to quote self-evaluating objects such as numbers, strings, and vectors.) -＠defspec quote object +＠deffn {Special Operator} quote object This special operator returns ＠var{object}, without evaluating it. -＠end defspec +＠end deffn ＠cindex ＠samp{'} for quoting ＠cindex quoting using apostrophe ＠＠ -743,48 +743,48 ＠＠ values. ＠end defun -＠defspec multiple-value-bind (var＠dots{}) values-form forms＠dots{} +＠deffn {Special Operator} multiple-value-bind (var＠dots{}) values-form forms＠dots{} This special operator 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 defspec +＠end deffn -＠defspec multiple-value-setq (var＠dots{}) form +＠deffn {Special Operator} multiple-value-setq (var＠dots{}) form This special operator 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 defspec +＠end deffn -＠defspec multiple-value-call function forms＠dots{} +＠deffn {Special Operator} multiple-value-call function forms＠dots{} This special operator evaluates function, discarding any multiple values. It then evaluates ＠var{forms}, preserving any multiple values, and calls ＠var{function} as a function with the results. Conceptually, this function is a version of ＠code{apply'}that by-passes the multiple values infrastructure, treating multiple values as intercalated lists. -＠end defspec +＠end deffn -＠defspec multiple-value-list form +＠deffn {Special Operator} multiple-value-list form This special operator evaluates ＠var{form} and returns a list of the multiple values given by it. -＠end defspec +＠end deffn -＠defspec multiple-value-prog1 first body＠dots{} +＠deffn {Special Operator} multiple-value-prog1 first body＠dots{} This special operator evaluates the form ＠var{first}, then the forms ＠var{body}. It returns the value given by ＠var{first}, preserving any multiple values. This is identical to ＠code{prog1}, except that ＠code{prog1} always discards multiple values. -＠end defspec +＠end deffn -＠defspec nth-value n form +＠deffn {Special Operator} nth-value n form This special operator 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 defspec +＠end deffn ＠defvar multiple-values-limit This constant describes the exclusive upper bound on the number of diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/frames.texi --- a/man/lispref/frames.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/frames.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -785,18 +785,18 ＠＠ ＠code{focus-follows-mouse}. ＠end defun -＠defspec save-selected-frame forms＠dots{} +＠deffn {Special Operator} save-selected-frame forms＠dots{} This special operator 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 defspec +＠end deffn -＠defspec with-selected-frame frame forms＠dots{} +＠deffn {Special Operator} with-selected-frame frame forms＠dots{} This special operator 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 defspec +＠end deffn ＠ignore (FSF Emacs, continued from defun select-frame) XEmacs cooperates with the X server and the window managers by arranging diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/functions.texi --- a/man/lispref/functions.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/functions.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -337,8 +337,9 ＠＠ ＠cindex CL note---default optional arg ＠quotation ＠b{Common Lisp note:} Common Lisp allows the function to specify what -default value to use when an optional argument is omitted; XEmacs Lisp -always uses ＠code{nil}. +default value to use when an optional argument is omitted; this is +available in XEmacs Lisp with the ＠code{defun*} macro, an alternative to +＠code{defun}. ＠end quotation For example, an argument list that looks like this: ＠＠ -474,7 +475,7 ＠＠ is called ＠dfn{defining a function}, and it is done with the ＠code{defun} special operator. -＠defspec defun name argument-list body-forms +＠deffn {Special Operator} defun name argument-list body-forms ＠code{defun} is the usual way to define new Lisp functions. It defines the symbol ＠var{name} as a function that looks like this: ＠＠ -543,7 +544,7 ＠＠ without any hesitation or notification. Redefining a function already defined is often done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition. -＠end defspec +＠end deffn ＠defun define-function name definition ＠defunx defalias name definition ＠＠ -833,14 +834,14 ＠＠ In such cases, we usually use the special operator ＠code{function} instead of simple quotation to quote the anonymous function. -＠defspec function function-object +＠deffn {Special Operator} function function-object ＠cindex function quoting This special operator returns ＠var{function-object} without evaluating it. In this, it is equivalent to ＠code{quote}. However, it serves as a note to the XEmacs Lisp compiler that ＠var{function-object} is intended to be used only as a function, and therefore can safely be compiled. Contrast this with ＠code{quote}, in ＠ref{Quoting}. -＠end defspec +＠end deffn Using ＠code{function} instead of ＠code{quote} makes a difference inside a function or macro that you are going to compile. For example: diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/internationalization.texi --- a/man/lispref/internationalization.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/internationalization.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -83,7 +83,7 ＠＠ nothing. ＠end defun -＠defspec domain string +＠deffn {Special Operator} domain string This function specifies the text domain used for translating documentation strings and interactive prompts of a function. For example, write: ＠＠ -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 defspec +＠end deffn ＠defun domain-of function This function returns the text domain of ＠var{function}; it returns ＠＠ -145,19 +145,19 ＠＠ For variables and constants which have documentation strings, specify the domain after the documentation. -＠defspec defvar symbol [value [doc-string [domain]]] +＠deffn {Special Operator} defvar symbol [value [doc-string [domain]]] Example: ＠example (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") ＠end example -＠end defspec +＠end deffn -＠defspec defconst symbol [value [doc-string [domain]]] +＠deffn {Special Operator} defconst symbol [value [doc-string [domain]]] Example: ＠example (defconst limbs 4 "Number of limbs" "emacs-gorilla") ＠end example -＠end defspec +＠end deffn ＠defun autoload function filename &optional docstring interactive type This function defines ＠var{function} to autoload from ＠var{filename} diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/intro.texi --- a/man/lispref/intro.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/intro.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -787,7 +787,7 ＠＠ arguments. Parentheses are used when several arguments are grouped into additional levels of list structure. Here is an example: -＠defspec count-loop (＠var{var} [＠var{from} ＠var{to} [＠var{inc}]]) ＠var{body}＠dots{} +＠deffn {Special Operator} count-loop (＠var{var} [＠var{from} ＠var{to} [＠var{inc}]]) ＠var{body}＠dots{} This imaginary special operator implements a loop that executes the ＠var{body} forms and then increments the variable ＠var{var} on each iteration. On the first iteration, the variable has the value ＠＠ -817,7 +817,7 ＠＠ ＠var{inc} may optionally be specified as well. These arguments are grouped with the argument ＠var{var} into a list, to distinguish them from ＠var{body}, which includes all remaining elements of the form. -＠end defspec +＠end deffn ＠node A Sample Variable Description ＠subsubsection A Sample Variable Description diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/lists.texi --- a/man/lispref/lists.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/lists.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -1271,7 +1271,7 ＠＠ ＠end example In the following example, the ＠code{(4)} that ＠code{remove*} attempts to match -and the ＠code{(4)} in the ＠code{sample-list} are not ＠code{eq}: +and the ＠code{(4)} in the ＠code{sample-list} are not ＠code{eql}: ＠example ＠group diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/macros.texi --- a/man/lispref/macros.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/macros.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -212,7 +212,7 ＠＠ In practice, almost all Lisp macros have names, and they are usually defined with the special operator ＠code{defmacro}. -＠defspec defmacro name argument-list body-forms＠dots{} +＠deffn {Special Operator} defmacro name argument-list body-forms＠dots{} ＠code{defmacro} defines the symbol ＠var{name} as a macro that looks like this: ＠＠ -229,7 +229,7 ＠＠ (＠pxref{Argument List}). Macros may have a documentation string, but any ＠code{interactive} declaration is ignored since macros cannot be called interactively. -＠end defspec +＠end deffn ＠node Backquote ＠section Backquote diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/positions.texi --- a/man/lispref/positions.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/positions.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -766,7 +766,7 ＠＠ described elsewhere (see ＠ref{Window Configurations} and ＠pxref{Frame Configurations}). -＠defspec save-excursion forms＠dots{} +＠deffn {Special Operator} save-excursion forms＠dots{} ＠cindex mark excursion ＠cindex point excursion ＠cindex current buffer excursion ＠＠ -810,29 +810,29 ＠＠ (set-marker (mark-marker) old-mark))) ＠end group ＠end example -＠end defspec +＠end deffn -＠defspec save-current-buffer forms＠dots{} +＠deffn {Special Operator} save-current-buffer forms＠dots{} This special operator is similar to ＠code{save-excursion} but it only saves and restores the current buffer. Beginning with XEmacs 20.3, ＠code{save-current-buffer} is a primitive. -＠end defspec +＠end deffn -＠defspec with-current-buffer buffer forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn -＠defspec with-temp-file filename forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn -＠defspec save-selected-window forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠node Narrowing ＠section Narrowing ＠＠ -893,7 +893,7 ＠＠ ＠var{buffer} defaults to the current buffer if omitted. ＠end deffn -＠defspec save-restriction body＠dots{} +＠deffn {Special Operator} save-restriction body＠dots{} This special operator saves the current bounds of the accessible portion, evaluates the ＠var{body} forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly ＠＠ -972,4 +972,4 ＠＠ ---------- Buffer: foo ---------- ＠end group ＠end example -＠end defspec +＠end deffn diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/searching.texi --- a/man/lispref/searching.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/searching.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -1458,10 +1458,10 ＠＠ You can save and restore the match data with ＠code{save-match-data}: -＠defspec save-match-data body＠dots{} +＠deffn {Special Operator} save-match-data body＠dots{} This special operator executes ＠var{body}, saving and restoring the match data around it. -＠end defspec +＠end deffn Emacs automatically saves and restores the match data when it runs process filter functions (＠pxref{Filter Functions}) and process diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/sequences.texi --- a/man/lispref/sequences.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/sequences.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -219,6 +219,44 ＠＠ ＠code{nth} (＠pxref{List Elements}). ＠end defun +＠defun fill sequence object ＠t{&key :start :end} +This function fills the sequence ＠var{sequence} with ＠var{object}, so +that each element of ＠var{sequence} between the indices specified by +＠code{:start} (inclusive) and ＠code{:end} (exclusive), is ＠var{object}. +It returns ＠var{sequence}. + +＠example +＠group +(setq a [a b c d e f g]) + ＠result{} [a b c d e f g] +(fill a 0 :end 2) + ＠result{} [0 0 c d e f g] +(fill a 0) + ＠result{} [0 0 0 0 0 0 0] +a + ＠result{} [0 0 0 0 0 0 0] +＠end group + +＠group +(setq s "When in the course") + ＠result{} "When in the course" +(fill s ?-) + ＠result{} "------------------" +＠end group + +＠group +(setq bv #*1101) + ＠result{} #*1101 +(fill bv 0) + ＠result{} #*0000 +＠end group +＠end example + +If ＠var{sequence} is of a type that cannot hold ＠var{object} ( +bit-vector can only hold the integers one or zero, strings can only hold +characters) a ＠code{wrong-type-argument} error results. +＠end defun + ＠node Arrays ＠section Arrays ＠cindex array ＠＠ -380,39 +418,6 ＠＠ ＠result{} 0 bv ＠result{} #*1101 -＠end group -＠end example - -If ＠var{array} is a string and ＠var{object} is not a character, a -＠code{wrong-type-argument} error results. -＠end defun - -＠defun fillarray array object -This function fills the array ＠var{array} with ＠var{object}, so that -each element of ＠var{array} is ＠var{object}. It returns ＠var{array}. - -＠example -＠group -(setq a [a b c d e f g]) - ＠result{} [a b c d e f g] -(fillarray a 0) - ＠result{} [0 0 0 0 0 0 0] -a - ＠result{} [0 0 0 0 0 0 0] -＠end group - -＠group -(setq s "When in the course") - ＠result{} "When in the course" -(fillarray s ?-) - ＠result{} "------------------" -＠end group - -＠group -(setq bv #*1101) - ＠result{} #*1101 -(fillarray bv 0) - ＠result{} #*0000 ＠end group ＠end example diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/specifiers.texi --- a/man/lispref/specifiers.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/specifiers.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -875,7 +875,7 ＠＠ ＠code{add-spec-list-to-specifier}. ＠end defun -＠defspec let-specifier specifier-list &rest body +＠deffn {Special Operator} 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 defspec +＠end deffn ＠defun set-specifier specifier value &optional locale tag-set how-to-add This function adds some specifications to ＠var{specifier}. ＠var{value} diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/variables.texi --- a/man/lispref/variables.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/variables.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -168,7 +168,7 ＠＠ The special operators ＠code{let} and ＠code{let*} exist to create local bindings. -＠defspec let (bindings＠dots{}) forms＠dots{} +＠deffn {Special Operator} let (bindings＠dots{}) forms＠dots{} This special operator binds variables according to ＠var{bindings} and then evaluates all of the ＠var{forms} in textual order. The ＠code{let}-form returns the value of the last form in ＠var{forms}. ＠＠ -196,9 +196,9 ＠＠ ＠result{} (1 2) ＠end group ＠end example -＠end defspec +＠end deffn -＠defspec let* (bindings＠dots{}) forms＠dots{} +＠deffn {Special Operator} let* (bindings＠dots{}) forms＠dots{} This special operator is like ＠code{let}, but it binds each variable right after computing its local value, before computing the local value for the next variable. Therefore, an expression in ＠var{bindings} can ＠＠ -218,7 +218,7 ＠＠ ＠result{} (1 1) ＠end group ＠end example -＠end defspec +＠end deffn Here is a complete list of the other facilities that create local bindings: ＠＠ -403,7 +403,7 ＠＠ files, and override the default values given in the definitions. For this reason, user options must be defined with ＠code{defvar}. -＠defspec defvar symbol [value [doc-string]] +＠deffn {Special Operator} defvar symbol [value [doc-string]] This special operator defines ＠var{symbol} as a value and initializes it. The definition informs a person reading your code that ＠var{symbol} is used as a variable that programs are likely to set or change. It is ＠＠ -491,9 +491,9 ＠＠ The ＠code{defvar} form returns ＠var{symbol}, but it is normally used at top level in a file where its value does not matter. -＠end defspec +＠end deffn -＠defspec defconst symbol [value [doc-string]] +＠deffn {Special Operator} defconst symbol [value [doc-string]] This special operator defines ＠var{symbol} as a value and initializes it. It informs a person reading your code that ＠var{symbol} has a global value, established here, that will not normally be changed or locally ＠＠ -530,7 +530,7 ＠＠ ＠result{} 3 ＠end group ＠end example -＠end defspec +＠end deffn ＠defun user-variable-p variable ＠cindex user option ＠＠ -615,7 +615,7 ＠＠ form ＠code{setq}. When you need to compute the choice of variable at run time, use the function ＠code{set}. -＠defspec setq [symbol form]＠dots{} +＠deffn {Special Operator} setq [symbol form]＠dots{} This special operator is the most common method of changing a variable's value. Each ＠var{symbol} is given a new value, which is the result of evaluating the corresponding ＠var{form}. The most-local existing ＠＠ -655,7 +655,7 ＠＠ ＠result{} 11 ＠end group ＠end example -＠end defspec +＠end deffn ＠defun set symbol value This function sets ＠var{symbol}'s value to ＠var{value}, then returns ＠＠ -1253,7 +1253,7 ＠＠ ＠code{symbol-value}. ＠end defun -＠defspec setq-default symbol value +＠deffn {Special Operator} setq-default symbol value This sets the default value of ＠var{symbol} to ＠var{value}. It does not evaluate ＠var{symbol}, but does evaluate ＠var{value}. The value of the ＠code{setq-default} form is ＠var{value}. ＠＠ -1314,7 +1314,7 ＠＠ ＠result{} another-default ＠end group ＠end example -＠end defspec +＠end deffn ＠defun set-default symbol value This function is like ＠code{setq-default}, except that ＠var{symbol} is diff -r f5a5501814f5 -r 62b9ef1ed4ac man/lispref/windows.texi --- a/man/lispref/windows.texi Sat Feb 19 11:03:46 2011 +0000 +++ b/man/lispref/windows.texi Tue Mar 01 14:18:45 2011 +0000 ＠＠ -442,12 +442,12 ＠＠ ＠end example ＠end defun -＠defspec save-selected-window forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠cindex finding windows The following functions choose one of the windows on the screen, ＠＠ -1969,7 +1969,7 ＠＠ ＠end example ＠end defun -＠defspec save-window-excursion forms＠dots{} +＠deffn {Special Operator} 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 defspec +＠end deffn ＠defun window-configuration-p object This function returns ＠code{t} if ＠var{object} is a window configuration. _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-patches