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.

4 files changed, 26 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  <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 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}.