| Message ID | pull.984.git.git.1616149021392.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Fix a typo in git-maintenance documentation | expand |
"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
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
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.
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
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