[PATCH] Add _PG_init to PL language handler documentation

Howdy,

This tiny doc patch adds _PG_init to the skeleton example code for a
PL. The information is quite valuable to PL authors, who might miss it
when it is described in the shared library documentation.

This patch was based off of 6e2ba96 in the git mirror and a colorized
diff can be viewed here:

http://github.com/leto/postgres/commit/a9e265a7f55a0605fb4c6135f0f689c8b89e9623

Duke

--
Jonathan "Duke" Leto
jonathan(at)leto(dot)net
http://leto.net

On Tue, May 25, 2010 at 4:34 AM, Jonathan Leto <jaleto(at)gmail(dot)com> wrote:
> This tiny doc patch adds _PG_init to the skeleton example code for a
> PL. The information is quite valuable to PL authors, who might miss it
> when it is described in the shared library documentation.

I'm not sure it does much good to add it to the template without any
explanation of what it does. What might make more sense is to add a
cross-reference to the section on dynamic loading, where this is
documented.

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

On Wed, May 26, 2010 at 03:47:25PM -0400, Robert Haas wrote:
> On Tue, May 25, 2010 at 4:34 AM, Jonathan Leto <jaleto(at)gmail(dot)com> wrote:
> > This tiny doc patch adds _PG_init to the skeleton example code for a
> > PL. The information is quite valuable to PL authors, who might miss it
> > when it is described in the shared library documentation.
>
> I'm not sure it does much good to add it to the template without any
> explanation of what it does. What might make more sense is to add a
> cross-reference to the section on dynamic loading, where this is
> documented.

+1. How about the attached (which, incidentally, tested successfully on my
box, because I've managed to achieve doc building nirvana through blindly
flailing about until it worked...)?

--
Joshua Tolley / eggyknap
End Point Corporation
http://www.endpoint.com

On Wed, May 26, 2010 at 11:24 PM, Joshua Tolley <eggyknap(at)gmail(dot)com> wrote:
> On Wed, May 26, 2010 at 03:47:25PM -0400, Robert Haas wrote:
>> On Tue, May 25, 2010 at 4:34 AM, Jonathan Leto <jaleto(at)gmail(dot)com> wrote:
>> > This tiny doc patch adds _PG_init to the skeleton example code for a
>> > PL. The information is quite valuable to PL authors, who might miss it
>> > when it is described in the shared library documentation.
>>
>> I'm not sure it does much good to add it to the template without any
>> explanation of what it does.  What might make more sense is to add a
>> cross-reference to the section on dynamic loading, where this is
>> documented.
>
> +1. How about the attached (which, incidentally, tested successfully on my
> box, because I've managed to achieve doc building nirvana through blindly
> flailing about until it worked...)?

I've committed a doc change along these lines, but I thought your
version was a little wordy and maybe not in the best spot, so I did it
a bit differently. Hopefully it's good - if not, I can always change
it again...

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

On Tue, Jun 08, 2010 at 04:18:08PM -0400, Robert Haas wrote:
> On Wed, May 26, 2010 at 11:24 PM, Joshua Tolley <eggyknap(at)gmail(dot)com> wrote:
> > On Wed, May 26, 2010 at 03:47:25PM -0400, Robert Haas wrote:
> >> On Tue, May 25, 2010 at 4:34 AM, Jonathan Leto <jaleto(at)gmail(dot)com> wrote:
> >> > This tiny doc patch adds _PG_init to the skeleton example code for a
> >> > PL. The information is quite valuable to PL authors, who might miss it
> >> > when it is described in the shared library documentation.
> >>
> >> I'm not sure it does much good to add it to the template without any
> >> explanation of what it does.  What might make more sense is to add a
> >> cross-reference to the section on dynamic loading, where this is
> >> documented.
> >
> > +1. How about the attached (which, incidentally, tested successfully on my
> > box, because I've managed to achieve doc building nirvana through blindly
> > flailing about until it worked...)?
>
> I've committed a doc change along these lines, but I thought your
> version was a little wordy and maybe not in the best spot, so I did it
> a bit differently. Hopefully it's good - if not, I can always change
> it again...

You're far from the first to label one of my productions "wordy" :) Your
version suits me fine (btw, in case anyone else is looking for it, it's here:
http://archives.postgresql.org/pgsql-committers/2010-06/msg00060.php)

--
Joshua Tolley / eggyknap
End Point Corporation
http://www.endpoint.com