pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedsome grammar fixes for docs
6+ messages / 4 participants
[nested] [flat]
* some grammar fixes for docs
@ 2019-05-16 14:11 Liudmila Mantrova <l.mantrova@postgrespro.ru>
0 siblings, 1 reply; 6+ messages in thread
From: Liudmila Mantrova @ 2019-05-16 14:11 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] grammar-fixes.patch (3.1K, ../../92961161-9b49-e42f-0a72-d5d47e0ed4de@postgrespro.ru/2-grammar-fixes.patch)
download | inline diff:
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ee2501b..ef22a48 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -443,7 +443,7 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
<term><option>--latency-limit=</option><replaceable>limit</replaceable></term>
<listitem>
<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>
<para>
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index d43ef13..7cf9d0e 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -206,7 +206,7 @@
<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>
<para>
@@ -292,9 +292,9 @@
<function>leaf_consistent</function> additionally returns a <type>boolean</type> result.
The methods must not modify any fields of their input structs. In all
cases, the output struct is initialized to zeroes before calling the
- user-defined method. Optional sixth method <function>compress</function>
- accepts datum to be indexed as the only argument and returns value suitable
- for physical storage in leaf tuple.
+ user-defined method. The optional sixth method <function>compress</function>
+ accepts datum to be indexed as the only argument and returns a value suitable
+ for physical storage in a leaf tuple.
</para>
<para>
@@ -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
<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
<structfield>datum</structfield> otherwise.
<structfield>leafDatum</structfield> can change at lower levels of the tree
if the <function>choose</function> or <function>picksplit</function>
@@ -868,7 +868,7 @@ typedef struct spgLeafConsistentOut
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
<structname>spgConfigOut</structname>.<structfield>leafType</structfield>
value. Output value should not be toasted.
</para>
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: some grammar fixes for docs
@ 2019-05-16 23:32 Michael Paquier <michael@paquier.xyz>
parent: Liudmila Mantrova <l.mantrova@postgrespro.ru>
0 siblings, 2 replies; 6+ messages in thread
From: Michael Paquier @ 2019-05-16 23:32 UTC (permalink / raw)
To: Liudmila Mantrova <l.mantrova@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
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
Attachments:
[application/pgp-signature] signature.asc (832B, ../../20190516233253.GB20887@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: some grammar fixes for docs
@ 2019-05-16 23:36 Jonathan S. Katz <jkatz@postgresql.org>
parent: Michael Paquier <michael@paquier.xyz>
1 sibling, 0 replies; 6+ messages in thread
From: Jonathan S. Katz @ 2019-05-16 23:36 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; Liudmila Mantrova <l.mantrova@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
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
Attachments:
[application/pgp-signature] signature.asc (832B, ../../8c3041c5-9d37-a310-c884-f38709ffbe65@postgresql.org/2-signature.asc)
download
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: some grammar fixes for docs
@ 2019-05-16 23:55 Tom Lane <tgl@sss.pgh.pa.us>
parent: Michael Paquier <michael@paquier.xyz>
1 sibling, 1 reply; 6+ messages in thread
From: Tom Lane @ 2019-05-16 23:55 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: Liudmila Mantrova <l.mantrova@postgrespro.ru>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: some grammar fixes for docs
@ 2019-05-17 00:22 Michael Paquier <michael@paquier.xyz>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 6+ messages in thread
From: Michael Paquier @ 2019-05-17 00:22 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Liudmila Mantrova <l.mantrova@postgrespro.ru>; pgsql-docs@lists.postgresql.org
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
Attachments:
[application/pgp-signature] signature.asc (832B, ../../20190517002209.GF20887@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: some grammar fixes for docs
@ 2019-05-20 00:51 Michael Paquier <michael@paquier.xyz>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 0 replies; 6+ messages in thread
From: Michael Paquier @ 2019-05-20 00:51 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Liudmila Mantrova <l.mantrova@postgrespro.ru>; pgsql-docs@lists.postgresql.org
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
Attachments:
[application/pgp-signature] signature.asc (832B, ../../20190520005120.GA1923@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2019-05-20 00:51 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-05-16 14:11 some grammar fixes for docs Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-05-16 23:32 ` Michael Paquier <michael@paquier.xyz>
2019-05-16 23:36 ` Jonathan S. Katz <jkatz@postgresql.org>
2019-05-16 23:55 ` Tom Lane <tgl@sss.pgh.pa.us>
2019-05-17 00:22 ` Michael Paquier <michael@paquier.xyz>
2019-05-20 00:51 ` Michael Paquier <michael@paquier.xyz>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox