Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Sean Whitton]

Hello Eli,

Thank you for reviewing the commit.

On Fri 30 Sep 2022 at 02:57PM -04, Eli Zaretskii wrote:

> diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
> index a8ceb1b790..05d2144380 100644
> --- a/doc/emacs/vc1-xtra.texi
> +++ b/doc/emacs/vc1-xtra.texi
> @@ -270,16 +270,17 @@ with the file's version control type.
>  @findex vc-edit-next-command
>  @kindex C-x v !
>  You can use the @kbd{C-x v !} (@code{vc-edit-next-command}) prefix
> -command to request an opportunity to edit the VC shell commands that
> -Emacs will run.  This is primarily intended to make it possible to
> -access version control system-specific functionality without
> -complexifying either the VC command set or the backend API.
> +command to edit the shell command line that VC is about to run.  This
> +is primarily intended to make it possible to add optional command-line
> +arguments to VCS commands without unnecessary complications of the VC
> +command set and its interfaces with the backend.

I would like to restore the idea that it's about accessing VC
system-specific features, because adding optional command line arguments
is merely the means by which they are accessed.  How about:

    This is primarily intended to make it possible to access version
    control system-specific functionality, by means of adding optional
    command line arguments to VCS commands, without unwanted
    complications of the VC command set and its interfaces with the
    backend.

-- 
Sean Whitton

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Date: Fri, 30 Sep 2022 16:46:51 -0700
> 
> Hello Eli,
> 
> Thank you for reviewing the commit.

You are welcome.

> > --- a/doc/emacs/vc1-xtra.texi
> > +++ b/doc/emacs/vc1-xtra.texi
> > @@ -270,16 +270,17 @@ with the file's version control type.
> >  @findex vc-edit-next-command
> >  @kindex C-x v !
> >  You can use the @kbd{C-x v !} (@code{vc-edit-next-command}) prefix
> > -command to request an opportunity to edit the VC shell commands that
> > -Emacs will run.  This is primarily intended to make it possible to
> > -access version control system-specific functionality without
> > -complexifying either the VC command set or the backend API.
> > +command to edit the shell command line that VC is about to run.  This
> > +is primarily intended to make it possible to add optional command-line
> > +arguments to VCS commands without unnecessary complications of the VC
> > +command set and its interfaces with the backend.
> 
> I would like to restore the idea that it's about accessing VC
> system-specific features, because adding optional command line arguments
> is merely the means by which they are accessed.  How about:
> 
>     This is primarily intended to make it possible to access version
>     control system-specific functionality, by means of adding optional
>     command line arguments to VCS commands, without unwanted
>     complications of the VC command set and its interfaces with the
>     backend.

The original text ("access version control system-specific
functionality") was too vague, and I attempted to make it more
concrete and clear.  I don't understand why that part is so important
to have it, especially if you agree that the most frequent expression
of "accessing version control system-specific functionality" is to add
optional command-line arguments.  Isn't it clear to any reader that
adding command-line arguments will activate additional functionality?

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Sean Whitton]

Hello,

On Sat 01 Oct 2022 at 08:48AM +03, Eli Zaretskii wrote:

> The original text ("access version control system-specific
> functionality") was too vague, and I attempted to make it more
> concrete and clear.  I don't understand why that part is so important
> to have it, especially if you agree that the most frequent expression
> of "accessing version control system-specific functionality" is to add
> optional command-line arguments.  Isn't it clear to any reader that
> adding command-line arguments will activate additional functionality?

I think it is important to distinguish just adding arguments, and adding
arguments that take one beyond VC's VCS-agnostic interface.

For example, it would not make much sense to use 'C-x v ! C-x v L'
to log another (singular) branch.  You should use 'C-x v b l'.

-- 
Sean Whitton

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: emacs-devel@gnu.org
> Date: Tue, 04 Oct 2022 16:24:24 -0700
> 
> On Sat 01 Oct 2022 at 08:48AM +03, Eli Zaretskii wrote:
> 
> > The original text ("access version control system-specific
> > functionality") was too vague, and I attempted to make it more
> > concrete and clear.  I don't understand why that part is so important
> > to have it, especially if you agree that the most frequent expression
> > of "accessing version control system-specific functionality" is to add
> > optional command-line arguments.  Isn't it clear to any reader that
> > adding command-line arguments will activate additional functionality?
> 
> I think it is important to distinguish just adding arguments, and adding
> arguments that take one beyond VC's VCS-agnostic interface.

Why is it important?  The user can do whatever they want with this
functionality, and we shouldn't second-guess them.  The manual
describes what we think is a good use of that, but other than that,
it's the user's call and prerogative.

> For example, it would not make much sense to use 'C-x v ! C-x v L'
> to log another (singular) branch.  You should use 'C-x v b l'.

"Would not make much sense" is in the eyes of the beholder.  Not all
of us are quick-thinking enough to realize the commands we sometimes
choose to do a job are not the optimal ones.  But there's no reason to
pretend that there's only one way of doing every job.

Are there other reasons to insist on the "VCS-specific functionality"
aspect of this command, beyond the above considerations of using VC
command in an optimal fashion?

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Sean Whitton]

Hello,

On Wed 05 Oct 2022 at 08:58AM +03, Eli Zaretskii wrote:

> "Would not make much sense" is in the eyes of the beholder.  Not all
> of us are quick-thinking enough to realize the commands we sometimes
> choose to do a job are not the optimal ones.  But there's no reason to
> pretend that there's only one way of doing every job.
>
> Are there other reasons to insist on the "VCS-specific functionality"
> aspect of this command, beyond the above considerations of using VC
> command in an optimal fashion?

What I'd like to get across in the manual, somehow and somewhere, is
that VC now has a broadly applicable answer to the question of accessing
VCS-specific functionality.  We've decided that in many cases, the best
thing is to require that the user edit command lines themselves, rather
than adding new VC commands or new VCS-specific commands.  So if someone
is wondering "how do I get at X with VC, do I just have to resort to a
shell?" it would be good for them to know that 'C-x v !' might be a
convenient option for them.

I accept that here is perhaps not the best place to try to get this
across.  Where do you think something like that might fit?  Would be
grateful for help.

-- 
Sean Whitton

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: emacs-devel@gnu.org
> Date: Wed, 05 Oct 2022 16:06:21 -0700
> 
> On Wed 05 Oct 2022 at 08:58AM +03, Eli Zaretskii wrote:
> 
> > "Would not make much sense" is in the eyes of the beholder.  Not all
> > of us are quick-thinking enough to realize the commands we sometimes
> > choose to do a job are not the optimal ones.  But there's no reason to
> > pretend that there's only one way of doing every job.
> >
> > Are there other reasons to insist on the "VCS-specific functionality"
> > aspect of this command, beyond the above considerations of using VC
> > command in an optimal fashion?
> 
> What I'd like to get across in the manual, somehow and somewhere, is
> that VC now has a broadly applicable answer to the question of accessing
> VCS-specific functionality.  We've decided that in many cases, the best
> thing is to require that the user edit command lines themselves, rather
> than adding new VC commands or new VCS-specific commands.  So if someone
> is wondering "how do I get at X with VC, do I just have to resort to a
> shell?" it would be good for them to know that 'C-x v !' might be a
> convenient option for them.
> 
> I accept that here is perhaps not the best place to try to get this
> across.  Where do you think something like that might fit?  Would be
> grateful for help.

I very much doubt that you can usefully say something like that in a
description of an obscure command: how will that be discovered?  And
where else in the manual would you say something like that, when it
involves a specific command?

So maybe say that in NEWS?

Re: master f7b84345f8 1/2: ; * doc/emacs/vc1-xtra.texi (Editing VC Commands): Fix wording.

[Sean Whitton]

Hello,

On Fri 07 Oct 2022 at 03:45PM +03, Eli Zaretskii wrote:

>> From: Sean Whitton <spwhitton@spwhitton.name>
>> Cc: emacs-devel@gnu.org
>> Date: Wed, 05 Oct 2022 16:06:21 -0700
>>
>> On Wed 05 Oct 2022 at 08:58AM +03, Eli Zaretskii wrote:
>>
>> > "Would not make much sense" is in the eyes of the beholder.  Not all
>> > of us are quick-thinking enough to realize the commands we sometimes
>> > choose to do a job are not the optimal ones.  But there's no reason to
>> > pretend that there's only one way of doing every job.
>> >
>> > Are there other reasons to insist on the "VCS-specific functionality"
>> > aspect of this command, beyond the above considerations of using VC
>> > command in an optimal fashion?
>>
>> What I'd like to get across in the manual, somehow and somewhere, is
>> that VC now has a broadly applicable answer to the question of accessing
>> VCS-specific functionality.  We've decided that in many cases, the best
>> thing is to require that the user edit command lines themselves, rather
>> than adding new VC commands or new VCS-specific commands.  So if someone
>> is wondering "how do I get at X with VC, do I just have to resort to a
>> shell?" it would be good for them to know that 'C-x v !' might be a
>> convenient option for them.
>> 
>> I accept that here is perhaps not the best place to try to get this
>> across.  Where do you think something like that might fit?  Would be
>> grateful for help.
>
> I very much doubt that you can usefully say something like that in a
> description of an obscure command: how will that be discovered?

Yes, good point.

> And where else in the manual would you say something like that, when
> it involves a specific command?

Not sure.

> So maybe say that in NEWS?

Okay, thanks for the suggestion, now done.

-- 
Sean Whitton