[Justin Pryzby <pryzby@telsasoft.com>]

On Sat, Mar 28, 2020 at 06:05:51PM +0300, Alexander Korotkov wrote:
> On Wed, Mar 18, 2020 at 3:28 AM Nikita Glukhov <n.gluhov@postgrespro.ru> wrote:
> > Attached new version of reordered patches.
> 
> I'm going to push this if no objections.

Find attached patch with editorial corrections to docs for this commit.

--word-diff to follow.

commit d3f077b813efa90b25a162bf8d227f3e4218c248
Author: Justin Pryzby <pryzbyj@telsasoft.com>
Date:   Mon Mar 30 20:55:06 2020 -0500

    Doc review: Implement operator class parameters
    
    commit 911e70207703799605f5a0e8aad9f06cff067c63
    Author: Alexander Korotkov <akorotkov@postgresql.org>

diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index f1f2b08cd7..b2e04d0815 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -468,13 +468,13 @@ CREATE INDEX hidx ON testhstore USING GIN (h);
</programlisting>

  <para>
   <literal>gist_hstore_ops</literal> GiST opclass approximates {+a+} set of
   key/value pairs as a bitmap signature.  [-Optional-]{+Its optional+} integer parameter
   <literal>siglen</literal>[-of <literal>gist_hstore_ops</literal>-] determines {+the+}
   signature length in bytes.  [-Default signature-]{+The default+} length is 16 bytes.
   Valid values of signature length are between 1 and 2024 bytes.  Longer
   signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan-]
[-   less-]{+the index and+}
{+   fewer+} heap pages), [-but-]{+at the cost of a+} larger index.
  </para>

  <para>
diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml
index 72b4b23c15..7956a746a6 100644
--- a/doc/src/sgml/intarray.sgml
+++ b/doc/src/sgml/intarray.sgml
@@ -265,7 +265,7 @@
  </para>

  <para>
   Two [-parametrized-]{+parameterized+} GiST index operator classes are provided:
   <literal>gist__int_ops</literal> (used by default) is suitable for
   small- to medium-size data sets, while
   <literal>gist__intbig_ops</literal> uses a larger signature and is more
@@ -276,22 +276,23 @@
  </para>
   
  <para>
   <literal>gist__int_ops</literal> approximates {+an+} integer set as an array of
   integer ranges.  [-Optional-]{+Its optional+} integer parameter <literal>numranges</literal>[-of-]
[-   <literal>gist__int_ops</literal>-]
   determines {+the+} maximum number of ranges in
   one index key.  [-Default-]{+The default+} value of <literal>numranges</literal> is 100.
   Valid values are between 1 and 253.  Using larger arrays as GiST index
   keys leads to {+a+} more precise search [-(scan less-]{+(scaning a smaller+} fraction of [-index, scan less-]{+the index and+}
{+   fewer+} heap pages), [-but-]{+at the cost of a+} larger index.
  </para>
   
  <para>
   <literal>gist__intbig_ops</literal> approximates {+an+} integer set as a bitmap
   [-signature.  Optional-]{+signature XXX.  Its optional+} integer parameter <literal>siglen</literal>[-of-]
[-   <literal>gist__intbig_ops</literal>-]
   determines {+the+} signature length in bytes.
   [-Default-]{+The default+} signature length is 16 bytes.  Valid values of signature length
   are between 1 and 2024 bytes.  Longer signatures [-leads-]{+lead+} to {+a+} more precise
   search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan less-]{+the index and fewer+} heap pages), [-but-]{+at+}
{+   the cost of a+} larger index.
  </para>

  <para>
diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml
index ae4b33ec85..4971b71524 100644
--- a/doc/src/sgml/ltree.sgml
+++ b/doc/src/sgml/ltree.sgml
@@ -506,16 +506,16 @@ Europe &amp; Russia*@ &amp; !Transportation
     <literal>@</literal>, <literal>~</literal>, <literal>?</literal>
    </para>
    <para>
     <literal>gist_ltree_ops</literal> GiST opclass approximates {+a+} set of
     path labels as a bitmap signature.  [-Optional-]{+Its optional+} integer parameter
     <literal>siglen</literal>[-of <literal>gist_ltree_ops</literal>-] determines {+the+}
     signature length in bytes.  [-Default-]{+The default+} signature length is 8 bytes.
     Valid values of signature length are between 1 and 2024 bytes.  Longer
     signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan-]
[-     less-]{+the index and+}
{+     fewer+} heap pages), [-but-]{+at the cost of a+} larger index.
    </para>
    <para>
     Example of creating such an index with [-a-]{+the+} default signature length of 8 bytes:
    </para>
<programlisting>
CREATE INDEX path_gist_idx ON test USING GIST (path);
@@ -535,13 +535,13 @@ CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100));
     <literal>@</literal>, <literal>~</literal>, <literal>?</literal>
    </para>
    <para>
     <literal>gist__ltree_ops</literal> GiST opclass works [-similar-]{+similarly+} to
     <literal>gist_ltree_ops</literal> and also takes signature length as
     a parameter.  [-Default-]{+The default+} value of <literal>siglen</literal> in
      <literal>gist__ltree_ops</literal> is 28 bytes.
    </para>
    <para>
     Example of creating such an index with [-a-]{+the+} default signature length of 28 bytes:
    </para>
<programlisting>
CREATE INDEX path_gist_idx ON test USING GIST (array_path);
diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml
index dde02634ae..97b3d13a88 100644
--- a/doc/src/sgml/pgtrgm.sgml
+++ b/doc/src/sgml/pgtrgm.sgml
@@ -391,13 +391,13 @@ CREATE INDEX trgm_idx ON test_trgm USING GIN (t gin_trgm_ops);
  </para>

  <para>
   <literal>gist_trgm_ops</literal> GiST opclass approximates {+a+} set of
   trigrams as a bitmap signature.  [-Optional-]{+Its optional+} integer parameter
   <literal>siglen</literal>[-of <literal>gist_trgm_ops</literal>-] determines {+the+}
   signature length in bytes.  [-Default signature-]{+The default+} length is 12 bytes.
   Valid values of signature length are between 1 and 2024 bytes.  Longer
   signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan-]
[-   less-]{+the index and+}
{+   fewer+} heap pages), [-but-]{+at the cost of a+} larger index.
  </para>

  <para>
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 2217fcd6c2..0dc427289d 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -3670,17 +3670,17 @@ SELECT plainto_tsquery('supernovae stars');
   to check the actual table row to eliminate such false matches.
   (<productname>PostgreSQL</productname> does this automatically when needed.)
   GiST indexes are lossy because each document is represented in the
   index by a fixed-length signature.  [-Signature-]{+The signature+} length in bytes is determined
   by the value of the optional integer parameter <literal>siglen</literal>.
   [-Default-]{+The default+} signature length (when <literal>siglen</literal> is not [-specied)-]{+specified)+} is
   124 bytes, [-maximal-]{+the maximum signature+} length is 2024 bytes. The signature is generated by hashing
   each word into a single bit in an n-bit string, with all these bits OR-ed
   together to produce an n-bit document signature.  When two words hash to
   the same bit position there will be a false match.  If all words in
   the query have matches (real or false) then the table row must be
   retrieved to see if the match is correct.  Longer signatures [-leads-]{+lead+} to {+a+} more
   precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan less-]{+the index and fewer+} heap
   pages), [-but-]{+at the cost of a+} larger index.
  </para>

  <para>

Attachments:

  [text/x-diff] v1-0001-Doc-review-Implement-operator-class-parameters.patch (9.4K, ../20200331024419.GB14618@telsasoft.com/2-v1-0001-Doc-review-Implement-operator-class-parameters.patch)
  download | inline diff:
From d3f077b813efa90b25a162bf8d227f3e4218c248 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Mon, 30 Mar 2020 20:55:06 -0500
Subject: [PATCH v1] Doc review: Implement operator class parameters

commit 911e70207703799605f5a0e8aad9f06cff067c63
Author: Alexander Korotkov <akorotkov@postgresql.org>
---
 doc/src/sgml/hstore.sgml     | 12 ++++++------
 doc/src/sgml/intarray.sgml   | 27 ++++++++++++++-------------
 doc/src/sgml/ltree.sgml      | 20 ++++++++++----------
 doc/src/sgml/pgtrgm.sgml     | 12 ++++++------
 doc/src/sgml/textsearch.sgml | 12 ++++++------
 5 files changed, 42 insertions(+), 41 deletions(-)

diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index f1f2b08cd7..b2e04d0815 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -468,13 +468,13 @@ CREATE INDEX hidx ON testhstore USING GIN (h);
 </programlisting>
 
   <para>
-   <literal>gist_hstore_ops</literal> GiST opclass approximates set of
-   key/value pairs as a bitmap signature.  Optional integer parameter
-   <literal>siglen</literal> of <literal>gist_hstore_ops</literal> determines
-   signature length in bytes.  Default signature length is 16 bytes.
+   <literal>gist_hstore_ops</literal> GiST opclass approximates a set of
+   key/value pairs as a bitmap signature.  Its optional integer parameter
+   <literal>siglen</literal> determines the
+   signature length in bytes.  The default length is 16 bytes.
    Valid values of signature length are between 1 and 2024 bytes.  Longer
-   signatures leads to more precise search (scan less fraction of index, scan
-   less heap pages), but larger index.
+   signatures lead to a more precise search (scanning a smaller fraction of the index and
+   fewer heap pages), at the cost of a larger index.
   </para>
 
   <para>
diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml
index 72b4b23c15..7956a746a6 100644
--- a/doc/src/sgml/intarray.sgml
+++ b/doc/src/sgml/intarray.sgml
@@ -265,7 +265,7 @@
   </para>
 
   <para>
-   Two parametrized GiST index operator classes are provided:
+   Two parameterized GiST index operator classes are provided:
    <literal>gist__int_ops</literal> (used by default) is suitable for
    small- to medium-size data sets, while
    <literal>gist__intbig_ops</literal> uses a larger signature and is more
@@ -276,22 +276,23 @@
   </para>
    
   <para>
-   <literal>gist__int_ops</literal> approximates integer set as an array of
-   integer ranges.  Optional integer parameter <literal>numranges</literal> of
-   <literal>gist__int_ops</literal> determines maximum number of ranges in
-   one index key.  Default value of <literal>numranges</literal> is 100.
+   <literal>gist__int_ops</literal> approximates an integer set as an array of
+   integer ranges.  Its optional integer parameter <literal>numranges</literal>
+   determines the maximum number of ranges in
+   one index key.  The default value of <literal>numranges</literal> is 100.
    Valid values are between 1 and 253.  Using larger arrays as GiST index
-   keys leads to more precise search (scan less fraction of index, scan less
-   heap pages), but larger index.
+   keys leads to a more precise search (scaning a smaller fraction of the index and
+   fewer heap pages), at the cost of a larger index.
   </para>
    
   <para>
-   <literal>gist__intbig_ops</literal> approximates integer set as a bitmap
-   signature.  Optional integer parameter <literal>siglen</literal> of
-   <literal>gist__intbig_ops</literal> determines signature length in bytes.
-   Default signature length is 16 bytes.  Valid values of signature length
-   are between 1 and 2024 bytes.  Longer signatures leads to more precise
-   search (scan less fraction of index, scan less heap pages), but larger index.
+   <literal>gist__intbig_ops</literal> approximates an integer set as a bitmap
+   signature XXX.  Its optional integer parameter <literal>siglen</literal>
+   determines the signature length in bytes.
+   The default signature length is 16 bytes.  Valid values of signature length
+   are between 1 and 2024 bytes.  Longer signatures lead to a more precise
+   search (scanning a smaller fraction of the index and fewer heap pages), at
+   the cost of a larger index.
   </para>
 
   <para>
diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml
index ae4b33ec85..4971b71524 100644
--- a/doc/src/sgml/ltree.sgml
+++ b/doc/src/sgml/ltree.sgml
@@ -506,16 +506,16 @@ Europe &amp; Russia*@ &amp; !Transportation
      <literal>@</literal>, <literal>~</literal>, <literal>?</literal>
     </para>
     <para>
-     <literal>gist_ltree_ops</literal> GiST opclass approximates set of
-     path labels as a bitmap signature.  Optional integer parameter
-     <literal>siglen</literal> of <literal>gist_ltree_ops</literal> determines
-     signature length in bytes.  Default signature length is 8 bytes.
+     <literal>gist_ltree_ops</literal> GiST opclass approximates a set of
+     path labels as a bitmap signature.  Its optional integer parameter
+     <literal>siglen</literal> determines the
+     signature length in bytes.  The default signature length is 8 bytes.
      Valid values of signature length are between 1 and 2024 bytes.  Longer
-     signatures leads to more precise search (scan less fraction of index, scan
-     less heap pages), but larger index.
+     signatures lead to a more precise search (scanning a smaller fraction of the index and
+     fewer heap pages), at the cost of a larger index.
     </para>
     <para>
-     Example of creating such an index with a default signature length of 8 bytes:
+     Example of creating such an index with the default signature length of 8 bytes:
     </para>
 <programlisting>
 CREATE INDEX path_gist_idx ON test USING GIST (path);
@@ -535,13 +535,13 @@ CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100));
      <literal>@</literal>, <literal>~</literal>, <literal>?</literal>
     </para>
     <para>
-     <literal>gist__ltree_ops</literal> GiST opclass works similar to
+     <literal>gist__ltree_ops</literal> GiST opclass works similarly to
      <literal>gist_ltree_ops</literal> and also takes signature length as
-     a parameter.  Default value of <literal>siglen</literal> in
+     a parameter.  The default value of <literal>siglen</literal> in
       <literal>gist__ltree_ops</literal> is 28 bytes.
     </para>
     <para>
-     Example of creating such an index with a default signature length of 28 bytes:
+     Example of creating such an index with the default signature length of 28 bytes:
     </para>
 <programlisting>
 CREATE INDEX path_gist_idx ON test USING GIST (array_path);
diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml
index dde02634ae..97b3d13a88 100644
--- a/doc/src/sgml/pgtrgm.sgml
+++ b/doc/src/sgml/pgtrgm.sgml
@@ -391,13 +391,13 @@ CREATE INDEX trgm_idx ON test_trgm USING GIN (t gin_trgm_ops);
   </para>
 
   <para>
-   <literal>gist_trgm_ops</literal> GiST opclass approximates set of
-   trigrams as a bitmap signature.  Optional integer parameter
-   <literal>siglen</literal> of <literal>gist_trgm_ops</literal> determines
-   signature length in bytes.  Default signature length is 12 bytes.
+   <literal>gist_trgm_ops</literal> GiST opclass approximates a set of
+   trigrams as a bitmap signature.  Its optional integer parameter
+   <literal>siglen</literal> determines the
+   signature length in bytes.  The default length is 12 bytes.
    Valid values of signature length are between 1 and 2024 bytes.  Longer
-   signatures leads to more precise search (scan less fraction of index, scan
-   less heap pages), but larger index.
+   signatures lead to a more precise search (scanning a smaller fraction of the index and
+   fewer heap pages), at the cost of a larger index.
   </para>
 
   <para>
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 2217fcd6c2..0dc427289d 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -3670,17 +3670,17 @@ SELECT plainto_tsquery('supernovae stars');
    to check the actual table row to eliminate such false matches.
    (<productname>PostgreSQL</productname> does this automatically when needed.)
    GiST indexes are lossy because each document is represented in the
-   index by a fixed-length signature.  Signature length in bytes is determined
+   index by a fixed-length signature.  The signature length in bytes is determined
    by the value of the optional integer parameter <literal>siglen</literal>.
-   Default signature length (when <literal>siglen</literal> is not specied) is
-   124 bytes, maximal length is 2024 bytes. The signature is generated by hashing
+   The default signature length (when <literal>siglen</literal> is not specified) is
+   124 bytes, the maximum signature length is 2024 bytes. The signature is generated by hashing
    each word into a single bit in an n-bit string, with all these bits OR-ed
    together to produce an n-bit document signature.  When two words hash to
    the same bit position there will be a false match.  If all words in
    the query have matches (real or false) then the table row must be
-   retrieved to see if the match is correct.  Longer signatures leads to more
-   precise search (scan less fraction of index, scan less heap pages), but
-   larger index.
+   retrieved to see if the match is correct.  Longer signatures lead to a more
+   precise search (scanning a smaller fraction of the index and fewer heap
+   pages), at the cost of a larger index.
   </para>
 
   <para>
-- 
2.17.0