Re: GIST operators docs [was: [HACKERS] Patch: add GiST support for BOX @> POINT queries]

Is there a TODO here?

---------------------------------------------------------------------------

On Tue, Aug 14, 2012 at 06:40:58PM +0100, Daniele Varrazzo wrote:
> On Sat, Aug 11, 2012 at 6:04 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Daniele Varrazzo <daniele(dot)varrazzo(at)gmail(dot)com> writes:
> >> The style of the docs is currently:
> >
> >> - in 11.2: on the type page, a list of operators without a single word
> >> on their meaning, with a link to 9.11
> >> <http://www.postgresql.org/docs/9.1/static/indexes-types.html>
> >> - in 9.11 the ops explanation with no info about indexing or types
> >> support <http://www.postgresql.org/docs/9.1/static/functions-geometry.html>
> >
> > I agree this is pretty incomplete ...
> >
> >> I would suggest dropping the list in 11.2, leaving only the link
> >> ("several operators support indexing: see section 9.11 for a list"),
> >> and be explicit in 9.11 in what operator and what data type can be
> >> used in an index.
> >
> > ... but I don't think I want to fix it along those lines. Consider
> > what would happen if we tried to annotate every operator supported by
> > btree indexes that way, for example. It'd be very cluttering.
>
> Agreed it would be cluttering for btree, but btree operators are
> pretty well known and surprise-free, whereas the geometric/interval
> ones are quite exotic and the interaction between types not obvious.
>
> > It'd
> > probably be pretty cluttering even if we restrict it to GIST cases.
>
> There would be more information, but I don't think a useful page is an
> impossible task. What I have in mind is a notes column and free
> descriptive text below the table as in
> <http://docs.python.org/library/stdtypes.html#index-15>.
>
> > I think the charter of 9.11 is to tell you what the operators *do*,
> > not which ones are amenable to indexing.
>
> In the context of using intervals or geometric types to build indexes
> one must design his system with this knowledge. He can only use the
> operators that support indexes, the others are out of the game.
>
> > Alternatively, I could see adding tables of supported operators in
> > the GIST (and SPGIST and GIN) chapters of part VII, and linking to
> > those from 11.2.
>
> That would be probably fine too. The other propositions (extending
> psql's \do and a query to be copypasted into psql) are still a form of
> help but require another tool to be used out of the Fine Manual.
>
> -- Daniele
>
>
> --
> Sent via pgsql-docs mailing list (pgsql-docs(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +