{"thread":{"id":"10863","subject":"[PATCH] Grammar fixes for gitattributes documentation","startedAt":"2007-11-14T07:51:41Z","lastAt":"2007-11-15T07:27:03Z","messageCount":7,"participants":["Wincent Colaiuta","Junio C Hamano","Jeff King","David Symonds"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"59821","messageId":"33080F0B-80C0-4860-9A74-C6878EE3B2CD@wincent.com","threadId":"10863","inReplyTo":null,"subject":"[PATCH] Grammar fixes for gitattributes documentation","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-14T07:51:41Z","receivedAt":"2007-11-14T07:51:41Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"Tweak the \"filter\" section of the gitattributes documentation to add \nsome\nmissing articles and improve some word choices without changing the\nsemantics of the section.\n\nSigned-off-by: Wincent Colaiuta \n---\n Documentation/gitattributes.txt | 17 +++++++++--------\n 1 files changed, 9 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/gitattributes.txt b/Documentation/ \ngitattributes.txt\nindex 20cf8ff..b01786b 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -148,22 +148,23 @@ with `$Id$` upon check-in.\n `filter`\n ^^^^^^^^\n\n-A `filter` attribute can be set to a string value. This names\n+A `filter` attribute can be set to a string value which names a\n filter driver specified in the configuration.\n\n-A filter driver consists of `clean` command and `smudge`\n+A filter driver consists of a `clean` command and a `smudge`\n command, either of which can be left unspecified. Upon\n-checkout, when `smudge` command is specified, the command is fed\n-the blob object from its standard input, and its standard output\n-is used to update the worktree file. Similarly, `clean` command\n-is used to convert the contents of worktree file upon checkin.\n+checkout, when the `smudge` command is specified, the command is\n+fed the blob object from its standard input, and its standard\n+output is used to update the worktree file. Similarly, the\n+`clean` command is used to convert the contents of worktree file\n+upon checkin.\n\n-Missing filter driver definition in the config is not an error\n+A missing filter driver definition in the config is not an error\n but makes the filter a no-op passthru.\n\n The content filtering is done to massage the content into a\n shape that is more convenient for the platform, filesystem, and\n-the user to use. The keyword here is \"more convenient\" and not\n+the user to use. The key phrase here is \"more convenient\" and not\n \"turning something unusable into usable\". In other words, the\n intent is that if someone unsets the filter driver definition,\n or does not have the appropriate filter program, the project\n-- \n1.5.3.5\n"},{"id":"59827","messageId":"7vfxz9kxz3.fsf@gitster.siamese.dyndns.org","threadId":"10863","inReplyTo":"33080F0B-80C0-4860-9A74-C6878EE3B2CD@wincent.com","subject":"Re: [PATCH] Grammar fixes for gitattributes documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-14T08:55:28Z","receivedAt":"2007-11-14T08:55:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Wincent Colaiuta writes:\n\n> Tweak the \"filter\" section of the gitattributes documentation to add\n> some missing articles and improve some word choices without changing\n> the semantics of the section.\n>\n> Signed-off-by: Wincent Colaiuta \n\nThanks.\n\n> diff --git a/Documentation/gitattributes.txt b/Documentation/\n> gitattributes.txt\n> index 20cf8ff..b01786b 100644\n> --- a/Documentation/gitattributes.txt\n> +++ b/Documentation/gitattributes.txt\n> @@ -148,22 +148,23 @@ with `$Id$` upon check-in.\n> `filter`\n> ^^^^^^^^\n>\n> -A `filter` attribute can be set to a string value. This names\n> +A `filter` attribute can be set to a string value which names a\n> filter driver specified in the configuration.\n\nWill we get the canned \"which vs that\" discussion on this change?\n\n> -A filter driver consists of `clean` command and `smudge`\n> +A filter driver consists of a `clean` command and a `smudge`\n> command, either of which can be left unspecified. Upon\n> -checkout, when `smudge` command is specified, the command is fed\n> +checkout, when the `smudge` command is specified, the command is fed\n> -the blob object from its standard input, and its standard output\n> +the blob object from its standard input, and its standard output\n> -is used to update the worktree file. Similarly, `clean` command\n> +is used to update the worktree file. Similarly, the `clean` command\n> -is used to convert the contents of worktree file upon checkin.\n> +is used to convert the contents of worktree file upon checkin.\n\nI do appreciate the grammar fixes, but I needed to re-wrap and\nswap lines to see the real change. Especially, after this\nre-wrapping, the updated lines with missing \"the\" fixed still\nfit nicely below 70 columns and the right edge is not too ragged\nto be distractive even for people who read unformatted text.\n\nCould you please avoid this kind of unnecessary re-wrapping in\nthe future patches?\n"},{"id":"59831","messageId":"3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com","threadId":"10863","inReplyTo":"7vfxz9kxz3.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Grammar fixes for gitattributes documentation","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-14T09:04:25Z","receivedAt":"2007-11-14T09:04:25Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 14/11/2007, a las 9:55, Junio C Hamano escribió:\n\n> Wincent Colaiuta writes:\n>\n>> -A `filter` attribute can be set to a string value. This names\n>> +A `filter` attribute can be set to a string value which names a\n>> filter driver specified in the configuration.\n>\n> Will we get the canned \"which vs that\" discussion on this change?\n\nPerhaps. Neither would be incorrect, although technically \"that\" is a \ntighter match.\n\n> I do appreciate the grammar fixes, but I needed to re-wrap and\n> swap lines to see the real change. Especially, after this\n> re-wrapping, the updated lines with missing \"the\" fixed still\n> fit nicely below 70 columns and the right edge is not too ragged\n> to be distractive even for people who read unformatted text.\n>\n> Could you please avoid this kind of unnecessary re-wrapping in\n> the future patches?\n\n\nOk, sorry about that. I wasn't sure of the maximum allowed length in \nthe doc files, and the longest line I could find in that file was 67 \nchars, so I made sure that nothing exceeded that. Will make a note \nthat the official limit is 70. Perhaps this could be added to the \nstyle document? Will whip up a patch for that.\n\nCheers,\nWincent\n"},{"id":"59832","messageId":"7vfxz9jhxk.fsf@gitster.siamese.dyndns.org","threadId":"10863","inReplyTo":"3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com","subject":"Re: [PATCH] Grammar fixes for gitattributes documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-14T09:27:19Z","receivedAt":"2007-11-14T09:27:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Wincent Colaiuta writes:\n\n> El 14/11/2007, a las 9:55, Junio C Hamano escribi󺊊> Wincent Colaiuta writes:\n>>\n>>> -A `filter` attribute can be set to a string value. This names\n>>> +A `filter` attribute can be set to a string value which names a\n>>> filter driver specified in the configuration.\n>>\n>> Will we get the canned \"which vs that\" discussion on this change?\n>\n> Perhaps. Neither would be incorrect, although technically \"that\" is a \n> tighter match.\n\nYes, that was what I was getting at, although I do not\nparticularly find the original wrong nor harder to read, either.\n\n>> Could you please avoid this kind of unnecessary re-wrapping in\n>> the future patches?\n>\n> Ok, sorry about that. I wasn't sure of the maximum allowed length in \n> the doc files, and the longest line I could find in that file was 67 \n> chars, so I made sure that nothing exceeded that. Will make a note \n> that the official limit is 70.\n\nI did not mean to say 70 was the official limit. Indeed, there\nis no hard official limit (and there shouldn't be any \"hard\"\nlimit). But 70 should certainly be lower than the limit anybody\naround here would want to impose, and that was why I said 70.\n\nSome considerations:\n\n - Many of us read the unformatted ASCII version, as AsciiDoc\n was designed to be very readable, and mixing excessively long\n and short lines will make the document harder to read.\n\n - We tend to exchange patches over e-mail and assume everybody\n has at least 80-column wide terminals, so although we say a\n line should be less than 80-chars, in practice the limit is\n somewhat lower. to accomodate diff change marks [-+ ] and\n quoting \">> \" in e-mails.\n\n - But \"80-chars minus a bit of slop\" is not a very hard limit.\n\nPlease apply some common sense to decide when to re-wrap and\nwhen not to within these constraints.\n"},{"id":"59938","messageId":"20071115071558.GE10185@sigill.intra.peff.net","threadId":"10863","inReplyTo":"3461FD6E-1C46-4278-9EB0-5D730BB99084@wincent.com","subject":"Re: [PATCH] Grammar fixes for gitattributes documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-11-15T07:15:59Z","receivedAt":"2007-11-15T07:15:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Nov 14, 2007 at 10:04:25AM +0100, Wincent Colaiuta wrote:\n\n>>> +A `filter` attribute can be set to a string value which names a\n>>> filter driver specified in the configuration.\n>>\n>> Will we get the canned \"which vs that\" discussion on this change?\n>\n> Perhaps. Neither would be incorrect, although technically \"that\" is a \n> tighter match.\n\nReally? I would think \"which\" works better, in that it is not\nrestrictive. I.e., \"The filter attribute is set to a string. This\nstring, btw, names a filter driver\" (which) rather than \"The filter\nattribute is set to a string, and from the set of strings, it is set to\nthe particular string that names a filter driver\" (that).\n\nBut in the non-restrictive case, it should be in a parenthetical phrase:\n\n A `filter` attribute can be set to a string value, which names a\n filter driver specified in the configuration.\n\nI think either is readable, though. :)\n\n-Peff\n"},{"id":"59939","messageId":"ee77f5c20711142320x1a070b21xf00f0853fe09e34c@mail.gmail.com","threadId":"10863","inReplyTo":"20071115071558.GE10185@sigill.intra.peff.net","subject":"Re: [PATCH] Grammar fixes for gitattributes documentation","fromName":"David Symonds","fromEmail":"dsymonds@gmail.com","sentAt":"2007-11-15T07:20:10Z","receivedAt":"2007-11-15T07:20:10Z","isPatch":true,"sender":{"key":"dsymonds@gmail.com","avatar":"https://gravatar.com/avatar/b22f5051cbfc11836e36cf7a690e6cde4e225d835e13295ff98d15c7a9ee3c0f?d=mp&s=160"},"body":"On Nov 15, 2007 6:15 PM, Jeff King wrote:\n> On Wed, Nov 14, 2007 at 10:04:25AM +0100, Wincent Colaiuta wrote:\n>\n> >>> +A `filter` attribute can be set to a string value which names a\n> >>> filter driver specified in the configuration.\n> >>\n> >> Will we get the canned \"which vs that\" discussion on this change?\n> >\n> > Perhaps. Neither would be incorrect, although technically \"that\" is a\n> > tighter match.\n>\n> Really? I would think \"which\" works better, in that it is not\n> restrictive. I.e., \"The filter attribute is set to a string. This\n> string, btw, names a filter driver\" (which) rather than \"The filter\n> attribute is set to a string, and from the set of strings, it is set to\n> the particular string that names a filter driver\" (that).\n\n\"that\" should be used to introduce restrictive clauses (as you point\nout), and this use should be a restrictive clause, since you can't set\nthe attribute to just any value--you need to set it to the value\n*that* names the desired filter driver.\n\n\nDave.\n... writing a thesis, so has grammar on the brain.\n"},{"id":"59940","messageId":"20071115072703.GF10185@sigill.intra.peff.net","threadId":"10863","inReplyTo":"ee77f5c20711142320x1a070b21xf00f0853fe09e34c@mail.gmail.com","subject":"Re: [PATCH] Grammar fixes for gitattributes documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-11-15T07:27:03Z","receivedAt":"2007-11-15T07:27:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Nov 15, 2007 at 06:20:10PM +1100, David Symonds wrote:\n\n> > >>> +A `filter` attribute can be set to a string value which names a\n> > >>> filter driver specified in the configuration.\n> \n> \"that\" should be used to introduce restrictive clauses (as you point\n> out), and this use should be a restrictive clause, since you can't set\n> the attribute to just any value--you need to set it to the value\n> *that* names the desired filter driver.\n\nI don't see it as restrictive, but I can see how one would. I think it\nis not a case of \"this wording is correct\" but rather \"this wording\nmeans one thing, and the other wording means another.\"\n\nBut the two meanings are likely to be interpreted the same way, so I\nthink it isn't a big deal (although \"which\" without a comma _is_ wrong\n:) ).\n\n-Peff\n"}]}