* lisp/subr.el (define-error): New function.

* doc/lispref/control.texi (Signaling Errors): Refer to define-error.
(Error Symbols): Add `define-error'.
* doc/lispref/errors.texi (Standard Errors): Don't refer to `error-conditions'.
* lisp/progmodes/ada-xref.el (ada-error-file-not-found): Rename from
error-file-not-found and define with define-error.
* lisp/emacs-lisp/cl-lib.el (cl-assertion-failed): Move here from subr.el
and define with define-error.
* lisp/userlock.el (file-locked, file-supersession):
* lisp/simple.el (mark-inactive):
* lisp/progmodes/js.el (js-moz-bad-rpc, js-js-error):
* lisp/progmodes/ada-mode.el (ada-mode-errors):
* lisp/play/life.el (life-extinct):
* lisp/nxml/xsd-regexp.el (xsdre-invalid-regexp, xsdre-parse-error):
* lisp/nxml/xmltok.el (xmltok-markup-declaration-parse-error):
* lisp/nxml/rng-util.el (rng-error):
* lisp/nxml/rng-uri.el (rng-uri-error):
* lisp/nxml/rng-match.el (rng-compile-error):
* lisp/nxml/rng-cmpct.el (rng-c-incorrect-schema):
* lisp/nxml/nxml-util.el (nxml-error, nxml-file-parse-error):
* lisp/nxml/nxml-rap.el (nxml-scan-error):
* lisp/nxml/nxml-outln.el (nxml-outline-error):
* lisp/net/soap-client.el (soap-error):
* lisp/net/gnutls.el (gnutls-error):
* lisp/net/ange-ftp.el (ftp-error):
* lisp/mpc.el (mpc-proc-error):
* lisp/json.el (json-error, json-readtable-error, json-unknown-keyword)
(json-number-format, json-string-escape, json-string-format)
(json-key-format, json-object-format):
* lisp/jka-compr.el (compression-error):
* lisp/international/quail.el (quail-error):
* lisp/international/kkc.el (kkc-error):
* lisp/emacs-lisp/ert.el (ert-test-failed):
* lisp/calc/calc.el (calc-error, inexact-result, math-overflow)
(math-underflow):
* lisp/bookmark.el (bookmark-error-no-filename):
* lisp/epg.el (epg-error): Define with define-error.

3 files changed, 36 insertions, 37 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 0aac5235a29..611badcbaa0 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2013-08-09  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* errors.texi (Standard Errors): Don't refer to `error-conditions'.
+
+	* control.texi (Signaling Errors): Refer to define-error.
+	(Error Symbols): Add `define-error'.
+
 2013-08-06  Dmitry Antipov  <dmantipov@yandex.ru>
 
 	* positions.texi (Motion by Screen Lines):
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 9ee01299260..b68f3184394 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -890,9 +890,8 @@ argument @var{data} is a list of additional Lisp objects relevant to
 the circumstances of the error.
 
 The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
-bearing a property @code{error-conditions} whose value is a list of
-condition names.  This is how Emacs Lisp classifies different sorts of
-errors. @xref{Error Symbols}, for a description of error symbols,
+defined with @code{define-error}.  This is how Emacs Lisp classifies different
+sorts of errors. @xref{Error Symbols}, for a description of error symbols,
 error conditions and condition names.
 
 If the error is not handled, the two arguments are used in printing
@@ -1118,8 +1117,8 @@ Here are examples of handlers:
 @end example
 
 Each error that occurs has an @dfn{error symbol} that describes what
-kind of error it is.  The @code{error-conditions} property of this
-symbol is a list of condition names (@pxref{Error Symbols}).  Emacs
+kind of error it is, and which describes also a list of condition names
+(@pxref{Error Symbols}).  Emacs
 searches all the active @code{condition-case} forms for a handler that
 specifies one or more of these condition names; the innermost matching
 @code{condition-case} handles the error.  Within this
@@ -1259,6 +1258,7 @@ should be robust if one does occur.  Note that this macro uses
 @cindex condition name
 @cindex user-defined error
 @kindex error-conditions
+@kindex define-error
 
   When you signal an error, you specify an @dfn{error symbol} to specify
 the kind of error you have in mind.  Each error has one and only one
@@ -1275,42 +1275,37 @@ Thus, each error has one or more condition names: @code{error}, the
 error symbol if that is distinct from @code{error}, and perhaps some
 intermediate classifications.
 
-  In order for a symbol to be an error symbol, it must have an
-@code{error-conditions} property which gives a list of condition names.
-This list defines the conditions that this kind of error belongs to.
-(The error symbol itself, and the symbol @code{error}, should always be
-members of this list.)  Thus, the hierarchy of condition names is
-defined by the @code{error-conditions} properties of the error symbols.
-Because quitting is not considered an error, the value of the
-@code{error-conditions} property of @code{quit} is just @code{(quit)}.
+@defun define-error name message &optional parent
+  In order for a symbol to be an error symbol, it must be defined with
+@code{define-error} which takes a parent condition (defaults to @code{error}).
+This parent defines the conditions that this kind of error belongs to.
+The transitive set of parents always includes the error symbol itself, and the
+symbol @code{error}.  Because quitting is not considered an error, the set of
+parents of @code{quit} is just @code{(quit)}.
 
 @cindex peculiar error
-  In addition to the @code{error-conditions} list, the error symbol
-should have an @code{error-message} property whose value is a string to
-be printed when that error is signaled but not handled.  If the
-error symbol has no @code{error-message} property or if the
-@code{error-message} property exists, but is not a string, the error
-message @samp{peculiar error} is used.  @xref{Definition of signal}.
+  In addition to its parents, the error symbol has a var{message} which
+is a string to be printed when that error is signaled but not handled.  If that
+message is not valid, the error message @samp{peculiar error} is used.
+@xref{Definition of signal}.
+
+Internally, the set of parents is stored in the @code{error-conditions}
+property of the error symbol and the message is stored in the
+@code{error-message} property of the error symbol.
 
   Here is how we define a new error symbol, @code{new-error}:
 
 @example
 @group
-(put 'new-error
-     'error-conditions
-     '(error my-own-errors new-error))
-@result{} (error my-own-errors new-error)
-@end group
-@group
-(put 'new-error 'error-message "A new error")
-@result{} "A new error"
+(define-error 'new-error "A new error" 'my-own-errors)
 @end group
 @end example
 
 @noindent
-This error has three condition names: @code{new-error}, the narrowest
+This error has several condition names: @code{new-error}, the narrowest
 classification; @code{my-own-errors}, which we imagine is a wider
-classification; and @code{error}, which is the widest of all.
+classification; and all the conditions of @code{my-own-errors} which should
+include @code{error}, which is the widest of all.
 
   The error string should start with a capital letter but it should
 not end with a period.  This is for consistency with the rest of Emacs.
@@ -1326,7 +1321,7 @@ your code can do this:
 @end group
 @end example
 
-  This error can be handled through any of the three condition names.
+  This error can be handled through any of its condition names.
 This example handles @code{new-error} and any other errors in the class
 @code{my-own-errors}:
 
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index 87cfcfa532c..8a10fbf0c47 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -7,12 +7,11 @@
 @appendix Standard Errors
 @cindex standard errors
 
-  Here is a list of the more important error symbols in standard Emacs,
-grouped by concept.  The list includes each symbol's message (on the
-@code{error-message} property of the symbol) and a cross reference to a
-description of how the error can occur.
+  Here is a list of the more important error symbols in standard Emacs, grouped
+by concept.  The list includes each symbol's message and a cross reference
+to a description of how the error can occur.
 
-  Each error symbol has an @code{error-conditions} property that is a
+  Each error symbol has an set of parent error conditions that is a
 list of symbols.  Normally this list includes the error symbol itself
 and the symbol @code{error}.  Occasionally it includes additional
 symbols, which are intermediate classifications, narrower than
@@ -24,8 +23,6 @@ conditions, that means it has none.
   As a special exception, the error symbol @code{quit} does not have the
 condition @code{error}, because quitting is not considered an error.
 
-@c You can grep for "(put 'foo 'error-conditions ...) to find
-@c examples defined in Lisp.  E.g., soap-client.el, sasl.el.
   Most of these error symbols are defined in C (mainly @file{data.c}),
 but some are defined in Lisp.  For example, the file @file{userlock.el}
 defines the @code{file-locked} and @code{file-supersession} errors.