Re: master b02c9bc: Improve documentation of new Xref options

[Dmitry Gutov <dgutov@yandex.ru>]

On 07.09.2021 18:45, Eli Zaretskii wrote:
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> Date: Tue, 7 Sep 2021 18:21:24 +0300
>>
>>>    @findex project-search
>>> -  @kbd{M-x project-search} is an interactive variant of
>>> +  @kbd{M-x project-search} is an incremental variant of
>>
>> Is it really incremental? Maybe call it "iterative".
> 
> Is "sequential" better?  "Iterative" sounds too "mathematical".

Yes, I think it's a fine choice.

>>> -@c Sadly, the new-and-improved Xref feature doesn't provide anything
>>> -@c close to the described below features of the now-obsoleted
>>> -@c tags-apropos.  I'm leaving this here to encourage enhancements to
>>> -@c xref.el.
>>> +@c Sadly, the new-and-improved Xref feature doesn't provide some
>>> +@c of the features of the now-obsoleted tags-apropos.  I'm leaving
>>> +@c this here to encourage enhancements to xref.el.
>>
>> Is that about the display of tag file names in the apropos output buffer?
> 
> No, it's about the features listed after the shown hunk.  I just made
> its language less extreme, because xref-find-apropos does exist.

tags-apropos-additional-actions, then? That seems easier to support.

>>>    The new user option 'xref-auto-jump-to-first-definition' controls the
>>> -behavior of 'xref-find-definitions' and related commands: if it's t or
>>> -'show', the first match is automatically displayed; if it's 'move',
>>> -point in the "*xref*" buffer is automatically moved to the first match
>>> -without displaying it.
>>> -The new user option 'xref-auto-jump-to-first-xref' changes the behavior of
>>> -all Xref commands in the same way as 'xref-auto-jump-to-first-definition'
>>> -affects the "find-definitions" commands.
>>> +behavior of 'xref-find-definitions' and related commands, like
>>
>> Maybe "similar" rather than related? The point is that those commands
>> use the same UI (to show, sometimes, very different information), rather
>> than that are united by subject matter.
> 
> I went with "variants", okay?

Thanks.