[PATCH] Fix a typo in git-maintenance documentation

[PATCH] Fix a typo in git-maintenance documentation

[Nils Leif Fischer via GitGitGadget]

From: Nils Leif Fischer <nils.fischer@aei.mpg.de>

Signed-off-by: Nils Leif Fischer <nils.fischer@aei.mpg.de>
---
    Fix typo in git-maintenance documentation
    
    Just a small typo.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-984%2Fnilsleiffischer%2Fnilsleiffischer-patch-1-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-984/nilsleiffischer/nilsleiffischer-patch-1-v1
Pull-Request: https://github.com/git/git/pull/984

 Documentation/git-maintenance.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index 80ddd33ceba0..8023504dc65d 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -106,7 +106,7 @@ any object transfer.
 
 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
 	smaller tasks. This task can be expensive for large repositories,
 	as it repacks all Git objects into a single pack-file. It can also
 	be disruptive in some situations, as it deletes stale data. See

base-commit: a5828ae6b52137b913b978e16cd2334482eb4c1f
-- 
gitgitgadget

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

[Junio C Hamano]

"Nils Leif Fischer via GitGitGadget" <gitgitgadget@gmail.com>
writes:

> From: Nils Leif Fischer <nils.fischer@aei.mpg.de>
>
> Signed-off-by: Nils Leif Fischer <nils.fischer@aei.mpg.de>
> ---
>     Fix typo in git-maintenance documentation
>     
>     Just a small typo.

This is from the very beginning at 2057d750 (maintenance: create
basic maintenance runner, 2020-09-17), I think.

> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-984%2Fnilsleiffischer%2Fnilsleiffischer-patch-1-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-984/nilsleiffischer/nilsleiffischer-patch-1-v1
> Pull-Request: https://github.com/git/git/pull/984
>
>  Documentation/git-maintenance.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
> index 80ddd33ceba0..8023504dc65d 100644
> --- a/Documentation/git-maintenance.txt
> +++ b/Documentation/git-maintenance.txt
> @@ -106,7 +106,7 @@ any object transfer.
>  
>  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?


>  	smaller tasks. This task can be expensive for large repositories,
>  	as it repacks all Git objects into a single pack-file. It can also
>  	be disruptive in some situations, as it deletes stale data. See
>
> base-commit: a5828ae6b52137b913b978e16cd2334482eb4c1f


cf.

https://www.grammarly.com/blog/quotation-marks
https://www.thepunctuationguide.com/british-versus-american-style.html
https://owl.purdue.edu/owl/general_writing/punctuation/quotation_marks/more_quotation_mark_rules.html

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

[Derrick Stolee]

On 3/19/2021 1:55 PM, Junio C Hamano wrote:
> "Nils Leif Fischer via GitGitGadget" <gitgitgadget@gmail.com>
>>  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?

Yes, I believe so.

> https://www.grammarly.com/blog/quotation-marks
> https://www.thepunctuationguide.com/british-versus-american-style.html
> https://owl.purdue.edu/owl/general_writing/punctuation/quotation_marks/more_quotation_mark_rules.html

Specifically, this quote from your first link:

  Commas and periods always go inside the quotation marks in
  American English; dashes, colons, and semicolons almost always
  go outside the quotation marks; question marks and exclamation
  marks sometimes go inside, sometimes stay outside.

The only time I break this is when the exact string matters,
such as referencing an exact command with options. In those
cases, I try to restructure the sentence to avoid having a
comma or period outside of the quote.

Thanks,
-Stolee

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

[Junio C Hamano]

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.


[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.

    Don't try to do that for the comma replaced with period; you'd be
    buried by "word..."  and the like.


*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.

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

[Derrick Stolee]

On 3/19/2021 4:19 PM, Junio C Hamano wrote:
> 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.
 
> [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