Re: Redisplay hook error backtraces

[Alan Mackenzie <acm@muc.de>]

Hello, everybody.

I know that there are technical issues in the code still to be thrashed
out, but the new backtrace facility needs documentation.  I've written
some and a proposed patch (for debugging.texi and NEWS) is below.

I've come to see that `backtrace-on-redisplay-lisp-error', although
accurate, is too much of a mouthful, and I think it needs shortening.
Would anybody object to me just calling this variable `debug-redisplay'?

Also, I think that writing the backtrace into *Backtrace* is a bad idea,
now.  Users expect such a buffer to have active facilities, whereas the
new backtrace is just a dead dump.  Is there any objection to me instead
calling the buffer something like "*Redisplay-trace*"?



diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 058c931954..3f9c9fea50 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -77,6 +77,7 @@ Debugger
 
 @menu
 * Error Debugging::       Entering the debugger when an error happens.
+* Debugging Redisplay::   Getting backtraces from redisplay hook errors.
 * Infinite Loops::        Stopping and debugging a program that doesn't exit.
 * Function Debugging::    Entering it when a certain function is called.
 * Variable Debugging::    Entering it when a variable is modified.
@@ -105,6 +106,10 @@ Error Debugging
 (The command @code{toggle-debug-on-error} provides an easy way to do
 this.)
 
+Note that, for technical reasons, you cannot use the facilities
+defined in this subsection to debug errors in hooks the redisplay code
+has invoked.  @xref{Debugging Redisplay} for help with these.
+
 @defopt debug-on-error
 This variable determines whether the debugger is called when an error
 is signaled and not handled.  If @code{debug-on-error} is @code{t},
@@ -213,6 +218,52 @@ Error Debugging
 bypasses the @code{condition-case} which normally catches errors in the
 init file.
 
+@node Debugging Redisplay
+@subsection Debugging Redisplay Hooks
+@cindex redisplay hooks
+@cindex debugging redisplay hooks
+
+When a Lisp error occurs in a hook function which redisplay has
+invoked, you cannot use Emacs's usual debugging mechanisms, for
+technical reasons.  This subsection describes how to get a backtrace
+from such an error, information which should be helpful in debugging
+it.
+
+Note that if you have had such an error, the error handling will
+likely have removed the function causing it from its hook.  You will
+thus need to reinitialize that hook somehow, perhaps with
+@code{add-hook}, to be able to replay the bug.
+
+The hooks which these directions apply to are the following:
+@enumerate
+@item
+@code{fontification-functions} (@pxref{Auto Faces}).
+@item
+@code{set-message-function} (@pxref{Displaying Messages}).
+@item
+@code{clear-message-function} (@pxref{Displaying Messages}).
+@item
+@code{pre-redisplay-function} (@pxref{Forcing Redisplay}).
+@item
+@code{pre-redisplay-functions} (@pxref{Forcing Redisplay}).
+@item
+@code{menu-bar-update-hook} (@pxref{Menu Bar}).
+@item
+@code{window-scroll-functions} (@pxref{Window Hooks}).
+@end enumerate
+
+To generate a backtrace in these circumstances, set the variable
+@code{backtrace-on-redisplay-lisp-error} to non-@code{nil}.  When the
+error occurs, Emacs will dump the backtrace to the buffer
+@file{*Backtrace*}.  This buffer is not automatically displayed in a
+window; you will need to display it yourself, with a command such as
+@code{switch-to-buffer-other-frame} (@key{C-x 5 b}).
+
+@defvar backtrace-on-redisplay-lisp-error
+Set this variable to non-@code{nil} to enable the generation of a
+backtrace when errors occur in any of the above hooks.
+@end defvar
+
 @node Infinite Loops
 @subsection Debugging Infinite Loops
 @cindex infinite loops
diff --git a/etc/NEWS b/etc/NEWS
index c2900b0bc4..0196d55306 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1227,6 +1227,13 @@ When invoked with a non-zero prefix argument, as in 'C-u C-x C-e',
 this command will pop up a new buffer and show the full pretty-printed
 value there.
 
++++
+*** It is now possible to generate a backtrace from errors in redisplay
+hooks.  To do this, set the new variable
+'backtrace-on-redisplay-lisp-error' to a non-nil value.  The backtrace
+will be written to buffer *Backtrace*, but this buffer will not be
+automatically displayed in a window.
+
 ** Compile
 
 +++


-- 
Alan Mackenzie (Nuremberg, Germany).