Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 30, 2023, 05:16 UTC
Message-ID: <xmqqcz3m9ch1.fsf@gitster.g>
In-Reply-To: <CAMMLpeQB1zdTEWd+=d0kaKwpzax093iLTuytZtvn0nTSJ2xT4A@mail.gmail.com>

Alex Henrie <alexhenrie24@gmail.com> writes:

> The new text may be slightly redundant, but it makes the
> important part crystal clear.

I tend to disagree and think it is a bit too redundant, but we do not have to agree on everything---after all you are doing all the work, and it is your motivation and your topic.

> Then again, maybe the fact that the `text` attribute does not
> normalize CR line endings is a bug in Git, and we shouldn't advertise
> it in the documentation as if it were intended behavior. What do you
> think?

Just not mentioning CRLF specifically would be sufficient. When (and if) somebody actually comes and complains, we can say "CR delimited files are not considered text these days, we aren't doing MacOS System 7" ;-).

Show 6 quoted lines

> The phrase "if necessary" would be a bit confusing. What makes
> conversion on checkin "necessary"? The reader would wonder if it
> depends on the Git config and the platform like conversion on checkout
> does.
>
> Would you be OK with your proposed wording minus "if necessary"?

I added it only because it would not be necessary if the original already uses LF line endings, in which you do not have to do any converison. As long as it is clear that no conversion happens in such a case without saying, I am perfectly fine to drop it.

Show 6 quoted lines

>> There are some exception handling in the code for odd cases like the
>> contents with mixed line endings, a path set to use LF but the file
>> actually has CRLF, etc.  While they are worth describing, I wonder
>> if they should be done in a separate paragraph.
>
> Probably best done in a separate patch after this rewrite is done.

What I meant was that that your "unless text=auto" and everything after it was one of thoese exception handling that should be dealt in a separate paragraph. Leaving it as a follow-on work is fine.

> Wow, that was a LOT of feedback on a relatively short piece of text.
> Are you sure you don't want to rewrite the documentation yourself? ;-)

Absolutely not.  It is not my itch to update this document.

My itch is to make sure any change makes the resulting text better than the previous one ;-).

Thanks.