bug#74361: [PATCH] New option xref-navigation-display-window-action

[Dmitry Gutov <dmitry@gutov.dev>]

On 18/11/2024 19:03, Eli Zaretskii wrote:

>> IIUC your suggestion was:
>>
>>     If non-nil, the `display-buffer' action for showing results of Xref
>> commands.
>>
>> And those are commands belonging to the package (for the moment), and as
>> such fitting the description.
> 
> Not in my book (they are replacement commands), but feel free to find
> better text.

Okay, if the phrasing still makes sense to you with the above details, 
let's use this version.

>>>> Also, there is a nuance: when the Xref buffer itself is shown (i.e. when
>>>> there are multiple locations matching a xref-find-definitions search),
>>>> we're not going to pass (category . xref) to display-buffer either - it
>>>> is reserved for displaying the buffers of destination locations.
>>>
>>> And this is a separate issue, not related to the doc string?
>>
>> Still about the doc string.
> 
> But not important enough to affect the first line of it.
> 
>> If we say "showing results of Xref
>> commands", then the Xref buffer with the list of locations also matches
>> that description, doesn't it? Or rather it might be the first thing a
>> user would think of - but our customization wouldn't apply to it
>> immediately.
> 
> The rest of the doc string could explain this subtlety.

Fair point, thanks.

Next step is to find the appropriate place for it. Maybe not a docstring 
if the user option to customize will be the global one 
(display-buffer-alist), but either in Commentary or somewhere in the manual.

Speaking of the reference that we used for this solution, it seems that

   (category . comint)

is only mentioned in NEWS and in the obsoletion message for 
'display-comint-buffer-action'. There is also a hit for it in the 
manual, but only in the form "If the caller display-buffer passes a 
category as a symbol ...", not saying exactly that comint modes do or 
should do that. Maybe that's something to be fixed as well.