From 84522dc77afd1b8ce0bf111279302888d9d3edcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Fri, 31 Jul 2020 10:20:48 +0100
Subject: [PATCH] Add section headers to index types doc

This makes it easier to compare the properties of different index
types at a glance.

In passing, make the index operator lists a single line each.
---
 doc/src/sgml/indices.sgml | 81 +++++++++++++++++++--------------------
 1 file changed, 39 insertions(+), 42 deletions(-)

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 671299ff05..f22253f4c3 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -122,6 +122,9 @@
    B-tree indexes, which fit the most common situations.
   </para>
 
+  <sect2 id="indexes-types-btree">
+   <title>B-tree</title>
+
   <para>
    <indexterm>
     <primary>index</primary>
@@ -137,13 +140,9 @@
    will consider using a B-tree index whenever an indexed column is
    involved in a comparison using one of these operators:
 
-   <simplelist>
-    <member><literal>&lt;</literal></member>
-    <member><literal>&lt;=</literal></member>
-    <member><literal>=</literal></member>
-    <member><literal>&gt;=</literal></member>
-    <member><literal>&gt;</literal></member>
-   </simplelist>
+<synopsis>
+&lt; &nbsp; &lt;= &nbsp; = &nbsp; &gt;= &nbsp; &gt;
+</synopsis>
 
    Constructs equivalent to combinations of these operators, such as
    <literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
@@ -172,6 +171,10 @@
    This is not always faster than a simple scan and sort, but it is
    often helpful.
   </para>
+  </sect2>
+
+  <sect2 id="indexes-types-hash">
+   <title>Hash</title>
 
   <para>
    <indexterm>
@@ -191,6 +194,10 @@
 CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH (<replaceable>column</replaceable>);
 </synopsis>
   </para>
+  </sect2>
+
+  <sect2 id="indexes-type-gist">
+   <title>GiST</title>
 
   <para>
    <indexterm>
@@ -210,20 +217,9 @@
    for several two-dimensional geometric data types, which support indexed
    queries using these operators:
 
-   <simplelist>
-    <member><literal>&lt;&lt;</literal></member>
-    <member><literal>&amp;&lt;</literal></member>
-    <member><literal>&amp;&gt;</literal></member>
-    <member><literal>&gt;&gt;</literal></member>
-    <member><literal>&lt;&lt;|</literal></member>
-    <member><literal>&amp;&lt;|</literal></member>
-    <member><literal>|&amp;&gt;</literal></member>
-    <member><literal>|&gt;&gt;</literal></member>
-    <member><literal>@&gt;</literal></member>
-    <member><literal>&lt;@</literal></member>
-    <member><literal>~=</literal></member>
-    <member><literal>&amp;&amp;</literal></member>
-   </simplelist>
+<synopsis>
+&lt;&lt; &nbsp; &amp;&lt; &nbsp; &amp;&gt; &nbsp; &gt;&gt; &nbsp; &lt;&lt;| &nbsp; &amp;&lt;| &nbsp; |&amp;&gt; &nbsp; |&gt;&gt; &nbsp; @&gt; &nbsp; &lt;@ &nbsp; ~= &nbsp; &amp;&amp;
+</synopsis>
 
    (See <xref linkend="functions-geometry"/> for the meaning of
    these operators.)
@@ -246,6 +242,10 @@
    In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
    used in this way are listed in the column <quote>Ordering Operators</quote>.
   </para>
+  </sect2>
+
+  <sect2 id="indexes-type-spgist">
+   <title>SP-GiST</title>
 
   <para>
    <indexterm>
@@ -264,14 +264,9 @@
    for two-dimensional points, which support indexed
    queries using these operators:
 
-   <simplelist>
-    <member><literal>&lt;&lt;</literal></member>
-    <member><literal>&gt;&gt;</literal></member>
-    <member><literal>~=</literal></member>
-    <member><literal>&lt;@</literal></member>
-    <member><literal>&lt;^</literal></member>
-    <member><literal>&gt;^</literal></member>
-   </simplelist>
+<synopsis>
+&lt;&lt; &nbsp; &gt;&gt; &nbsp; ~= &nbsp; &lt;@ &nbsp; &lt;^ &nbsp; &gt;^
+</synopsis>
 
    (See <xref linkend="functions-geometry"/> for the meaning of
    these operators.)
@@ -286,6 +281,10 @@
    corresponding operator is specified in the <quote>Ordering Operators</quote>
    column in <xref linkend="spgist-builtin-opclasses-table"/>.
   </para>
+  </sect2>
+
+  <sect2 id="indexes-types-gin">
+   <title>GIN</title>
 
   <para>
    <indexterm>
@@ -312,12 +311,9 @@
    <productname>PostgreSQL</productname> includes a GIN operator class
    for arrays, which supports indexed queries using these operators:
 
-   <simplelist>
-    <member><literal>&lt;@</literal></member>
-    <member><literal>@&gt;</literal></member>
-    <member><literal>=</literal></member>
-    <member><literal>&amp;&amp;</literal></member>
-   </simplelist>
+<synopsis>
+&lt;@ &nbsp; @&gt; &nbsp; = &nbsp; &amp;&amp;
+</synopsis>
 
    (See <xref linkend="functions-array"/> for the meaning of
    these operators.)
@@ -327,6 +323,10 @@
    classes are available in the <literal>contrib</literal> collection or as separate
    projects.  For more information see <xref linkend="gin"/>.
   </para>
+  </sect2>
+
+  <sect2 id="indexes-types-brin">
+   <title>BRIN</title>
 
   <para>
    <indexterm>
@@ -348,18 +348,15 @@
    values in the column for each block range.  This supports indexed queries
    using these operators:
 
-   <simplelist>
-    <member><literal>&lt;</literal></member>
-    <member><literal>&lt;=</literal></member>
-    <member><literal>=</literal></member>
-    <member><literal>&gt;=</literal></member>
-    <member><literal>&gt;</literal></member>
-   </simplelist>
+<synopsis>
+&lt; &nbsp; &lt;= &nbsp; = &nbsp; &gt;= &nbsp; &gt;
+</synopsis>
 
    The BRIN operator classes included in the standard distribution are
    documented in <xref linkend="brin-builtin-opclasses-table"/>.
    For more information see <xref linkend="brin"/>.
   </para>
+  </sect2>
  </sect1>
 
 
-- 
2.27.0

