threads / patch / 45174

patchgit-check-ref-format: fix typo in man page

Subject: [PATCH] git-check-ref-format: fix typo in man page

## tl;dr

6 messages between Feb 18, 2017 and Feb 19, 2017. Diffs are folded; open one to read it.

replies: 5people: 4as markdown or json

Damien Regad· Feb 18, 2017, 22:47 UTC · lore
---
 Documentation/git-check-ref-format.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-check-ref-format.txt +1 −1
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· Feb 19, 2017, 00:17 UTC · re: Damien Regad · lore

Re: [PATCH] git-check-ref-format: fix typo in man page

On Sat, Feb 18, 2017 at 2:47 PM, Damien Regad <dregad@mantisbt.org> wrote:
Show 16 quoted lines
>
> ---
>  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

Show 7 quoted lines
>         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· Feb 19, 2017, 00:20 UTC · re: Damien Regad · lore

Re: [PATCH] git-check-ref-format: fix typo in man page

From: "Damien Regad" <dregad@mantisbt.org>
Show 19 quoted lines
> ---
> 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· Feb 19, 2017, 02:27 UTC · re: Philip Oakley · lore

Re: [PATCH] git-check-ref-format: fix typo in man page

On Sun, Feb 19, 2017 at 12:20:33AM -0000, Philip Oakley wrote:
Show 11 quoted lines
> >  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· Feb 19, 2017, 20:41 UTC · re: Jeff King · lore

Re: [PATCH] git-check-ref-format: fix typo in man page

From: "Jeff King" <peff@peff.net>
Show 19 quoted lines
> 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.

Show 9 quoted lines
>
> 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.
Show 6 quoted lines
>
>  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· Feb 19, 2017, 22:13 UTC · re: Philip Oakley · lore

Re: [PATCH] git-check-ref-format: fix typo in man page

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

← back to recent threads