From bcbb402e319d17b12eb45f8dc5b3f5ebbf2514ea Mon Sep 17 00:00:00 2001
From: Teodor Sigaev <teodor@sigaev.ru>
Date: Mon, 18 Sep 2006 12:11:36 +0000
Subject: [PATCH] Improve wordings by David Fuhry <dfuhry@cs.kent.edu>
---
doc/src/sgml/config.sgml | 4 ++--
doc/src/sgml/gin.sgml | 37 +++++++++++++++++++------------------
doc/src/sgml/indices.sgml | 6 +++---
doc/src/sgml/mvcc.sgml | 12 +++++++-----
doc/src/sgml/xindex.sgml | 6 +++---
5 files changed, 34 insertions(+), 31 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cd2edd3d2c8..a4e3eb020bb 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.87 2006/09/16 00:30:12 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.88 2006/09/18 12:11:36 teodor Exp $ -->
<chapter Id="runtime-config">
<title>Server Configuration</title>
@@ -2180,7 +2180,7 @@ SELECT * FROM parent WHERE key = 2400;
</indexterm>
<listitem>
<para>
- Soft upper limit of the size of the returned set by GIN index. For more
+ Soft upper limit of the size of the set returned by GIN index. For more
information see <xref linkend="gin-tips">.
</para>
</listitem>
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 0e9365cce27..6b382230fd0 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/gin.sgml,v 2.3 2006/09/14 21:15:07 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/gin.sgml,v 2.4 2006/09/18 12:11:36 teodor Exp $ -->
<chapter id="GIN">
<title>GIN Indexes</title>
@@ -14,7 +14,7 @@
<para>
<acronym>GIN</acronym> stands for Generalized Inverted Index. It is
an index structure storing a set of (key, posting list) pairs, where
- 'posting list' is a set of rows in which the key occurs. The
+ 'posting list' is a set of rows in which the key occurs. Each
row may contain many keys.
</para>
@@ -104,7 +104,8 @@
<listitem>
<para>
Returns an array of keys of the query to be executed. n contains
- strategy number of operation (see <xref linkend="xindex-strategies">).
+ the strategy number of the operation
+ (see <xref linkend="xindex-strategies">).
Depending on n, query may be different type.
</para>
</listitem>
@@ -114,9 +115,9 @@
<term>bool consistent( bool check[], StrategyNumber n, Datum query)</term>
<listitem>
<para>
- Returns TRUE if indexed value satisfies query qualifier with strategy n
- (or may satisfy in case of RECHECK mark in operator class).
- Each element of the check array is TRUE if indexed value has a
+ Returns TRUE if the indexed value satisfies the query qualifier with
+ strategy n (or may satisfy in case of RECHECK mark in operator class).
+ Each element of the check array is TRUE if the indexed value has a
corresponding key in the query: if (check[i] == TRUE ) the i-th key of
the query is present in the indexed value.
</para>
@@ -135,10 +136,10 @@
<term>Create vs insert</term>
<listitem>
<para>
- In most cases, insertion into <acronym>GIN</acronym> index is slow because
- many GIN keys may be inserted for each table row. So, when loading data
- in bulk it may be useful to drop index and recreate it
- after the data is loaded in the table.
+ In most cases, insertion into <acronym>GIN</acronym> index is slow
+ due to the likelihood of many keys being inserted for each value.
+ So, for bulk insertions into a table it is advisable to to drop the GIN
+ index and recreate it after finishing bulk insertion.
</para>
</listitem>
</varlistentry>
@@ -147,7 +148,7 @@
<term>gin_fuzzy_search_limit</term>
<listitem>
<para>
- The primary goal of development <acronym>GIN</acronym> indices was
+ The primary goal of developing <acronym>GIN</acronym> indices was
support for highly scalable, full-text search in
<productname>PostgreSQL</productname> and there are often situations when
a full-text search returns a very large set of results. Since reading
@@ -158,7 +159,7 @@
<para>
Such queries usually contain very frequent words, so the results are not
very helpful. To facilitate execution of such queries
- <acronym>GIN</acronym> has a configurable soft upper limit of the size
+ <acronym>GIN</acronym> has a configurable soft upper limit of the size
of the returned set, determined by the
<varname>gin_fuzzy_search_limit</varname> GUC variable. It is set to 0 by
default (no limit).
@@ -182,16 +183,16 @@
<title>Limitations</title>
<para>
- <acronym>GIN</acronym> doesn't support full scan of index due to it's
- extremely inefficiency: because of a lot of keys per value,
+ <acronym>GIN</acronym> doesn't support full index scans due to their
+ extremely inefficiency: because there are often many keys per value,
each heap pointer will returned several times.
</para>
<para>
- When extractQuery returns zero number of keys, <acronym>GIN</acronym> will
- emit a error: for different opclass and strategy semantic meaning of void
- query may be different (for example, any array contains void array,
- but they aren't overlapped with void one), and <acronym>GIN</acronym> can't
+ When extractQuery returns zero keys, <acronym>GIN</acronym> will emit a
+ error: for different opclasses and strategies the semantic meaning of a void
+ query may be different (for example, any array contains the void array,
+ but they don't overlap the void array), and <acronym>GIN</acronym> can't
suggest reasonable answer.
</para>
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 04f6401f6ca..59ca5525caf 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.63 2006/09/16 00:30:14 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.64 2006/09/18 12:11:36 teodor Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
@@ -248,7 +248,7 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
<see>index</see>
</indexterm>
GIN is a inverted index and it's usable for values which have more
- than one key, arrays for example. Like to GiST, GIN may support
+ than one key, arrays for example. Like GiST, GIN may support
many different user-defined indexing strategies and the particular
operators with which a GIN index can be used vary depending on the
indexing strategy.
@@ -266,7 +266,7 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
(See <xref linkend="functions-array"> for the meaning of
these operators.)
- Another GIN operator classes are available in the <literal>contrib</>
+ Other GIN operator classes are available in the <literal>contrib</>
tsearch2 and intarray modules. For more information see <xref linkend="GIN">.
</para>
</sect1>
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index d2deee2bfca..2dd3f993725 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.61 2006/09/17 22:50:31 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.62 2006/09/18 12:11:36 teodor Exp $ -->
<chapter id="mvcc">
<title>Concurrency Control</title>
@@ -993,10 +993,12 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
</term>
<listitem>
<para>
- Short-term share/exclusive page-level locks are used for
- read/write access. Locks are released immediately after each
- index row is fetched or inserted. However, note that a GIN index
- usually requires several inserts for each table row.
+ Short-term share/exclusive page-level locks are used for
+ read/write access. Locks are released immediately after each
+ index row is fetched or inserted. But note that a GIN-indexed
+ value insertion usually produces several index key insertions
+ per row, so GIN may do substantial work for a single value's
+ insertion.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 11d63f4d647..eda2aa5ca2b 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/xindex.sgml,v 1.48 2006/09/16 00:30:16 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/xindex.sgml,v 1.49 2006/09/18 12:11:36 teodor Exp $ -->
<sect1 id="xindex">
<title>Interfacing Extensions To Indexes</title>
@@ -243,8 +243,8 @@
</table>
<para>
- GIN indexes are similar to GiST in flexibility: it hasn't a fixed set
- of strategies. Instead, the <quote>consistency</> support routine
+ GIN indexes are similar to GiST's in flexibility: they don't have a fixed
+ et of strategies. Instead, the <quote>consistency</> support routine
interprets the strategy numbers accordingly with operator class
definition. As an example, strategies of operator class over arrays
is shown in <xref linkend="xindex-gin-array-strat-table">.
--
GitLab