xemacs-beta: man/lispref/control.texi comparison

comparison man/lispref/control.texi @ 5361:62b9ef1ed4ac

Change "special form" to "special operator" in the manuals, too 2011-03-01 Aidan Kehoe <kehoea@parhasard.net> * 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.

author	Aidan Kehoe <kehoea@parhasard.net>
date	Tue, 01 Mar 2011 14:18:45 +0000
parents	755ae5b97edb
children	9fae6227ede5

comparison

equal deleted inserted replaced

-:f5a5501814f5
+:62b9ef1ed4ac
 Many other control structures likewise contain an implicit @code{progn}.
 As a result, @code{progn} is not used as often as it used to be.  It is
 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.
 @example
 @group
 @print{} "The second form"
 @print{} "The third form"
 @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}.
 @example
 @group
 @code{x}, then return the value of that former element:
 @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}.
 @example
 @print{} "The second form"
 @print{} "The third form"
 @result{} "The second form"
 @end group
 @end example
-@end defspec
+@end deffn
 @node Conditionals
 @section Conditionals
 @cindex conditional evaluation
 Conditional control structures choose among alternatives.  XEmacs Lisp
 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.
 Otherwise, the @var{else-forms} are evaluated in textual order, and the
 value of the last one is returned.  (The @var{else} part of @code{if} is
 (print 'true)
 'very-false)
 @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
 @var{body-forms}.  Thus, a clause looks like this:
 @end example
 @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.
 For example:
 @code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise.
 The function @code{not} is identical to @code{null}, and we recommend
 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.
 If any of the @var{conditions} evaluates to @code{nil}, then the result
 (if @var{arg1} (if @var{arg2} @var{arg3}))
 @equiv{}
 (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.
 If any of the @var{conditions} evaluates to a non-@code{nil} value, then
 @noindent
 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
 @cindex iteration
 @cindex recursion
 Iteration means executing part of a program repetitively.  For
 example, you might want to repeat some computation once for each element
 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
 evaluates @var{forms} again.  This process repeats until @var{condition}
 evaluates to @code{nil}.
 @noindent
 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
 @cindex nonlocal exits
 chronologically after entry to the @code{catch}, and chronologically
 before exit from it, it has access to that @code{catch}.  This is why
 @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
+@deffn {Special Operator} catch tag body@dots{}
-@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{}
 @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},
 which may be any Lisp object.  The argument @var{tag} is evaluated normally
 before the return point is established.
 the @code{catch}.
 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
 established with @code{catch}.  The argument @var{tag} is used to choose
 among the various existing return points; it must be @code{eq} to the value
 @code{catch}, but they are entirely separate facilities.  An error
 cannot be caught by a @code{catch}, and a @code{throw} cannot be handled
 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
 @code{condition-case} form; in this case, the @code{condition-case} has
 no effect.  The @code{condition-case} form makes a difference when an
 the file name is the second element of @var{data}---the third element of
 @var{var}.
 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
 that results from dividing by zero.  The handler prints out a warning
 message and returns a very large number.
 The @code{unwind-protect} construct is essential whenever you
 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
 @cindex unwinding
 @code{unwind-protect} executes the @var{body} with a guarantee that the
 with another @code{unwind-protect} around that form.
 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:
 @smallexample

Mercurial > hg > xemacs-beta

comparison man/lispref/control.texi @ 5361:62b9ef1ed4ac