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

From: Stefan Monnier <[email-masked]>
Date: Mon, 04 Dec 2023 17:59:46 -0500

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

I think if it comes from a buffer (and one that's not associated with
a file, to boot), it's usually not byte-compiled, so I suspect you'll be
better off confining that handling to the interpreted case.

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

I'm having a hard time imagining why you'd need two positions.  Instead,
I want to go to *the* position, which should be "the best we can come up with".
And that's also what `byte-compile-warn-x` wants and it has access to
the same information.

IOW if you think you can do better for lambdas-with-pos, then please try
and retro fit it into `byte-compile-warn-x`.

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

(defining-symbol N) is nice as well.

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

Yup.  It's even worse, because at this stage I don't think anyone
truly understands its semantics.

[ I just wish we had a "similar" DSL that served /all/ those purposes,
  i.e. would let the macro writer express where the docstring is (if any),
  where the defining names are, how to indent each part, how to instrument
  each part, ...
  And of course, with a well-defined and well-understood semantics,
  a simple implementation (that works efficiently for all those uses),
  and a simple&concise syntax.
  Oh and while at it, it would also be used during macro-expansion to
  provide meaningful error messages when the macro is used
  incorrectly.
  Clearly, [Fortifying macros](https://dl.acm.org/doi/10.1145/1863543.1863577)
  can provide useful inspiration.  ]

        Stefan