From: Tom Lane <tgl@sss.pgh.pa.us>
To: pgsql-docs@lists.postgresql.org
Subject: Pushing btree opclass implementor's docs to the main SGML docs
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <23140.1517874668.1@sss.pgh.pa.us>
Date: Mon, 05 Feb 2018 18:51:08 -0500
Message-ID: <23141.1517874668@sss.pgh.pa.us>
Precedence: bulk

I whined in <17947.1517767809@sss.pgh.pa.us> about the lack of any good
place in the main documentation to explain how to write in_range() support
functions for the upcoming window RANGE patch.

What I would like to do, to create such a place, is to move the last
section of src/backend/access/nbtree/README (the "Notes to Operator Class
Implementors" part) into the main docs.  There are really two subparts
to that: there's some rather abstract handwaving about the mathematical
properties of a btree ordering, and then there's an API spec for the
comparison support function.  The RANGE patch would want to add an API
spec for the in_range function.  (At some point somebody might feel like
adding some text about the sortsupport API too; though since it's
basically impossible to do sortsupport except in C, I don't feel too bad
about just pointing to sortsupport.h for now.)

So I can see two ways to approach this: add two new subsections at the end
of xindex.sgml, or create a new chapter about b-trees in Part VII
("Internals") to go beside the existing ones about the more recently added
index types.  The latter would make more sense if anyone was inspired to
write something comparable in length to the existing per-index-type
chapters.  But I'm not volunteering to do that, so if it's a chapter it'd
be a mighty thin one to start with.

Anybody have a preference, an objection, or a better idea?

			regards, tom lane