{"thread":{"id":"34562","subject":"[PATCH] Documentation: fix typos in man pages","startedAt":"2013-07-29T21:15:43Z","lastAt":"2013-08-02T14:16:34Z","messageCount":12,"participants":["Øystein Walle","Marc Branchaud","Junio C Hamano","Fredrik Gustafsson","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"224264","messageId":"1375132543-20361-1-git-send-email-oystwa@gmail.com","threadId":"34562","inReplyTo":null,"subject":"[PATCH] Documentation: fix typos in man pages","fromName":"Øystein Walle","fromEmail":"oystwa@gmail.com","sentAt":"2013-07-29T21:15:43Z","receivedAt":"2013-07-29T21:15:43Z","isPatch":true,"sender":{"key":"oystwa@gmail.com","avatar":"https://avatars.githubusercontent.com/u/794585?v=4"},"body":"Signed-off-by: Øystein Walle <oystwa@gmail.com>\n---\nI thought I'd take part in the typo fixing frenzy :)\n\nI have some other potential typos lines up. Right now the docs refer to both\n'filesystem' and 'file system', as well as both 'testsuite' and 'test suite'. I\nthink words like these are generally split in English but I'm not sure.\n\nThere are also some words that I think look better with with a dash, e.g.\n'trade-off'. Should I just send these as a patch too instead of jabbering on\nabout it?\n\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-clone.txt        | 2 +-\n Documentation/git-daemon.txt       | 2 +-\n Documentation/git-diff.txt         | 2 +-\n Documentation/gitcli.txt           | 2 +-\n Documentation/githooks.txt         | 2 +-\n Documentation/gitweb.conf.txt      | 4 ++--\n Documentation/user-manual.txt      | 2 +-\n 8 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\nindex d2df487..5354301 100644\n--- a/Documentation/git-check-ignore.txt\n+++ b/Documentation/git-check-ignore.txt\n@@ -35,7 +35,7 @@ OPTIONS\n \tRead file names from stdin instead of from the command-line.\n \n -z::\n-\tThe output format is modified to be machine-parseable (see\n+\tThe output format is modified to be machine-parsable (see\n \tbelow).  If `--stdin` is also given, input paths are separated\n \twith a NUL character instead of a linefeed character.\n \ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 450f158..3865658 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -213,7 +213,7 @@ objects from the source repository into a pack in the cloned repository.\n --separate-git-dir=<git dir>::\n \tInstead of placing the cloned repository where it is supposed\n \tto be, place the cloned repository at the specified directory,\n-\tthen make a filesytem-agnostic Git symbolic link to there.\n+\tthen make a filesystem-agnostic Git symbolic link to there.\n \tThe result is Git repository can be separated from working\n \ttree.\n \ndiff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\nindex 223f731..a3283e1 100644\n--- a/Documentation/git-daemon.txt\n+++ b/Documentation/git-daemon.txt\n@@ -189,7 +189,7 @@ Git configuration files in that directory are readable by `<user>`.\n \tservice by exiting with a non-zero status (or to allow it by\n \texiting with a zero status).  It can also look at the $REMOTE_ADDR\n \tand $REMOTE_PORT environment variables to learn about the\n-\trequestor when making this decision.\n+\trequester when making this decision.\n +\n The external command can optionally write a single line to its\n standard output to be sent to the requestor as an error message when\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 78d6d50..fe42bf6 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -39,7 +39,7 @@ directories. This behavior can be forced by --no-index.\n \tcommit relative to the named <commit>.  Typically you\n \twould want comparison with the latest commit, so if you\n \tdo not give <commit>, it defaults to HEAD.\n-\tIf HEAD does not exist (e.g. unborned branches) and\n+\tIf HEAD does not exist (e.g. unborn branches) and\n \t<commit> is not given, it shows all staged changes.\n \t--staged is a synonym of --cached.\n \ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 9ac5088..670c285 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -28,7 +28,7 @@ arguments.  Here are the rules:\n    they can be disambiguated by placing `--` between them.\n    E.g. `git diff -- HEAD` is, \"I have a file called HEAD in my work\n    tree.  Please show changes between the version I staged in the index\n-   and what I have in the work tree for that file\". not \"show difference\n+   and what I have in the work tree for that file\", not \"show difference\n    between the HEAD commit and the work tree as a whole\".  You can say\n    `git diff HEAD --` to ask for the latter.\n \ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex d48bf4d..d954bf6 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -251,7 +251,7 @@ three parameters:\n \n  - the name of the ref being updated,\n  - the old object name stored in the ref,\n- - and the new objectname to be stored in the ref.\n+ - and the new object name to be stored in the ref.\n \n A zero exit from the update hook allows the ref to be updated.\n Exiting with a non-zero status prevents 'git-receive-pack'\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nindex 305db63..5945d7a 100644\n--- a/Documentation/gitweb.conf.txt\n+++ b/Documentation/gitweb.conf.txt\n@@ -630,13 +630,13 @@ need to set this element to empty list i.e. `[]`.\n \n override::\n \tIf this field has a true value then the given feature is\n-\toverriddable, which means that it can be configured\n+\toverridable, which means that it can be configured\n \t(or enabled/disabled) on a per-repository basis.\n +\n Usually given \"<feature>\" is configurable via the `gitweb.<feature>`\n config variable in the per-repository Git configuration file.\n +\n-*Note* that no feature is overriddable by default.\n+*Note* that no feature is overridable by default.\n \n sub::\n \tInternal detail of implementation.  What is important is that\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex fe723e4..618345d 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3807,7 +3807,7 @@ like so:\n $ git update-index filename\n -------------------------------------------------\n \n-but to avoid common mistakes with filename globbing etc, the command\n+but to avoid common mistakes with filename globbing etc., the command\n will not normally add totally new entries or remove old entries,\n i.e. it will normally just update existing cache entries.\n \n-- \n1.8.2.2\n"},{"id":"224295","messageId":"51F7D2FA.7020208@xiplink.com","threadId":"34562","inReplyTo":"1375132543-20361-1-git-send-email-oystwa@gmail.com","subject":"Re: [PATCH] Documentation: fix typos in man pages","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2013-07-30T14:51:38Z","receivedAt":"2013-07-30T14:51:38Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 13-07-29 05:15 PM, Øystein Walle wrote:\n> Signed-off-by: Øystein Walle <oystwa@gmail.com>\n> ---\n> I thought I'd take part in the typo fixing frenzy :)\n> \n> I have some other potential typos lines up. Right now the docs refer to both\n> 'filesystem' and 'file system', as well as both 'testsuite' and 'test suite'. I\n> think words like these are generally split in English but I'm not sure.\n\nI generally prefer to see the spaces in these words, otherwise it starts to\nlook more like German.\n\nBut of course English is full of exceptions...\n\n> There are also some words that I think look better with with a dash, e.g.\n> 'trade-off'. Should I just send these as a patch too instead of jabbering on\n> about it?\n\nI'm indifferent to that.  I guess it depends on the context, so seeing the\npatch would help.\n\n\nI personally don't have a lot of time to investigate the nuances of English.\n However, I desperately hope this list can avoid any linguistic flame wars.\nIn that spirit, I suggest that anyone posting an orthographic patch (i.e. for\nsomething that isn't an obvious spelling mistake) could helpfully include a\nlink or two to an explanation of the reasoning for the change.  Especially\nfor folks who aren't native English speakers, this could help avoid a lot of\nback-and-forth.\n\nOne general source I've found is the English StackExchange:\n\thttp://english.stackexchange.com/\n\n>  Documentation/git-check-ignore.txt | 2 +-\n>  Documentation/git-clone.txt        | 2 +-\n>  Documentation/git-daemon.txt       | 2 +-\n>  Documentation/git-diff.txt         | 2 +-\n>  Documentation/gitcli.txt           | 2 +-\n>  Documentation/githooks.txt         | 2 +-\n>  Documentation/gitweb.conf.txt      | 4 ++--\n>  Documentation/user-manual.txt      | 2 +-\n>  8 files changed, 9 insertions(+), 9 deletions(-)\n> \n> diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\n> index d2df487..5354301 100644\n> --- a/Documentation/git-check-ignore.txt\n> +++ b/Documentation/git-check-ignore.txt\n> @@ -35,7 +35,7 @@ OPTIONS\n>  \tRead file names from stdin instead of from the command-line.\n>  \n>  -z::\n> -\tThe output format is modified to be machine-parseable (see\n> +\tThe output format is modified to be machine-parsable (see\n\nI believe this is a US/UK nuance.  As I've recently stated, I think this kind\nof change isn't all that helpful as we're likely to see some well-intentioned\nperson switch it back sometime in the future.  If the git project could\nchoose an official English dialect it would go a long way towards mitigating\nsuch churn.\n\n>  \tbelow).  If `--stdin` is also given, input paths are separated\n>  \twith a NUL character instead of a linefeed character.\n>  \n> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\n> index 450f158..3865658 100644\n> --- a/Documentation/git-clone.txt\n> +++ b/Documentation/git-clone.txt\n> @@ -213,7 +213,7 @@ objects from the source repository into a pack in the cloned repository.\n>  --separate-git-dir=<git dir>::\n>  \tInstead of placing the cloned repository where it is supposed\n>  \tto be, place the cloned repository at the specified directory,\n> -\tthen make a filesytem-agnostic Git symbolic link to there.\n> +\tthen make a filesystem-agnostic Git symbolic link to there.\n>  \tThe result is Git repository can be separated from working\n>  \ttree.\n>  \n> diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\n> index 223f731..a3283e1 100644\n> --- a/Documentation/git-daemon.txt\n> +++ b/Documentation/git-daemon.txt\n> @@ -189,7 +189,7 @@ Git configuration files in that directory are readable by `<user>`.\n>  \tservice by exiting with a non-zero status (or to allow it by\n>  \texiting with a zero status).  It can also look at the $REMOTE_ADDR\n>  \tand $REMOTE_PORT environment variables to learn about the\n> -\trequestor when making this decision.\n> +\trequester when making this decision.\n\nAlthough I prefer the -or form for this word, this really is one of English's\nvague areas.  Some words that end with -st definitely take the -er suffix\n(tester, jester) but others take the -or suffix (investor).  A bit of\nGoogling also gave no firm result[1][2].\n\nSo I think this change is neither good nor bad.  However, like the\nUK/US-isms, I wonder if there's some way to avoid people changing this back\nand forth.  But I don't think simply choosing a dialect will help here.\n\n[1]\nhttp://english.stackexchange.com/questions/29254/whats-the-difference-between-requester-and-requestor\n[2] http://www.spelling.hemscott.net/ends4.html\n\n>  +\n>  The external command can optionally write a single line to its\n>  standard output to be sent to the requestor as an error message when\n> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> index 78d6d50..fe42bf6 100644\n> --- a/Documentation/git-diff.txt\n> +++ b/Documentation/git-diff.txt\n> @@ -39,7 +39,7 @@ directories. This behavior can be forced by --no-index.\n>  \tcommit relative to the named <commit>.  Typically you\n>  \twould want comparison with the latest commit, so if you\n>  \tdo not give <commit>, it defaults to HEAD.\n> -\tIf HEAD does not exist (e.g. unborned branches) and\n> +\tIf HEAD does not exist (e.g. unborn branches) and\n>  \t<commit> is not given, it shows all staged changes.\n>  \t--staged is a synonym of --cached.\n>  \n> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\n> index 9ac5088..670c285 100644\n> --- a/Documentation/gitcli.txt\n> +++ b/Documentation/gitcli.txt\n> @@ -28,7 +28,7 @@ arguments.  Here are the rules:\n>     they can be disambiguated by placing `--` between them.\n>     E.g. `git diff -- HEAD` is, \"I have a file called HEAD in my work\n>     tree.  Please show changes between the version I staged in the index\n> -   and what I have in the work tree for that file\". not \"show difference\n> +   and what I have in the work tree for that file\", not \"show difference\n\nGood eyes!\n\n\t\tM.\n"},{"id":"224298","messageId":"7vehagxf3q.fsf@alter.siamese.dyndns.org","threadId":"34562","inReplyTo":"51F7D2FA.7020208@xiplink.com","subject":"Re: [PATCH] Documentation: fix typos in man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-07-30T15:05:45Z","receivedAt":"2013-07-30T15:05:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud <marcnarc@xiplink.com> writes:\n\n> I personally don't have a lot of time to investigate the nuances of English.\n> However, I desperately hope this list can avoid any linguistic flame wars.\n> In that spirit, I suggest that anyone posting an orthographic patch (i.e. for\n> something that isn't an obvious spelling mistake) could helpfully include a\n> link or two to an explanation of the reasoning for the change.  Especially\n> for folks who aren't native English speakers, this could help avoid a lot of\n> back-and-forth.\n>\n> One general source I've found is the English StackExchange:\n> \thttp://english.stackexchange.com/\n\nI'd rather not to see any change that turns one accepted form into\nanother accepted form at all (like \"parseable\" vs \"parsable\" in this\npatch).  For that purpose, asking \"What is parseable\" to Google and\nseeing if there is a hit is good enough ;-)\n\nI'd of course welcome genuine typofixes, like s/filesytem/filesystem/.\n\nThanks.\n"},{"id":"224299","messageId":"1375197114-10742-1-git-send-email-marcnarc@xiplink.com","threadId":"34562","inReplyTo":"51F7D2FA.7020208@xiplink.com","subject":"[PATCH] Specify UK English for the documentation source files.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2013-07-30T15:11:54Z","receivedAt":"2013-07-30T15:11:54Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"This will hopefully avoid questions over which spelling and grammar should\nbe used.  Translators are of course free to create localizations for other\nEnglish dialects.\n\nSigned-off-by: Marc Branchaud <marcnarc@xiplink.com>\n---\n\nAlthough I'm Canadian I figured en_CA would be a little too parochial.  I\ndon't have a strong preference for en_UK over en_US though.\n\nOn 13-07-30 11:05 AM, Junio C Hamano wrote:> \n> I'd rather not to see any change that turns one accepted form into\n> another accepted form at all (like \"parseable\" vs \"parsable\" in this\n> patch).  For that purpose, asking \"What is parseable\" to Google and\n> seeing if there is a hit is good enough ;-)\n\nI think choosing a dialect for git will help mitigate such changes.  But\nperhaps it's a bit too draconian.\n\n\t\tM.\n\n\n Documentation/CodingGuidelines | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 559d5f9..43af82e 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -242,6 +242,9 @@ Writing Documentation:\n  processed into HTML and manpages (e.g. git.html and git.1 in the\n  same directory).\n \n+ The human lanuage of the documentation source files is UK English (en_UK).\n+ Please follow UK English norms for spelling and grammar.\n+\n  Every user-visible change should be reflected in the documentation.\n  The same general rule as for code applies -- imitate the existing\n  conventions.  A few commented examples follow to provide reference\n-- \n1.8.3.1\n"},{"id":"224303","messageId":"20130730155228.GB19369@paksenarrion.iveqy.com","threadId":"34562","inReplyTo":"1375197114-10742-1-git-send-email-marcnarc@xiplink.com","subject":"Re: [PATCH] Specify UK English for the documentation source files.","fromName":"Fredrik Gustafsson","fromEmail":"iveqy@iveqy.com","sentAt":"2013-07-30T15:52:28Z","receivedAt":"2013-07-30T15:52:28Z","isPatch":true,"sender":{"key":"iveqy@iveqy.com","avatar":"https://avatars.githubusercontent.com/u/761743?v=4"},"body":"On Tue, Jul 30, 2013 at 11:11:54AM -0400, Marc Branchaud wrote:\n> This will hopefully avoid questions over which spelling and grammar should\n> be used.  Translators are of course free to create localizations for other\n> English dialects.\n> \n> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>\n> ---\n> \n> Although I'm Canadian I figured en_CA would be a little too parochial.  I\n> don't have a strong preference for en_UK over en_US though.\n> \n\nSince the settings (for example color) use en_US, I suggest _not_ to\nspecify en_UK as documentation language. Either set en_US or rather\ndon't set anything at all but go after \"google correct\". That's the most\npopulair alternative. For example colour gets 422 000 000 hits and color\ngets 2 260 000 000 hits. We should use color even if it's not en_UK.\n\nIt's a more pragmatic approach and most git users aren't native english\nspeakers anyway.\n\n-- \nMed vänliga hälsningar\nFredrik Gustafsson\n\ntel: 0733-608274\ne-post: iveqy@iveqy.com\n"},{"id":"224305","messageId":"7vppu0vw4m.fsf@alter.siamese.dyndns.org","threadId":"34562","inReplyTo":"1375197114-10742-1-git-send-email-marcnarc@xiplink.com","subject":"Re: [PATCH] Specify UK English for the documentation source files.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-07-30T16:40:57Z","receivedAt":"2013-07-30T16:40:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud <marcnarc@xiplink.com> writes:\n\n> This will hopefully avoid questions over which spelling and grammar should\n> be used.  Translators are of course free to create localizations for other\n> English dialects.\n>\n> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>\n> ---\n>\n> Although I'm Canadian I figured en_CA would be a little too parochial.  I\n> don't have a strong preference for en_UK over en_US though.\n\nIf we were to specify one, I would have to say we should standardise\non en_US.  Like it or not, that is the lingua franca in the CS world\n(I'd also admit that most of the extra 'u' in words like \"behaviour\"\nare my typoes, not even coming from a conscious decision to choose\nen_UK).\n\nI'd appreciate \"typofix\" patches to address genuine typoes like\n\"s/filesytem/filesystem/\" done separately, so that we do not even\nhave to get into language bikeshedding.  Even if we did decide to\nstick to en_US, the typofix patches and en_US patches should be\nseparate to ease reviews.\n"},{"id":"224419","messageId":"1375369825-28636-1-git-send-email-marcnarc@xiplink.com","threadId":"34562","inReplyTo":"1375197114-10742-1-git-send-email-marcnarc@xiplink.com","subject":"[PATCH v2] Provide some linguistic guidance for the documentation.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2013-08-01T15:10:25Z","receivedAt":"2013-08-01T15:10:25Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"This will hopefully avoid questions over which spelling and grammar should\nbe used.  Translators are of course free to create localizations for other\nspecific English dialects.\n\nSigned-off-by: Marc Branchaud <marcnarc@xiplink.com>\n---\n\nA little less stringent now.\n\n Documentation/CodingGuidelines  |  6 ++++++\n Documentation/SubmittingPatches | 10 ++++++++++\n 2 files changed, 16 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 559d5f9..fc397f3 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -242,6 +242,12 @@ Writing Documentation:\n  processed into HTML and manpages (e.g. git.html and git.1 in the\n  same directory).\n \n+ The documentation generally follows US English (en_US) norms for spelling\n+ and grammar, although most spelling variations are tolerated.  Just avoid\n+ mixing styles when updating existing text.  If you wish to correct the\n+ English of some of the existing documentation, please see the documentation-\n+ related advice in the Documentation/SubmittingPatches file.\n+\n  Every user-visible change should be reflected in the documentation.\n  The same general rule as for code applies -- imitate the existing\n  conventions.  A few commented examples follow to provide reference\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d0a4733..998e407 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -65,6 +65,16 @@ feature does not trigger when it shouldn't.  Also make sure that the\n test suite passes after your commit.  Do not forget to update the\n documentation to describe the updated behaviour.\n \n+Speaking of the documentation, if you are attempting to correct typographical\n+or grammatical errors use one patch for indisputably correct changes (e.g.\n+\"teh\" -> \"the\") and put subjective/stylistic changes in a separate patch.\n+This helps to streamline reviews of your patches.  Also, although the\n+documentation is mainly written in US English, most non-US spelling variants\n+are acceptable.  Patches that change one common spelling to another (such as\n+changing \"behaviour\" to \"behavior\") are generally not helpful, as\n+oftentimes a few months later some generous soul will want to change the\n+spelling the other way.\n+\n Oh, another thing.  I am picky about whitespaces.  Make sure your\n changes do not trigger errors with the sample pre-commit hook shipped\n in templates/hooks--pre-commit.  To help ensure this does not happen,\n-- \n1.8.3.1\n"},{"id":"224420","messageId":"51FA7B62.2040505@xiplink.com","threadId":"34562","inReplyTo":"1375369825-28636-1-git-send-email-marcnarc@xiplink.com","subject":"Re: [PATCH v2] Provide some linguistic guidance for the documentation.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2013-08-01T15:14:42Z","receivedAt":"2013-08-01T15:14:42Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 13-08-01 11:10 AM, Marc Branchaud wrote:\n> This will hopefully avoid questions over which spelling and grammar should\n> be used.  Translators are of course free to create localizations for other\n\nOops, I should have removed the word \"other\" here.\n\n\t\tM.\n\n> specific English dialects.\n> \n> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>\n"},{"id":"224426","messageId":"7vfvuts25p.fsf@alter.siamese.dyndns.org","threadId":"34562","inReplyTo":"1375369825-28636-1-git-send-email-marcnarc@xiplink.com","subject":"Re: [PATCH v2] Provide some linguistic guidance for the documentation.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-08-01T18:21:06Z","receivedAt":"2013-08-01T18:21:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud <marcnarc@xiplink.com> writes:\n\n> + The documentation generally follows US English (en_US) norms for spelling\n> + and grammar, although most spelling variations are tolerated.  Just avoid\n> + mixing styles when updating existing text.  If you wish to correct the\n> + English of some of the existing documentation, please see the documentation-\n> + related advice in the Documentation/SubmittingPatches file.\n\nIs that accurate?  My impression has been:\n\n    The documentation liberally mixes US and UK English (en_US/UK)\n    norms for spelling and grammar, which is somewhat unfortunate.\n    In an ideal world, it would have been better if it consistently\n    used only one and not the other, and we would have picked en_US.\n\n    A huge patch that touches the files all over the place only to\n    correct the inconsistency is not welcome, though.  Potential\n    clashes with other changes that can result from such a patch is\n    simply not worth it.  What we would want is to gradually convert\n    them, with small and easily digestable patches, as a side effect\n    of doing some other _real_ work in the vicinity (e.g. rewriting\n    a paragraph to clarify, while turning en_UK spelling to en_US).\n"},{"id":"224428","messageId":"1375382994-30010-1-git-send-email-marcnarc@xiplink.com","threadId":"34562","inReplyTo":"7vfvuts25p.fsf@alter.siamese.dyndns.org","subject":"[PATCH v3] Provide some linguistic guidance for the documentation.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2013-08-01T18:49:54Z","receivedAt":"2013-08-01T18:49:54Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"This will hopefully avoid questions over which spelling and grammar should\nbe used.  Translators are of course free to create localizations for\nspecific English dialects.\n\nSigned-off-by: Marc Branchaud <marcnarc@xiplink.com>\n---\n\nOn 13-08-01 02:21 PM, Junio C Hamano wrote:\n> Marc Branchaud <marcnarc@xiplink.com> writes:\n> \n>> + The documentation generally follows US English (en_US) norms for spelling\n>> + and grammar, although most spelling variations are tolerated.  Just avoid\n>> + mixing styles when updating existing text.  If you wish to correct the\n>> + English of some of the existing documentation, please see the documentation-\n>> + related advice in the Documentation/SubmittingPatches file.\n> \n> Is that accurate?  My impression has been:\n> \n>     The documentation liberally mixes US and UK English (en_US/UK)\n>     norms for spelling and grammar, which is somewhat unfortunate.\n>     In an ideal world, it would have been better if it consistently\n>     used only one and not the other, and we would have picked en_US.\n> \n>     A huge patch that touches the files all over the place only to\n>     correct the inconsistency is not welcome, though.  Potential\n>     clashes with other changes that can result from such a patch is\n>     simply not worth it.  What we would want is to gradually convert\n>     them, with small and easily digestable patches, as a side effect\n>     of doing some other _real_ work in the vicinity (e.g. rewriting\n>     a paragraph to clarify, while turning en_UK spelling to en_US).\n\nI 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?\n\n(The SubmittingPatches change also switches \"I am \" to \"we are\" in the following paragraph, because I found the jump a bit too jarring.)\n\n\t\tM.\n\n\n Documentation/CodingGuidelines  |  8 ++++++++\n Documentation/SubmittingPatches | 14 +++++++++++++-\n 2 files changed, 21 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 559d5f9..8acf557 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -242,6 +242,14 @@ Writing Documentation:\n  processed into HTML and manpages (e.g. git.html and git.1 in the\n  same directory).\n \n+ The documentation liberally mixes US and UK English (en_US/UK)\n+ norms for spelling and grammar, which is somewhat unfortunate.\n+ In an ideal world, it would have been better if it consistently\n+ used only one and not the other, and we would have picked en_US.\n+ (If you wish to correct the English of some of the existing\n+ documentation, please see the documentation-related advice in the\n+ Documentation/SubmittingPatches file.)\n+\n  Every user-visible change should be reflected in the documentation.\n  The same general rule as for code applies -- imitate the existing\n  conventions.  A few commented examples follow to provide reference\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d0a4733..b3477ba 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -65,7 +65,19 @@ feature does not trigger when it shouldn't.  Also make sure that the\n test suite passes after your commit.  Do not forget to update the\n documentation to describe the updated behaviour.\n \n-Oh, another thing.  I am picky about whitespaces.  Make sure your\n+Speaking of the documentation, it is currently a liberal mixture of US\n+and UK English norms for spelling and grammar.  A huge patch that\n+touches the files all over the place only to correct the inconsistency\n+is not welcome, though.  Potential clashes with other changes that can\n+result from such a patch are simply not worth it.  We prefer to\n+gradually reconcile the inconsistencies (in favor of US English), with\n+small and easily digestible patches, as a side effect of doing some\n+other real work in the vicinity (e.g. rewriting a paragraph for clarity,\n+while turning en_UK spelling to en_US).  Obvious typographical fixes are\n+also welcome (\"teh -> \"the\"), preferably submitted as independent patches\n+separate from other documentation changes.\n+\n+Oh, another thing.  We are picky about whitespaces.  Make sure your\n changes do not trigger errors with the sample pre-commit hook shipped\n in templates/hooks--pre-commit.  To help ensure this does not happen,\n run git diff --check on your changes before you commit.\n-- \n1.8.3.1\n"},{"id":"224443","messageId":"20130802062511.GA3013@elie.Belkin","threadId":"34562","inReplyTo":"7vfvuts25p.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2] Provide some linguistic guidance for the documentation.","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-08-02T06:25:41Z","receivedAt":"2013-08-02T06:25:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> Is that accurate?  My impression has been:\n>\n>     The documentation liberally mixes US and UK English (en_US/UK)\n>     norms for spelling and grammar, which is somewhat unfortunate.\n>     In an ideal world, it would have been better if it consistently\n>     used only one and not the other, and we would have picked en_US.\n\nI'm not convinced that would be better, even in an ideal world.\n\nIt's certainly useful to have a consistent spelling of each term to\nmake searching with \"grep\" easier.  But searches with \"grep\" do not\nwork well with line breaks anyway, and search engines for larger\ncollections of documents seem to know about the usual spelling\nvariants (along with knowing about stemming, etc).  Unless we are\nplanning to provide a separate en_GB translation, it seems unfortunate\nto consistently have everything spelled in the natural way for one\ngroup of people and in an unnatural way for another, just in the name\nof having a convention.\n\nI am not sure it makes sense for the documentation to say \"A huge\ndisruptive patch of such-and-such specific kind of no immediate\nbenefit is unwelcome\".  Isn't there some more general principle that\nimplies that?  Or the CodingGuidelines could simply say\n\n\tThe documentation uses a mixture of U.S. and British English.\n\nMy two cents,\nJonathan\n"},{"id":"224451","messageId":"51FBBF42.5040102@xiplink.com","threadId":"34562","inReplyTo":"20130802062511.GA3013@elie.Belkin","subject":"Re: [PATCH v2] Provide some linguistic guidance for the documentation.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2013-08-02T14:16:34Z","receivedAt":"2013-08-02T14:16:34Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 13-08-02 02:25 AM, Jonathan Nieder wrote:\n> Junio C Hamano wrote:\n>\n>> Is that accurate?  My impression has been:\n>>\n>>      The documentation liberally mixes US and UK English (en_US/UK)\n>>      norms for spelling and grammar, which is somewhat unfortunate.\n>>      In an ideal world, it would have been better if it consistently\n>>      used only one and not the other, and we would have picked en_US.\n>\n> I'm not convinced that would be better, even in an ideal world.\n>\n> It's certainly useful to have a consistent spelling of each term to\n> make searching with \"grep\" easier.  But searches with \"grep\" do not\n> work well with line breaks anyway, and search engines for larger\n> collections of documents seem to know about the usual spelling\n> variants (along with knowing about stemming, etc).  Unless we are\n> planning to provide a separate en_GB translation, it seems unfortunate\n> to consistently have everything spelled in the natural way for one\n> group of people and in an unnatural way for another, just in the name\n> of having a convention.\n\nPersonally I find it distracting when the norms are mixed.  I don't \nthink the current mishmash pleases anyone (as evidenced by the steady \nstream of patches that change spellings).\n\n> I am not sure it makes sense for the documentation to say \"A huge\n> disruptive patch of such-and-such specific kind of no immediate\n> benefit is unwelcome\".  Isn't there some more general principle that\n> implies that?  Or the CodingGuidelines could simply say\n>\n> \tThe documentation uses a mixture of U.S. and British English.\n\nI'm hoping this patch will help the list avoid seeing patches that \nmerely flip between alternate spellings.  (Perhaps the commit message \nshould state this?)  I think it's important to be clear about the kind \nof work the git community wants to see.  So I don't think that single \nsentence by itself would be helpful.\n\nIn the case of alternate spellings in the documentation, I think there's \na temptation to create a blanket patch that \"fixes\" lots of perceived \nmisspellings since such changes are mere typographic tweaks.  It's a bit \neasy to overlook the disruptive nature of such a patch, so IMO it bears \nrepeating here.\n\nAre you suggesting maybe that there should be no \"official\" dialect? \nThat the guidance should simply say that we don't want to see patches \nthat merely flip between alternate spellings (because we don't really care)?\n\n\t\tM.\n"}]}