From 38868ad716a4d33a81fbaeea17fc0ee64616252c Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 10 Nov 2012 16:37:40 -0800 Subject: [PATCH] Document new error symbol and function user-error * doc/lispref/control.texi (Signaling Errors): * doc/lispref/debugging.texi (Error Debugging): * doc/lispref/errors.texi (Standard Errors): Add user-error. * etc/NEWS: Related markup. --- doc/lispref/ChangeLog | 4 ++++ doc/lispref/control.texi | 13 +++++++++++++ doc/lispref/debugging.texi | 12 ++++++------ doc/lispref/errors.texi | 3 +++ etc/NEWS | 1 + 5 files changed, 27 insertions(+), 6 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 9dd833a4328..bc48f74401f 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,9 @@ 2012-11-11 Glenn Morris + * control.texi (Signaling Errors): + * debugging.texi (Error Debugging): + * errors.texi (Standard Errors): Add user-error. + * variables.texi (Adding Generalized Variables): Use standard formatting for common lisp note about setf functions. diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index cf393b59c49..489e5cc5b22 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -824,6 +824,19 @@ The function @code{signal} never returns. @end example @end defun +@cindex user errors, signaling +@defun user-error format-string &rest args +This function behaves exactly like @code{error}, except that it uses +the error symbol @code{user-error} rather than @code{error}. As the +name suggests, this is intended to report errors on the part of the +user, rather than errors in the code itself. For example, +if you try to use the command @code{Info-history-back} (@kbd{l}) to +move back beyond the start of your Info browsing history, Emacs +signals a @code{user-error}. Such errors do not cause entry to the +debugger, even when @code{debug-on-error} is non-@code{nil}. +@xref{Error Debugging}. +@end defun + @cindex CL note---no continuable errors @quotation @b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 2226db942d1..74000c2ba66 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -117,12 +117,12 @@ has any of those condition symbols, or if the error message matches any of the regular expressions, then that error does not enter the debugger. -The normal value of this variable lists several errors that happen -often during editing but rarely result from bugs in Lisp programs. -However, ``rarely'' is not ``never''; if your program fails with an -error that matches this list, you may try changing this list to debug -the error. The easiest way is usually to set -@code{debug-ignored-errors} to @code{nil}. +The normal value of this variable includes @code{user-error}, as well +as several errors that happen often during editing but rarely result +from bugs in Lisp programs. However, ``rarely'' is not ``never''; if +your program fails with an error that matches this list, you may try +changing this list to debug the error. The easiest way is usually to +set @code{debug-ignored-errors} to @code{nil}. @end defopt @defopt eval-expression-debug-on-error diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index a57f74d6c86..b92fd9ed665 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -172,6 +172,9 @@ The message is @samp{Text is read-only}. This is a subcategory of @item undefined-color The message is @samp{Undefined color}. @xref{Color Names}. +@item user-error +The message is the empty string. @xref{Signaling Errors}. + @item void-function The message is @samp{Symbol's function definition is void}. @xref{Function Cells}. diff --git a/etc/NEWS b/etc/NEWS index 985bedf2960..6ab23a4239d 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -800,6 +800,7 @@ table, but with a different prefix. ** Debugger changes ++++ *** New error type and new function `user-error'. These do not trigger the debugger. -- 2.39.5