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

[Alan Mackenzie <acm@muc.de>]

Hello, Stefan.

On Mon, Dec 04, 2023 at 16:56:41 -0500, Stefan Monnier wrote:
> >> Why include the file name?  Presumably we will rely on a `(FILE . POS)`
> >> to find that docstring so including FILE in there is rather redundant
> >> (and in addition to that, this file name can be wrong if it's absolute
> >> since files often get moved between compilation and use).
> > No, the (FILE . POS) is the .elc file, the one I'm putting into the new
> > info is the source file.

> Until now, Emacs has always lived with the `.elc` file names (e.g. in
> `load-history`) and managed to find the corresponding `.el` file (when
> you try to jump to the source via `M-.` or by clicking in `C-h f`).
> It comes with its share of problems, but we've learned to live with them.

Yes.  I've come to the same conclusion in the last hour or so that, no
doubt, early Emacs hackers reached forty years ago.  We can find the
..elc full filename from load-history (via symbol-file), but there's no
more useful way of finding the corresponding source than removing the
'c' from the end of foo.elc.  And if it's not there, it's nowhere.

> Is there any reason you think this new functionality should go through
> the extra trouble to record the `.el` name (and thus develop its own
> set of workarounds for the cases where the `.el` doesn't live where we
> think it should)?

Not any more, having thought it through.

Maybe, though, it would be useful in some circumstances to record the
buffer the definition was loaded from if it's not a file.  But it's
getting rather late here, so I haven't thought this through at all.

> >> > the position of the defining symbol in the file, and the position of
> >> > the lambda (should we be in one) in the file.
> >> Why two positions?
> >> Why not use the same position info as used in `byte-compile-warn-x`?
> > I'm not sure, yet, but I suspect both positions will be useful.

> Can you give an example scenario?

Something about a lambda form, when we need to find the lambda itself,
but also its containing form.  Sorry I can't be more definite, yet.
When I start hacking out the code to use all this information, it will
become clearer what we actually need.  It's very easy to change at this
stage.

> >> > or (defining-symbol (if (consp struct) (car struct) struct))
> >> [ Haven't seen that yet.  ]
> > Have a look at cl-defgeneric and cl-defmethod in cl-generic.el.

> Ah, got it.  I like the way you can refer to args by name.
> So I guess all the (defining-symbol 1) could similarly be replaced with
> (defining-symbol THE-ARG-NAME).

Yes, I hadn't really thought of that.  But (defining-symbol 1) matches
similar forms like (docstring 3) which are used somewhere.

> [ I also notice that this extension is somewhat incompatible with the
>   use I proposed for `font-lock`.  :-(  ]

> [ As you noted, this info is also related to the `&define` debug spec.
>   I wish we could unify that information.  ]

Ah, the debug spec; yet another difficult domain specific language.  ;-(

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).