pgsql: Copy-editing for contrib/pg_visibility documentation.

On Sat, Oct 1, 2016 at 3:33 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Copy-editing for contrib/pg_visibility documentation.

Add omitted names for some function parameters.
Fix some minor grammatical issues.

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.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Oct 3, 2016 at 1:36 PM, Robert Haas <robertmhaas@gmail.com> wrote:

On Sat, Oct 1, 2016 at 3:33 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Copy-editing for contrib/pg_visibility documentation.

Add omitted names for some function parameters.
Fix some minor grammatical issues.

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.

'Which' looks OK to me too here, but I speak some kind of British
English, and it looks like at least some writers of formal American
English prefer 'that' here:

* http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Whichvs.That.html?old=Whichvs.That01.html
* https://en.oxforddictionaries.com/usage/that-or-which

--
Thomas Munro
http://www.enterprisedb.com

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Sun, Oct 2, 2016 at 9:00 PM, Thomas Munro
<thomas.munro@enterprisedb.com> wrote:

On Mon, Oct 3, 2016 at 1:36 PM, Robert Haas <robertmhaas@gmail.com> wrote:

On Sat, Oct 1, 2016 at 3:33 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Copy-editing for contrib/pg_visibility documentation.

Add omitted names for some function parameters.
Fix some minor grammatical issues.

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.

'Which' looks OK to me too here, but I speak some kind of British
English, and it looks like at least some writers of formal American
English prefer 'that' here:

* http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Whichvs.That.html?old=Whichvs.That01.html
* https://en.oxforddictionaries.com/usage/that-or-which

Gosh, I think "she held out the hand that was hurt" is clearly worse
than "she held out the hand which was hurt", but even if someone
prefers the opposite, correcting it as a supposed grammatical error
strikes me as arrant pedantry. You know, the kind up with which I
don't particularly wish to put.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Oct 3, 2016 at 11:06 AM, Robert Haas <robertmhaas@gmail.com> wrote:

On Sun, Oct 2, 2016 at 9:00 PM, Thomas Munro
<thomas.munro@enterprisedb.com> wrote:

On Mon, Oct 3, 2016 at 1:36 PM, Robert Haas <robertmhaas@gmail.com> wrote:

On Sat, Oct 1, 2016 at 3:33 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Copy-editing for contrib/pg_visibility documentation.

Add omitted names for some function parameters.
Fix some minor grammatical issues.

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.

'Which' looks OK to me too here, but I speak some kind of British
English, and it looks like at least some writers of formal American
English prefer 'that' here:

* http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Whichvs.That.html?old=Whichvs.That01.html
* https://en.oxforddictionaries.com/usage/that-or-which

Gosh, I think "she held out the hand that was hurt" is clearly worse
than "she held out the hand which was hurt", but even if someone
prefers the opposite, correcting it as a supposed grammatical error
strikes me as arrant pedantry. You know, the kind up with which I
don't particularly wish to put.

Interesting, "which" seems more natural to me, perhaps because of
classes at school based on "Britain English". My teachers sometimes
referred to "American English" as something to run away from as far as
possible.
--
Michael

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Robert Haas <robertmhaas@gmail.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?

regards, tom lane

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Oct 3, 2016 at 8:51 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Robert Haas <robertmhaas@gmail.com> writes:

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.

Yeah, as was noted downthread, that's the British view of it.

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.

I deliberately chose an example in which the implication was silly, but
in other cases it's less silly and so it may not be clear to the reader
that you didn't intend to imply it.

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

Sure, but you can make examples in the other direction as well. FWIW,
I agree that it's a good idea to try to avoid "that that" and similar
cases where confusion could be introduced by multiple possible meanings
of "that"; and this particular grammatical rule sometimes loses out in
such cases. But the changes you complained about didn't involve any
such situation.

Anyway, we've probably beaten this horse to death.

regards, tom lane

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Oct 3, 2016 at 9:22 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

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.

Yeah, as was noted downthread, that's the British view of it.

Even in the Midwest I have frequently heard people arguing to avoid
"that" in most situations where either could work. I ran into one
professor who went to what I considered silly lengths to expurgate
the word from documents.

Anyway, we've probably beaten this horse to death.

Just to be sure of that, I'll cite the Chicago Manual of Style (my
preferred style guide), which seems to chart a course somewhere in
the middle:

http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Whichvs.That.html

--
Kevin Grittner
EDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Oct 3, 2016 at 3:33 PM, Kevin Grittner <kgrittn@gmail.com> wrote:

Anyway, we've probably beaten this horse to death.

Just to be sure of that, I'll cite the Chicago Manual of Style (my
preferred style guide), which seems to chart a course somewhere in
the middle:

http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Whichvs.That.html

I'd say that charts a policy which I can live with.

/me ducks

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers