{"thread":{"id":"45174","subject":"[PATCH] git-check-ref-format: fix typo in man page","startedAt":"2017-02-18T22:47:36Z","lastAt":"2017-02-19T22:14:11Z","messageCount":6,"participants":["Damien Regad","Jacob Keller","Philip Oakley","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"312060","messageId":"c27d7861-b161-a3eb-fcfc-bf766fc7b20b@gmail.com","threadId":"45174","inReplyTo":null,"subject":"[PATCH] git-check-ref-format: fix typo in man page","fromName":"Damien Regad","fromEmail":"dregad@mantisbt.org","sentAt":"2017-02-18T22:47:21Z","receivedAt":"2017-02-18T22:47:36Z","isPatch":true,"sender":{"key":"dregad@mantisbt.org","avatar":"https://avatars.githubusercontent.com/u/449891?v=4"},"body":"\n---\n Documentation/git-check-ref-format.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-check-ref-format.txt\nb/Documentation/git-check-ref-format.txt\nindex 8611a99..377c85a 100644\n--- a/Documentation/git-check-ref-format.txt\n+++ b/Documentation/git-check-ref-format.txt\n@@ -100,7 +100,7 @@ OPTIONS\n --normalize::\n \tNormalize 'refname' by removing any leading slash (`/`)\n \tcharacters and collapsing runs of adjacent slashes between\n-\tname components into a single slash. Iff the normalized\n+\tname components into a single slash. If the normalized\n \trefname is valid then print it to standard output and exit\n \twith a status of 0. (`--print` is a deprecated way to spell\n \t`--normalize`.)\n-- \n2.7.4\n\n\n"},{"id":"312063","messageId":"CA+P7+xrNb8xdbjFFAVVRDNe4Mho764PKYCbrLWmu4ykzU9A5dA@mail.gmail.com","threadId":"45174","inReplyTo":"c27d7861-b161-a3eb-fcfc-bf766fc7b20b@gmail.com","subject":"Re: [PATCH] git-check-ref-format: fix typo in man page","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2017-02-19T00:17:22Z","receivedAt":"2017-02-19T00:17:50Z","isPatch":true,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Sat, Feb 18, 2017 at 2:47 PM, Damien Regad wrote:\n>\n> ---\n> Documentation/git-check-ref-format.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-check-ref-format.txt\n> b/Documentation/git-check-ref-format.txt\n> index 8611a99..377c85a 100644\n> --- a/Documentation/git-check-ref-format.txt\n> +++ b/Documentation/git-check-ref-format.txt\n> @@ -100,7 +100,7 @@ OPTIONS\n> --normalize::\n> Normalize 'refname' by removing any leading slash (`/`)\n> characters and collapsing runs of adjacent slashes between\n> - name components into a single slash. Iff the normalized\n> + name components into a single slash. If the normalized\n\nI think this is a good change, but I do know in some contexts, \"Iff\"\nis used intentionally to mean \"If and only if\". It's somewhat unlikely\nthat's what was going on here, and I don't think we need to be that\npedantic in our help documentation anyway.\n\nThanks,\nJake\n\n> refname is valid then print it to standard output and exit\n> with a status of 0. (`--print` is a deprecated way to spell\n> `--normalize`.)\n> --\n> 2.7.4\n>\n>\n"},{"id":"312065","messageId":"2116CBFFB78A482D8FA176BC680B3B9C@PhilipOakley","threadId":"45174","inReplyTo":"c27d7861-b161-a3eb-fcfc-bf766fc7b20b@gmail.com","subject":"Re: [PATCH] git-check-ref-format: fix typo in man page","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2017-02-19T00:20:39Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Damien Regad\" \n> ---\n> Documentation/git-check-ref-format.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-check-ref-format.txt\n> b/Documentation/git-check-ref-format.txt\n> index 8611a99..377c85a 100644\n> --- a/Documentation/git-check-ref-format.txt\n> +++ b/Documentation/git-check-ref-format.txt\n> @@ -100,7 +100,7 @@ OPTIONS\n> --normalize::\n> Normalize 'refname' by removing any leading slash (`/`)\n> characters and collapsing runs of adjacent slashes between\n> - name components into a single slash. Iff the normalized\n> + name components into a single slash. If the normalized\n> refname is valid then print it to standard output and exit\n> with a status of 0. (`--print` is a deprecated way to spell\n> `--normalize`.)\n> -- \n\nCould that be an 'iff' == 'If and only if' (which is common in mathematics)? \nStill could be spelling error though.\n--\nPhilip \n\n"},{"id":"312069","messageId":"20170219022756.pwxhjluxizuedf46@sigill.intra.peff.net","threadId":"45174","inReplyTo":"2116CBFFB78A482D8FA176BC680B3B9C@PhilipOakley","subject":"Re: [PATCH] git-check-ref-format: fix typo in man page","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-02-19T02:27:56Z","receivedAt":"2017-02-19T02:28:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Feb 19, 2017 at 12:20:33AM -0000, Philip Oakley wrote:\n\n> > Normalize 'refname' by removing any leading slash (`/`)\n> > characters and collapsing runs of adjacent slashes between\n> > - name components into a single slash. Iff the normalized\n> > + name components into a single slash. If the normalized\n> > refname is valid then print it to standard output and exit\n> > with a status of 0. (`--print` is a deprecated way to spell\n> > `--normalize`.)\n> > -- \n> \n> Could that be an 'iff' == 'If and only if' (which is common in mathematics)?\n> Still could be spelling error though.\n\nWhen we're not sure what the intent of a change is, a good first step is\nto dig up the original commit via `git blame` or similar. In this case,\nit comes from a40e6fb67 (Change check_refname_format() to reject\nunnormalized refnames, 2011-09-15).\n\nThe commit message doesn't mention it (not that I really expected it\nto), but it does tell you who the author is. And a good second step is\nto cc them on the patch. :)\n\nI suspect it _was_ intended as \"iff\" here. In my opinion, we probably\ndon't need to be so rigorous in this instance. However, I note that we\ndo not describe the \"else\" half of that \"if\". So maybe an overall\nimprovement would be something like:\n\n If the normalized refname is valid then print it to standard output\n and exit with a status of 0. Otherwise, exit with a non-zero status.\n\n-Peff\n"},{"id":"312090","messageId":"8147218721BE4F239D00CBFAFD9B495D@PhilipOakley","threadId":"45174","inReplyTo":"20170219022756.pwxhjluxizuedf46@sigill.intra.peff.net","subject":"Re: [PATCH] git-check-ref-format: fix typo in man page","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2017-02-19T20:41:05Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jeff King\" \n> On Sun, Feb 19, 2017 at 12:20:33AM -0000, Philip Oakley wrote:\n>\n>> > Normalize 'refname' by removing any leading slash (`/`)\n>> > characters and collapsing runs of adjacent slashes between\n>> > - name components into a single slash. Iff the normalized\n>> > + name components into a single slash. If the normalized\n>> > refname is valid then print it to standard output and exit\n>> > with a status of 0. (`--print` is a deprecated way to spell\n>> > `--normalize`.)\n>> > -- \n>>\n>> Could that be an 'iff' == 'If and only if' (which is common in \n>> mathematics)?\n>> Still could be spelling error though.\n>\n> When we're not sure what the intent of a change is, a good first step is\n> to dig up the original commit via `git blame` or similar. In this case,\n> it comes from a40e6fb67 (Change check_refname_format() to reject\n> unnormalized refnames, 2011-09-15).\n\nOops, blaming a bit of code feels 'obvious' but I just hadn't thought to \nblame the doc, though it does feel as though code and the docs don't always \ngo hand in hand.\n\n>\n> The commit message doesn't mention it (not that I really expected it\n> to), but it does tell you who the author is. And a good second step is\n> to cc them on the patch. :)\n>\n> I suspect it _was_ intended as \"iff\" here. In my opinion, we probably\n> don't need to be so rigorous in this instance. However, I note that we\n> do not describe the \"else\" half of that \"if\". So maybe an overall\n> improvement would be something like:\n\nI read the commit message the same, that is, only if the given ref name \nnormalises to a true (properly formatted) ref will it be printed (sucess).\n\nFor those not familiar with 'iff', then a change to the doc is worthwhile.\n\n>\n> If the normalized refname is valid then print it to standard output\n> and exit with a status of 0. Otherwise, exit with a non-zero status.\n>\n> -Peff\n>\nThanks, Philip. \n\n"},{"id":"312096","messageId":"o8d5au$fqu$1@blaine.gmane.org","threadId":"45174","inReplyTo":"8147218721BE4F239D00CBFAFD9B495D@PhilipOakley","subject":"Re: [PATCH] git-check-ref-format: fix typo in man page","fromName":"Damien Regad","fromEmail":"dregad@mantisbt.org","sentAt":"2017-02-19T22:13:56Z","receivedAt":"2017-02-19T22:14:11Z","isPatch":true,"sender":{"key":"dregad@mantisbt.org","avatar":"https://avatars.githubusercontent.com/u/449891?v=4"},"body":"Thanks all for the feedback.\n\nOn 2017-02-19 21:40, Philip Oakley wrote:\n> For those not familiar with 'iff', then a change to the doc is worthwhile.\n\nExactly. Not being a native English speaker, I had never seen 'iff' used\nbefore. Now that you guys have pointed me to its meaning I guess it\nmakes sense in this context.\n\nThat being said, IMHO software documentation is not a mathematics\ntextbook, and should be written in \"plain\" English, so\n\nOn 2017-02-19 03:27, Jeff King wrote:\n> So maybe an overall improvement would be something like:\n>\n> If the normalized refname is valid then print it to standard output\n> and exit with a status of 0. Otherwise, exit with a non-zero status.\n\nI'll submit a revised patch shortly, following your suggestion.\n\nCheers\nDamien\n\n\n"}]}