[PATCH] Documentation: fix typos in man pages

[PATCH] Documentation: fix typos in man pages

[Øystein Walle]

Signed-off-by: Øystein Walle <oystwa@gmail.com>
---
I thought I'd take part in the typo fixing frenzy :)

I have some other potential typos lines up. Right now the docs refer to both
'filesystem' and 'file system', as well as both 'testsuite' and 'test suite'. I
think words like these are generally split in English but I'm not sure.

There are also some words that I think look better with with a dash, e.g.
'trade-off'. Should I just send these as a patch too instead of jabbering on
about it?

 Documentation/git-check-ignore.txt | 2 +-
 Documentation/git-clone.txt        | 2 +-
 Documentation/git-daemon.txt       | 2 +-
 Documentation/git-diff.txt         | 2 +-
 Documentation/gitcli.txt           | 2 +-
 Documentation/githooks.txt         | 2 +-
 Documentation/gitweb.conf.txt      | 4 ++--
 Documentation/user-manual.txt      | 2 +-
 8 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index d2df487..5354301 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -35,7 +35,7 @@ OPTIONS
 	Read file names from stdin instead of from the command-line.
 
 -z::
-	The output format is modified to be machine-parseable (see
+	The output format is modified to be machine-parsable (see
 	below).  If `--stdin` is also given, input paths are separated
 	with a NUL character instead of a linefeed character.
 
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 450f158..3865658 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -213,7 +213,7 @@ objects from the source repository into a pack in the cloned repository.
 --separate-git-dir=<git dir>::
 	Instead of placing the cloned repository where it is supposed
 	to be, place the cloned repository at the specified directory,
-	then make a filesytem-agnostic Git symbolic link to there.
+	then make a filesystem-agnostic Git symbolic link to there.
 	The result is Git repository can be separated from working
 	tree.
 
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 223f731..a3283e1 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -189,7 +189,7 @@ Git configuration files in that directory are readable by `<user>`.
 	service by exiting with a non-zero status (or to allow it by
 	exiting with a zero status).  It can also look at the $REMOTE_ADDR
 	and $REMOTE_PORT environment variables to learn about the
-	requestor when making this decision.
+	requester when making this decision.
 +
 The external command can optionally write a single line to its
 standard output to be sent to the requestor as an error message when
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 78d6d50..fe42bf6 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -39,7 +39,7 @@ directories. This behavior can be forced by --no-index.
 	commit relative to the named <commit>.  Typically you
 	would want comparison with the latest commit, so if you
 	do not give <commit>, it defaults to HEAD.
-	If HEAD does not exist (e.g. unborned branches) and
+	If HEAD does not exist (e.g. unborn branches) and
 	<commit> is not given, it shows all staged changes.
 	--staged is a synonym of --cached.
 
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 9ac5088..670c285 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -28,7 +28,7 @@ arguments.  Here are the rules:
    they can be disambiguated by placing `--` between them.
    E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work
    tree.  Please show changes between the version I staged in the index
-   and what I have in the work tree for that file". not "show difference
+   and what I have in the work tree for that file", not "show difference
    between the HEAD commit and the work tree as a whole".  You can say
    `git diff HEAD --` to ask for the latter.
 
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index d48bf4d..d954bf6 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -251,7 +251,7 @@ three parameters:
 
  - the name of the ref being updated,
  - the old object name stored in the ref,
- - and the new objectname to be stored in the ref.
+ - and the new object name to be stored in the ref.
 
 A zero exit from the update hook allows the ref to be updated.
 Exiting with a non-zero status prevents 'git-receive-pack'
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 305db63..5945d7a 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -630,13 +630,13 @@ need to set this element to empty list i.e. `[]`.
 
 override::
 	If this field has a true value then the given feature is
-	overriddable, which means that it can be configured
+	overridable, which means that it can be configured
 	(or enabled/disabled) on a per-repository basis.
 +
 Usually given "<feature>" is configurable via the `gitweb.<feature>`
 config variable in the per-repository Git configuration file.
 +
-*Note* that no feature is overriddable by default.
+*Note* that no feature is overridable by default.
 
 sub::
 	Internal detail of implementation.  What is important is that
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index fe723e4..618345d 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3807,7 +3807,7 @@ like so:
 $ git update-index filename
 -------------------------------------------------
 
-but to avoid common mistakes with filename globbing etc, the command
+but to avoid common mistakes with filename globbing etc., the command
 will not normally add totally new entries or remove old entries,
 i.e. it will normally just update existing cache entries.
 
-- 
1.8.2.2

Re: [PATCH] Documentation: fix typos in man pages

[Marc Branchaud]

On 13-07-29 05:15 PM, Øystein Walle wrote:
> Signed-off-by: Øystein Walle <oystwa@gmail.com>
> ---
> I thought I'd take part in the typo fixing frenzy :)
> 
> I have some other potential typos lines up. Right now the docs refer to both
> 'filesystem' and 'file system', as well as both 'testsuite' and 'test suite'. I
> think words like these are generally split in English but I'm not sure.

I generally prefer to see the spaces in these words, otherwise it starts to
look more like German.

But of course English is full of exceptions...

> There are also some words that I think look better with with a dash, e.g.
> 'trade-off'. Should I just send these as a patch too instead of jabbering on
> about it?

I'm indifferent to that.  I guess it depends on the context, so seeing the
patch would help.


I personally don't have a lot of time to investigate the nuances of English.
 However, I desperately hope this list can avoid any linguistic flame wars.
In that spirit, I suggest that anyone posting an orthographic patch (i.e. for
something that isn't an obvious spelling mistake) could helpfully include a
link or two to an explanation of the reasoning for the change.  Especially
for folks who aren't native English speakers, this could help avoid a lot of
back-and-forth.

One general source I've found is the English StackExchange:
	http://english.stackexchange.com/

>  Documentation/git-check-ignore.txt | 2 +-
>  Documentation/git-clone.txt        | 2 +-
>  Documentation/git-daemon.txt       | 2 +-
>  Documentation/git-diff.txt         | 2 +-
>  Documentation/gitcli.txt           | 2 +-
>  Documentation/githooks.txt         | 2 +-
>  Documentation/gitweb.conf.txt      | 4 ++--
>  Documentation/user-manual.txt      | 2 +-
>  8 files changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
> index d2df487..5354301 100644
> --- a/Documentation/git-check-ignore.txt
> +++ b/Documentation/git-check-ignore.txt
> @@ -35,7 +35,7 @@ OPTIONS
>  	Read file names from stdin instead of from the command-line.
>  
>  -z::
> -	The output format is modified to be machine-parseable (see
> +	The output format is modified to be machine-parsable (see

I believe this is a US/UK nuance.  As I've recently stated, I think this kind
of change isn't all that helpful as we're likely to see some well-intentioned
person switch it back sometime in the future.  If the git project could
choose an official English dialect it would go a long way towards mitigating
such churn.

>  	below).  If `--stdin` is also given, input paths are separated
>  	with a NUL character instead of a linefeed character.
>  
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 450f158..3865658 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -213,7 +213,7 @@ objects from the source repository into a pack in the cloned repository.
>  --separate-git-dir=<git dir>::
>  	Instead of placing the cloned repository where it is supposed
>  	to be, place the cloned repository at the specified directory,
> -	then make a filesytem-agnostic Git symbolic link to there.
> +	then make a filesystem-agnostic Git symbolic link to there.
>  	The result is Git repository can be separated from working
>  	tree.
>  
> diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
> index 223f731..a3283e1 100644
> --- a/Documentation/git-daemon.txt
> +++ b/Documentation/git-daemon.txt
> @@ -189,7 +189,7 @@ Git configuration files in that directory are readable by `<user>`.
>  	service by exiting with a non-zero status (or to allow it by
>  	exiting with a zero status).  It can also look at the $REMOTE_ADDR
>  	and $REMOTE_PORT environment variables to learn about the
> -	requestor when making this decision.
> +	requester when making this decision.

Although I prefer the -or form for this word, this really is one of English's
vague areas.  Some words that end with -st definitely take the -er suffix
(tester, jester) but others take the -or suffix (investor).  A bit of
Googling also gave no firm result[1][2].

So I think this change is neither good nor bad.  However, like the
UK/US-isms, I wonder if there's some way to avoid people changing this back
and forth.  But I don't think simply choosing a dialect will help here.

[1]
http://english.stackexchange.com/questions/29254/whats-the-difference-between-requester-and-requestor
[2] http://www.spelling.hemscott.net/ends4.html

>  +
>  The external command can optionally write a single line to its
>  standard output to be sent to the requestor as an error message when
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 78d6d50..fe42bf6 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -39,7 +39,7 @@ directories. This behavior can be forced by --no-index.
>  	commit relative to the named <commit>.  Typically you
>  	would want comparison with the latest commit, so if you
>  	do not give <commit>, it defaults to HEAD.
> -	If HEAD does not exist (e.g. unborned branches) and
> +	If HEAD does not exist (e.g. unborn branches) and
>  	<commit> is not given, it shows all staged changes.
>  	--staged is a synonym of --cached.
>  
> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
> index 9ac5088..670c285 100644
> --- a/Documentation/gitcli.txt
> +++ b/Documentation/gitcli.txt
> @@ -28,7 +28,7 @@ arguments.  Here are the rules:
>     they can be disambiguated by placing `--` between them.
>     E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work
>     tree.  Please show changes between the version I staged in the index
> -   and what I have in the work tree for that file". not "show difference
> +   and what I have in the work tree for that file", not "show difference

Good eyes!

		M.

Re: [PATCH] Documentation: fix typos in man pages

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

> I personally don't have a lot of time to investigate the nuances of English.
> However, I desperately hope this list can avoid any linguistic flame wars.
> In that spirit, I suggest that anyone posting an orthographic patch (i.e. for
> something that isn't an obvious spelling mistake) could helpfully include a
> link or two to an explanation of the reasoning for the change.  Especially
> for folks who aren't native English speakers, this could help avoid a lot of
> back-and-forth.
>
> One general source I've found is the English StackExchange:
> 	http://english.stackexchange.com/

I'd rather not to see any change that turns one accepted form into
another accepted form at all (like "parseable" vs "parsable" in this
patch).  For that purpose, asking "What is parseable" to Google and
seeing if there is a hit is good enough ;-)

I'd of course welcome genuine typofixes, like s/filesytem/filesystem/.

Thanks.

[PATCH] Specify UK English for the documentation source files.

[Marc Branchaud]

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

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

Although I'm Canadian I figured en_CA would be a little too parochial.  I
don't have a strong preference for en_UK over en_US though.

On 13-07-30 11:05 AM, Junio C Hamano wrote:> 
> I'd rather not to see any change that turns one accepted form into
> another accepted form at all (like "parseable" vs "parsable" in this
> patch).  For that purpose, asking "What is parseable" to Google and
> seeing if there is a hit is good enough ;-)

I think choosing a dialect for git will help mitigate such changes.  But
perhaps it's a bit too draconian.

		M.


 Documentation/CodingGuidelines | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 559d5f9..43af82e 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -242,6 +242,9 @@ Writing Documentation:
  processed into HTML and manpages (e.g. git.html and git.1 in the
  same directory).
 
+ The human lanuage of the documentation source files is UK English (en_UK).
+ Please follow UK English norms for spelling and grammar.
+
  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
-- 
1.8.3.1

Re: [PATCH] Specify UK English for the documentation source files.

[Fredrik Gustafsson]

On Tue, Jul 30, 2013 at 11:11:54AM -0400, Marc Branchaud wrote:
> This will hopefully avoid questions over which spelling and grammar should
> be used.  Translators are of course free to create localizations for other
> English dialects.
> 
> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
> ---
> 
> Although I'm Canadian I figured en_CA would be a little too parochial.  I
> don't have a strong preference for en_UK over en_US though.
> 

Since the settings (for example color) use en_US, I suggest _not_ to
specify en_UK as documentation language. Either set en_US or rather
don't set anything at all but go after "google correct". That's the most
populair alternative. For example colour gets 422 000 000 hits and color
gets 2 260 000 000 hits. We should use color even if it's not en_UK.

It's a more pragmatic approach and most git users aren't native english
speakers anyway.

-- 
Med vänliga hälsningar
Fredrik Gustafsson

tel: 0733-608274
e-post: iveqy@iveqy.com

Re: [PATCH] Specify UK English for the documentation source files.

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

> This will hopefully avoid questions over which spelling and grammar should
> be used.  Translators are of course free to create localizations for other
> English dialects.
>
> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
> ---
>
> Although I'm Canadian I figured en_CA would be a little too parochial.  I
> don't have a strong preference for en_UK over en_US though.

If we were to specify one, I would have to say we should standardise
on en_US.  Like it or not, that is the lingua franca in the CS world
(I'd also admit that most of the extra 'u' in words like "behaviour"
are my typoes, not even coming from a conscious decision to choose
en_UK).

I'd appreciate "typofix" patches to address genuine typoes like
"s/filesytem/filesystem/" done separately, so that we do not even
have to get into language bikeshedding.  Even if we did decide to
stick to en_US, the typofix patches and en_US patches should be
separate to ease reviews.

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

[Marc Branchaud]

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

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

A little less stringent now.

 Documentation/CodingGuidelines  |  6 ++++++
 Documentation/SubmittingPatches | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 559d5f9..fc397f3 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -242,6 +242,12 @@ Writing Documentation:
  processed into HTML and manpages (e.g. git.html and git.1 in the
  same directory).
 
+ 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.
+
  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..998e407 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -65,6 +65,16 @@ 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.
 
+Speaking of the documentation, if you are attempting to correct typographical
+or grammatical errors use one patch for indisputably correct changes (e.g.
+"teh" -> "the") and put subjective/stylistic changes in a separate patch.
+This helps to streamline reviews of your patches.  Also, although the
+documentation is mainly written in US English, most non-US spelling variants
+are acceptable.  Patches that change one common spelling to another (such as
+changing "behaviour" to "behavior") are generally not helpful, as
+oftentimes a few months later some generous soul will want to change the
+spelling the other way.
+
 Oh, another thing.  I am 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,
-- 
1.8.3.1

Re: [PATCH v2] Provide some linguistic guidance for the documentation.

[Marc Branchaud]

On 13-08-01 11:10 AM, Marc Branchaud wrote:
> This will hopefully avoid questions over which spelling and grammar should
> be used.  Translators are of course free to create localizations for other

Oops, I should have removed the word "other" here.

		M.

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

Re: [PATCH v2] Provide some linguistic guidance for the documentation.

[Junio C Hamano]

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

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

[Marc Branchaud]

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

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

Re: [PATCH v2] Provide some linguistic guidance for the documentation.

[Jonathan Nieder]

Junio C Hamano wrote:

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

I'm not convinced that would be better, even in an ideal world.

It's certainly useful to have a consistent spelling of each term to
make searching with "grep" easier.  But searches with "grep" do not
work well with line breaks anyway, and search engines for larger
collections of documents seem to know about the usual spelling
variants (along with knowing about stemming, etc).  Unless we are
planning to provide a separate en_GB translation, it seems unfortunate
to consistently have everything spelled in the natural way for one
group of people and in an unnatural way for another, just in the name
of having a convention.

I am not sure it makes sense for the documentation to say "A huge
disruptive patch of such-and-such specific kind of no immediate
benefit is unwelcome".  Isn't there some more general principle that
implies that?  Or the CodingGuidelines could simply say

	The documentation uses a mixture of U.S. and British English.

My two cents,
Jonathan

Re: [PATCH v2] Provide some linguistic guidance for the documentation.

[Marc Branchaud]

On 13-08-02 02:25 AM, Jonathan Nieder wrote:
> Junio C Hamano wrote:
>
>> 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.
>
> I'm not convinced that would be better, even in an ideal world.
>
> It's certainly useful to have a consistent spelling of each term to
> make searching with "grep" easier.  But searches with "grep" do not
> work well with line breaks anyway, and search engines for larger
> collections of documents seem to know about the usual spelling
> variants (along with knowing about stemming, etc).  Unless we are
> planning to provide a separate en_GB translation, it seems unfortunate
> to consistently have everything spelled in the natural way for one
> group of people and in an unnatural way for another, just in the name
> of having a convention.

Personally I find it distracting when the norms are mixed.  I don't 
think the current mishmash pleases anyone (as evidenced by the steady 
stream of patches that change spellings).

> I am not sure it makes sense for the documentation to say "A huge
> disruptive patch of such-and-such specific kind of no immediate
> benefit is unwelcome".  Isn't there some more general principle that
> implies that?  Or the CodingGuidelines could simply say
>
> 	The documentation uses a mixture of U.S. and British English.

I'm hoping this patch will help the list avoid seeing patches that 
merely flip between alternate spellings.  (Perhaps the commit message 
should state this?)  I think it's important to be clear about the kind 
of work the git community wants to see.  So I don't think that single 
sentence by itself would be helpful.

In the case of alternate spellings in the documentation, I think there's 
a temptation to create a blanket patch that "fixes" lots of perceived 
misspellings since such changes are mere typographic tweaks.  It's a bit 
easy to overlook the disruptive nature of such a patch, so IMO it bears 
repeating here.

Are you suggesting maybe that there should be no "official" dialect? 
That the guidance should simply say that we don't want to see patches 
that merely flip between alternate spellings (because we don't really care)?

		M.