* [PATCH] git-check-ref-format: fix typo in man page
@ 2017-02-18 22:47 Damien Regad
2017-02-19 0:17 ` Jacob Keller
2017-02-19 0:20 ` Philip Oakley
0 siblings, 2 replies; 6+ messages in thread
From: Damien Regad @ 2017-02-18 22:47 UTC (permalink / raw)
To: git
---
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] git-check-ref-format: fix typo in man page
2017-02-18 22:47 [PATCH] git-check-ref-format: fix typo in man page Damien Regad
@ 2017-02-19 0:17 ` Jacob Keller
2017-02-19 0:20 ` Philip Oakley
1 sibling, 0 replies; 6+ messages in thread
From: Jacob Keller @ 2017-02-19 0:17 UTC (permalink / raw)
To: Damien Regad; +Cc: Git mailing list
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
>
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] git-check-ref-format: fix typo in man page
2017-02-18 22:47 [PATCH] git-check-ref-format: fix typo in man page Damien Regad
2017-02-19 0:17 ` Jacob Keller
@ 2017-02-19 0:20 ` Philip Oakley
2017-02-19 2:27 ` Jeff King
1 sibling, 1 reply; 6+ messages in thread
From: Philip Oakley @ 2017-02-19 0:20 UTC (permalink / raw)
To: Damien Regad, git
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] git-check-ref-format: fix typo in man page
2017-02-19 0:20 ` Philip Oakley
@ 2017-02-19 2:27 ` Jeff King
2017-02-19 20:40 ` Philip Oakley
0 siblings, 1 reply; 6+ messages in thread
From: Jeff King @ 2017-02-19 2:27 UTC (permalink / raw)
To: Philip Oakley; +Cc: Michael Haggerty, Damien Regad, git
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] git-check-ref-format: fix typo in man page
2017-02-19 2:27 ` Jeff King
@ 2017-02-19 20:40 ` Philip Oakley
2017-02-19 22:13 ` Damien Regad
0 siblings, 1 reply; 6+ messages in thread
From: Philip Oakley @ 2017-02-19 20:40 UTC (permalink / raw)
To: Jeff King; +Cc: Michael Haggerty, Damien Regad, git
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] git-check-ref-format: fix typo in man page
2017-02-19 20:40 ` Philip Oakley
@ 2017-02-19 22:13 ` Damien Regad
0 siblings, 0 replies; 6+ messages in thread
From: Damien Regad @ 2017-02-19 22:13 UTC (permalink / raw)
To: git
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2017-02-19 22:14 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-02-18 22:47 [PATCH] git-check-ref-format: fix typo in man page Damien Regad
2017-02-19 0:17 ` Jacob Keller
2017-02-19 0:20 ` Philip Oakley
2017-02-19 2:27 ` Jeff King
2017-02-19 20:40 ` Philip Oakley
2017-02-19 22:13 ` Damien Regad
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.