Re: [PATCH] Fix a typo in git-maintenance documentation

From: Derrick Stolee <stolee@gmail.com>
Date: Mar 20, 2021, 01:55 UTC
Message-ID: <d27633aa-8e68-36e9-ddd3-0d05d74a780c@gmail.com>
In-Reply-To: <xmqqa6qynbfm.fsf@gitster.g>

On 3/19/2021 4:19 PM, Junio C Hamano wrote:

Show 18 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
> 
>>>  gc::
>>>  	Clean up unnecessary files and optimize the local repository. "GC"
>>> -	stands for "garbage collection," but this task performs many
>>> +	stands for "garbage collection", but this task performs many
>>
>> Isn't this merely an American style vs British style issue?
> 
> Having said that, I think a lot of existing documentation (and my
> gut feeling says "majority of", but I cannot claim anything like
> that without actually counting [*1*]) we have tend to stick to the
> "punctuation outside" British style [*2*].
> 
> If somebody (not me, and probably not Derrick) is willing to do the
> counting and tree-wide style fixes, I am OK if we add some new text
> to Documentation/CodingGuidelines to declare which style we stick
> to, and enforce consistency throughout the documentation set.

I'm not lining up to volunteer for this effort, but if it is truly
the typical case in the Git documentation, I would agree to a change
to the coding guidelines and this specific change.

Show 12 quoted lines

> [Footnote]
> 
> *1* A quick count:
> 
>     $ git grep -e '," ' Documentation/
> 
>     gives just a single hit.  On the other hand, '", ' hits too many,
>     but many are sentences like 
> 
>       "git clone -q", "git fetch -q", and the like are quiet.
> 
>     which is not quite fair.

Right. I would use this order in these cases.

> *2* After all, that is more "logical", for us CS types---opening and
>     closing quotes pair with each other, and the punctuation that
>     appears near the quoted portion is part of the larger sentence
>     structure.

 
I'm willing to concede that using ", universally avoids needing
a special rule, especially because phrases like

	If you run "git commit", then X happens.

is obviously the right thing to do.

I can't speak for contributors whose first language isn't English, but I can imagine that removing the difference between these cases would make it just a tiny bit easier to contribute.

I can break my own habits. The only thing I ask is to make it officially part of the guidelines.

Thanks, -Stolee