[PATCH] commit-template: change a message to be more intuitive

[PATCH] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

It's not possible to 'touch' the cut-line that is shown when the
user requests a patch in his commit template.

So, make the sentence more intuitive.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Just a small tweak. May or may not be worth the patch.

 wt-status.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/wt-status.c b/wt-status.c
index 77c27c511..1f54b1df2 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
 
 void wt_status_add_cut_line(FILE *fp)
 {
-	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
+	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");
 	struct strbuf buf = STRBUF_INIT;
 
 	fprintf(fp, "%c %s", comment_line_char, cut_line);
-- 
2.14.1.1006.g90ad9a07c

Re: [PATCH] commit-template: change a message to be more intuitive

[Kevin Daudt]

On Tue, Sep 12, 2017 at 04:25:36PM +0530, Kaartic Sivaraam wrote:
> It's not possible to 'touch' the cut-line that is shown when the
> user requests a patch in his commit template.
> 

Touching something can also mean to disturb or change something, which
is the meaning being used here, so it is not an incorrect use of the
word.

> So, make the sentence more intuitive.

I can understand however that it might be not so clear for people with
less fluency in English.

> 
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Just a small tweak. May or may not be worth the patch.
> 
>  wt-status.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 77c27c511..1f54b1df2 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
>  
>  void wt_status_add_cut_line(FILE *fp)
>  {
> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> +	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");
>  	struct strbuf buf = STRBUF_INIT;
>  
>  	fprintf(fp, "%c %s", comment_line_char, cut_line);
> -- 
> 2.14.1.1006.g90ad9a07c
> 

Re: [PATCH] commit-template: change a message to be more intuitive

[Jeff King]

On Wed, Sep 13, 2017 at 12:29:15PM +0200, Kevin Daudt wrote:

> On Tue, Sep 12, 2017 at 04:25:36PM +0530, Kaartic Sivaraam wrote:
> > It's not possible to 'touch' the cut-line that is shown when the
> > user requests a patch in his commit template.
> > 
> 
> Touching something can also mean to disturb or change something, which
> is the meaning being used here, so it is not an incorrect use of the
> word.
> 
> > So, make the sentence more intuitive.
> 
> I can understand however that it might be not so clear for people with
> less fluency in English.

I agree with both of your points. It is very clear to me as a native
speaker, but I can see how it might not be for everyone.

Interestingly, the change here:

> > -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> > +	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");

actually seems less clear to me. I think of "edit" as "modify". But
obviously it also should not be removed. Perhaps

  Do not modify or remove the line above.

would be the most clear. Or perhaps it is overly verbose.

-Peff

Re: [PATCH] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

On Wednesday 13 September 2017 03:59 PM, Kevin Daudt wrote:
> Touching something can also mean to disturb or change something, which
> is the meaning being used here, so it is not an incorrect use of the
> word.

I do get your point but I should have been clearer in my commit message 
about the
fact that it's a word that could be misinterpreted.

>> So, make the sentence more intuitive.
> I can understand however that it might be not so clear for people with
> less fluency in English.

Not just that, it could also make the translations a little unclear. 
i.e., the when the words that convey
clear meaning in a particular context in english speaker get translated 
"as such" to another language,
they might turn out to become unclear or might even convey a totally 
different meaning. I'm not sure
if is currently happening as I am not familiar with any languages for 
which translations are currently
available but I'm pretty sure that the sentence "Do not touch the line 
above." would not give a clear
meaning when it gets translated "as such" to my native language (Tamil). 
Of course, it's only a problem
if the sentences get translated "as such" but I'm not sure if 
translators (human/non-human) try do
meaningful translations or try to preserve a one-to-one relationship 
with the words in the source
language, either.

---
Kaartic

Re: [PATCH] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

On Wednesday 13 September 2017 04:50 PM, Jeff King wrote:
> I agree with both of your points. It is very clear to me as a native
> speaker, but I can see how it might not be for everyone.
>
> Interestingly, the change here:
>
>>> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
>>> +	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");
> actually seems less clear to me. I think of "edit" as "modify". But
> obviously it also should not be removed. Perhaps
>
>    Do not modify or remove the line above.
>
> would be the most clear. Or perhaps it is overly verbose.
>
Seems to be a valid point. Further, it doesn't seem to be too verbose at 
least to me. So, I'll change the
sentence and revert back to the one I use if someone finds it to be verbose.

---
Kaartic

[PATCH v2] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

Changes in v2:

    - Changed the message as suggested by Jeff

    - Made the commit message to be even more clear


---

Kaartic

[PATCH v2] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

It's not good to use the phrase 'do not touch' to convey the information
that the cut-line should not be modified or removed as it could possibly
be mis-interpreted by a person who doesn't know that the word 'touch' has
the meaning of 'tamper with'. Further, it could make translations a little
difficult as it might not have the intended meaning in a few languages when
translated as such.

So, use more intuitive terms in the sentence.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 wt-status.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/wt-status.c b/wt-status.c
index 77c27c51134d2..be53579760ee7 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
 
 void wt_status_add_cut_line(FILE *fp)
 {
-	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
+	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");
 	struct strbuf buf = STRBUF_INIT;
 
 	fprintf(fp, "%c %s", comment_line_char, cut_line);

--
https://github.com/git/git/pull/401

Re: [PATCH v2] commit-template: change a message to be more intuitive

[Michael J Gruber]

Kaartic Sivaraam venit, vidit, dixit 13.09.2017 15:05:
> It's not good to use the phrase 'do not touch' to convey the information
> that the cut-line should not be modified or removed as it could possibly
> be mis-interpreted by a person who doesn't know that the word 'touch' has
> the meaning of 'tamper with'. Further, it could make translations a little
> difficult as it might not have the intended meaning in a few languages when
> translated as such.
> 
> So, use more intuitive terms in the sentence.
> 
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  wt-status.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 77c27c51134d2..be53579760ee7 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
>  
>  void wt_status_add_cut_line(FILE *fp)
>  {
> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> +	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");

I don't want to complicate things. But now - due to the repeated usage
of "remove" - these two sentences seem to be connected by an invisible
"or else" ("will" vs. "would" not withstanding). i.e. "or else
everything below will be removed, too", which is wrong. Before, they
were separated more clearly.

Also, given all the translations that we have, it seems somewhat strange
to try and foresee and workaround possible misunderstandings of commonly
used English phrases.

>  	struct strbuf buf = STRBUF_INIT;
>  
>  	fprintf(fp, "%c %s", comment_line_char, cut_line);
> 
> --
> https://github.com/git/git/pull/401
> 

Re: [PATCH v2] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

On Thursday 14 September 2017 01:06 PM, Michael J Gruber wrote:
> Kaartic Sivaraam venit, vidit, dixit 13.09.2017 15:05:
>>   void wt_status_add_cut_line(FILE *fp)
>>   {
>> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
>> +	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");
> I don't want to complicate things. But now - due to the repeated usage
> of "remove" - these two sentences seem to be connected by an invisible
> "or else" ("will" vs. "would" not withstanding). i.e. "or else
> everything below will be removed, too", which is wrong. Before, they
> were separated more clearly.

At least I don't think they are connected by an invisible "or else" because
they appear on different lines,

    #

    # ------------------------ >8 ------------------------

    # Do not modify or remove the line above.

    # Everything below will be removed.

    diff --git a/hook-checks/hooks/applypatch-msg b/hook-checks/hooks/applypatch-msg

    new file mode 100755

    index 0000000..a5d7b84

    --- /dev/null

    +++ b/hook-checks/hooks/applypatch-msg

> Also, given all the translations that we have, it seems somewhat strange
> to try and foresee and workaround possible misunderstandings of commonly
> used English phrases.
I thought the translators wouldn't mind this! If they do, then it's 
better to drop
this patch.

---
Kaartic

Re: [PATCH v2] commit-template: change a message to be more intuitive

[Jeff King]

On Thu, Sep 14, 2017 at 07:47:51PM +0530, Kaartic Sivaraam wrote:

> > > -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> > > +	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");
> > I don't want to complicate things. But now - due to the repeated usage
> > of "remove" - these two sentences seem to be connected by an invisible
> > "or else" ("will" vs. "would" not withstanding). i.e. "or else
> > everything below will be removed, too", which is wrong. Before, they
> > were separated more clearly.
> 
> At least I don't think they are connected by an invisible "or else" because
> they appear on different lines,

You could switch out the second "removed" for "ignored", which I think
has the same meaning but avoids repeating the same word. So:

  # ------------------------ >8 ------------------------
  # Do not modify or remove the line above.
  # Everything below will be ignored.

(I might say "everything below it" to be more precise).

I dunno. We are deep in bikeshed territory here, and I admit I don't
overly care that much in the first place.

-Peff

Re: [PATCH v2] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

On Thu, 2017-09-14 at 09:36 +0200, Michael J Gruber wrote:
> 
> Also, given all the translations that we have, it seems somewhat strange
> to try and foresee and workaround possible misunderstandings of commonly
> used English phrases.

In case you're trying to say that "Translators have successfully
translated the phrase with misunderstanding for many languages" then I
have to say that I foresaw the difficulty to translate it in other
languages for which a translation does not exist yet (specifically my
mother tongue). If that's not useful as it might only be an rare case,
then this patch isn't either.

-- 
Kaartic

Re: [PATCH v2] commit-template: change a message to be more intuitive

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>   # ------------------------ >8 ------------------------
>   # Do not modify or remove the line above.
>   # Everything below will be ignored.
>
> (I might say "everything below it" to be more precise).
>
> I dunno. We are deep in bikeshed territory here, and I admit I don't
> overly care that much in the first place.

So should I drop this topic altogether?  My inclination is to
declare that "everything below it will be ignored" is the best
version and stop reading further updates to this thread ;-)

[PATCH v3] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

It's not good to use the phrase 'do not touch' to convey the information
that the cut-line should not be modified or removed as it could possibly
be mis-interpreted by a person who doesn't know that the word 'touch' has
the meaning of 'tamper with'. Further, it could make translations a little
difficult as it might not have the intended meaning in a few languages (for
which translations don't exist yet) when translated as such.

So, use intuitive terms in the sentence. Replacing the word 'touch' with
other terms has introduced the possibility of the following sentence to be
mis-interpreted, so change the terms in that too.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Changes in v3:
 
    - changed the wordings of the second sentence as there seemed to be a
      magical 'or else' connecting the two lines.
 
 I didn't expect the least that this would go upto v3. In case anyboy finds
 something wrong with this change too, it's a lot better to drop this altogether
 than going for a v4.

 wt-status.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/wt-status.c b/wt-status.c
index 77c27c511..23e87e74d 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
 
 void wt_status_add_cut_line(FILE *fp)
 {
-	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
+	const char *explanation = _("Do not modify or remove the line above.\nEverything below it will be ignored.");
 	struct strbuf buf = STRBUF_INIT;
 
 	fprintf(fp, "%c %s", comment_line_char, cut_line);
-- 
2.14.1.1006.g90ad9a07c

Re: [PATCH v3] commit-template: change a message to be more intuitive

[Michael J Gruber]

Kaartic Sivaraam venit, vidit, dixit 15.09.2017 06:50:
> It's not good to use the phrase 'do not touch' to convey the information
> that the cut-line should not be modified or removed as it could possibly
> be mis-interpreted by a person who doesn't know that the word 'touch' has
> the meaning of 'tamper with'. Further, it could make translations a little
> difficult as it might not have the intended meaning in a few languages (for
> which translations don't exist yet) when translated as such.
> 
> So, use intuitive terms in the sentence. Replacing the word 'touch' with
> other terms has introduced the possibility of the following sentence to be
> mis-interpreted, so change the terms in that too.
> 
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Changes in v3:
>  
>     - changed the wordings of the second sentence as there seemed to be a
>       magical 'or else' connecting the two lines.
>  
>  I didn't expect the least that this would go upto v3. In case anyboy finds
>  something wrong with this change too, it's a lot better to drop this altogether
>  than going for a v4.

That happens more often than not :)

Your original intent was to avoid any misunderstandings, and all the
comments and iterations made sure that we don't trade one possible
source of misunderstanding for another but avoid them all.

I consider v4 to be a strict improvement over the status quo and (as fas
as I can see) to serve your original intent as good as possible.

>  wt-status.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 77c27c511..23e87e74d 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
>  
>  void wt_status_add_cut_line(FILE *fp)
>  {
> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> +	const char *explanation = _("Do not modify or remove the line above.\nEverything below it will be ignored.");
>  	struct strbuf buf = STRBUF_INIT;
>  
>  	fprintf(fp, "%c %s", comment_line_char, cut_line);
> 

Re: [PATCH v3] commit-template: change a message to be more intuitive

[Kaartic Sivaraam]

On Fri, 2017-09-15 at 12:00 +0200, Michael J Gruber wrote:
> Kaartic Sivaraam venit, vidit, dixit 15.09.2017 06:50:
> > 
> >  I didn't expect the least that this would go upto v3. In case anyboy finds

That's should have been 'anybody'.

> >  something wrong with this change too, it's a lot better to drop this altogether
> >  than going for a v4.
> 
> That happens more often than not :)
> 

:)

> Your original intent was to avoid any misunderstandings, and all the
> comments and iterations made sure that we don't trade one possible
> source of misunderstanding for another but avoid them all.
> 

Of course they did. 

> I consider v4 to be a strict improvement over the status quo and (as fas
> as I can see) to serve your original intent as good as possible.

I thought I shouldn't go for a v4 as I feared it might make things
worse than better because the original sentence wasn't that confusing
in the first place ;-)

-- 
Kaartic