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

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

[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`.)
-- 
2.7.4

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

[Jacob Keller]

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

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

[Philip Oakley]

From: "Damien Regad" <dregad@mantisbt.org>
> ---
> 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 

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

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

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

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

[Philip Oakley]

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

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

[Damien Regad]

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