[v2] doc: imply that interactive.singleKey is disabled by default

Commit Message

Dragan Simic May 22, 2024, 9:24 p.m. UTC

Make it clear that the interactive.singleKey configuration option is disabled
by default, using rather subtle wording that avoids an emphasis on the actual
default value.  This should eliminate any associated doubts.

While there, touch up the remaining wording of the description a bit.

Signed-off-by: Dragan Simic <[e-mail]>
---

Notes:
    Changes in v2:
      - As agreed upon with Junio, [1] switched to more subtle wording that
        does not explicitly mention the default value.
    
    [1] https://lore.kernel.org/git/xmqqttip379x.fsf@gitster.g/
    
    Link to v1: https://lore.kernel.org/git/[e-mail]/T/#u

Range-diff against v1:
1:  3141fe9f7328 ! 1:  7da73f15a018 doc: note that interactive.singleKey is disabled by default
    @@ Metadata
     Author: Dragan Simic <[e-mail]>
     
      ## Commit message ##
    -    doc: note that interactive.singleKey is disabled by default
    +    doc: imply that interactive.singleKey is disabled by default
     
         Make it clear that the interactive.singleKey configuration option is disabled
    -    by default.  This should eliminate any associated doubts.
    +    by default, using rather subtle wording that avoids an emphasis on the actual
    +    default value.  This should eliminate any associated doubts.
    +
    +    While there, touch up the remaining wording of the description a bit.
     
         Signed-off-by: Dragan Simic <[e-mail]>
     
    +
    + ## Notes ##
    +    Changes in v2:
    +      - As agreed upon with Junio, [1] switched to more subtle wording that
    +        does not explicitly mention the default value.
    +
    +    [1] https://lore.kernel.org/git/xmqqttip379x.fsf@gitster.g/
    +
    +    Link to v1: https://lore.kernel.org/git/[e-mail]/T/#u
    +
      ## Documentation/config/interactive.txt ##
    -@@ Documentation/config/interactive.txt: interactive.singleKey::
    - 	linkgit:git-add[1], linkgit:git-checkout[1],
    +@@
    + interactive.singleKey::
    +-	In interactive commands, allow the user to provide one-letter
    +-	input with a single key (i.e., without hitting enter).
    +-	Currently this is used by the `--patch` mode of
    +-	linkgit:git-add[1], linkgit:git-checkout[1],
    ++	When set to true, allow the user to provide one-letter input
    ++	with a single key (i.e., without hitting the Enter key) in
    ++	interactive commands.  This is currently used by the `--patch`
    ++	mode of linkgit:git-add[1], linkgit:git-checkout[1],
      	linkgit:git-restore[1], linkgit:git-commit[1],
      	linkgit:git-reset[1], and linkgit:git-stash[1].
    -+	This is disabled by default.
      
    - interactive.diffFilter::
    - 	When an interactive command (such as `git add --patch`) shows

 Documentation/config/interactive.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

Comments

Junio C Hamano May 22, 2024, 9:31 p.m. UTC | #1

Dragan Simic <[e-mail]> writes:

> 1:  3141fe9f7328 ! 1:  7da73f15a018 doc: note that interactive.singleKey is disabled by default
>     @@ Metadata
>      Author: Dragan Simic <[e-mail]>
>      
>       ## Commit message ##
>     -    doc: note that interactive.singleKey is disabled by default
>     +    doc: imply that interactive.singleKey is disabled by default
>      
>          Make it clear that the interactive.singleKey configuration option is disabled

Heh, "note that" would probably be better, as we are going to say
"Make it clear" anyway, no?  That is stronger than just to imply.

Keeping the original version of the log message probably was
sufficient.

> +	When set to true, allow the user to provide one-letter input
> +	with a single key (i.e., without hitting the Enter key) in
> +	interactive commands.  This is currently used by the `--patch`
> +	mode of linkgit:git-add[1], linkgit:git-checkout[1],
>  	linkgit:git-restore[1], linkgit:git-commit[1],
>  	linkgit:git-reset[1], and linkgit:git-stash[1].
>  

The resulting text reads well.
Nicely done.

Dragan Simic May 22, 2024, 9:34 p.m. UTC | #2

On 2024-05-22 23:31, Junio C Hamano wrote:
> Dragan Simic <[e-mail]> writes:
> 
>> 1:  3141fe9f7328 ! 1:  7da73f15a018 doc: note that 
>> interactive.singleKey is disabled by default
>>     @@ Metadata
>>      Author: Dragan Simic <[e-mail]>
>> 
>>       ## Commit message ##
>>     -    doc: note that interactive.singleKey is disabled by default
>>     +    doc: imply that interactive.singleKey is disabled by default
>> 
>>          Make it clear that the interactive.singleKey configuration 
>> option is disabled
> 
> Heh, "note that" would probably be better, as we are going to say
> "Make it clear" anyway, no?  That is stronger than just to imply.
> 
> Keeping the original version of the log message probably was
> sufficient.

Yeah, but I felt like it needed some adjustments, because the patch
itself was actually changed.  I hope I won't have to send the v3
because of that? :)

>> +	When set to true, allow the user to provide one-letter input
>> +	with a single key (i.e., without hitting the Enter key) in
>> +	interactive commands.  This is currently used by the `--patch`
>> +	mode of linkgit:git-add[1], linkgit:git-checkout[1],
>>  	linkgit:git-restore[1], linkgit:git-commit[1],
>>  	linkgit:git-reset[1], and linkgit:git-stash[1].
>> 
> 
> The resulting text reads well.
> Nicely done.

Thanks.

Dragan Simic May 31, 2024, 12:49 a.m. UTC | #3

On 2024-05-22 23:34, Dragan Simic wrote:
> On 2024-05-22 23:31, Junio C Hamano wrote:
>> Dragan Simic <[e-mail]> writes:
>> 
>>> 1:  3141fe9f7328 ! 1:  7da73f15a018 doc: note that 
>>> interactive.singleKey is disabled by default
>>>     @@ Metadata
>>>      Author: Dragan Simic <[e-mail]>
>>> 
>>>       ## Commit message ##
>>>     -    doc: note that interactive.singleKey is disabled by default
>>>     +    doc: imply that interactive.singleKey is disabled by default
>>> 
>>>          Make it clear that the interactive.singleKey configuration 
>>> option is disabled
>> 
>> Heh, "note that" would probably be better, as we are going to say
>> "Make it clear" anyway, no?  That is stronger than just to imply.
>> 
>> Keeping the original version of the log message probably was
>> sufficient.
> 
> Yeah, but I felt like it needed some adjustments, because the patch
> itself was actually changed.  I hope I won't have to send the v3
> because of that? :)
> 
>>> +	When set to true, allow the user to provide one-letter input
>>> +	with a single key (i.e., without hitting the Enter key) in
>>> +	interactive commands.  This is currently used by the `--patch`
>>> +	mode of linkgit:git-add[1], linkgit:git-checkout[1],
>>>  	linkgit:git-restore[1], linkgit:git-commit[1],
>>>  	linkgit:git-reset[1], and linkgit:git-stash[1].
>>> 
>> 
>> The resulting text reads well.
>> Nicely done.
> 
> Thanks.

Just checking, is there something left to be addressed for this patch,
before it can be considered to be pulled into the next branch?

Junio C Hamano May 31, 2024, 5:23 p.m. UTC | #4

Dragan Simic <[e-mail]> writes:

> On 2024-05-22 23:34, Dragan Simic wrote:
>> On 2024-05-22 23:31, Junio C Hamano wrote:
>>> Dragan Simic <[e-mail]> writes:
>>> 
>>>> 1:  3141fe9f7328 ! 1:  7da73f15a018 doc: note that
>>>> interactive.singleKey is disabled by default
>>>>     @@ Metadata
>>>>      Author: Dragan Simic <[e-mail]>
>>>>       ## Commit message ##
>>>>     -    doc: note that interactive.singleKey is disabled by default
>>>>     +    doc: imply that interactive.singleKey is disabled by default
>>>>          Make it clear that the interactive.singleKey
>>>> configuration option is disabled
>>> Heh, "note that" would probably be better, as we are going to say
>>> "Make it clear" anyway, no?  That is stronger than just to imply.
>>> Keeping the original version of the log message probably was
>>> sufficient.
>> Yeah, but I felt like it needed some adjustments, because the patch
>> itself was actually changed.  I hope I won't have to send the v3
>> because of that? :)
>> 
>>>> +	When set to true, allow the user to provide one-letter input
>>>> +	with a single key (i.e., without hitting the Enter key) in
>>>> +	interactive commands.  This is currently used by the `--patch`
>>>> +	mode of linkgit:git-add[1], linkgit:git-checkout[1],
>>>>  	linkgit:git-restore[1], linkgit:git-commit[1],
>>>>  	linkgit:git-reset[1], and linkgit:git-stash[1].
>>>> 
>>> The resulting text reads well.
>>> Nicely done.
>> Thanks.
>
> Just checking, is there something left to be addressed for this patch,
> before it can be considered to be pulled into the next branch?

Thanks for pinging, as these small things were on the back burner
while preparing for updates to maintenance tracks.

Apparently v2 cannot be pulled into the next branch, and I forgot if
I saw v3 already.  In general, unless I explicitly say there is no
need to resend (sometimes with conditions), I'd expect an updated
iteration sent to the list.

Thanks.

Dragan Simic May 31, 2024, 10:21 p.m. UTC | #5

Hello Junio,

On 2024-05-31 19:23, Junio C Hamano wrote:
> Dragan Simic <[e-mail]> writes:
> 
>> On 2024-05-22 23:34, Dragan Simic wrote:
>>> On 2024-05-22 23:31, Junio C Hamano wrote:
>>>> Dragan Simic <[e-mail]> writes:
>>>> 
>>>>> 1:  3141fe9f7328 ! 1:  7da73f15a018 doc: note that
>>>>> interactive.singleKey is disabled by default
>>>>>     @@ Metadata
>>>>>      Author: Dragan Simic <[e-mail]>
>>>>>       ## Commit message ##
>>>>>     -    doc: note that interactive.singleKey is disabled by 
>>>>> default
>>>>>     +    doc: imply that interactive.singleKey is disabled by 
>>>>> default
>>>>>          Make it clear that the interactive.singleKey
>>>>> configuration option is disabled
>>>> Heh, "note that" would probably be better, as we are going to say
>>>> "Make it clear" anyway, no?  That is stronger than just to imply.
>>>> Keeping the original version of the log message probably was
>>>> sufficient.
>>> Yeah, but I felt like it needed some adjustments, because the patch
>>> itself was actually changed.  I hope I won't have to send the v3
>>> because of that? :)
>>> 
>>>>> +	When set to true, allow the user to provide one-letter input
>>>>> +	with a single key (i.e., without hitting the Enter key) in
>>>>> +	interactive commands.  This is currently used by the `--patch`
>>>>> +	mode of linkgit:git-add[1], linkgit:git-checkout[1],
>>>>>  	linkgit:git-restore[1], linkgit:git-commit[1],
>>>>>  	linkgit:git-reset[1], and linkgit:git-stash[1].
>>>>> 
>>>> The resulting text reads well.
>>>> Nicely done.
>>> Thanks.
>> 
>> Just checking, is there something left to be addressed for this patch,
>> before it can be considered to be pulled into the next branch?
> 
> Thanks for pinging, as these small things were on the back burner
> while preparing for updates to maintenance tracks.
> 
> Apparently v2 cannot be pulled into the next branch, and I forgot if
> I saw v3 already.  In general, unless I explicitly say there is no
> need to resend (sometimes with conditions), I'd expect an updated
> iteration sent to the list.

I see, but I'm not really sure is there need for the v3?  Maybe the
patch description could be tweaked a bit further, but I wasn't under
impression that you asked for that to be done?  Am I wrong there?

Dragan Simic June 4, 2024, 8:11 p.m. UTC | #6

On 2024-06-01 00:21, Dragan Simic wrote:
> On 2024-05-31 19:23, Junio C Hamano wrote:
>> Dragan Simic <[e-mail]> writes:
>>> Just checking, is there something left to be addressed for this 
>>> patch,
>>> before it can be considered to be pulled into the next branch?
>> 
>> Thanks for pinging, as these small things were on the back burner
>> while preparing for updates to maintenance tracks.
>> 
>> Apparently v2 cannot be pulled into the next branch, and I forgot if
>> I saw v3 already.  In general, unless I explicitly say there is no
>> need to resend (sometimes with conditions), I'd expect an updated
>> iteration sent to the list.
> 
> I see, but I'm not really sure is there need for the v3?  Maybe the
> patch description could be tweaked a bit further, but I wasn't under
> impression that you asked for that to be done?  Am I wrong there?

Any chances, please, to have a look at this?

Junio C Hamano June 7, 2024, 10:15 p.m. UTC | #7

Dragan Simic <[e-mail]> writes:

> On 2024-06-01 00:21, Dragan Simic wrote:
>> On 2024-05-31 19:23, Junio C Hamano wrote:
>>> Dragan Simic <[e-mail]> writes:
>>>> Just checking, is there something left to be addressed for this
>>>> patch,
>>>> before it can be considered to be pulled into the next branch?
>>> Thanks for pinging, as these small things were on the back burner
>>> while preparing for updates to maintenance tracks.
>>> Apparently v2 cannot be pulled into the next branch, and I forgot
>>> if
>>> I saw v3 already.  In general, unless I explicitly say there is no
>>> need to resend (sometimes with conditions), I'd expect an updated
>>> iteration sent to the list.
>> I see, but I'm not really sure is there need for the v3?  Maybe the
>> patch description could be tweaked a bit further, but I wasn't under
>> impression that you asked for that to be done?  Am I wrong there?
>
> Any chances, please, to have a look at this?

I _have_ taken a look---as I said, "I saw v3 already".

Unless you were asking other folks, that is, but the message was
addressed to me with others CC'ed, so I am not sure what the true
intention was.

Dragan Simic June 8, 2024, 9:59 a.m. UTC | #8

Hello Junio,

On 2024-06-08 00:15, Junio C Hamano wrote:
> Dragan Simic <[e-mail]> writes:
> 
>> On 2024-06-01 00:21, Dragan Simic wrote:
>>> On 2024-05-31 19:23, Junio C Hamano wrote:
>>>> Dragan Simic <[e-mail]> writes:
>>>>> Just checking, is there something left to be addressed for this
>>>>> patch,
>>>>> before it can be considered to be pulled into the next branch?
>>>> Thanks for pinging, as these small things were on the back burner
>>>> while preparing for updates to maintenance tracks.
>>>> Apparently v2 cannot be pulled into the next branch, and I forgot
>>>> if
>>>> I saw v3 already.  In general, unless I explicitly say there is no
>>>> need to resend (sometimes with conditions), I'd expect an updated
>>>> iteration sent to the list.
>>> I see, but I'm not really sure is there need for the v3?  Maybe the
>>> patch description could be tweaked a bit further, but I wasn't under
>>> impression that you asked for that to be done?  Am I wrong there?
>> 
>> Any chances, please, to have a look at this?
> 
> I _have_ taken a look---as I said, "I saw v3 already".
> 
> Unless you were asking other folks, that is, but the message was
> addressed to me with others CC'ed, so I am not sure what the true
> intention was.

Ah, I see now [1] what you asked for, which was a slight rewording
of the patch subject and description.  That's what my intention was,
to check was rewording the patch v2 subject and description necessary.
Sorry for the confusion, and thanks for putting the v3 [1] together.

[1] https://lore.kernel.org/git/xmqq4ja4e6d6.fsf@gitster.g/

Patch

diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt
index 5cc26555f19a..8b876cb4eb8e 100644
--- a/Documentation/config/interactive.txt
+++ b/Documentation/config/interactive.txt
@@ -1,8 +1,8 @@ 
 interactive.singleKey::
-	In interactive commands, allow the user to provide one-letter
-	input with a single key (i.e., without hitting enter).
-	Currently this is used by the `--patch` mode of
-	linkgit:git-add[1], linkgit:git-checkout[1],
+	When set to true, allow the user to provide one-letter input
+	with a single key (i.e., without hitting the Enter key) in
+	interactive commands.  This is currently used by the `--patch`
+	mode of linkgit:git-add[1], linkgit:git-checkout[1],
 	linkgit:git-restore[1], linkgit:git-commit[1],
 	linkgit:git-reset[1], and linkgit:git-stash[1].