GNU bug report logs - #35702
xref revert-buffer

Previous Next

Full log

View this message in rfc822 format

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 35702 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: bug#35702: xref revert-buffer
Date: Fri, 24 May 2019 15:57:03 +0300

On 24.05.2019 15:25, Eli Zaretskii wrote:

>>> Thanks, but that changeset has a few problems:
>>>
>>>     . the new command xref--revert-xref-buffer uses an internal name,
>>
>> Is that a problem by itself? We have other bindings that use internal
>> command names as well.
> 
> That's a problem, yes.  Commands shouldn't be internal functions, by
> their very definition.

I've been kind of using it as a means of denoting "we're free to change 
it later", which is, of course, not great for a user, but I don't feel 
like we're settled on a final UI.

If we have a rule about private commands, though, let's fix them. But 
I'd prefer to do it a bit later, in a separate discussion.

>>>       and has no doc string
>>
>> How about something like:
>>
>>     Refresh the search results by repeating the search.
> 
> Given that it doesn't, at least after M-., this sounds like not all
> the truth.  Can it be more detailed?

The truth is, most xref datasets support refreshing, but some don't. At 
least xref-find-definitions doesn't.

I'm not sure we should document that in the command's docstring, though, 
because I think we'll end up with a more different UI for 
xref-find-definitions results, with a different major mode and a keymap 
where 'g' is simply not bound.

>>>     . neither NEWS nor the user manual document the 'g' key in XREF
>>>       buffers
>>
>> I can add the NEWS entry.
> 
> Please do, and thanks.

OK. Does it have to mention the command name?

Here's what I have:

** Xref

*** Refreshing the search results
When an Xref buffer shows search results (e.g. from
xref-find-references or project-find-regexp) you can type 'g' to
repeat the search and refresh the results.

>>>     . it looks like this new command is not useful after M-., because I
>>>       get an error message when I try using it (perhaps this is because
>>>       I didn't understand its use case due to lack of docs)
>>
>> It has been a deliberate choice to simplify the implementation. IME, you
>> don't ever want to refresh the list of definitions.
> 
> Well, one situation where I'd like to refresh is when the TAGS file
> was updated.  It could mean that more identifiers matching the search
> string are now known.

Right, but how often would the event of updading the TAGS file with 
coincide with you wanting to refresh the xref-find-definitions results?

Wouldn't you just do the search again with 'M-.'? This command has the 
easiest keybinding.

>> But for other search results (references, apropos,
>> project-find-regexp, dired-do-find-regexp) it's a lot more common.
> 
> At the very least, this should be reflected in the doc string.

Given that we're dealing with a certain level of abstration, and the 
list of commands using Xref is not limited, how would you phrase it?

>> Commit 49a363c875 also brings in another difference between the
>> behaviors of xref-find-definitions and xref-find-references: the latter
>> now shows the xref buffer even when there is just one hit.
> 
> This should arguable be in NEWS.

How about:

*** New variable 'xref-show-definitions-function'
It encapsulates the logic pertinent to showing the result of
xref-find-definitions. The user can change it to customize its
behavior and the display of results.

*** Search results show the buffer even for one hit
The search-type Xref commands (e.g. xref-find-references or
project-find-regexp) now show the results buffer even when there is
only one hit. This can be altered by changing
xref-show-xrefs-function.

You can probably see a certain level of duplication there, though.

>> Do you have a better idea now?
> 
> Only slightly so.  The code still doesn't speak to me, but I guess
> there isn't much that can be done about that.

This idea is pretty simple: instead of passing a list of search results 
to xref--show-xrefs, we pass an anonymous function that can be called to 
do the search, as well as repeat it, and returns the said list.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.