Re: [COMMITTERS] pgsql: Copy-editing for contrib/pg_visibility documentation.

On Mon, Oct 3, 2016 at 8:51 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
>> Why do you keep insisting on changing case where I've written "which"
>> to instead say "that" in situations where AFAIK either is perfectly
>> correct? I find such changes at best neutral, and in some cases
>> worse.
>
> What I was taught in school was that "that" introduces a restrictive
> clause, i.e. one that limits the membership of whatever group was
> just mentioned, while "which" introduces a descriptive clause, i.e.
> one that just provides more information about the group. So for
> example
>
> Functions that return a pass-by-reference type must do X.
>
> is correct, while
>
> Functions, which return a pass-by-reference type, must do X.
>
> carries an implication that *all* functions in the system return
> pass-by-reference types. Even if you think that that's obviously
> silly, it may confuse readers who are accustomed to this distinction
> being drawn. On the other hand, this is fine:
>
> Functions that return text, which is a pass-by-reference type,
> must do X.
>
> I've made the point more obvious in the above by setting off descriptive
> clauses with commas, which is a common thing to do. But the punctuation
> is optional.
>
> I realize that this is nitpickery, and wouldn't usually bother about
> the distinction in, say, code comments. But we are striving to be
> somewhat formal in the user-facing documentation, no?

Sure, I'm not arguing with trying to be formal. The grammatical rule
that you're describing doesn't exist for me, though. I believe that
"that" can only introduce a restrictive clause, whereas "which" can
introduce either a descriptive or a restrictive clause. It's
impossible for to imagine someone reading "functions which return text
must do X" and coming away with the conclusion that all functions
return text.

The reason I tend to prefer "which" is that "that" can mean lots of
other things, too. Consider:

Donald Trump takes advantage of tax loopholes. The tax loopholes that
that man uses should be eliminated.
vs.
Donald Trump takes advantage of tax loopholes. The tax loopholes
which that man uses should be eliminated.

In my opinion, the second one is considerably superior. If "which"
can only introduce a descriptive clause, then what does the second one
mean? The sentence must now be construed to mean that some
unspecified set of tax loopholes should be eliminated. We know that
each of them are used by Donald Trump, but not that they include every
loophole used by Donald Trump. Of course, nobody would read the
sentence that way: it is drop-dead obvious that "which that man uses"
is intended to define the set of tax loopholes, not to describe it. I
certainly used such constructions many times in the papers I wrote in
college, which I think also qualify as formal writing, and I don't
think I got dinged for doing so.

I tend to find the construction involving "which" to lead to easier
reading, because there's no ambiguity about it. Note that this is
perfectly fine:

The tax loopholes Donald Trump uses should be eliminated.

I don't know what that's called from the standpoint of formal grammar,
but it's clear enough. So presumably I can also replace "Donald
Trump" with "that man":

The tax loopholes that man uses should be eliminated.

Well, now when I get to the word "that", my brain freezes up for a
second: is this introducing a clause beginning with "that", or is
introducing a clause beginning with nothing with "that" as the first
word of the clause? I can't tell until I keep reading, and I might
have to backup and reread to be sure I'm understanding the meaning
correctly. In contrast, if the clause had been introduced with
"which", it would have been clear immediately, which is a desirable
property for documentation to have.

I apologize for writing an email that mentions "Donald Trump" no less
than 7 times. Sorry.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company