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.

4 files changed, 16 insertions, 1 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
diff --git a/etc/NEWS b/etc/NEWS
index 1c9072d38af..67073cb1acf 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1403,7 +1403,9 @@ as well as those in the -*- line.
 
 ** keymaps can inherit from multiple parents.
 
-** `debug-on-event' lets you debug Emacs when stuck because of inhibit-quit.
++++
+** Set `debug-on-event' to make Emacs enter the debugger e.g. on receipt
+of SIGUSR1.  This can be useful when `inhibit-quit' is set.
 
 +++
 ** New reader macro ## which stands for the empty symbol.