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

9 files changed, 100 insertions, 91 deletions

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d898cc4720c..64fb520db7e 100644
--- 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 be8210286b6..2b3997988cf 100644
--- 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 6360707d9f6..3fb0709f5df 100644
--- 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 5bd1efae92e..46e87e01324 100644
--- 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 8a19f156d83..3f7df103b83 100644
--- 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 e35911ebf8e..9e69ef91fe8 100644
--- 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
index 00000000000..94a2b01afcc
--- /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 1ac9d3a9b8f..e9a350234e7 100644
--- 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 102f8627bd0..6af93719b84 100644
--- 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>