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

[Arthur Miller <arthur.miller@live.com>]

martin rudalics <rudalics@gmx.at> writes:

>>>> It would be nice to make it fit to N lines in height, and C columns in width,
>>>> i.e. to make it fit to certain size.
>>>
>>> Who would specify that "certain size"?
>> User, of course, who else? We put some default size and a defcuctom for user to
>> change, as always?
>
> Do you mean "one size fits all"?
Of course not :).

I said "user", because I meant an user should have the final word. I just said in
short words that there should be a defcustom variable for users to customize the
default value. But also every value that is in use, has to have some default
value to start with, no? I didn't proposed a hadcoded literal, I proposed a
defcustom variable, so users can set this their liking.

>> Let's
>> have a face lift for built in help for 28. I am sure we could debate for years
>> and always someone will like it differently. Let's have something that works.
>
> That something will take its time to be written.  Certainly not before
> Emacs 28 comes out.
>
>> I  haven't read the other thread, but I have used help and why I think it is
>> good, and some other have as well.
>
> There are two threads and I think you should read them if you plan to
> change anything in this area.
>
>> Can you try what I send in yesterday, with soucre view toggle? I think it works
>> quite nice (I did a misstake and went 1 row too far when deleting, but that's a
>> trivial to fix).
>
> Compiling it tells me
>
> ../../lisp/help-mode.el:530:22: Warning: the function
>     ‘find-function-advised-original’ is not known to be defined.
>
> so it should require 'find-func'.  A few remarks:
Thank you for spotting that one! I used to have it in fetch-c-src, but than I
removed it, and than refactored that code from 'find-function-C-source' but
forgott that it might require find-func.

> +(defcustom help-mode-inline-source nil
> +  "Display inlined source code for SYMBOL in `help-mode' buffer.
>
> What is SYMBOL here?

Current symbol in the help buffer. There is always a 'current symbol' in the
help buffer, as I understand the implementation, the one that help was asked
about. I can reword the docs. I have tried to be short as possible so it fits in
one line. I see also now that it shoudl at least be 'the SYMBOL', but I can
probably just skip "for SYMBOL" completely.

> +  "Find C source code for a Lisp symbol in a `file'.
> +
> +sym is the symbol to find.
> +type is the type as obtained by 'describe-*' functions.
> +file is the source file to search in."
>
> Arguments should be uppercase and not hyphenated.

Ok, thank you, I wasn't thinking about that one. I'll fix that of course.

> +             (with-no-warnings (font-lock-fontify-buffer)))
>
> Do you know how long it takes to fontify xdisp.c?  With a non-optimized
> build, C-h v for 'scroll-minibuffer-conservatively' takes more than 10
> seconds here.
I would't be surprised. I try to do as little work as possible: only function
oor defvar in question is fontified, so xdisp.c will never get fontified all at
once in this context. If that would still be problematic for low-level CPUs I
can of course do this optionally as well, with another defcustom.

I am really concerned with efficiency; I always am. I really like Helpful, and I
am not the only one, it is a popular library. What is problem is that it
does not use any built-in functionality but provides everything from scratch. It
has complete implementation of a help buffer on its own. So it is a dubble
functionality when I import it. I like it's implementation too, it is simpler
than built-in help infrastructure. So I hoped to get it into Emacs, and let old
help die out :). It won't happen so the next best thing is to re-implement Helpful
in terms of Emacs built-in features, i.e. bring Helpful features (not the source
code) to built-in *Help* buffers. At least some of them.

> Other than that I can only say that this is _one_ possible option for
> showing the source of the code.  BTW, we should decide on a suitable
> interface for 'help-toggle-source-view' probably using the button for
> showing the code.

Yes, I had my thoughts to propertize the "Source Code:" string in help buffer to
act similar as other link (or buttons as they are called in Emacs), but I just
haven't got to that yet. Also until there is any decision to use
'help-toggle-source-view' as an API, it can wait for a bit; but generally yes,
it should be another help-xref button.

I have also explicitly coded it so it can be used from any buffer, so user does
not need to switch to a help buffer to toggle the source view on/off. I see it
as a feature that help does not switch my cursor to help buffer by default :).

Thank you for your input Martin, that was really helpful. Some pun unavaoided
here :).