Thread: some grammar fixes for docs

Hi,

I have noticed imperfect grammar in a couple of sgml files, please 
consider a small patch (attached).

-- 
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company

On Thu, May 16, 2019 at 05:11:37PM +0300, Liudmila Mantrova wrote:
> I have noticed imperfect grammar in a couple of sgml files, please consider
> a small patch (attached).

Thanks, Liudmila for caring about such matters.

>         <para>
> -        Transaction which last more than <replaceable>limit</replaceable> milliseconds
> +        Transactions that last more than <replaceable>limit</replaceable> milliseconds
>          are counted and reported separately, as <firstterm>late</firstterm>.
>         </para>

I don't see much of a difference between "which" or "that" in this
context, and you are right about the plural for "Transactions".  Any
native English speaker around or anybody with an extra opinion?

>   <para>
>    Of the two operator classes for type <type>point</type>,
>    <literal>quad_point_ops</literal> is the default.  <literal>kd_point_ops</literal>
> -  supports the same operators but uses a different index data structure which
> +  supports the same operators but uses a different index data structure that
>    may offer better performance in some applications.
>   </para>

Same here.

> @@ -447,9 +447,9 @@ typedef struct spgChooseOut
>         type that was to be inserted into the index.
>         <structfield>leafDatum</structfield> is a value of
>         <structname>spgConfigOut</structname>.<structfield>leafType</structfield>
> -       type which is initially an result of method
> +       type, which is initially a result of method

I actually would not add a comma here, as the follow-up expression
gives more details about the leaf type previously mentioned.

>         <function>compress</function> applied to <structfield>datum</structfield>
> -       when method <function>compress</function> is provided, or same value as
> +       when method <function>compress</function> is provided, or the same value as

I would do what you suggest here.

>         Converts the data item into a format suitable for physical storage in
>         a leaf tuple of index page.  It accepts
>         <structname>spgConfigIn</structname>.<structfield>attType</structfield>
> -       value and return
> +       value and returns

This one is right.  Good catch.
--
Michael

On 5/16/19 7:32 PM, Michael Paquier wrote:
> On Thu, May 16, 2019 at 05:11:37PM +0300, Liudmila Mantrova wrote:
>> I have noticed imperfect grammar in a couple of sgml files, please consider
>> a small patch (attached).
>
> Thanks, Liudmila for caring about such matters.
>
>>         <para>
>> -        Transaction which last more than <replaceable>limit</replaceable> milliseconds
>> +        Transactions that last more than <replaceable>limit</replaceable> milliseconds
>>          are counted and reported separately, as <firstterm>late</firstterm>.
>>         </para>
>
> I don't see much of a difference between "which" or "that" in this
> context, and you are right about the plural for "Transactions".  Any
> native English speaker around or anybody with an extra opinion?
>
>>   <para>
>>    Of the two operator classes for type <type>point</type>,
>>    <literal>quad_point_ops</literal> is the default.  <literal>kd_point_ops</literal>
>> -  supports the same operators but uses a different index data structure which
>> +  supports the same operators but uses a different index data structure that
>>    may offer better performance in some applications.
>>   </para>
>
> Same here.

Technically it should be "that" - often you say "which" when one is
speaking, but in writing, in the above cases, "that" is grammatically
correct.

Thanks,

Jonathan

Michael Paquier <michael@paquier.xyz> writes:
> On Thu, May 16, 2019 at 05:11:37PM +0300, Liudmila Mantrova wrote:
>> -        Transaction which last more than <replaceable>limit</replaceable> milliseconds
>> +        Transactions that last more than <replaceable>limit</replaceable> milliseconds

> I don't see much of a difference between "which" or "that" in this
> context, and you are right about the plural for "Transactions".  Any
> native English speaker around or anybody with an extra opinion?

A lot of native speakers are sloppy about this :-(, but Liudmila is
correct.

Grammarians will tell you that "which" after a noun introduces a
descriptive clause (something that just adds information about an
already sufficiently-defined subject) while "that" introduces a
restrictive clause (something that narrows the scope of the subject).
So,

    Transactions that have property X have property Y.

is just asserting "if X then Y"; it makes no claims about transactions
that do not have property X.  But

    Transactions, which have property X, have property Y.

is basically asserting that all transactions have both properties.
(Adding or removing the commas doesn't change the meaning, but it's
often easier to read it correctly with the commas.  Or you could use
parentheses for the same effect.  Using commas/parens in this way
with "that" is incorrect, mainly because it makes the reader wonder
if you meant "which" instead.)

This distinction is widely ignored in casual speech or writing, but
it's still recognized in formal writing.  I think our manual is
formal enough that we should try to get it right.

            regards, tom lane

On Thu, May 16, 2019 at 07:55:57PM -0400, Tom Lane wrote:
> This distinction is widely ignored in casual speech or writing, but
> it's still recognized in formal writing.  I think our manual is
> formal enough that we should try to get it right.

Thanks for the inputs, Tom and Jonathan.  I see the difference now.
--
Michael

On Fri, May 17, 2019 at 09:22:09AM +0900, Michael Paquier wrote:
> Thanks for the inputs, Tom and Jonathan.  I see the difference now.

And committed down to 9.4 where relevant parts apply.
--
Michael