Provide some linguistic guidance for the documentation.

This will hopefully avoid questions over which spelling and grammar should
be used.  Translators are of course free to create localizations for
specific English dialects.

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 559d5f9ebf6fefe57b403327ed3e06942d0b822b..e5ca3b75d3778308ee1b7b20e3a86475244f7b96 100644 (file)
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -242,6 +242,14 @@ Writing Documentation:
  processed into HTML and manpages (e.g. git.html and git.1 in the
  same directory).
 
  processed into HTML and manpages (e.g. git.html and git.1 in the
  same directory).
 

+ The documentation liberally mixes US and UK English (en_US/UK)
+ norms for spelling and grammar, which is somewhat unfortunate.
+ In an ideal world, it would have been better if it consistently
+ used only one and not the other, and we would have picked en_US
+ (if you wish to correct the English of some of the existing
+ documentation, please see the documentation-related advice in the
+ Documentation/SubmittingPatches file).
+

  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing
  conventions.  A few commented examples follow to provide reference
  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing
  conventions.  A few commented examples follow to provide reference

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d0a4733e456777d97555ffd475799b468dc8b9de..705557689d7fa46f88f936bb8c42471ffbfb052b 100644 (file)
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -65,7 +65,20 @@ feature does not trigger when it shouldn't.  Also make sure that the
 test suite passes after your commit.  Do not forget to update the
 documentation to describe the updated behaviour.
 
 test suite passes after your commit.  Do not forget to update the
 documentation to describe the updated behaviour.
 

-Oh, another thing.  I am picky about whitespaces.  Make sure your
+Speaking of the documentation, it is currently a liberal mixture of US
+and UK English norms for spelling and grammar, which is somewhat
+unfortunate.  A huge patch that touches the files all over the place
+only to correct the inconsistency is not welcome, though.  Potential
+clashes with other changes that can result from such a patch are not
+worth it.  We prefer to gradually reconcile the inconsistencies in
+favor of US English, with small and easily digestible patches, as a
+side effect of doing some other real work in the vicinity (e.g.
+rewriting a paragraph for clarity, while turning en_UK spelling to
+en_US).  Obvious typographical fixes are much more welcomed ("teh ->
+"the"), preferably submitted as independent patches separate from
+other documentation changes.
+
+Oh, another thing.  We are picky about whitespaces.  Make sure your

 changes do not trigger errors with the sample pre-commit hook shipped
 in templates/hooks--pre-commit.  To help ensure this does not happen,
 run git diff --check on your changes before you commit.
 changes do not trigger errors with the sample pre-commit hook shipped
 in templates/hooks--pre-commit.  To help ensure this does not happen,
 run git diff --check on your changes before you commit.