Re: [PATCH]: Re: Early backtrace.

[Alan Mackenzie]

Hello, Eli.

On Thu, Feb 03, 2022 at 10:38:08 +0200, Eli Zaretskii wrote:
> > From: Stefan Monnier <monnier@iro.umontreal.ca>
> > Cc: emacs-devel@gnu.org
> > Date: Wed, 02 Feb 2022 15:59:14 -0500

> > > OK.  I've now committed this change.

> > Yay!

> How about adding to debug-early.el some minimal documentation, which
> would explain how to use this facility for debugging bootstrap
> problems and batch-mode problems in general?  The doc strings you,
> Alan, provided don't describe the context and the intended use in any
> level of useful detail.

I'm not sure entirely what's needed here, probably because I've been
working a lot at this level for quite a long time.

Still, I've tried to imporve the level of detail, and come up with this.
Comments and criticism are welcome, as always:



diff --git a/lisp/emacs-lisp/debug-early.el b/lisp/emacs-lisp/debug-early.el
index 718000bfa4..aeb8e8f1b2 100644
--- a/lisp/emacs-lisp/debug-early.el
+++ b/lisp/emacs-lisp/debug-early.el
@@ -60,14 +60,20 @@ 'debug-early-backtrace
 
 (defalias 'debug-early
   #'(lambda (&rest args)
-  "Print a trace of Lisp function calls currently active.
+  "Print an error message with a backtrace of active Lisp function calls.
 The output stream used is the value of `standard-output'.
 
-There should be two ARGS, the symbol `error' and a cons of
-the error symbol and its data.
+There should be two ARGS: the symbol `error' (which is ignored)
+and a cons of the error symbol and the error data.
+
+This is a simplified version of `debug', intended to produce
+diagnostics to help in debugging the early parts of the build
+process.  It is typically called by the Emacs core when an error
+is signaled.
 
-This is a simplified version of `debug', intended for use
-in debugging the early parts of the build process."
+`debug-early' is the default value of the symbol `debugger'
+before enough Lisp has been loaded to support `debug' itself, and
+in batch mode."
   (princ "\nError: ")
   (prin1 (car (car (cdr args))))       ; The error symbol.
   (princ " ")


-- 
Alan Mackenzie (Nuremberg, Germany).