[PATCH] Grammar fixes for gitattributes documentation

[PATCH] Grammar fixes for gitattributes documentation

[Wincent Colaiuta]

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 <win@wincent.com>
---
  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

Re: [PATCH] Grammar fixes for gitattributes documentation

[Junio C Hamano]

Wincent Colaiuta <win@wincent.com> 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 <win@wincent.com>

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?

Re: [PATCH] Grammar fixes for gitattributes documentation

[Wincent Colaiuta]

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.

> 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

Re: [PATCH] Grammar fixes for gitattributes documentation

[Junio C Hamano]

Wincent Colaiuta <win@wincent.com> writes:

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

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

Re: [PATCH] Grammar fixes for gitattributes documentation

[Jeff King]

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

Re: [PATCH] Grammar fixes for gitattributes documentation

[David Symonds]

On Nov 15, 2007 6:15 PM, Jeff King <peff@peff.net> 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.

Re: [PATCH] Grammar fixes for gitattributes documentation

[Jeff King]

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