Doc updates for with-demoted-errors

* doc/lispref/control.texi (Handling Errors): Update with-demoted-errors.

* lisp/subr.el (with-demoted-errors): Doc fix.

* etc/NEWS: Related edit.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index cbbf91272350da9933060e5da244398c164d2092..6f27e71b7b740228804a8abf0105791bfcb6741c 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,7 @@
 2014-01-24  Glenn Morris  <rgm@gnu.org>
 
+       * control.texi (Handling Errors): Update with-demoted-errors.
+
        * files.texi (File Locks): Every platform supports locking now.
 
 2014-01-22  Glenn Morris  <rgm@gnu.org>

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 0d6aaff81c5619f53c1d44711293f32d21aec2be..edf60dd5cc8f1953aeb896cd3b8dc8f5af8b3685 100644 (file)
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1252,10 +1252,13 @@ Here's the example at the beginning of this subsection rewritten using
 @end example
 @end defmac
 
-@defmac with-demoted-errors body@dots{}
+@defmac with-demoted-errors format body@dots{}
 This macro is like a milder version of @code{ignore-errors}.  Rather
 than suppressing errors altogether, it converts them into messages.
-Use this form around code that is not expected to signal errors, but
+It uses the string @var{format} to format the message.
+@var{format} should contain a single @samp{%}-sequence; e.g.,
+@code{"Error: %S"}.  Use @code{with-demoted-errors} around code
+that is not expected to signal errors, but
 should be robust if one does occur.  Note that this macro uses
 @code{condition-case-unless-debug} rather than @code{condition-case}.
 @end defmac

diff --git a/etc/NEWS b/etc/NEWS
index b4c3b001d16dc23c2b006dc02f65cafe451ae54e..39fdefeb8f08947ab89ba3984280bf7efc27336e 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1080,6 +1080,7 @@ displaying the buffer in a window.
 +++
 *** New function `define-error'.
 
++++
 *** `with-demoted-errors' takes an additional argument `format'.
 
 +++

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 738fe6d37be31f5894448e70035809afc4ab922b..6743a537744135e5831475d91d30eb8f746365d5 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2014-01-24  Glenn Morris  <rgm@gnu.org>
+
+       * subr.el (with-demoted-errors): Doc fix.
+
 2014-01-23  Stefan Monnier  <monnier@iro.umontreal.ca>
 
        * emacs-lisp/cl-macs.el: Improve type->predicate mapping (bug#16520).

diff --git a/lisp/subr.el b/lisp/subr.el
index 6709ebf0d025a56217e8899493d4d05a1485dfb4..e3cc4b05f3f5db60b639940f81b256325ba19317 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3246,9 +3246,13 @@ even if this catches the signal."
 
 (defmacro with-demoted-errors (format &rest body)
   "Run BODY and demote any errors to simple messages.
+FORMAT is a string passed to `message' to format any error message.
+It should contain a single %-sequence; e.g., \"Error: %S\".
+
 If `debug-on-error' is non-nil, run BODY without catching its errors.
 This is to be used around code which is not expected to signal an error
 but which should be robust in the unexpected case that an error is signaled.
+
 For backward compatibility, if FORMAT is not a constant string, it
 is assumed to be part of BODY, in which case the message format
 used is \"Error: %S\"."