Date: Fri, 31 Aug 2012 13:57:57 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, pgsql-docs@postgresql.org
Subject: Re: GIST operators docs [was: [HACKERS] Patch: add GiST
	support for BOX @> POINT queries]
Message-ID: <20120831175757.GP32350@momjian.us>
References: 
 <CA+mi_8Y58Z7iLB=eZkd1u3xf1kK=1Vu3vw5TbfHcu6ug=n2Nbg@mail.gmail.com>
	<8409.1344704658@sss.pgh.pa.us>
	<CA+mi_8b_h83fLeea6+-RTJDU8_FLAO_ZnkhkYR9cZOx-Vq0g3w@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CA+mi_8b_h83fLeea6+-RTJDU8_FLAO_ZnkhkYR9cZOx-Vq0g3w@mail.gmail.com>
User-Agent: Mutt/1.5.20 (2009-06-14)


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@sss.pgh.pa.us> wrote:
> > Daniele Varrazzo <daniele.varrazzo@gmail.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@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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