Subject: Add contrib module functions to docs' function index

From: Craig Ringer <[email-masked]>
Date: Wed, 14 Nov 2012 07:15:21 +0800

Hi all

Andreas Heiduk on -bugs suggested that we add the functions provided by
contrib modules to the function index in the docs, so it's easier to go
from, say,  "what the heck is idx(...)" to finding it in the intarray
contrib module.

This seems like a good idea and I'd like to pop it in the TODO until I
get time to check it out, flagged as a minor/newbie-friendly problem.
Any objections?

-- 
 Craig Ringer                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

---

From: "David Johnston" <[email-masked]>
Date: Tue, 13 Nov 2012 18:56:23 -0500

> -----Original Message-----
> From: [email-masked] [mailto:pgsql-hackers-
> [email-masked]] On Behalf Of Craig Ringer
> Sent: Tuesday, November 13, 2012 6:15 PM
> To: PostgreSQL Hackers
> Subject: [HACKERS] Add contrib module functions to docs' function index
> 
> Hi all
> 
from,
> say,  "what the heck is idx(...)" to finding it in the intarray contrib
module.
> 
> This seems like a good idea and I'd like to pop it in the TODO until I get
time to
> check it out, flagged as a minor/newbie-friendly problem.
> Any objections?
> 

For clarity does this proposal refer to Chapter 9 of the documentation, the
"Index", or both.

If modifying Chapter 9 the function and operator tables should be extended
to include a "source" column with values of "base" or "contrib: <module
name>" or something similar.

As to the desirability of such a change I concur that it would be a nice
usability enhancement to consider beyond just updating the actual "Index".

David J.

---

From: Craig Ringer <[email-masked]>
Date: Wed, 14 Nov 2012 08:10:27 +0800

> usability enhancement to consider beyond just updating the actual "Index".
Sorry I was unclear.

I'm talking about making sure that contrib module functions (and
settings) appear in the documentation index (
http://www.postgresql.org/docs/current/static/bookindex.html
<http://www.postgresql.org/docs/9.2/static/bookindex.html>) so it's easy
to find a function by name whether it's in core or contrib. This is what
I want to add to TODO.

Separately, it might also be nice to add the contrib functions to the
section 9 tables with an extra column showing their origin, but that's
less clearly a good thing. Even if there's a column saying "intarray"
for intarray functions in the array functions list, people will still
try to use them without loading the extension and get confused when
they're not found. It'll also bloat the listings of core functions.
Rather than do that, I'd probably prefer to add a note to relevant
sections. For example, in array functions I'd want to add "Additional
functions that operate only on arrays of integers are available in the
<a href="...">intarray extension</a>".

---

From: Robert Haas <[email-masked]>
Date: Wed, 14 Nov 2012 17:46:57 -0500

On Tue, Nov 13, 2012 at 7:10 PM, Craig Ringer <[email-masked]> wrote:
> I'm talking about making sure that contrib module functions (and settings)
> appear in the documentation index (
> http://www.postgresql.org/docs/current/static/bookindex.html) so it's easy
> to find a function by name whether it's in core or contrib. This is what I
> want to add to TODO.

+1.

> section 9 tables with an extra column showing their origin, but that's less
> clearly a good thing. Even if there's a column saying "intarray" for
> intarray functions in the array functions list, people will still try to use
> them without loading the extension and get confused when they're not found.
> It'll also bloat the listings of core functions. Rather than do that, I'd
> probably prefer to add a note to relevant sections. For example, in array
> functions I'd want to add "Additional functions that operate only on arrays
> of integers are available in the <a href="...">intarray extension</a>".

The second approach seems better, and maybe only in cases where it's
particularly relevant.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 2 Jul 2013 15:56:10 -0400

> The second approach seems better, and maybe only in cases where it's

Seems we never considered index entries when we moved the contrib
information into our main docs.

I have developed the this patch to do this.  I would like to apply
this to head and 9.3:

	http://momjian.us/expire/contrib.diff

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 4 Jul 2013 11:33:36 -0400

> 	http://momjian.us/expire/contrib.diff

Applied, and backpatched to 9.3.  Craig, thanks for the suggestion.