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.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 54dbdb9..459ccf6 100644 (file)
--- 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 aff7a0c..91e224a 100644 (file)
--- 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 9466f21..a17fc60 100644 (file)
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -146,6 +146,15 @@ enter the debugger.
 
 @strong{Warning:} @code{debug-on-signal} has no effect when
 @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

diff --git a/etc/NEWS b/etc/NEWS
index 1c9072d..67073cb 100644 (file)
--- 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.