* debugging.texi (Error Debugging): Don't mislead the reader into

[gnu-emacs] / doc / lispref / control.texi

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 1ff1f89cff2edd9918cfc3acb226fa084f427d14..41f844b4e217c5827559df4cbd8c66ac95fed0df 100644 (file)
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,

-@c   2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
+@c   2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/control
 @node Control Structures, Variables, Evaluation, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/control
 @node Control Structures, Variables, Evaluation, Top


@@ -15,6 +15,7 @@ We control the order of execution of these forms by enclosing them in
 control when, whether, or how many times to execute the forms they
 contain.
 
 control when, whether, or how many times to execute the forms they
 contain.
 

+@cindex textual order

   The simplest order of execution is sequential execution: first form
 @var{a}, then form @var{b}, and so on.  This is what happens when you
 write several forms in succession in the body of a function, or at top
   The simplest order of execution is sequential execution: first form
 @var{a}, then form @var{b}, and so on.  This is what happens when you
 write several forms in succession in the body of a function, or at top


@@ -803,7 +804,7 @@ error message is the @sc{car} of @var{data} (that must be a string).
 Subcategories of @code{file-error} are handled specially.
 
 The number and significance of the objects in @var{data} depends on
 Subcategories of @code{file-error} are handled specially.
 
 The number and significance of the objects in @var{data} depends on

-@var{error-symbol}.  For example, with a @code{wrong-type-arg} error,
+@var{error-symbol}.  For example, with a @code{wrong-type-argument} error,

 there should be two objects in the list: a predicate that describes the type
 that was expected, and the object that failed to fit that type.
 
 there should be two objects in the list: a predicate that describes the type
 that was expected, and the object that failed to fit that type.
 


@@ -891,7 +892,9 @@ establishing an error handler, with the special form
 
 @noindent
 This deletes the file named @var{filename}, catching any error and
 
 @noindent
 This deletes the file named @var{filename}, catching any error and

-returning @code{nil} if an error occurs.
+returning @code{nil} if an error occurs@footnote{
+Actually, you should use @code{ignore-errors} in such a simple case;
+see below.}.

 
   The @code{condition-case} construct is often used to trap errors that
 are predictable, such as failure to open a file in a call to
 
   The @code{condition-case} construct is often used to trap errors that
 are predictable, such as failure to open a file in a call to


@@ -1089,6 +1092,23 @@ including those signaled with @code{error}:
 @end group
 @end smallexample
 
 @end group
 @end smallexample
 

+@defmac ignore-errors body@dots{}
+This construct executes @var{body}, ignoring any errors that occur
+during its execution.  If the execution is without error,
+@code{ignore-errors} returns the value of the last form in @var{body};
+otherwise, it returns @code{nil}.
+
+Here's the example at the beginning of this subsection rewritten using
+@code{ignore-errors}:
+
+@smallexample
+@group
+  (ignore-errors
+   (delete-file filename))
+@end group
+@end smallexample
+@end defmac
+

 @node Error Symbols
 @subsubsection Error Symbols and Condition Names
 @cindex error symbol
 @node Error Symbols
 @subsubsection Error Symbols and Condition Names
 @cindex error symbol