[PATCH RESEND] git-svn: don't confuse editors with an apostrophe

[PATCH RESEND] git-svn: don't confuse editors with an apostrophe

[Carlos Martín Nieto]

The quotation mark serving as an apostrophe confuses editors and they
think a large part of the rest of the file is a string. Change
"you're" to "you are" to avoid this.

Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Acked-by: Eric Wong <normalperson@yhbt.net>
---

I sent this on 31-03-2011 but apart from Eric's ack, there was no
reaction and I don't see it in the patch queue.

   cmn

 git-svn.perl |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/git-svn.perl b/git-svn.perl
index bf0451b..bc5981d 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -348,7 +348,7 @@ Usage: git svn <command> [options] [arguments]\n
 	}
 	print $fd <<"";
 \nGIT_SVN_ID may be set in the environment or via the --id/-i switch to an
-arbitrary identifier if you're tracking multiple SVN branches/repositories in
+arbitrary identifier if you are tracking multiple SVN branches/repositories in
 one git repository and want to keep them separate.  See git-svn(1) for more
 information.
 
-- 
1.7.4.2.437.g4fc7e.dirty

Re: [PATCH RESEND] git-svn: don't confuse editors with an apostrophe

[Junio C Hamano]

Carlos Martín Nieto <cmn@elego.de> writes:

> The quotation mark serving as an apostrophe confuses editors and they
> think a large part of the rest of the file is a string. Change
> "you're" to "you are" to avoid this.
>
> Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
> Acked-by: Eric Wong <normalperson@yhbt.net>
> ---
>
> I sent this on 31-03-2011 but apart from Eric's ack, there was no
> reaction and I don't see it in the patch queue.

It was on purpose that I did not apply it, as the usual mode of operation
has been for me to pull git-svn changes via Eric, and more importantly, I
did not think it was important.

It did not look like a bugfix that needed to be handled quickly (even by
bypassing Eric if needed), and more importantly, I did not think your
justification of the patch was sound. So I (implicitly) made it up to
Eric either to discard it or to include it as part of his pull-request.

The explanation Eric gave (Avoiding contractions may make life easier for
folks less familiar with English overall) makes some sense to me, but
after re-reading your justification today, it still does not make sense.

For one thing, many editors would not even think "you" is not a string and
"re" and everything follows is a string, when "you're" is given to
them. Everything is a string in a text editor, isn't it?

I suspect that you are talking about syntax highlighting, and some syntax
highlighter may be stupid to be confused, but in that case, at least you
would need s/editors/some editors/.

Most fundamentally, I do not see why output from "sub usage" that lists
available commands when "git svn -h" is asked for has anything to do with
an editor getting confused. Why do you have that output in your editor in
the first place?

Even if the reason you have that output in your editor were sane, do you
mean to say that _all_ messages we output from our program, not just "git
svn", need to be cleansed of contractions? That is madness, and I do not
think that is what you meant. You need to clarify when your "do not
contract" rule applies fairly narrowly to avoid such a misunderstanding.

Re: [PATCH RESEND] git-svn: don't confuse editors with an apostrophe

[Carlos Martín Nieto]

[-- Attachment #1: Type: text/plain, Size: 2470 bytes --]

On Fri, Apr 29, 2011 at 09:28:44AM -0700, Junio C Hamano wrote:
> Carlos Martín Nieto <cmn@elego.de> writes:
> 
> > The quotation mark serving as an apostrophe confuses editors and they
> > think a large part of the rest of the file is a string. Change
> > "you're" to "you are" to avoid this.
> >
> > Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
> > Acked-by: Eric Wong <normalperson@yhbt.net>
> > ---
> >
> > I sent this on 31-03-2011 but apart from Eric's ack, there was no
> > reaction and I don't see it in the patch queue.
> 
> It was on purpose that I did not apply it, as the usual mode of operation
> has been for me to pull git-svn changes via Eric, and more importantly, I
> did not think it was important.

 From his reply (adding Ack) I inferred he expected you to apply it.

> 
> It did not look like a bugfix that needed to be handled quickly (even by
> bypassing Eric if needed), and more importantly, I did not think your
> justification of the patch was sound. So I (implicitly) made it up to
> Eric either to discard it or to include it as part of his pull-request.
> 
> The explanation Eric gave (Avoiding contractions may make life easier for
> folks less familiar with English overall) makes some sense to me, but
> after re-reading your justification today, it still does not make sense.
> 
> For one thing, many editors would not even think "you" is not a string and
> "re" and everything follows is a string, when "you're" is given to
> them. Everything is a string in a text editor, isn't it?
> 
> I suspect that you are talking about syntax highlighting, and some syntax
> highlighter may be stupid to be confused, but in that case, at least you
> would need s/editors/some editors/.

It confuses emacs and vim and I'd be surprised if any weren't, but
I'll change the message a bit.

> 
> Most fundamentally, I do not see why output from "sub usage" that lists
> available commands when "git svn -h" is asked for has anything to do with
> an editor getting confused. Why do you have that output in your editor in
> the first place?

It's not the output of the tool, it's the perl script. It uses the cat
<< EOF trick/method so there is a stray quotation mark and the editor
thinks that's the start of a string, so half the file is green or red
or whatever color your strings are.

I'll mention this more explicitly in the commit log, as it looks like
it's not clear enough.

   cmn

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

Re: [PATCH RESEND] git-svn: don't confuse editors with an apostrophe

[Junio C Hamano]

Carlos Martín Nieto <cmn@elego.de> writes:

> It's not the output of the tool, it's the perl script. It uses the cat
> << EOF trick/method so ...

Ahhhhh (a lightbulb dimly lits, and then explodes).

As it is generally a bad practice to cater to those who edit this file by
changing the output that is served to the end user, _unless_ the updated
output clearly gives a better experience to the end user [*1*], it never
occurred to me that that is what you are doing in this patch.

Yes, the message should be made clearer.

Thanks for an explanation.

[Footnote]

*1* In other words, updating the output to help users is fine.  And if
such a change unconfuses your editor, that would be a nice side effect.
Doing things the other way around is simply the tail wagging the dog.

Re: [PATCH RESEND] git-svn: don't confuse editors with an apostrophe

[Eric Wong]

Carlos Martín Nieto <cmn@elego.de> wrote:
> On Fri, Apr 29, 2011 at 09:28:44AM -0700, Junio C Hamano wrote:
>  From his reply (adding Ack) I inferred he expected you to apply it.

Oops, I Acked but forgot to commit + push

> > I suspect that you are talking about syntax highlighting, and some syntax
> > highlighter may be stupid to be confused, but in that case, at least you
> > would need s/editors/some editors/.
> 
> It confuses emacs and vim and I'd be surprised if any weren't, but
> I'll change the message a bit.

I've pushed the patch with the following message:

Subject: [PATCH] git-svn: avoid contraction in usage text

Contractions may be difficult for non-native English speakers.
The quotation mark may also confuse syntax highlighting in
some text editors.

[ew: reworded commit message]

Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Acked-by: Eric Wong <normalperson@yhbt.net>
-- 
Eric Wong