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

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

[Dmitry Gutov]

On 05.09.2021 10:59, Eli Zaretskii wrote:
> +@vindex xref-auto-jump-to-first-xref
> +  If the value of the variable @code{xref-auto-jump-to-first-xref} is
> +@code{t}, @emph{all} Xref commands automatically jump to the first result.

To be more accurate, all Xref commands except the ones that display 
"definitions". Basically, xref-find-definitions is the main exception 
(even though it is also an "Xref command").

I wasn't sure how to better clarify this in the docstring.

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

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 5 Sep 2021 22:38:42 +0300
> 
> On 05.09.2021 10:59, Eli Zaretskii wrote:
> > +@vindex xref-auto-jump-to-first-xref
> > +  If the value of the variable @code{xref-auto-jump-to-first-xref} is
> > +@code{t}, @emph{all} Xref commands automatically jump to the first result.
> 
> To be more accurate, all Xref commands except the ones that display 
> "definitions". Basically, xref-find-definitions is the main exception 
> (even though it is also an "Xref command").

What is the rationale for this strange partition between these two
options?

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

[Dmitry Gutov]

On 06.09.2021 07:30, Eli Zaretskii wrote:
> What is the rationale for this strange partition between these two
> options?

We've discussed it in the bug thread, haven't we?

The existence of two options is more or less a direct result from one of 
your responses. And Juri's.

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 6 Sep 2021 14:24:02 +0300
> 
> On 06.09.2021 07:30, Eli Zaretskii wrote:
> > What is the rationale for this strange partition between these two
> > options?
> 
> We've discussed it in the bug thread, haven't we?
> 
> The existence of two options is more or less a direct result from one of 
> your responses. And Juri's.

My responses were only about a separate boolean option for
xref-find-references.  AFAIU, that's not what you described,
disregarding the "boolean" part.

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
and xref-find-references?  And what about stuff like
dired-do-find-regexp-and-replace -- is that affected by any of these?

Thanks.

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).

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 6 Sep 2021 15:47:57 +0300
> 
> 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.

I'm okay with 2 options, there's no need to argue about that.

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

So basically xref-auto-jump-to-first-xref affects any command that is
expected to display many matches, would that be a correct summary?

> > 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).

I see you fixed that already, but what about dired-do-find-regexp?

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

[Dmitry Gutov]

On 06.09.2021 18:33, Eli Zaretskii wrote:

>>> 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.
> 
> So basically xref-auto-jump-to-first-xref affects any command that is
> expected to display many matches, would that be a correct summary?

Could be.

Or "commands which display many matches, with high likelihood that the 
user will want to visit every match, rather than just pick one". At 
least that was the thinking behind xref-show-definitions-function vs 
xref-show-xrefs-function.

>>> 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).
> 
> I see you fixed that already, but what about dired-do-find-regexp?

It's in the same category as xref-find-references and others. Should 
work fine already.

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 6 Sep 2021 18:43:55 +0300
> 
> On 06.09.2021 18:33, Eli Zaretskii wrote:
> 
> >>> 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.
> > 
> > So basically xref-auto-jump-to-first-xref affects any command that is
> > expected to display many matches, would that be a correct summary?
> 
> Could be.
> 
> Or "commands which display many matches, with high likelihood that the 
> user will want to visit every match, rather than just pick one". At 
> least that was the thinking behind xref-show-definitions-function vs 
> xref-show-xrefs-function.

OK, I hope I fixed this stuff now, please take a look.

> >>> 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).
> > 
> > I see you fixed that already, but what about dired-do-find-regexp?
> 
> It's in the same category as xref-find-references and others. Should 
> work fine already.

Should we perhaps treat dired-do-find-regexp like we do with
dired-do-find-regexp-and-replace, to avoid confusion due to
inconsistency?

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

[Dmitry Gutov]

On 07.09.2021 16:05, Eli Zaretskii wrote:

>> Or "commands which display many matches, with high likelihood that the
>> user will want to visit every match, rather than just pick one". At
>> least that was the thinking behind xref-show-definitions-function vs
>> xref-show-xrefs-function.
> 
> OK, I hope I fixed this stuff now, please take a look.

Thank you, sent some comments.

You didn't seem to adopt the suggested description, but OK.

>>>>> 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).
>>>
>>> I see you fixed that already, but what about dired-do-find-regexp?
>>
>> It's in the same category as xref-find-references and others. Should
>> work fine already.
> 
> Should we perhaps treat dired-do-find-regexp like we do with
> dired-do-find-regexp-and-replace, to avoid confusion due to
> inconsistency?

dired-do-find-regexp-and-replace is a totally different command, which 
could use an entirely different UI (as soon as someone wrote one).

There is no way to have it obey xref-auto-jump-to-first-xref: it simply 
failed to work without the fix.

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

[Dmitry Gutov]

On 07.09.2021 18:24, Dmitry Gutov wrote:
> You didn't seem to adopt the suggested description, but OK.

I see it now, sorry. But here's another typo:

many match -> many matches

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 7 Sep 2021 18:24:46 +0300
> 
> On 07.09.2021 16:05, Eli Zaretskii wrote:
> 
> >> Or "commands which display many matches, with high likelihood that the
> >> user will want to visit every match, rather than just pick one". At
> >> least that was the thinking behind xref-show-definitions-function vs
> >> xref-show-xrefs-function.
> > 
> > OK, I hope I fixed this stuff now, please take a look.
> 
> Thank you, sent some comments.
> 
> You didn't seem to adopt the suggested description, but OK.

Which ones?

> > Should we perhaps treat dired-do-find-regexp like we do with
> > dired-do-find-regexp-and-replace, to avoid confusion due to
> > inconsistency?
> 
> dired-do-find-regexp-and-replace is a totally different command, which 
> could use an entirely different UI (as soon as someone wrote one).
> 
> There is no way to have it obey xref-auto-jump-to-first-xref: it simply 
> failed to work without the fix.

I understand.  But wouldn't it confuse users that dired-do-find-regexp
obeys the option, while dired-do-find-regexp-and-replace does not?  I
though perhaps we should make both not obey.

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

[Dmitry Gutov]

On 07.09.2021 18:47, Eli Zaretskii wrote:
>>> Should we perhaps treat dired-do-find-regexp like we do with
>>> dired-do-find-regexp-and-replace, to avoid confusion due to
>>> inconsistency?
>> dired-do-find-regexp-and-replace is a totally different command, which
>> could use an entirely different UI (as soon as someone wrote one).
>>
>> There is no way to have it obey xref-auto-jump-to-first-xref: it simply
>> failed to work without the fix.
> I understand.  But wouldn't it confuse users that dired-do-find-regexp
> obeys the option, while dired-do-find-regexp-and-replace does not?  I
> though perhaps we should make both not obey.

Having dired-do-find-regexp and project-find-regexp behave differently 
should be more confusing.

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

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Cc: emacs-devel@gnu.org
> Date: Tue, 7 Sep 2021 18:27:33 +0300
> 
> On 07.09.2021 18:24, Dmitry Gutov wrote:
> > You didn't seem to adopt the suggested description, but OK.
> 
> I see it now, sorry. But here's another typo:
> 
> many match -> many matches

Thanks, already fixed.

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 7 Sep 2021 19:01:46 +0300
> 
> On 07.09.2021 18:47, Eli Zaretskii wrote:
> >>> Should we perhaps treat dired-do-find-regexp like we do with
> >>> dired-do-find-regexp-and-replace, to avoid confusion due to
> >>> inconsistency?
> >> dired-do-find-regexp-and-replace is a totally different command, which
> >> could use an entirely different UI (as soon as someone wrote one).
> >>
> >> There is no way to have it obey xref-auto-jump-to-first-xref: it simply
> >> failed to work without the fix.
> > I understand.  But wouldn't it confuse users that dired-do-find-regexp
> > obeys the option, while dired-do-find-regexp-and-replace does not?  I
> > though perhaps we should make both not obey.
> 
> Having dired-do-find-regexp and project-find-regexp behave differently 
> should be more confusing.

I only meant the former, because it is a Dired command, like
dired-do-find-regexp-and-replace.  I was thinking about Dired users.

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

[Dmitry Gutov]

On 07.09.2021 19:18, Eli Zaretskii wrote:
>> Having dired-do-find-regexp and project-find-regexp behave differently
>> should be more confusing.
> I only meant the former, because it is a Dired command, like
> dired-do-find-regexp-and-replace.  I was thinking about Dired users.

Behave differently between themselves, I mean.

RE: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Drew Adams]

> I only meant the former, because it is a Dired command, like
> dired-do-find-regexp-and-replace.  I was thinking about Dired users.

If possible, `dired-do-*' commands should
behave similarly.  There's value in them
having a consistent interface.

So much so that I'd say that if some command
has to break this consistency then its name
shouldn't use the prefix `dired-do-'.  Just
one opinion, of course.

Re: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Dmitry Gutov]

On 07.09.2021 20:03, Drew Adams wrote:
> If possible, `dired-do-*' commands should
> behave similarly.  There's value in them
> having a consistent interface.
> 
> So much so that I'd say that if some command
> has to break this consistency then its name
> shouldn't use the prefix `dired-do-'.  Just
> one opinion, of course.

find-tag and find-file also have a matching first word in the name.

RE: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Drew Adams]

> > If possible, `dired-do-*' commands should
> > behave similarly.  There's value in them
> > having a consistent interface.
> >
> > So much so that I'd say that if some command
> > has to break this consistency then its name
> > shouldn't use the prefix `dired-do-'.  Just
> > one opinion, of course.
> 
> find-tag and find-file also have a matching first word in the name.

Cute, but not very relevant.

The `dired-do-*' commands are a particular subset
of Dired commands.  They all have the same UI.

That's not true of Dired commands generally (of
which there are hundreds).

As Eli suggested (but in my words), this little
thing is about the Dired UI, not Xref.

(But nothing prevents you from having an alias
whose name is more Xref-relevant.)

Re: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Dmitry Gutov]

On 07.09.2021 20:28, Drew Adams wrote:
>>> If possible, `dired-do-*' commands should
>>> behave similarly.  There's value in them
>>> having a consistent interface.
>>>
>>> So much so that I'd say that if some command
>>> has to break this consistency then its name
>>> shouldn't use the prefix `dired-do-'.  Just
>>> one opinion, of course.
>>
>> find-tag and find-file also have a matching first word in the name.
> 
> Cute, but not very relevant.
> 
> The `dired-do-*' commands are a particular subset
> of Dired commands.  They all have the same UI.

dired-do-search
dired-do-copy
dired-do-touch
dired-do-print
dired-do-kill-lines

Same UI, right.

> That's not true of Dired commands generally (of
> which there are hundreds).
> 
> As Eli suggested (but in my words), this little
> thing is about the Dired UI, not Xref.
> 
> (But nothing prevents you from having an alias
> whose name is more Xref-relevant.)

I've explained the distinction, in different terms, at least 4 times 
already. Please stop wasting my time.

RE: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Drew Adams]

> > The `dired-do-*' commands are a particular subset
> > of Dired commands.  They all have the same UI.
> 
> dired-do-search
> dired-do-copy
> dired-do-touch
> dired-do-print
> dired-do-kill-lines
> 
> Same UI, right.

I was talking about the behavior of the ARG argument.
And I think I'm correct about that: they accept and
handle ARG the same way.

But mea culpa.  You found one exception (out of 26
such commands in vanilla Emacs): with `emacs -Q',
`dired-do-search' does not accept an ARG argument:

It _should_ accept an optional ARG, IMO.  Would you
like to fix that minor bug? ;-)

In my shame-faced defense, that command in Dired+
does have an optional ARG.  (IOW, I fixed the bug;
dunno whether I also filed a bug report for it.)

And I've added 13 more `dired-do-*' commands (so 39
instead of 26).  And all that I've added also have
that same ARG behavior.  It's not hard to DTRT in
this regard.

> > That's not true of Dired commands generally (of
> > which there are hundreds).
> >
> > As Eli suggested (but in my words), this little
> > thing is about the Dired UI, not Xref.
> >
> > (But nothing prevents you from having an alias
> > whose name is more Xref-relevant.)
> 
> I've explained the distinction, in different terms, at least 4 times
> already. Please stop wasting my time.

Sure thing, Boss.  Far be it from me to chime in
on one of your threads.  Feel free to keep doing
what you're doing.  Don't let anyone tell you
otherwise.

ARG and Dired commands, was: Re: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Dmitry Gutov]

On 07.09.2021 22:44, Drew Adams wrote:
> I was talking about the behavior of the ARG argument.
> And I think I'm correct about that: they accept and
> handle ARG the same way.

Then we're really having different discussions. May I ask you to read 
the contents of the thread next time before replying?

> But mea culpa.  You found one exception (out of 26
> such commands in vanilla Emacs): with `emacs -Q',
> `dired-do-search' does not accept an ARG argument:
> 
> It_should_  accept an optional ARG, IMO.  Would you
> like to fix that minor bug?;-)

Considering that neither dired-do-search nor 
dired-do-query-replace-regexp have an ARG argument, it doesn't seem 
logical for the newer counterparts to have it.

Either way, it's orthogonal to the question at hand. Please file a bug 
if there is a problem there that annoys you.

It doesn't sound hard to write a patch for it as well, if you work out 
the issue of backward compatibility.

> In my shame-faced defense, that command in Dired+
> does have an optional ARG.  (IOW, I fixed the bug;
> dunno whether I also filed a bug report for it.)

...or point at one, if the bug is already filed.

RE: ARG and Dired commands, was: Re: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Drew Adams]

> > I was talking about the behavior of the ARG argument.
> > And I think I'm correct about that: they accept and
> > handle ARG the same way.
> 
> Then we're really having different discussions. May I ask you to read
> the contents of the thread next time before replying?

May I ask you not to add `dired-do-*' commands that
are inconsistent with the existing ones regarding ARG?

(I do care about vanilla Emacs, even if I can fix such
blunders in Dired+.)

> > But mea culpa.  You found one exception (out of 26
> > such commands in vanilla Emacs): with `emacs -Q',
> > `dired-do-search' does not accept an ARG argument:
> >
> > It_should_  accept an optional ARG, IMO.  Would you
> > like to fix that minor bug?;-)
> 
> Considering that neither dired-do-search nor
> dired-do-query-replace-regexp have an ARG argument,

Bravo!  You found a second one.  So 2 out of 26.

> it doesn't seem logical for the newer counterparts
> to have it.

It does to me.  Why doesn't it to you?

A user will expect the same ARG behavior with a
prefix arg, IMO.  Why wouldn't s?he?  The principle
of least surprise, Occam's razor, and common sense
argue in favor.

Sure, it's possible to have exceptions, IF there's
a good reason (and unfamiliarity with Dired isn't
a good reason).  Do you really have a good reason?

I offered you a simple way out: add your own
command with its own name - just don't prefix it
with `dired-do-'.

> Either way, it's orthogonal to the question at hand. 

It's not orthogonal if you're adding a command
named `dired-do-*' that doesn't accept a prefix-arg
ARG with the usual behavior.

You were able to find 2 exceptions out of 26 commands.
That's NOT a good reason to add a 3rd exception.
Maybe you have a reason that's good, but that one ain't.

Re: ARG and Dired commands, was: Re: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Dmitry Gutov]

On 07.09.2021 23:42, Drew Adams wrote:
> Bravo!  You found a second one.  So 2 out of 26.

These two, then the two commands this thread has been discussing before 
your arrival. And you can also add dired-do-isearch and 
dired-do-isearch-regexp.

That's six.

Still don't understand why we're talking about it here.

 > I offered you a simple way out: add your own
command with its own name - just don't prefix it
with `dired-do-'.

I also offered you a simple way out.

RE: ARG and Dired commands, was: Re: [External] : Re: master 2ed2999: Improve documentation of new Xref options

[Drew Adams]

I'll just give this additional argument in favor
of an optional ARG parameter for `dired-do-*'
commands:

It's handy to be able to act on one or a few
files without regard to which files are marked.
That lets you _keep a set of markings_ and yet
perform a one-off action on some other files.

This is built into the basic Dired UI.  Just
provide a numeric prefix arg N, to act on the
file of the current line and the next N-1 files.
E.g., `C-1 C' to copy the current line's file,
ignoring all marks.

That's really the point behind ARG, IMO.

Yes, it can be handy to act on the next ARG
files even when no files are marked, but where
ARG really shines is when there are markings
that you don't want to lose.

An alternative for that use case is to use
`* c' to temporarily change all `*' marks to
some other mark (e.g. `X'), then act on some
files as a one-off (having to mark them, if
more than one), then erase those temporary
`*' marks and change the other mark (e.g. `X')
back to the regular mark (`*').  You can see
why that's less handy, hopefully.

I hope you do consider adding an optional ARG
argument to your `dired-do-*' commands, and
give that ARG the usual behavior.  Unless you
have a good reason not to (do you?).