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

[Junio C Hamano <gitster@pobox.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" ;-).

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

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