Re: [PATCH]: Re: Early backtrace.

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 3 Feb 2022 21:35:26 +0000
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > 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.

It might be a misunderstanding on my part, caused by your particular
choice of words:

>  (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.

What do you mean by "should be" here?  Is that something the user
should arrange for, or does this already happen?  If the latter, why
"should"?

> +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.

"Typically" means it is, or can be, also called in other cases?  What
are those?

> -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."

When you say "intended for use" and "intended to produce", it sounds
like users should do something to benefit from this "intended use".
If, instead, you mean that this feature is activated automatically in
some circumstances, then I suggest to reword this to describe the
feature from that perspective: when it is activated and what it
provides when activated.

Bottom line, I still miss some higher-level overview of this feature,
which should probably go into the Commentary section of the file.

Thanks.