[PATCH v3] Provide some linguistic guidance for the documentation.

From

Marc Branchaud <marcnarc@xiplink.com>

Date

Aug 1, 2013, 18:49 UTC

Message-ID

<1375382994-30010-1-git-send-email-marcnarc@xiplink.com>

In-Reply-To

<7vfvuts25p.fsf@alter.siamese.dyndns.org>

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---

On 13-08-01 02:21 PM, Junio C Hamano wrote:

> Marc Branchaud <marcnarc@xiplink.com> writes:
> 
>> + The documentation generally follows US English (en_US) norms for spelling
>> + and grammar, although most spelling variations are tolerated.  Just avoid
>> + mixing styles when updating existing text.  If you wish to correct the
>> + English of some of the existing documentation, please see the documentation-
>> + related advice in the Documentation/SubmittingPatches file.
> 
> Is that accurate?  My impression has been:
> 
>     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.
> 
>     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 is
>     simply not worth it.  What we would want is to gradually convert
>     them, with small and easily digestable patches, as a side effect
>     of doing some other _real_ work in the vicinity (e.g. rewriting
>     a paragraph to clarify, while turning en_UK spelling to en_US).

I was focused more on just describing what the documentation should be rather than what it is.  I don't feel strongly about it & I think your phrasing is fine.  I do think the topic needs to be in both CodingGuidelines and SubmittingPatches.  How about this?

(The SubmittingPatches change also switches "I am " to "we are" in the following paragraph, because I found the jump a bit too jarring.)

		M.

 Documentation/CodingGuidelines  |  8 ++++++++
 Documentation/SubmittingPatches | 14 +++++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 559d5f9..8acf557 100644
--- 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).
 
+ 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
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d0a4733..b3477ba 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -65,7 +65,19 @@ 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.
 
-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.  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 simply 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
+also welcome ("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.

-- 
1.8.3.1