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.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 9dd833a43289e9bd00de132b586978e1946464f6..bc48f74401fd033af5e4b6e06a5d48a1bda3a9ec 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,9 @@
 2012-11-11  Glenn Morris  <rgm@gnu.org>
 
+       * 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 cf393b59c4969e5a8ea76074ab6effe8680e1984..489e5cc5b22f15741f0840a63c1c0cb195c11ff5 100644 (file)
--- 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 2226db942d1e0c4c861f6a5804ba921a3bfb9db1..74000c2ba66483fab68b6448d8cce7c821c2f4b1 100644 (file)
--- 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 a57f74d6c860a9722e9c4d67d95ede908abcbef7..b92fd9ed665fb4c549ec588d788587c94d8dfa4f 100644 (file)
--- 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 985bedf2960e06393824f96e13325965c6256f4e..6ab23a4239d89ca069aa00f012aaee9eb1af9cde 100644 (file)
--- 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.