Question about xref and adding "find all references" button to built-in help

Question about xref and adding "find all references" button to built-in help

[Arthur Miller]

If I would like to add a link as there is one in Helpful, to find all references
for a current symbol in help-mode buffer; which xref functionality should I look
at? Is there a ready made function already, or do I have to write something?

Re: Question about xref and adding "find all references" button to built-in help

[Dmitry Gutov]

Hi!

On 19.09.2021 23:17, Arthur Miller wrote:
> If I would like to add a link as there is one in Helpful, to find all references
> for a current symbol in help-mode buffer; which xref functionality should I look
> at? Is there a ready made function already, or do I have to write something?

We have functionality to searching for references in the current project 
(also works when inside an Emacs sources checkout) and throughout the 
load-path.

But you probably want this to work in installed Emacs as well?

Re: Question about xref and adding "find all references" button to built-in help

[Arthur Miller]

[-- Attachment #1: Type: text/plain, Size: 1299 bytes --]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Hi!
>
> On 19.09.2021 23:17, Arthur Miller wrote:
>> If I would like to add a link as there is one in Helpful, to find all references
>> for a current symbol in help-mode buffer; which xref functionality should I look
>> at? Is there a ready made function already, or do I have to write something?
>
> We have functionality to searching for references in the current project (also
> works when inside an Emacs sources checkout) and throughout the load-path.

As extensive as helpful's help-ref? He searches through each and every source
file found in the load-path. Where do I look, can you give me some pointer I can
start playing with? Or should I do build my own search?

> But you probably want this to work in installed Emacs as well?

What do you mean by "installed Emacs"? Emacs without sources? Sorry, I just woke
up, have to get that coffein going up :).

What about to just have a keyboard shortcuts; say 'R', instead of link. With
source code displayed it already looks a bit crouded. I think helpfuls buffer
looks a bit busy with all the links.

I could imagine living with just a shortcut and maybe a context menu item.

I attached a screeshots of helpful and built-in help with my yserdays patch both
showing source code for the comparison.


[-- Attachment #2: helpful.png --]
[-- Type: image/png, Size: 177508 bytes --]

[-- Attachment #3: built-in-help.png --]
[-- Type: image/png, Size: 154371 bytes --]

Re: Question about xref and adding "find all references" button to built-in help

[Dmitry Gutov]

On 20.09.2021 08:47, Arthur Miller wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
>> Hi!
>>
>> On 19.09.2021 23:17, Arthur Miller wrote:
>>> If I would like to add a link as there is one in Helpful, to find all references
>>> for a current symbol in help-mode buffer; which xref functionality should I look
>>> at? Is there a ready made function already, or do I have to write something?
>>
>> We have functionality to searching for references in the current project (also
>> works when inside an Emacs sources checkout) and throughout the load-path.
> 
> As extensive as helpful's help-ref? He searches through each and every source
> file found in the load-path. Where do I look, can you give me some pointer I can
> start playing with? Or should I do build my own search?

That's just 'M-x xref-find-references'. Try it in an Elisp buffer.

The implementation is fairly simple: see 'xref-backend-references' in 
xref.el and elisp-load-path-roots.

For your own backend, you will probably not dispatch through project.el 
method, and use load-path directly combined with package-user-dir. Maybe 
after pruning it for entries that reside inside other entries.

>> But you probably want this to work in installed Emacs as well?
> 
> What do you mean by "installed Emacs"? Emacs without sources? Sorry, I just woke
> up, have to get that coffein going up :).

Without sources or with compressed sources.

> What about to just have a keyboard shortcuts; say 'R', instead of link. With
> source code displayed it already looks a bit crouded. I think helpfuls buffer
> looks a bit busy with all the links.
> 
> I could imagine living with just a shortcut and maybe a context menu item.

I don't really have an opinion on the UI part of this. It can be a 
button, command, whatever.

> I attached a screeshots of helpful and built-in help with my yserdays patch both
> showing source code for the comparison.

UI for references and definitions will probably need to be different, no?

Re: Question about xref and adding "find all references" button to built-in help

[Arthur Miller]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 20.09.2021 08:47, Arthur Miller wrote:
>> Dmitry Gutov <dgutov@yandex.ru> writes:
>> 
>>> Hi!
>>>
>>> On 19.09.2021 23:17, Arthur Miller wrote:
>>>> If I would like to add a link as there is one in Helpful, to find all references
>>>> for a current symbol in help-mode buffer; which xref functionality should I look
>>>> at? Is there a ready made function already, or do I have to write something?
>>>
>>> We have functionality to searching for references in the current project (also
>>> works when inside an Emacs sources checkout) and throughout the load-path.
>> As extensive as helpful's help-ref? He searches through each and every source
>> file found in the load-path. Where do I look, can you give me some pointer I can
>> start playing with? Or should I do build my own search?
>
> That's just 'M-x xref-find-references'. Try it in an Elisp buffer.
>
> The implementation is fairly simple: see 'xref-backend-references' in xref.el
> and elisp-load-path-roots.

Thank you that was what I needed. I have tried it, will have to test and look
around a bit more.

> For your own backend, you will probably not dispatch through project.el method,
> and use load-path directly combined with package-user-dir. Maybe after pruning
> it for entries that reside inside other entries.

Yes probably. I thought I could skip writing a backend; but i'll see.

>>> But you probably want this to work in installed Emacs as well?
>> What do you mean by "installed Emacs"? Emacs without sources? Sorry, I just
>> woke
>> up, have to get that coffein going up :).
>
> Without sources or with compressed sources.

Yes. Maybe it would be possible to search in elc files? I mean some functions
have opcodes, but more are called by name. But I meant just when sources are
avialable, when 'source-directory' is not nil.

>> What about to just have a keyboard shortcuts; say 'R', instead of link. With
>> source code displayed it already looks a bit crouded. I think helpfuls buffer
>> looks a bit busy with all the links.
>> I could imagine living with just a shortcut and maybe a context menu item.
>
> I don't really have an opinion on the UI part of this. It can be a button,
> command, whatever.
>
>> I attached a screeshots of helpful and built-in help with my yserdays patch both
>> showing source code for the comparison.
>
> UI for references and definitions will probably need to be different, no?

A whole ui? :) I just meant a key, like for sources of info view. Helpful has a
link, but I would like to skip the link.

Re: Question about xref and adding "find all references" button to built-in help

[Dmitry Gutov]

On 20.09.2021 23:52, Arthur Miller wrote:

>> That's just 'M-x xref-find-references'. Try it in an Elisp buffer.
>>
>> The implementation is fairly simple: see 'xref-backend-references' in xref.el
>> and elisp-load-path-roots.
> 
> Thank you that was what I needed. I have tried it, will have to test and look
> around a bit more.
> 
>> For your own backend, you will probably not dispatch through project.el method,
>> and use load-path directly combined with package-user-dir. Maybe after pruning
>> it for entries that reside inside other entries.
> 
> Yes probably. I thought I could skip writing a backend; but i'll see.

I think it might be easier to defined a separate backend (say, called 
'elisp-help), but go ahead and experiment.

>>>> But you probably want this to work in installed Emacs as well?
>>> What do you mean by "installed Emacs"? Emacs without sources? Sorry, I just
>>> woke
>>> up, have to get that coffein going up :).
>>
>> Without sources or with compressed sources.
> 
> Yes. Maybe it would be possible to search in elc files? I mean some functions
> have opcodes, but more are called by name. But I meant just when sources are
> avialable, when 'source-directory' is not nil.

I don't know. Searching compressed sources (after the user installs 
them) might be a closer goal.

Or perhaps this feature will be mostly used by people who already have 
an Emacs sources checked out anyway.

>>> What about to just have a keyboard shortcuts; say 'R', instead of link. With
>>> source code displayed it already looks a bit crouded. I think helpfuls buffer
>>> looks a bit busy with all the links.
>>> I could imagine living with just a shortcut and maybe a context menu item.
>>
>> I don't really have an opinion on the UI part of this. It can be a button,
>> command, whatever.
>>
>>> I attached a screeshots of helpful and built-in help with my yserdays patch both
>>> showing source code for the comparison.
>>
>> UI for references and definitions will probably need to be different, no?
> 
> A whole ui? :) I just meant a key, like for sources of info view. Helpful has a
> link, but I would like to skip the link.

Ah, I see it now. You wanted to show the "Find all references" button 
printed by Helpful.

Re: Question about xref and adding "find all references" button to built-in help

[Arthur Miller]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 20.09.2021 23:52, Arthur Miller wrote:
>
>>> That's just 'M-x xref-find-references'. Try it in an Elisp buffer.
>>>
>>> The implementation is fairly simple: see 'xref-backend-references' in xref.el
>>> and elisp-load-path-roots.
>> Thank you that was what I needed. I have tried it, will have to test and look
>> around a bit more.
>> 
>>> For your own backend, you will probably not dispatch through project.el method,
>>> and use load-path directly combined with package-user-dir. Maybe after pruning
>>> it for entries that reside inside other entries.
>> Yes probably. I thought I could skip writing a backend; but i'll see.
>
> I think it might be easier to defined a separate backend (say, called
> 'elisp-help), but go ahead and experiment.
Will do, thanks for the tips.

>>>>> But you probably want this to work in installed Emacs as well?
>>>> What do you mean by "installed Emacs"? Emacs without sources? Sorry, I just
>>>> woke
>>>> up, have to get that coffein going up :).
>>>
>>> Without sources or with compressed sources.
>> Yes. Maybe it would be possible to search in elc files? I mean some functions
>> have opcodes, but more are called by name. But I meant just when sources are
>> avialable, when 'source-directory' is not nil.
>
> I don't know. Searching compressed sources (after the user installs them) might
> be a closer goal.
>
> Or perhaps this feature will be mostly used by people who already have an Emacs
> sources checked out anyway.
User have to have sources installed; I don't plan on parsing elc files, it was
more of a wild thought, but to get somthing going, user would need to have
sources installed in some way; compressed, uncompressed or dev sources. I don't
know though if I have to decompress sources myself or Emacs does that
auto. Nobody cared to answer any of questions I asked in the patch proposal for
the source inlined in help buffers. 

>>>> What about to just have a keyboard shortcuts; say 'R', instead of link. With
>>>> source code displayed it already looks a bit crouded. I think helpfuls buffer
>>>> looks a bit busy with all the links.
>>>> I could imagine living with just a shortcut and maybe a context menu item.
>>>
>>> I don't really have an opinion on the UI part of this. It can be a button,
>>> command, whatever.
>>>
>>>> I attached a screeshots of helpful and built-in help with my yserdays patch both
>>>> showing source code for the comparison.
>>>
>>> UI for references and definitions will probably need to be different, no?
>> A whole ui? :) I just meant a key, like for sources of info view. Helpful has
>> a
>> link, but I would like to skip the link.
>
> Ah, I see it now. You wanted to show the "Find all references" button printed by
> Helpful.

Yeah. But without the button :). You were thinkng on the presentation of
results? For there I just meant a buffer with a list of links or buttons, I
don't know what else. Would there be some better option?

Re: Question about xref and adding "find all references" button to built-in help

[Dmitry Gutov]

On 21.09.2021 13:32, Arthur Miller wrote:

>> Or perhaps this feature will be mostly used by people who already have an Emacs
>> sources checked out anyway.
> User have to have sources installed; I don't plan on parsing elc files, it was
> more of a wild thought, but to get somthing going, user would need to have
> sources installed in some way; compressed, uncompressed or dev sources. I don't
> know though if I have to decompress sources myself or Emacs does that
> auto. Nobody cared to answer any of questions I asked in the patch proposal for
> the source inlined in help buffers.

When we're talking about find-definition, it might be already taken care 
of by find-func and tramp-archive (someone needs to test, though).

But as far as "find references" goes, we're scanning the sources with 
external programs. There is 'zgrep', but I'm not sure how to set up its 
automatic use best.

>> Ah, I see it now. You wanted to show the "Find all references" button printed by
>> Helpful.
> 
> Yeah. But without the button :). You were thinkng on the presentation of
> results?

I figured that's what the screenshots were about.

> For there I just meant a buffer with a list of links or buttons, I
> don't know what else. Would there be some better option?

A button somewhere near the end might be a good idea. I don't know -- 
it's a fairly arbitrary choice that you could start with the rest of the 
work first, get it installed, and then post a question on emacs-devel 
(or wherever) whether people want to see the button as well.