Re: master b02c9bc: Improve documentation of new Xref options

[Dmitry Gutov]

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.