Re: [PATCH] documentation symlink restrictions for .git* files

[Philip Oakley <philipoakley@iee.email>]

On 27/10/2020 18:45, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
>
>>>  DESCRIPTION
>>>  -----------
>>>  
>>> -A `gitattributes` file is a simple text file that gives
>>> -`attributes` to pathnames.
>>> +A `gitattributes` file is a simple text file (it cannot be a
>>> +symbolic link to anything) that gives `attributes` to pathnames.
>> I worried that even a short mention like this would be distracting. Not
>> because it's so long, but because it's right there in the very first
>> sentence, and I really think this is a corner case that most people
>> would not even think about.
>>
>> So it is helpful if you are looking for info on symlinks and these
>> files, but probably clutter if you are looking for something else.
>>
>> I have to admit I don't feel all that strongly either way, though.
> I don't, either, and as I said, I found that the placement of new
> text was OK.
>
>
I do think that the extra text above is the right thing to do.

We should be informing readers early about things that are expressly
prohibited.

Leaving just the note till nearly the end of the rather long
attributes/ignore man pages makes it very hard to discover for
frustrated users, which would accidentally reinforce the idea of the
docs being poor (rather than being focussed).

Philip