# [PATCH] Grammar fixes for gitattributes documentation 7 messages from 2007-11-14 to 2007-11-15. Participants: Wincent Colaiuta, Junio C Hamano, Jeff King, David Symonds. Thread: https://gitlist.dev/t/10863 ## Wincent Colaiuta, 2007-11-14 07:51 Subject: [PATCH] Grammar fixes for gitattributes documentation Message-ID: <33080F0B-80C0-4860-9A74-C6878EE3B2CD@wincent.com> URL: https://gitlist.dev/e/33080F0B-80C0-4860-9A74-C6878EE3B2CD%40wincent.com ``` Tweak the "filter" section of the gitattributes documentation to add some missing articles and improve some word choices without changing the semantics of the section. Signed-off-by: Wincent Colaiuta --- Documentation/gitattributes.txt | 17 +++++++++-------- 1 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Documentation/gitattributes.txt b/Documentation/ gitattributes.txt index 20cf8ff..b01786b 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -148,22 +148,23 @@ with `$Id$` upon check-in. `filter` ^^^^^^^^ -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. -A filter driver consists of `clean` command and `smudge` +A filter driver consists of a `clean` command and a `smudge` command, either of which can be left unspecified. Upon -checkout, when `smudge` command is specified, the command is fed -the blob object from its standard input, and its standard output -is used to update the worktree file. Similarly, `clean` command -is used to convert the contents of worktree file upon checkin. +checkout, when the `smudge` command is specified, the command is +fed the blob object from its standard input, and its standard +output is used to update the worktree file. Similarly, the +`clean` command is used to convert the contents of worktree file +upon checkin. -Missing filter driver definition in the config is not an error +A missing filter driver definition in the config is not an error but makes the filter a no-op passthru. The content filtering is done to massage the content into a shape that is more convenient for the platform, filesystem, and -the user to use. The keyword here is "more convenient" and not +the user to use. The key phrase here is "more convenient" and not "turning something unusable into usable". In other words, the intent is that if someone unsets the filter driver definition, or does not have the appropriate filter program, the project -- 1.5.3.5 ``` ## Junio C Hamano, 2007-11-14 08:55 Subject: Re: [PATCH] Grammar fixes for gitattributes documentation Message-ID: <7vfxz9kxz3.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vfxz9kxz3.fsf%40gitster.siamese.dyndns.org In-Reply-To: <33080F0B-80C0-4860-9A74-C6878EE3B2CD@wincent.com> ``` Wincent Colaiuta writes: > Tweak the "filter" section of the gitattributes documentation to add > some missing articles and improve some word choices without changing > the semantics of the section. > > Signed-off-by: Wincent Colaiuta Thanks. > diff --git a/Documentation/gitattributes.txt b/Documentation/ > gitattributes.txt > index 20cf8ff..b01786b 100644 > --- a/Documentation/gitattributes.txt > +++ b/Documentation/gitattributes.txt > @@ -148,22 +148,23 @@ with `$Id$` upon check-in. > `filter` > ^^^^^^^^ > > -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? > -A filter driver consists of `clean` command and `smudge` > +A filter driver consists of a `clean` command and a `smudge` > command, either of which can be left unspecified. Upon > -checkout, when `smudge` command is specified, the command is fed > +checkout, when the `smudge` command is specified, the command is fed > -the blob object from its standard input, and its standard output > +the blob object from its standard input, and its standard output > -is used to update the worktree file. Similarly, `clean` command > +is used to update the worktree file. Similarly, the `clean` command > -is used to convert the contents of worktree file upon checkin. > +is used to convert the contents of worktree file upon checkin. I do appreciate the grammar fixes, but I needed to re-wrap and swap lines to see the real change. Especially, after this re-wrapping, the updated lines with missing "the" fixed still fit nicely below 70 columns and the right edge is not too ragged to be distractive even for people who read unformatted text. Could you please avoid this kind of unnecessary re-wrapping in the future patches? ``` ## Wincent Colaiuta, 2007-11-14 09:04 Subject: Re: [PATCH] Grammar fixes for gitattributes documentation Message-ID: <3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com> URL: https://gitlist.dev/e/3461FD6E-1C46-4278-9EB0-5D730BB99084%40wincent.com In-Reply-To: <7vfxz9kxz3.fsf@gitster.siamese.dyndns.org> ``` El 14/11/2007, a las 9:55, Junio C Hamano escribió: > Wincent Colaiuta 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. > I do appreciate the grammar fixes, but I needed to re-wrap and > swap lines to see the real change. Especially, after this > re-wrapping, the updated lines with missing "the" fixed still > fit nicely below 70 columns and the right edge is not too ragged > to be distractive even for people who read unformatted text. > > 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. Perhaps this could be added to the style document? Will whip up a patch for that. Cheers, Wincent ``` ## Junio C Hamano, 2007-11-14 09:27 Subject: Re: [PATCH] Grammar fixes for gitattributes documentation Message-ID: <7vfxz9jhxk.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vfxz9jhxk.fsf%40gitster.siamese.dyndns.org In-Reply-To: <3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com> ``` Wincent Colaiuta writes: > El 14/11/2007, a las 9:55, Junio C Hamano escribi󺊊> Wincent Colaiuta 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. >> 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. ``` ## Jeff King, 2007-11-15 07:15 Subject: Re: [PATCH] Grammar fixes for gitattributes documentation Message-ID: <20071115071558.GE10185@sigill.intra.peff.net> URL: https://gitlist.dev/e/20071115071558.GE10185%40sigill.intra.peff.net In-Reply-To: <3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com> ``` On Wed, Nov 14, 2007 at 10:04:25AM +0100, Wincent Colaiuta wrote: >>> +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. Really? I would think "which" works better, in that it is not restrictive. I.e., "The filter attribute is set to a string. This string, btw, names a filter driver" (which) rather than "The filter attribute is set to a string, and from the set of strings, it is set to the particular string that names a filter driver" (that). But in the non-restrictive case, it should be in a parenthetical phrase: A `filter` attribute can be set to a string value, which names a filter driver specified in the configuration. I think either is readable, though. :) -Peff ``` ## David Symonds, 2007-11-15 07:20 Subject: Re: [PATCH] Grammar fixes for gitattributes documentation Message-ID: URL: https://gitlist.dev/e/ee77f5c20711142320x1a070b21xf00f0853fe09e34c%40mail.gmail.com In-Reply-To: <20071115071558.GE10185@sigill.intra.peff.net> ``` On Nov 15, 2007 6:15 PM, Jeff King wrote: > On Wed, Nov 14, 2007 at 10:04:25AM +0100, Wincent Colaiuta wrote: > > >>> +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. > > Really? I would think "which" works better, in that it is not > restrictive. I.e., "The filter attribute is set to a string. This > string, btw, names a filter driver" (which) rather than "The filter > attribute is set to a string, and from the set of strings, it is set to > the particular string that names a filter driver" (that). "that" should be used to introduce restrictive clauses (as you point out), and this use should be a restrictive clause, since you can't set the attribute to just any value--you need to set it to the value *that* names the desired filter driver. Dave. ... writing a thesis, so has grammar on the brain. ``` ## Jeff King, 2007-11-15 07:27 Subject: Re: [PATCH] Grammar fixes for gitattributes documentation Message-ID: <20071115072703.GF10185@sigill.intra.peff.net> URL: https://gitlist.dev/e/20071115072703.GF10185%40sigill.intra.peff.net In-Reply-To: ``` On Thu, Nov 15, 2007 at 06:20:10PM +1100, David Symonds wrote: > > >>> +A `filter` attribute can be set to a string value which names a > > >>> filter driver specified in the configuration. > > "that" should be used to introduce restrictive clauses (as you point > out), and this use should be a restrictive clause, since you can't set > the attribute to just any value--you need to set it to the value > *that* names the desired filter driver. I don't see it as restrictive, but I can see how one would. I think it is not a case of "this wording is correct" but rather "this wording means one thing, and the other wording means another." But the two meanings are likely to be interpreted the same way, so I think it isn't a big deal (although "which" without a comma _is_ wrong :) ). -Peff ```