Thread: Pushing btree opclass implementor's docs to the main SGML docs

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

On 2/5/18 18:51, Tom Lane wrote:
> 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.

xindex seems better to me.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> On 2/5/18 18:51, Tom Lane wrote:
>> 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.

> xindex seems better to me.

Oh, I already did it as a chapter.  I'm inclined to think that somebody
will want to write something more there someday, and anyway it's already
longer than some existing chapters ...

            regards, tom lane