bug#67455: Record source position, etc., in doc strings, and use this in *Help* and backtraces.

[Alan Mackenzie <acm@muc.de>]

Hello, Stefan and Eli.

On Sun, Nov 26, 2023 at 14:30:25 +0000, Alan Mackenzie wrote:
> Hello, Emacs.

> The reasons for this bug and the ways to solve it have been discussed
> extensively in the thread for bug#66750.

> We will, in functions' and macros' doc strings record the file name and
> position of the source code, and possibly other items, in a machine
> parseable format (which has yet to be decided).

> This is particularly intended for lambda functions, which currently
> appear in backtraces and *Help* buffers with insufficient information to
> identify them.  These displays will be enhanced to identify these lambda
> functions satisfactorally.

> The functions in Emacs which currently use doc strings will be modified
> so as not to be negatively affected by the new information written into
> them.

I've committed the first stage of this implementation in the new git
branch feature/positioned-lambdas.

It creates for compiled functions (but not yet for interpreted ones) doc
strings starting with a specially formatted string containing the
defining symbol, the source file name, the position of the defining
symbol in the file, and the position of the lambda (should we be in one)
in the file.

To instruct a defining macro to set a defining-symbol, it is only
necessary to add a clause like (defining-symbol 1) or (defining-symbol
(if (consp struct) (car struct) struct)) to the macro's declare form.
This is how defun now works.  (Thank you Stefan for the handy "cl.el
feature" in byte-run--parse-declarations.  ;-)

I scanned our Lisp code for debug-spec &define keywords, and added
defining-symbol declare clauses to (most of) the ones I found.

As yet, no use is made of the new position information (beyond stripping
it off for other uses of the doc string).

> -- 
> Alan Mackenzie (Nuremberg, Germany).