[PATCH] pretty-options.txt: fix --no-abbrev-commit description

[PATCH] pretty-options.txt: fix --no-abbrev-commit description

[Sergey Organov]

Description suggested --no-abbrev-commit negates --oneline as well as any other
option that implies --abbrev-commit. Fix it to say that it's --abbrev-commit
that is negated, not the option that implies it.

Signed-off-by: Sergey Organov <sorganov@gmail.com>
---
 Documentation/pretty-options.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 7a6da6db780e..17c5aac4b71d 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -25,8 +25,8 @@ people using 80-column terminals.
 
 --no-abbrev-commit::
 	Show the full 40-byte hexadecimal commit object name. This negates
-	`--abbrev-commit` and those options which imply it such as
-	"--oneline". It also overrides the `log.abbrevCommit` variable.
+	`--abbrev-commit`, either explicit or implied by other options such
+	as "--oneline". It also overrides the `log.abbrevCommit` variable.
 
 --oneline::
 	This is a shorthand for "--pretty=oneline --abbrev-commit"
-- 
2.25.1

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

[Junio C Hamano]

Sergey Organov <sorganov@gmail.com> writes:

>  --no-abbrev-commit::
>  	Show the full 40-byte hexadecimal commit object name. This negates
> -	`--abbrev-commit` and those options which imply it such as
> -	"--oneline". It also overrides the `log.abbrevCommit` variable.
> +	`--abbrev-commit`, either explicit or implied by other options such
> +	as "--oneline". It also overrides the `log.abbrevCommit` variable.

I personally do not think it would be crazy to misread that one-line
format itself would be defeated when no abbreviation of object names
is requested, so from that point of view, the original text would be
OK enough, but as long as the updated text is easier to understand,
that is fine ;-)

Keeping the original sentence structure, e.g.

    ... and those options which imply abbreviating commit object
    names such as ...

would have been what I wrote, instead of "either explicit or implied
by", though.

Thanks.

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

[Sergey Organov]

Junio C Hamano <gitster@pobox.com> writes:

> Sergey Organov <sorganov@gmail.com> writes:
>
>>  --no-abbrev-commit::
>>  	Show the full 40-byte hexadecimal commit object name. This negates
>> -	`--abbrev-commit` and those options which imply it such as
>> -	"--oneline". It also overrides the `log.abbrevCommit` variable.
>> +	`--abbrev-commit`, either explicit or implied by other options such
>> +	as "--oneline". It also overrides the `log.abbrevCommit` variable.
>
> I personally do not think it would be crazy to misread that one-line
> format itself would be defeated when no abbreviation of object names
> is requested, so from that point of view, the original text would be
> OK enough,

Well, I don't think it's OK to essentially say:

  "--no-abbrev-commit" negates "--oneline"

when it doesn't. Yes, I even actually checked it doesn't, just in case.

> but as long as the updated text is easier to understand,
> that is fine ;-)

Admittedly, not being a native speaker, I'm not sure the form I used is
a good English, but at least it's factually correct.

Actually, I'd drop it altogether, to read like this:

--no-abbrev-commit::
	Show the full 40-byte hexadecimal commit object name. This negates
	`--abbrev-commit` as well as overrides the `log.abbrevCommit` variable.


as I don't see why such clarification is at all needed in the first
place.

I'll re-roll if you agree this variant is better.

>
> Keeping the original sentence structure, e.g.
>
>     ... and those options which imply abbreviating commit object names
>     such as ...
>
> would have been what I wrote, instead of "either explicit or implied
> by", though.

Sorry, but it'd then read:

  This negates `--abbrev-commit` and those options which imply
  abbreviating commit object names such as "--oneline".

that again essentially reduces to:

  This negates "--oneline"

that is simply false statement, being exactly the problem of the
original that the patch tries to fix.

Thanks,
-- Sergey

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

[Junio C Hamano]

Sergey Organov <sorganov@gmail.com> writes:

>> Keeping the original sentence structure, e.g.
>>
>>     ... and those options which imply abbreviating commit object names
>>     such as ...
>>
>> would have been what I wrote, instead of "either explicit or implied
>> by", though.
>
> Sorry, but it'd then read:
>
>   This negates `--abbrev-commit` and those options which imply
>   abbreviating commit object names such as "--oneline".
>
> that again essentially reduces to:
>
>   This negates "--oneline"

"--oneline" means a lot more than "do not use full object name", and
I think we are on the same page with our shared goal of not negating
everything "--oneline" means.  We just want to say the option
negates only the "do not use full object name" aspect.

"and the effect of abbreviating commit objects implied by other
options, such as '--oneline'" may be a more verbose way to say the
same thing, I would think, but that would be overkill.  I would have
expected that with common sense readers would think it would be
crazy for --no-abbrev to override everything --oneline means, but if
you found that the original risks such an interpretation, perhaps we
would need to be more verbose and explicit.  I dunno.

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

[Jeff King]

On Wed, Aug 26, 2020 at 03:07:52PM -0700, Junio C Hamano wrote:

> Sergey Organov <sorganov@gmail.com> writes:
> 
> >> Keeping the original sentence structure, e.g.
> >>
> >>     ... and those options which imply abbreviating commit object names
> >>     such as ...
> >>
> >> would have been what I wrote, instead of "either explicit or implied
> >> by", though.
> >
> > Sorry, but it'd then read:
> >
> >   This negates `--abbrev-commit` and those options which imply
> >   abbreviating commit object names such as "--oneline".
> >
> > that again essentially reduces to:
> >
> >   This negates "--oneline"
> 
> "--oneline" means a lot more than "do not use full object name", and
> I think we are on the same page with our shared goal of not negating
> everything "--oneline" means.  We just want to say the option
> negates only the "do not use full object name" aspect.
> 
> "and the effect of abbreviating commit objects implied by other
> options, such as '--oneline'" may be a more verbose way to say the
> same thing, I would think, but that would be overkill.  I would have
> expected that with common sense readers would think it would be
> crazy for --no-abbrev to override everything --oneline means, but if
> you found that the original risks such an interpretation, perhaps we
> would need to be more verbose and explicit.  I dunno.

FWIW, as a third-party observer (because you wanted more opinions,
right?), I found the result of Sergey's original patch easy to read and
understand.

I also think it's unlikely for people to misinterpret the current text,
but it does not hurt to be more precise just in case.

-Peff

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, Aug 26, 2020 at 03:07:52PM -0700, Junio C Hamano wrote:
>
>> Sergey Organov <sorganov@gmail.com> writes:
>> 
>> >> Keeping the original sentence structure, e.g.
>> >>
>> >>     ... and those options which imply abbreviating commit object names
>> >>     such as ...
>> >>
>> >> would have been what I wrote, instead of "either explicit or implied
>> >> by", though.
>> >
>> > Sorry, but it'd then read:
>> >
>> >   This negates `--abbrev-commit` and those options which imply
>> >   abbreviating commit object names such as "--oneline".
>> >
>> > that again essentially reduces to:
>> >
>> >   This negates "--oneline"
>> 
>> "--oneline" means a lot more than "do not use full object name", and
>> I think we are on the same page with our shared goal of not negating
>> everything "--oneline" means.  We just want to say the option
>> negates only the "do not use full object name" aspect.
>> 
>> "and the effect of abbreviating commit objects implied by other
>> options, such as '--oneline'" may be a more verbose way to say the
>> same thing, I would think, but that would be overkill.  I would have
>> expected that with common sense readers would think it would be
>> crazy for --no-abbrev to override everything --oneline means, but if
>> you found that the original risks such an interpretation, perhaps we
>> would need to be more verbose and explicit.  I dunno.
>
> FWIW, as a third-party observer (because you wanted more opinions,
> right?), I found the result of Sergey's original patch easy to read and
> understand.
>
> I also think it's unlikely for people to misinterpret the current text,
> but it does not hurt to be more precise just in case.

Yup, I think I said the same already ;-)