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.

5 files changed, 16 insertions, 2 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index cbbf9127235..6f27e71b7b7 100644
--- 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 0d6aaff81c5..edf60dd5cc8 100644
--- 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 b4c3b001d16..39fdefeb8f0 100644
--- 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 738fe6d37be..6743a537744 100644
--- 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 6709ebf0d02..e3cc4b05f3f 100644
--- 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\"."