Thread: Documentation gap: Perl interfaces

Documentation gap: Perl interfaces

From
Tom Lane
Date:
I just noticed that the SGML documents contain no description of the
perl5 interface (Pg.pm), nor yet any mention that there is a DBI/DBD
driver available.  Anyone looking at the "Client Interfaces" section
would think there is no Perl interface available at all :-(.

I am not sure that it's worth transcribing interfaces/perl5/README
into SGML, given that we aren't encouraging new development with that
code anyway.  But surely there should be some mention of DBI.

            regards, tom lane

Re: Documentation gap: Perl interfaces

From
Bruce Momjian
Date:
> I just noticed that the SGML documents contain no description of the
> perl5 interface (Pg.pm), nor yet any mention that there is a DBI/DBD
> driver available.  Anyone looking at the "Client Interfaces" section
> would think there is no Perl interface available at all :-(.
>
> I am not sure that it's worth transcribing interfaces/perl5/README
> into SGML, given that we aren't encouraging new development with that
> code anyway.  But surely there should be some mention of DBI.

Added to TODO:

    * Add documentation for perl, including mention of DBI/DBD perl
          location

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: Documentation gap: Perl interfaces

From
Peter Eisentraut
Date:
Tom Lane writes:

> I am not sure that it's worth transcribing interfaces/perl5/README
> into SGML, given that we aren't encouraging new development with that
> code anyway.

There's a pod2docbook, but it's not very pretty.  Hand-tuning would be
required.

> But surely there should be some mention of DBI.

I've thought many times about a chapter "other client interfaces" (not
supplied with PostgreSQL).  However, this would really only duplicate
information found on the web site (I hope), in the FAQ, at freshmeat,
CPAN, or whereever else, and it would tend to be outdated.

It's not our job to tell people what the wide world of database
programming has to offer.  We control neither Perl nor the DBD:Pg driver,
so if we start bothering with that then there is no theoretical boundary
-- what about all the other Python, Scheme, Emacs Lisp, Ruby, or
language-of-the-day interfaces?

--
Peter Eisentraut   peter_e@gmx.net


Re: Documentation gap: Perl interfaces

From
Thomas Lockhart
Date:
...
> It's not our job to tell people what the wide world of database
> programming has to offer.  We control neither Perl nor the DBD:Pg driver,
> so if we start bothering with that then there is no theoretical boundary
> -- what about all the other Python, Scheme, Emacs Lisp, Ruby, or
> language-of-the-day interfaces?

We should mention that they exist, and give pointers on where to find
them and what is involved in installing them (maybe even some shortcut
instructions).

                     - Thomas

Re: Documentation gap: Perl interfaces

From
Peter Eisentraut
Date:
Thomas Lockhart writes:

> ...
> > It's not our job to tell people what the wide world of database
> > programming has to offer.  We control neither Perl nor the DBD:Pg driver,
> > so if we start bothering with that then there is no theoretical boundary
> > -- what about all the other Python, Scheme, Emacs Lisp, Ruby, or
> > language-of-the-day interfaces?
>
> We should mention that they exist, and give pointers on where to find
> them and what is involved in installing them (maybe even some shortcut
> instructions).

We've been there, and it all that information became outdated pretty soon.
In fact we've just removed all not-included-here documentation in this
release.  There are literally thousands of packages interfacing with
PostgreSQL, and I don't see how we're going to manage to put these into
the documentation.  People that are looking for software can go to
freshmeat or the PG web site (a.k.a. elephantmeat) or other such places.

--
Peter Eisentraut   peter_e@gmx.net


Re: Documentation gap: Perl interfaces

From
terry@greatgulfhomes.com
Date:
Let me interject as a user:

At least document something about some of the major modules, like say:
Some moduless exist to interface to other languages like DBD::Pg

This way I as a user at least have a "shot in the dark" of knowing what to
look for on the search engines.  And you won't have to maintain anything
like URL's etc for the ever changing language interfaces.

Terry Fielder
Network Engineer
Great Gulf Homes / Ashton Woods Homes
terry@greatgulfhomes.com

> -----Original Message-----
> From: pgsql-docs-owner@postgresql.org
> [mailto:pgsql-docs-owner@postgresql.org]On Behalf Of Peter Eisentraut
> Sent: Tuesday, November 27, 2001 9:37 AM
> To: Thomas Lockhart
> Cc: Tom Lane; pgsql-docs@postgresql.org
> Subject: Re: [DOCS] Documentation gap: Perl interfaces
>
>
> Thomas Lockhart writes:
>
> > ...
> > > It's not our job to tell people what the wide world of database
> > > programming has to offer.  We control neither Perl nor
> the DBD:Pg driver,
> > > so if we start bothering with that then there is no
> theoretical boundary
> > > -- what about all the other Python, Scheme, Emacs Lisp, Ruby, or
> > > language-of-the-day interfaces?
> >
> > We should mention that they exist, and give pointers on
> where to find
> > them and what is involved in installing them (maybe even
> some shortcut
> > instructions).
>
> We've been there, and it all that information became outdated
> pretty soon.
> In fact we've just removed all not-included-here documentation in this
> release.  There are literally thousands of packages interfacing with
> PostgreSQL, and I don't see how we're going to manage to put
> these into
> the documentation.  People that are looking for software can go to
> freshmeat or the PG web site (a.k.a. elephantmeat) or other
> such places.
>
> --
> Peter Eisentraut   peter_e@gmx.net
>
>
> ---------------------------(end of
> broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to
> majordomo@postgresql.org
>


Re: Documentation gap: Perl interfaces

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> We've been there, and it all that information became outdated pretty soon.
> In fact we've just removed all not-included-here documentation in this
> release.  There are literally thousands of packages interfacing with
> PostgreSQL, and I don't see how we're going to manage to put these into
> the documentation.

I agree that we shouldn't try to track the exact version, location,
features, etc of outside packages --- but the *existence* of a DBI/DBD
driver for Postgres strikes me as an important, and not unstable, piece
of information.  That's not "one package" that interfaces with Postgres,
that's the foundation for countless applications.  Right now, Perl
people who come looking at the PG docs might well go away again feeling
unwanted.  That's bad for us in the long run.

            regards, tom lane