Document debug-on-event

* doc/lispref/debugging.texi (Error Debugging): Mention debug-on-event.
* doc/lispref/commands.texi (Misc Events): Mention sigusr1,2 and debugging.
* etc/NEWS: Related edit.

3 files changed, 13 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 54dbdb9c9b2..459ccf63372 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,8 @@
 2012-02-04  Glenn Morris  <rgm@gnu.org>
 
+        * debugging.texi (Error Debugging): Mention debug-on-event.
+        * commands.texi (Misc Events): Mention sigusr1,2 and debugging.
+
         * modes.texi (Running Hooks): Try to clarify with-wrapper-hook.
 
         * text.texi (Buffer Contents):
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index aff7a0c5f27..91e224a439f 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1696,6 +1696,7 @@ parameters are used to display the help-echo text are described in
 These events are generated when the Emacs process receives
 the signals @code{SIGUSR1} and @code{SIGUSR2}.  They contain no
 additional data because signals do not carry additional information.
+They can be useful for debugging (@pxref{Error Debugging}).
 
 To catch a user signal, bind the corresponding event to an interactive
 command in the @code{special-event-map} (@pxref{Active Keymaps}).
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 9466f21a563..a17fc60718b 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -148,6 +148,15 @@ enter the debugger.
 @code{debug-on-error} is @code{nil}.
 @end defopt
 
+@defopt debug-on-event
+If you set @code{debug-on-event} to a special event (@pxref{Special
+Events}), Emacs will try to enter the debugger as soon as it receives
+this event, bypassing @code{special-event-map}.  At present, the only
+supported values correspond to the signals @code{SIGUSR1} and
+@code{SIGUSR2}.  This can be helpful when @code{inhibit-quit} is set
+and Emacs is not otherwise responding.
+@end defopt
+
   To debug an error that happens during loading of the init
 file, use the option @samp{--debug-init}.  This binds
 @code{debug-on-error} to @code{t} while loading the init file, and