Re: master 2ed2999: Improve documentation of new Xref options

[Dmitry Gutov]

On 06.09.2021 15:28, Eli Zaretskii wrote:
> My responses were only about a separate boolean option for
> xref-find-references.  AFAIU, that's not what you described,
> disregarding the "boolean" part.

We already differentiate between the -definitions[-*] commands and all 
other Xref commands, e.g. we have xref-show-definitions-function and 
xref-show-xrefs-function. This change follows the same pattern.

We could have gone the one-defcustom-per-command route, but that's a lot 
of micromanagement for the users, with seemingly little benefit.

> So, bottom line: which commands are affected by each option?  E.g.,
> what about the -other-window and -at-mouse etc. variants: I guess they
> are affected by the corresponding options?  Also, what other commands
> are affected, in addition to the "families" of xref-find-definitions

Right. To clarify: all of xref-find-definitions-* are affected by 
xref-auto-jump-to-first-definition.

> and xref-find-references?

Also xref-find-apropos, project-find-regexp, dired-do-find-regexp and 
any other third-party or future callers of xref-show-xrefs-function will 
be affected by xref-auto-jump-to-first-xref.

> And what about stuff like
> dired-do-find-regexp-and-replace -- is that affected by any of these?

dired-do-find-regexp-and-replace is affected as well right now, but 
that's a bug to be fixed (thanks for bringing it up).