# [PATCH] git-check-ref-format: fix typo in man page 6 messages from 2017-02-18 to 2017-02-19. Participants: Damien Regad, Jacob Keller, Philip Oakley, Jeff King. Thread: https://gitlist.dev/t/45174 ## Damien Regad, 2017-02-18 22:47 Subject: [PATCH] git-check-ref-format: fix typo in man page Message-ID: URL: https://gitlist.dev/e/c27d7861-b161-a3eb-fcfc-bf766fc7b20b%40gmail.com ``` --- Documentation/git-check-ref-format.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 8611a99..377c85a 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -100,7 +100,7 @@ OPTIONS --normalize:: Normalize 'refname' by removing any leading slash (`/`) characters and collapsing runs of adjacent slashes between - name components into a single slash. Iff the normalized + name components into a single slash. If the normalized refname is valid then print it to standard output and exit with a status of 0. (`--print` is a deprecated way to spell `--normalize`.) -- 2.7.4 ``` ## Jacob Keller, 2017-02-19 00:17 Subject: Re: [PATCH] git-check-ref-format: fix typo in man page Message-ID: URL: https://gitlist.dev/e/CA%2BP7%2BxrNb8xdbjFFAVVRDNe4Mho764PKYCbrLWmu4ykzU9A5dA%40mail.gmail.com In-Reply-To: ``` On Sat, Feb 18, 2017 at 2:47 PM, Damien Regad wrote: > > --- > Documentation/git-check-ref-format.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/git-check-ref-format.txt > b/Documentation/git-check-ref-format.txt > index 8611a99..377c85a 100644 > --- a/Documentation/git-check-ref-format.txt > +++ b/Documentation/git-check-ref-format.txt > @@ -100,7 +100,7 @@ OPTIONS > --normalize:: > Normalize 'refname' by removing any leading slash (`/`) > characters and collapsing runs of adjacent slashes between > - name components into a single slash. Iff the normalized > + name components into a single slash. If the normalized I think this is a good change, but I do know in some contexts, "Iff" is used intentionally to mean "If and only if". It's somewhat unlikely that's what was going on here, and I don't think we need to be that pedantic in our help documentation anyway. Thanks, Jake > refname is valid then print it to standard output and exit > with a status of 0. (`--print` is a deprecated way to spell > `--normalize`.) > -- > 2.7.4 > > ``` ## Philip Oakley, 2017-02-19 00:20 Subject: Re: [PATCH] git-check-ref-format: fix typo in man page Message-ID: <2116CBFFB78A482D8FA176BC680B3B9C@PhilipOakley> URL: https://gitlist.dev/e/2116CBFFB78A482D8FA176BC680B3B9C%40PhilipOakley In-Reply-To: ``` From: "Damien Regad" > --- > Documentation/git-check-ref-format.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/git-check-ref-format.txt > b/Documentation/git-check-ref-format.txt > index 8611a99..377c85a 100644 > --- a/Documentation/git-check-ref-format.txt > +++ b/Documentation/git-check-ref-format.txt > @@ -100,7 +100,7 @@ OPTIONS > --normalize:: > Normalize 'refname' by removing any leading slash (`/`) > characters and collapsing runs of adjacent slashes between > - name components into a single slash. Iff the normalized > + name components into a single slash. If the normalized > refname is valid then print it to standard output and exit > with a status of 0. (`--print` is a deprecated way to spell > `--normalize`.) > -- Could that be an 'iff' == 'If and only if' (which is common in mathematics)? Still could be spelling error though. -- Philip ``` ## Jeff King, 2017-02-19 02:27 Subject: Re: [PATCH] git-check-ref-format: fix typo in man page Message-ID: <20170219022756.pwxhjluxizuedf46@sigill.intra.peff.net> URL: https://gitlist.dev/e/20170219022756.pwxhjluxizuedf46%40sigill.intra.peff.net In-Reply-To: <2116CBFFB78A482D8FA176BC680B3B9C@PhilipOakley> ``` On Sun, Feb 19, 2017 at 12:20:33AM -0000, Philip Oakley wrote: > > Normalize 'refname' by removing any leading slash (`/`) > > characters and collapsing runs of adjacent slashes between > > - name components into a single slash. Iff the normalized > > + name components into a single slash. If the normalized > > refname is valid then print it to standard output and exit > > with a status of 0. (`--print` is a deprecated way to spell > > `--normalize`.) > > -- > > Could that be an 'iff' == 'If and only if' (which is common in mathematics)? > Still could be spelling error though. When we're not sure what the intent of a change is, a good first step is to dig up the original commit via `git blame` or similar. In this case, it comes from a40e6fb67 (Change check_refname_format() to reject unnormalized refnames, 2011-09-15). The commit message doesn't mention it (not that I really expected it to), but it does tell you who the author is. And a good second step is to cc them on the patch. :) I suspect it _was_ intended as "iff" here. In my opinion, we probably don't need to be so rigorous in this instance. However, I note that we do not describe the "else" half of that "if". So maybe an overall improvement would be something like: If the normalized refname is valid then print it to standard output and exit with a status of 0. Otherwise, exit with a non-zero status. -Peff ``` ## Philip Oakley, 2017-02-19 20:41 Subject: Re: [PATCH] git-check-ref-format: fix typo in man page Message-ID: <8147218721BE4F239D00CBFAFD9B495D@PhilipOakley> URL: https://gitlist.dev/e/8147218721BE4F239D00CBFAFD9B495D%40PhilipOakley In-Reply-To: <20170219022756.pwxhjluxizuedf46@sigill.intra.peff.net> ``` From: "Jeff King" > On Sun, Feb 19, 2017 at 12:20:33AM -0000, Philip Oakley wrote: > >> > Normalize 'refname' by removing any leading slash (`/`) >> > characters and collapsing runs of adjacent slashes between >> > - name components into a single slash. Iff the normalized >> > + name components into a single slash. If the normalized >> > refname is valid then print it to standard output and exit >> > with a status of 0. (`--print` is a deprecated way to spell >> > `--normalize`.) >> > -- >> >> Could that be an 'iff' == 'If and only if' (which is common in >> mathematics)? >> Still could be spelling error though. > > When we're not sure what the intent of a change is, a good first step is > to dig up the original commit via `git blame` or similar. In this case, > it comes from a40e6fb67 (Change check_refname_format() to reject > unnormalized refnames, 2011-09-15). Oops, blaming a bit of code feels 'obvious' but I just hadn't thought to blame the doc, though it does feel as though code and the docs don't always go hand in hand. > > The commit message doesn't mention it (not that I really expected it > to), but it does tell you who the author is. And a good second step is > to cc them on the patch. :) > > I suspect it _was_ intended as "iff" here. In my opinion, we probably > don't need to be so rigorous in this instance. However, I note that we > do not describe the "else" half of that "if". So maybe an overall > improvement would be something like: I read the commit message the same, that is, only if the given ref name normalises to a true (properly formatted) ref will it be printed (sucess). For those not familiar with 'iff', then a change to the doc is worthwhile. > > If the normalized refname is valid then print it to standard output > and exit with a status of 0. Otherwise, exit with a non-zero status. > > -Peff > Thanks, Philip. ``` ## Damien Regad, 2017-02-19 22:13 Subject: Re: [PATCH] git-check-ref-format: fix typo in man page Message-ID: URL: https://gitlist.dev/e/o8d5au%24fqu%241%40blaine.gmane.org In-Reply-To: <8147218721BE4F239D00CBFAFD9B495D@PhilipOakley> ``` Thanks all for the feedback. On 2017-02-19 21:40, Philip Oakley wrote: > For those not familiar with 'iff', then a change to the doc is worthwhile. Exactly. Not being a native English speaker, I had never seen 'iff' used before. Now that you guys have pointed me to its meaning I guess it makes sense in this context. That being said, IMHO software documentation is not a mathematics textbook, and should be written in "plain" English, so On 2017-02-19 03:27, Jeff King wrote: > So maybe an overall improvement would be something like: > > If the normalized refname is valid then print it to standard output > and exit with a status of 0. Otherwise, exit with a non-zero status. I'll submit a revised patch shortly, following your suggestion. Cheers Damien ```