Re: [PATCH] Grammar fixes for gitattributes documentation

Wincent Colaiuta [off-list ref] 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 <redacted>

Thanks.

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?

El 14/11/2007, a las 9:55, Junio C Hamano escribió:

Wincent Colaiuta [off-list ref] writes:

quoted

-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

On Wed, Nov 14, 2007 at 10:04:25AM +0100, Wincent Colaiuta wrote:

quoted

quoted

+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

On Nov 15, 2007 6:15 PM, Jeff King [off-list ref] wrote:

On Wed, Nov 14, 2007 at 10:04:25AM +0100, Wincent Colaiuta wrote:

quoted

quoted

quoted

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

On Thu, Nov 15, 2007 at 06:20:10PM +1100, David Symonds wrote:

quoted

quoted

quoted

quoted

+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