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

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

Junio C Hamano [off-list ref] writes:

quoted

quoted

 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.
 

[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