From: ilmari@ilmari.org (Dagfinn Ilmari =?utf-8?Q?Manns=C3=A5ker?=)
To: pgsql-hackers@postgresql.org
Subject: Re: [PATCH] Add section headings to index types doc
References: <877dukhvzg.fsf@wibble.ilmari.org>
Date: Mon, 03 Aug 2020 12:32:17 +0100
In-Reply-To: <877dukhvzg.fsf@wibble.ilmari.org> ("Dagfinn Ilmari
 \=\?utf-8\?Q\?Manns\=C3\=A5ker\=22's\?\=
	message of "Fri, 31 Jul 2020 10:30:59 +0100")
Message-ID: <87wo2gge2m.fsf@wibble.ilmari.org>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes:

> Hi hackers,
>
> Every time I have to look up what kinds of operations each index type is
> suitable for, I get annoyed by the index types page being virtually
> unskimmable due to not having headings for each index type.
>
> Attached is a patch that adds <sect2> tags for each index type to make
> it easier to see where the description of each one starts.

Added to the next commitfest:

https://commitfest.postgresql.org/29/2665/

Also, for easier review, here's the `git diff -w` output, since the
<sect2> tags caused most of the page to have to be renidented.

Tangentially, does anyone know of a tool to strip whitespace changes
from an existing diff, as if it had been generated with `-w` in the
first place?

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 28adaba72d..332d161547 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>
@@ -172,6 +175,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 +198,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>
@@ -246,6 +257,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>
@@ -286,6 +301,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>
@@ -327,6 +346,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>
@@ -360,6 +383,7 @@
     documented in <xref linkend="brin-builtin-opclasses-table"/>.
     For more information see <xref linkend="brin"/>.
    </para>
+  </sect2>
  </sect1>
 

- ilmari 
-- 
"A disappointingly low fraction of the human race is,
 at any given time, on fire." - Stig Sandbeck Mathisen