Re: [PATCH] Grammar fixes for gitattributes documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 14, 2007, 09:27 UTC
Message-ID: <7vfxz9jhxk.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com>

Wincent Colaiuta <win@wincent.com> writes:

Show 10 quoted lines

> El 14/11/2007, a las 9:55, Junio C Hamano escribi󺊊> Wincent Colaiuta <win@wincent.com> writes:
>>
>>> -A `filter` attribute can be set to a string value.  This names
>>> +A `filter` attribute can be set to a string value which names a
>>> filter driver specified in the configuration.
>>
>> Will we get the canned "which vs that" discussion on this change?
>
> Perhaps. Neither would be incorrect, although technically "that" is a  
> tighter match.

Yes, that was what I was getting at, although I do not particularly find the original wrong nor harder to read, either.

Show 7 quoted lines

>> Could you please avoid this kind of unnecessary re-wrapping in
>> the future patches?
>
> Ok, sorry about that. I wasn't sure of the maximum allowed length in  
> the doc files, and the longest line I could find in that file was 67  
> chars, so I made sure that nothing exceeded that. Will make a note  
> that the official limit is 70.

I did not mean to say 70 was the official limit. Indeed, there is no hard official limit (and there shouldn't be any "hard" limit). But 70 should certainly be lower than the limit anybody around here would want to impose, and that was why I said 70.

Some considerations:

 - Many of us read the unformatted ASCII version, as AsciiDoc
   was designed to be very readable, and mixing excessively long
   and short lines will make the document harder to read.

 - We tend to exchange patches over e-mail and assume everybody
   has at least 80-column wide terminals, so although we say a
   line should be less than 80-chars, in practice the limit is
   somewhat lower. to accomodate diff change marks [-+ ] and
   quoting ">> " in e-mails.

 - But "80-chars minus a bit of slop" is not a very hard limit.

Please apply some common sense to decide when to re-wrap and when not to within these constraints.