Subject: Re: bug#60568: [FR] 30.0.50; Help buffers and function bodies for generated functions

From: Ihor Radchenko <[email-masked]>
Date: Thu, 05 Jan 2023 08:20:21 +0000

Eli Zaretskii <[email-masked]> writes:

>> Would it be possible to provide function body info via *Help* system in
>> Emacs?
>
> Provide how?

For example, clicking source code link for function without definition
may display a new separate buffer with function body stored in the
function symbol.

> You basically ignore the valid objections voiced against such a
> feature, and present a specific case where (a) the source code is
> extremely short, and (b) the existing Help facilities are less than
> helpful because they have a deficiency.  How does it follow from the
> specific use case you present that we must show the source code in
> Help buffers?

Sorry, I did not imply that the function body will be _displayed_ in
*Help* buffers. Just accessible via some means.

As an alternative to my above suggestion, the function body might be
displayed upon clicking on some button in help buffer. Maybe using
outlines to fold/unfold the definition as necessary.

(BTW, don't *Help* buffer already suffer from too long variable values
being displayed? I don't mean it as an argument to add function body -
rather pointing that we might want some ideas how to deal with long
sexps displayed in *Help*)

> An alternative solution would be to teach Help
> functions to find the place where the source code is generated and let
> users examine that if they want.  I could even argue that this
> alternative is better, because with your proposal we will show a
> source code that doesn't actually exist anywhere in the form we show
> it.

Yes, for the particular use case I mentioned here. But how? I do not see
any obvious ways how to know where the function was generated unless
`defun' stores some extra auxiliary information when defining a
function.

> If we do decide to show the source code in some circumstances, we need
> to do that selectively and in a way that doesn't display unnecessarily
> large Help buffers that would then run the risk of "drowning" useful
> information, making it easy to miss.  So any such proposal should
> suggest how to avoid the downsides, at least.

I agree that too long function bodies, similar to too long variable
values are objectively degrading readability.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>