Re: Patch proposal: display symbol source code in help buffers

[Arthur Miller]

Stefan Kangas <stefankangas@gmail.com> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> I haven't tried the patch, but this is for showing the source code of
>> the function/variable in question in the *Help* buffer?

Yes, that is a feature of Helpful. We had some discussion last week, which I
started by asking if we can get Helpful in i Emacs. I thought to have Helpful as
"advanced" help enabled in Emacs as-is, but some peopel expressed that would be
better to refactor it. Also, when looking at Helfpul sources it would some
refactoring to reomve dependency on some external libraries. Since Helfpul does
not use Emacs help-mode buffer, and nothing of built-in help-mode infrastructure
but implements everythin on it's own, I am of opinion that it takes less effort
to implement comparable features from scratch. Helpful author(s) have also not
said anything, either for or against, I cc:d willfred when I posted on the mail
list. 

>>                                                          I'm not quite
>> sure I understand the utility of that

To me it has been useful when I was learning, it still is; it is kind of nice to
be able to see the code together with the docs. It also makes, at least me, more
inclined to look at the sources when it is thrown at my face directly to see
what is going on, than if I have to take extra action to look at the sources.

>> sure I understand the utility of that -- if you want to look at the
>> source, you can just hit the `s' key.  And then you get all the proper
>> language-related Emacs stuff in that buffer -- looking at sources is
>> usually nicer in the correct major mode than in other buffers.

Yes, I agree that it is easy to hit 's' key. Often I would like to see functions
called in a function, and it that case I would anyway open the source file. But
there are cases when it is good enough to just glimpse through the source and
confirm what is going on. Most of the times I don't want to look at the source
at all, but if it is already there, I am actually more inclined to look at the
source than if it wasn't there.

Another feature compared to Helfpul (or anti-feature, depends whom you ask), is
that built-in help does not focus the help buffer, while Helpful shifts
focus. Many time I just want to glimpse on the source to confirm if my
understanding is correct, and I will maybe scroll other buffer (I like
two-buffer setup), so I prefer my cursor not to jump over to help buffer every
time as it does with helpful.

>> So I don't understand who'd want this.

People who are used to Helpful; people not used to Elisp at all, 

> I believe this is a feature in helpful.el:
>
> https://github.com/Wilfred/helpful/blob/master/screenshots/helpful_source.png
>
> FWIW, I personally also ask myself why/how this is useful.  Is it
> because some users don't know that you can get to the source code?
>
> That said, I don't see any reason not to have this as an optional
> feature, if some users find that it works well for them.

Of course, this can be/is cpu intensive so it should always be an opt-in
feature. I have put in a defcustom to enable/disable this, and it is nil by
default. I think that my implementation is slightly more effective than one in
Helpful, but that would be just very slightly, and probably does not matter when
it comes to compressed sources which have to be decompressed to be shown.