Re: master b02c9bc: Improve documentation of new Xref options

[Dmitry Gutov]

Thanks for the updates, some comments:

On 07.09.2021 16:04, Eli Zaretskii wrote:

>   @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".

Compared to isearch (which is "incremental search"), we are not allowed 
to change the search string on-the-fly, for example.

> -@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?

TBH I'm only reading this paragraph now. A bug report with a fuller 
explanation might help (no promises, though, sorry).

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -2309,13 +2309,18 @@ before navigating to the selected location.
>   +++
>   *** New user options to automatically show the first Xref match.
>   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.

> +'xref-find-definitions-other-windo': if it's t or 'show', the first

Typo: windo -> window

> +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 Xref commands such as 'xref-find-references',
> +'xref-find-apropos', and 'project-find-regexp', which are expected to
> +display many match that the user would like to
> +visit. 'xref-auto-jump-to-first-xref' changes their behavior muuch in

Typo: muuch

> +the same way as 'xref-auto-jump-to-first-definition' affects the
> +"find-definitions" commands.
>   
>   *** New user options 'xref-search-program' and 'xref-search-program-alist'.
>   So far 'grep' and 'ripgrep' are supported.  'ripgrep' seems to offer better
> diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
> index d022baaf..f6d88e1 100644
> --- a/lisp/progmodes/xref.el
> +++ b/lisp/progmodes/xref.el
> @@ -420,7 +420,9 @@ elements is negated: these commands will NOT prompt."
>     "If t, `xref-find-definitions' always jumps to the first result.
>   `show' means to show the first result's location, but keep the
>   focus on the Xref buffer's window.
> -`move' means to only move point to the first result."
> +`move' means to only move point to the first result.
> +This variable also affects commands similar to `xref-find-definitions',
> +such as `xref-find-definitions-other-window'."

I would call them "variations", rather than separate commands, probably.

This is in contrast to xref-find-references and xref-find-apropos 
actually being similar while being different commands.

>     :type '(choice (const :tag "Jump" t)
>                    (const :tag "Show" show)
>                    (const :tag "Move point only" move)
> @@ -429,13 +431,16 @@ focus on the Xref buffer's window.
>     :package-version '(xref . "1.2.0"))
>   
>   (defcustom xref-auto-jump-to-first-xref nil
> -  "If t, xref commands always jump to the first result.
> +  "If t, `xref-find-references' always jumps to the first result.
>   `show' means to show the first result's location, but keep the
>   focus on the Xref buffer's window.
>   `move' means to only move point to the first result.
> +This variable also affects commands similar to `xref-find-definitions',

similar to `xref-find-references'

Here you call them "similar", like I suggest above. That seems like a 
good choice.

Thanks.