docs: Merge separate chapters on built-in index AMs into one.

The documentation index is getting very long, which makes it hard
to find things. Since these chapters are all very similar in structure
and content, merging them is a natural way of reducing the size of
the toplevel index.

Rather than actually combining all of the SGML into a single file,
keep one file per <sect1>, and add a glue file that includes all
of them.

Discussion: http://postgr.es/m/CA+Tgmob7_uoYuS2=rVwpVXaRwP-UXz+++saYTC-BCZ42QzSNKQ@mail.gmail.com

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d898cc4720c00c58e797afb74ae6be32e3b9902e..64fb520db7e5129eabb1859a5f21d2f018ba0f2b 100644 (file)
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/brin.sgml -->
 
-<chapter id="brin">
+<sect1 id="brin">
 <title>BRIN Indexes</title>
 
    <indexterm>
@@ -8,7 +8,7 @@
     <secondary>BRIN</secondary>
    </indexterm>
 
-<sect1 id="brin-intro">
+<sect2 id="brin-intro">
  <title>Introduction</title>
 
  <para>
@@ -64,7 +64,7 @@
   be more precise and more data blocks can be skipped during an index scan.
  </para>
 
- <sect2 id="brin-operation">
+ <sect3 id="brin-operation">
   <title>Index Maintenance</title>
 
   <para>
@@ -136,10 +136,10 @@ LOG:  request for BRIN range summarization for index "brin_wi_idx" page 128 was
    See <xref linkend="functions-admin-index"/> for details.
   </para>
 
- </sect2>
-</sect1>
+ </sect3>
+</sect2>
 
-<sect1 id="brin-builtin-opclasses">
+<sect2 id="brin-builtin-opclasses">
  <title>Built-in Operator Classes</title>
 
  <para>
@@ -743,7 +743,7 @@ LOG:  request for BRIN range summarization for index "brin_wi_idx" page 128 was
   </tgroup>
  </table>
 
-  <sect2 id="brin-builtin-opclasses--parameters">
+  <sect3 id="brin-builtin-opclasses--parameters">
    <title>Operator Class Parameters</title>
 
    <para>
@@ -808,11 +808,11 @@ LOG:  request for BRIN range summarization for index "brin_wi_idx" page 128 was
    </varlistentry>
 
    </variablelist>
-  </sect2>
+  </sect3>
 
-</sect1>
+</sect2>
 
-<sect1 id="brin-extensibility">
+<sect2 id="brin-extensibility">
  <title>Extensibility</title>
 
  <para>
@@ -1340,5 +1340,5 @@ typedef struct BrinOpcInfo
     <literal>float4_minmax_ops</literal> as an example of minmax, and
     <literal>box_inclusion_ops</literal> as an example of inclusion.
  </para>
+</sect2>
 </sect1>
-</chapter>

diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index be8210286b63220576c72cca8e3ad60ea99fa3f5..2b3997988cff0fd38db32da643266c05fab7ba1a 100644 (file)
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/btree.sgml -->
 
-<chapter id="btree">
+<sect1 id="btree">
 <title>B-Tree Indexes</title>
 
    <indexterm>
@@ -8,7 +8,7 @@
     <secondary>B-Tree</secondary>
    </indexterm>
 
-<sect1 id="btree-intro">
+<sect2 id="btree-intro">
  <title>Introduction</title>
 
  <para>
@@ -30,9 +30,9 @@
   btree <acronym>AM</acronym> make use of them.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="btree-behavior">
+<sect2 id="btree-behavior">
  <title>Behavior of B-Tree Operator Classes</title>
 
  <para>
@@ -200,9 +200,9 @@
   planner relies on them for optimization purposes.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="btree-support-funcs">
+<sect2 id="btree-support-funcs">
  <title>B-Tree Support Functions</title>
 
  <para>
@@ -585,9 +585,9 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
   </varlistentry>
  </variablelist>
 
-</sect1>
+</sect2>
 
-<sect1 id="btree-implementation">
+<sect2 id="btree-implementation">
  <title>Implementation</title>
 
  <para>
@@ -597,7 +597,7 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
   distribution for a much more detailed, internals-focused description
   of the B-Tree implementation.
  </para>
- <sect2 id="btree-structure">
+ <sect3 id="btree-structure">
   <title>B-Tree Structure</title>
   <para>
    <productname>PostgreSQL</productname> B-Tree indexes are
@@ -627,9 +627,9 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
    the tree structure by creating a new root page that is one level
    above the original root page.
   </para>
- </sect2>
+ </sect3>
 
- <sect2 id="btree-deletion">
+ <sect3 id="btree-deletion">
   <title>Bottom-up Index Deletion</title>
   <para>
    B-Tree indexes are not directly aware that under MVCC, there might
@@ -731,9 +731,9 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
    two logical rows whose lifetimes span the same
    <command>VACUUM</command> cycle).
   </para>
- </sect2>
+ </sect3>
 
- <sect2 id="btree-deduplication">
+ <sect3 id="btree-deduplication">
   <title>Deduplication</title>
   <para>
    A duplicate is a leaf page tuple (a tuple that points to a table
@@ -908,7 +908,7 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
    </itemizedlist>
   </para>
 
- </sect2>
-</sect1>
+ </sect3>
+</sect2>
 
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 6360707d9f698b61060980865d3208c29c2a6ea3..3fb0709f5dfc868f240aa08be9bda6d4815da9bd 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -85,6 +85,7 @@
 <!ENTITY catalogs   SYSTEM "catalogs.sgml">
 <!ENTITY system-views  SYSTEM "system-views.sgml">
 <!ENTITY geqo       SYSTEM "geqo.sgml">
+<!ENTITY indextypes SYSTEM "indextypes.sgml">
 <!ENTITY btree      SYSTEM "btree.sgml">
 <!ENTITY gist       SYSTEM "gist.sgml">
 <!ENTITY spgist     SYSTEM "spgist.sgml">

diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 5bd1efae92e67a365b859ee436101c6904195a36..46e87e01324dd00c460dd98746788bd95d5ccfa3 100644 (file)
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/gin.sgml -->
 
-<chapter id="gin">
+<sect1 id="gin">
 <title>GIN Indexes</title>
 
    <indexterm>
@@ -8,7 +8,7 @@
     <secondary>GIN</secondary>
    </indexterm>
 
-<sect1 id="gin-intro">
+<sect2 id="gin-intro">
  <title>Introduction</title>
 
  <para>
@@ -60,9 +60,9 @@
   information about <acronym>GIN</acronym> on their
   <ulink url="http://www.sai.msu.su/~megera/wiki/Gin">website</ulink>.
  </para>
-</sect1>
+</sect2>
 
-<sect1 id="gin-builtin-opclasses">
+<sect2 id="gin-builtin-opclasses">
  <title>Built-in Operator Classes</title>
 
  <para>
@@ -140,9 +140,9 @@
   See <xref linkend="json-indexing"/> for details.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="gin-extensibility">
+<sect2 id="gin-extensibility">
  <title>Extensibility</title>
 
  <para>
@@ -458,9 +458,9 @@
   though the actual type might be something else depending on the operator.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="gin-implementation">
+<sect2 id="gin-implementation">
  <title>Implementation</title>
 
  <para>
@@ -497,7 +497,7 @@
   </mediaobject>
  </figure>
 
- <sect2 id="gin-fast-update">
+ <sect3 id="gin-fast-update">
   <title>GIN Fast Update Technique</title>
 
   <para>
@@ -535,9 +535,9 @@
    <acronym>GIN</acronym> index.  See <xref linkend="sql-createindex"/>
    for details.
   </para>
- </sect2>
+ </sect3>
 
- <sect2 id="gin-partial-match">
+ <sect3 id="gin-partial-match">
   <title>Partial Match Algorithm</title>
 
   <para>
@@ -554,11 +554,11 @@
    to be searched, or greater than zero if the index key is past the range
    that could match.
   </para>
- </sect2>
+ </sect3>
 
-</sect1>
+</sect2>
 
-<sect1 id="gin-tips">
+<sect2 id="gin-tips">
 <title>GIN Tips and Tricks</title>
 
  <variablelist>
@@ -653,9 +653,9 @@
   </varlistentry>
  </variablelist>
 
-</sect1>
+</sect2>
 
-<sect1 id="gin-limit">
+<sect2 id="gin-limit">
  <title>Limitations</title>
 
  <para>
@@ -667,9 +667,9 @@
   however that null key values contained within a non-null composite item
   or query value are supported.
  </para>
-</sect1>
+</sect2>
 
-<sect1 id="gin-examples">
+<sect2 id="gin-examples">
  <title>Examples</title>
 
  <para>
@@ -709,6 +709,6 @@
   </varlistentry>
  </variablelist>
  </para>
-</sect1>
+</sect2>
 
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 8a19f156d83c3a19e54733cfca97b912803366a5..3f7df103b8302b1e374f491eb0fee4f15f3b9d78 100644 (file)
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/gist.sgml -->
 
-<chapter id="gist">
+<sect1 id="gist">
 <title>GiST Indexes</title>
 
    <indexterm>
@@ -8,7 +8,7 @@
     <secondary>GiST</secondary>
    </indexterm>
 
-<sect1 id="gist-intro">
+<sect2 id="gist-intro">
  <title>Introduction</title>
 
  <para>
@@ -38,9 +38,9 @@
     <ulink url="http://www.sai.msu.su/~megera/postgres/gist/">web site</ulink>.
   </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="gist-builtin-opclasses">
+<sect2 id="gist-builtin-opclasses">
  <title>Built-in Operator Classes</title>
 
  <para>
@@ -222,9 +222,9 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
 </programlisting>
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="gist-extensibility">
+<sect2 id="gist-extensibility">
  <title>Extensibility</title>
 
  <para>
@@ -1260,12 +1260,12 @@ my_stratnum(PG_FUNCTION_ARGS)
    will accumulate for the duration of the operation.
   </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="gist-implementation">
+<sect2 id="gist-implementation">
  <title>Implementation</title>
 
- <sect2 id="gist-buffering-build">
+ <sect3 id="gist-buffering-build">
   <title>GiST Index Build Methods</title>
 
   <para>
@@ -1314,10 +1314,10 @@ my_stratnum(PG_FUNCTION_ARGS)
    is ordered.
   </para>
 
- </sect2>
-</sect1>
+ </sect3>
+</sect2>
 
-<sect1 id="gist-examples">
+<sect2 id="gist-examples">
  <title>Examples</title>
 
  <para>
@@ -1382,6 +1382,6 @@ my_stratnum(PG_FUNCTION_ARGS)
  </variablelist>
  </para>
 
-</sect1>
+</sect2>
 
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/hash.sgml b/doc/src/sgml/hash.sgml
index e35911ebf8eb4422a88fac78ce964de1b18c82dd..9e69ef91fe834886ecfafccd83e74c4660dd8920 100644 (file)
--- a/doc/src/sgml/hash.sgml
+++ b/doc/src/sgml/hash.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/hash.sgml -->
 
-<chapter id="hash-index">
+<sect1 id="hash-index">
 <title>Hash Indexes</title>
 
    <indexterm>
@@ -8,7 +8,7 @@
     <secondary>Hash</secondary>
    </indexterm>
 
-<sect1 id="hash-intro">
+<sect2 id="hash-intro">
  <title>Overview</title>
 
  <para>
@@ -108,9 +108,9 @@
   with rapidly increasing number of rows.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="hash-implementation">
+<sect2 id="hash-implementation">
  <title>Implementation</title>
 
  <para>
@@ -157,6 +157,6 @@
   successfully.
  </para>
 
-</sect1>
+</sect2>
 
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/indextypes.sgml b/doc/src/sgml/indextypes.sgml
new file mode 100644 (file)
index 0000000..94a2b01
--- /dev/null
+++ b/doc/src/sgml/indextypes.sgml
@@ -0,0 +1,13 @@
+ <!-- doc/src/sgml/indextypes.sgml -->
+
+<chapter id="indextypes">
+<title>Built-in Index Access Methods</title>
+
+&btree;
+&gist;
+&spgist;
+&gin;
+&brin;
+&hash;
+
+</chapter>

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1ac9d3a9b8fff99329334dc8902e0f121f106b6a..e9a350234e7a5fc26433613525962d33a4f9a894 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -258,12 +258,7 @@ break is not needed in a wider output rendering.
   &indexam;
   &generic-wal;
   &custom-rmgr;
-  &btree;
-  &gist;
-  &spgist;
-  &gin;
-  &brin;
-  &hash;
+  &indextypes;
   &storage;
   &transaction;
   &bki;

diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index 102f8627bd05d5a93c2b60e0596a0c8572985b63..6af93719b843921d2b2e7b3882e1145cb30afb38 100644 (file)
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/spgist.sgml -->
 
-<chapter id="spgist">
+<sect1 id="spgist">
 <title>SP-GiST Indexes</title>
 
    <indexterm>
@@ -8,7 +8,7 @@
     <secondary>SP-GiST</secondary>
    </indexterm>
 
-<sect1 id="spgist-intro">
+<sect2 id="spgist-intro">
  <title>Introduction</title>
 
  <para>
@@ -51,9 +51,9 @@
   <ulink url="http://www.sai.msu.su/~megera/wiki/spgist_dev">web site</ulink>.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="spgist-builtin-opclasses">
+<sect2 id="spgist-builtin-opclasses">
  <title>Built-in Operator Classes</title>
 
  <para>
@@ -191,9 +191,9 @@
   search over indexed point or polygon data sets.
  </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="spgist-extensibility">
+<sect2 id="spgist-extensibility">
  <title>Extensibility</title>
 
  <para>
@@ -933,9 +933,9 @@ LANGUAGE C STRICT;
    <function>PG_GET_COLLATION()</function> mechanism.
   </para>
 
-</sect1>
+</sect2>
 
-<sect1 id="spgist-implementation">
+<sect2 id="spgist-implementation">
  <title>Implementation</title>
 
   <para>
@@ -944,7 +944,7 @@ LANGUAGE C STRICT;
    know.
   </para>
 
- <sect2 id="spgist-limits">
+ <sect3 id="spgist-limits">
   <title>SP-GiST Limits</title>
 
   <para>
@@ -991,9 +991,9 @@ LANGUAGE C STRICT;
    leaf datum does not become any smaller within ten cycles
    of <function>choose</function> method calls.
   </para>
- </sect2>
+ </sect3>
 
- <sect2 id="spgist-null-labels">
+ <sect3 id="spgist-null-labels">
   <title>SP-GiST Without Node Labels</title>
 
   <para>
@@ -1018,9 +1018,9 @@ LANGUAGE C STRICT;
    for <function>choose</function> to return <literal>spgAddNode</literal>, since the set
    of nodes is supposed to be fixed in such cases.
   </para>
- </sect2>
+ </sect3>
 
- <sect2 id="spgist-all-the-same">
+ <sect3 id="spgist-all-the-same">
   <title><quote>All-the-Same</quote> Inner Tuples</title>
 
   <para>
@@ -1056,11 +1056,11 @@ LANGUAGE C STRICT;
    depending on how much the <function>inner_consistent</function> function normally
    assumes about the meaning of the nodes.
   </para>
- </sect2>
+ </sect3>
 
-</sect1>
+</sect2>
 
-<sect1 id="spgist-examples">
+<sect2 id="spgist-examples">
  <title>Examples</title>
 
  <para>
@@ -1071,6 +1071,6 @@ LANGUAGE C STRICT;
   and <filename>src/backend/utils/adt/</filename> to see the code.
  </para>
 
-</sect1>
+</sect2>
 
-</chapter>
+</sect1>