Received: from magus.postgresql.org ([87.238.57.229])
	by malur.postgresql.org with esmtp (Exim 4.72)
	(envelope-from <craig@2ndQuadrant.com>) id 1TYQYv-0007GI-Jp
	for pgsql-hackers@postgresql.org; Wed, 14 Nov 2012 00:10:37 +0000
Received: from outmail148111.authsmtp.net ([62.13.148.111])
	by magus.postgresql.org with esmtp (Exim 4.72)
	(envelope-from <craig@2ndQuadrant.com>) id 1TYQYr-00089p-JL
	for pgsql-hackers@postgresql.org; Wed, 14 Nov 2012 00:10:37 +0000
Received: from mail-c232.authsmtp.com (mail-c232.authsmtp.com [62.13.128.232])
	by punt8.authsmtp.com (8.14.2/8.14.2/Kp) with ESMTP id
	qAE0AXkV027530; Wed, 14 Nov 2012 00:10:33 GMT
Received: from ayaki.localdomain (124-148-90-153.dyn.iinet.net.au
	[124.148.90.153]) (authenticated bits=0)
	by mail.authsmtp.com (8.14.2/8.14.2/) with ESMTP id qAE0ASHl080893
	(version=TLSv1/SSLv3 cipher=DHE-RSA-CAMELLIA256-SHA bits=256 verify=NO);
	Wed, 14 Nov 2012 00:10:30 GMT
Message-ID: <50A2E173.6030404@2ndQuadrant.com>
Date: Wed, 14 Nov 2012 08:10:27 +0800
From: Craig Ringer <craig@2ndQuadrant.com>
Organization: 2nd Quadrant
User-Agent: Mozilla/5.0 (X11; Linux x86_64;
	rv:16.0) Gecko/20121016 Thunderbird/16.0.1
MIME-Version: 1.0
To: David Johnston <polobo@yahoo.com>
CC: "'PostgreSQL Hackers'" <pgsql-hackers@postgresql.org>
Subject: Re: Add contrib module functions to docs' function index
References: <50A2D489.7020102@2ndQuadrant.com>
	<002101cdc1fa$7c5a2640$750e72c0$@yahoo.com>
In-Reply-To: <002101cdc1fa$7c5a2640$750e72c0$@yahoo.com>
Content-Type: multipart/alternative;
	boundary="------------070605040104050901040503"
X-Server-Quench: b414109d-2def-11e2-b10b-0025903375e2
X-AuthReport-Spam: If SPAM / abuse - report it at:
	http://www.authsmtp.com/abuse
X-AuthRoute: OCdxZQATClZeVg0b BQteCiN5VAwpPBRK HVkIKg5MJUcNSQVJ
	NksadBtFaQFbY1ZH HGQLWlZEUF17WGN/ aAsfbAdZfEtKVxtj
	UFZIR1FNFgBqBAMA SF9vJxkDFH0aeHZw bU9hEHFfW015OxR5
	Q0pVFWRSeGU0PTYC UUENdR4GcQMYYx9F aFV2VHAOZmBSZDQC
	El17DBAYFhZyEh9g CigBIRoZRkAXBD82 DxUFESgrEAULWiM4
	Mx0hLEVUAEFZPkI5 KhRpV08eOAMTDQsW HkdBDT8x
X-Authentic-SMTP: 61633235383639.1019:706
X-AuthFastPath: 0 (Was 255)
X-AuthSMTP-Origin: 124.148.90.153/2525
X-AuthVirus-Status: No virus detected - but ensure you scan with your own
	anti-virus system.
X-Pg-Spam-Score: -2.6 (--)
X-Archive-Number: 201211/595
X-Sequence-Number: 216447

This is a multi-part message in MIME format.
--------------070605040104050901040503
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

On 11/14/2012 07:56 AM, David Johnston wrote:
>
> 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".
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>".

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


--------------070605040104050901040503
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <div class="moz-cite-prefix">On 11/14/2012 07:56 AM, David Johnston
      wrote:<br>
    </div>
    <blockquote cite="mid:002101cdc1fa$7c5a2640$750e72c0$@yahoo.com"
      type="cite"><br>
      <pre wrap="">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: &lt;module
name&gt;" 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".
</pre>
    </blockquote>
    Sorry I was unclear.<br>
    <br>
    I'm talking about making sure that contrib module functions (and
    settings) appear in the documentation index (
    <meta http-equiv="content-type" content="text/html;
      charset=ISO-8859-1">
    <a href="http://www.postgresql.org/docs/9.2/static/bookindex.html">http://www.postgresql.org/docs/current/static/bookindex.html</a>)
    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.<br>
    <br>
    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 &lt;a href="..."&gt;intarray
    extension&lt;/a&gt;".<br>
    <pre class="moz-signature" cols="72">-- 
 Craig Ringer                   <a class="moz-txt-link-freetext" href="http://www.2ndQuadrant.com/">http://www.2ndQuadrant.com/</a>
 PostgreSQL Development, 24x7 Support, Training &amp; Services</pre>
  </body>
</html>

--------------070605040104050901040503--