Subject: DBlink documentation

From: Andre Truter <[email-masked]>
Date: Sat, 17 Dec 2005 14:53:13 +0200

Where do I find documentation for using dblink?

I am running PostgreSQL 8.03 on SuSE 9.3 and I installed the
postgresql-contrib package, but it only includes the README for dblink,
which only lists the functions, but it does not include any information
on how to use it.

For instance, it would list:

dblink_connect(text) RETURNS text.

But what should 'text' be?

I searched through the Postgres site and mailing list archives and I get
a lot of references of "look in the dblink documentation".
Unfortunately I have have not yet been able to find this documentation?

Can anybody please give me a link to the documentation?

Thanks 
-- 
Andre Truter | Software Engineer | Registered Linux user #185282
ICQ #40935899 | AIM: trusoftzaf | http://www.trusoft.co.za

~ A dinosaur is a salamander designed to Mil Spec ~

---

From: Leonel Nunez <[email-masked]>
Date: Sat, 17 Dec 2005 06:20:28 -0700

>Can anybody please give me a link to the documentation?

It's  on  the contrib package
or in the contrib  dir  if you installed from source

leonel

---

From: Andre Truter <[email-masked]>
Date: Sat, 17 Dec 2005 15:44:23 +0200

> It's  on  the contrib package

No, unfortunately the SUSE people did not include it in the contrib
package.

> or in the contrib  dir  if you installed from source
Installed from rpm package.
I have searched for the dblink source to get the docs from there, but I
have also failed to find it so far.
Maybe I am searching wrong?

I searched the Postgres site for 'dblink source'

~ "Oh Bother!" said the Borg, "We assimilated the Pooh!" ~

---

From: Leonel Nunez <[email-masked]>
Date: Sat, 17 Dec 2005 07:04:46 -0700

>I searched the Postgres site for 'dblink source'

download  the  source for your PostgreSQL  version  unpackit
and check on    the   contrib/dblink   dir

leonel

---

From: Andre Truter <[email-masked]>
Date: Sat, 17 Dec 2005 16:14:09 +0200

> and check on    the   contrib/dblink   dir

Yes, that is what I have been trying to do, but where do I download the
dblink source from?

---

From: Douglas McNaught <[email-masked]>
Date: Sat, 17 Dec 2005 09:21:29 -0500

> Yes, that is what I have been trying to do, but where do I download the

That's what he's trying to tell you--it's in the 'contrib' directory
of the main source tarball.

-Doug

---

From: "Russ Brown" <[email-masked]>
Date: Sat, 17 Dec 2005 08:33:02 -0600

> of the main source tarball.

Is the documentation not available online somewhere?

-- 

Russ

---

From: Douglas McNaught <[email-masked]>
Date: Sat, 17 Dec 2005 09:37:07 -0500

> Is the documentation not available online somewhere?

For the stuff in 'contrib', I don't think so.  Might be a good project
for someone.  :)

-Doug

---

From: Andre Truter <[email-masked]>
Date: Sat, 17 Dec 2005 16:53:04 +0200

> of the main source tarball.

Ah!  I misunderstood.  
I expected the dblink or contrib stuff to be a separate project, not
part of the postgres source tree.

That explain why I could not find it.

Thanks, I'll download the Posgres source then.

I would be nice if the documentation could be online though, then I
would not need to download the whole postgres source just to get the
documentation for one small part.

Or, is there a CVS browser available, so I can only checkout/download
the dblink stuff?
(Bandwidth is a problem for me at the moment)

---

From: "Greg Sabino Mullane" <[email-masked]>
Date: Sat, 17 Dec 2005 14:53:39 -0000

> Is the documentation not available online somewhere?

Quick version for you:

http://www.gtsm.com/dblink/

- --
Greg Sabino Mullane [email-masked]
PGP Key: 0x14964AC8 200512170951
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8

---

From: Andre Truter <[email-masked]>
Date: Sat, 17 Dec 2005 18:03:21 +0200

> http://www.gtsm.com/dblink/

Great!
This is exactly what I want.

Thanks Greg!

---

From: Tino Wildenhain <[email-masked]>
Date: Sat, 17 Dec 2005 17:09:16 +0100

Am Samstag, den 17.12.2005, 16:53 +0200 schrieb Andre Truter:
...
> documentation for one small part.

This is understandable ;) But in this case not postgres peoples
fault. There is no reason a package manager should exclude parts
of the software at will. The complete software includes all you need.
Well done packages either have a big package of all or single packages
you install which include the documentation too.
If someone does not use a package, (s)he is downloading the source
anyway to get postgres :-)

Regards
Tino

---

From: Andre Truter <[email-masked]>
Date: Sat, 17 Dec 2005 20:02:04 +0200

On Sat, 2005-12-17 at 17:09 +0100, Tino Wildenhain wrote:

> fault. 

Yes, I realise it is not the fault of the postgres people and I did not
intend to make it sound like that.

I am a bit disappointed that the rpm package that comes with SuSE does
not include all the docs.
I will mention this on the SuSE mailing list.

---

From: Tom Lane <[email-masked]>
Date: Sat, 17 Dec 2005 13:31:08 -0500

> of the software at will.

Actually, I don't think you can reasonably blame the Debian packager
for having overlooked the fact that contrib/dblink has more
documentation files besides its README.  The PGDG RPM people overlooked
that too, as did Red Hat (ie, me).

Now that I look, tsearch2 has also adopted a nonstandard documentation
layout.

While we (the packagers) could fix this now that our attention has been
called to it, I wonder whether the better plan wouldn't be to insist
that dblink and tsearch2 fall into line with the rest of the contrib
modules.  At the very least we need a uniform convention for docs files
so that packagers won't be playing catchup forever.

			regards, tom lane

---

From: Joe Conway <[email-masked]>
Date: Sat, 17 Dec 2005 12:17:50 -0800

> that too, as did Red Hat (ie, me).

Well, in my own defense, I pointed out the change explicitly when I 
submitted the patch (which was over 3 years ago now, prior to 7.3 beta 
feature freeze), and no one objected back then:
   http://archives.postgresql.org/pgsql-patches/2002-08/msg00640.php

> so that packagers won't be playing catchup forever.

I'm happy to lump all the docs back into the README if that's what you 
want, but I split it up in the first place because it was getting very long.

Joe

---

From: Tom Lane <[email-masked]>
Date: Sat, 17 Dec 2005 15:47:54 -0500

> want, but I split it up in the first place because it was getting very long.

No, I'm not really proposing that we force all contrib modules to have
only a README.  I'm just annoyed by the lack of consistency (dblink/doc
versus tsearch2/docs, and some of the other modules seem to have some
doc files just loose in their top directory).

It's not only the downstream packagers that have missed these: the
Makefiles don't install them either.

It'd be a good idea to settle on what we want the installed file layout
to be --- do we need to create subdirectories under {prefix}/doc to
forestall name conflicts?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 17 Dec 2005 16:10:25 -0500 (EST)

> forestall name conflicts?

I personally never saw those doc/ files when I was modifying dblink.  I
had to grope around in the regression tests to see how the functions
worked.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: "Karl O. Pinc" <[email-masked]>
Date: Sun, 18 Dec 2005 04:35:26 +0000

> Is the documentation not available online somewhere?

There is always the CVS web interface:
http://developer.postgresql.org/cvsweb.cgi/pgsql/

Karl <[email-masked]>
Free Software:  "You don't pay back, you pay forward."
                  -- Robert A. Heinlein

---

From: "Jim C. Nasby" <[email-masked]>
Date: Mon, 19 Dec 2005 15:55:38 -0600

> forestall name conflicts?

README is probably fine for most of what's in contrib, but for other
stuff we should support a doc directory. tsearch2 currently has 100k of
HTML in docs, I really don't think we want to cram all that into the
README.
-- 
Jim C. Nasby, Sr. Engineering Consultant      [email-masked]
Pervasive Software      http://pervasive.com    work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf       cell: 512-569-9461

---

From: Joe Conway <[email-masked]>
Date: Tue, 03 Jan 2006 15:52:24 -0800

> forestall name conflicts?

While I'm messing with dblink, did you want me to do anything WRT this?

Thanks,

Joe

---

From: Tom Lane <[email-masked]>
Date: Tue, 03 Jan 2006 18:56:37 -0500

> While I'm messing with dblink, did you want me to do anything WRT this?

I don't think we settled on what we want to do yet.  Any thoughts?

I'm kind of leaning toward the subdirectory idea myself...

			regards, tom lane

---

From: Joe Conway <[email-masked]>
Date: Tue, 03 Jan 2006 16:20:38 -0800

> I'm kind of leaning toward the subdirectory idea myself...

(I removed GENERAL, and added DOCS to the distribution of this thread)

Well I like {prefix}/doc given that's how dblink is already set up ;-)

Questions:
   - Do we want a naming convention for the files in
     {prefix}/doc?
   - Do we pre-create {prefix}/doc for every contrib
     directory in advance?

I think the answers are no, and yes, but I don't feel strongly about either.

Joe

---

From: "Jim C. Nasby" <[email-masked]>
Date: Tue, 3 Jan 2006 20:19:58 -0600

> I think the answers are no, and yes, but I don't feel strongly about either.

By {prefix} do you mean where PostgreSQL is being installed? If so, that
would be highly non-standard. I think what you'd want is
{prefix}/share/doc/postgresql/contrib/.
-- 
Jim C. Nasby, Sr. Engineering Consultant      [email-masked]
Pervasive Software      http://pervasive.com    work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf       cell: 512-569-9461

---

From: Joe Conway <[email-masked]>
Date: Tue, 03 Jan 2006 20:19:18 -0800

> {prefix}/share/doc/postgresql/contrib/.

Well, I assumed Tom was referring to placement in the source tree, i.e. 
{prefix} is contrib/dblink, etc.

But this raises a good question in terms of where these files should be 
installed. The README.xxx files all go to {install-prefix}/doc/contrib. 
I experimented with changing the Makefile line:
   DOCS = README.dblink
to be:
   DOCS = README.dblink doc/*

Unfortunately the files from contrib/dblink/doc still wound up being 
installed to {install-prefix}/doc/contrib, which would become a naming 
collision hazard. Maybe they should go to 
{install-prefix}/doc/contrib/xxx (where xxx is the name of each contrib 
dir)?

Joe

---

From: Tom Lane <[email-masked]>
Date: Wed, 04 Jan 2006 00:03:56 -0500

> {prefix} is contrib/dblink, etc.

I'm concerned about both location in the source tree (dblink and
tsearch2 are inconsistent) and location in the installation tree.
The former seems easy to resolve: doc/ is the universal standard
directory name for documentation, not docs/.  I am not sure that
we want to commit to creating a pile of subdirectories under the
installation doc/ directory, though.  If they were mostly full,
fine, but a bunch of directories that are mostly empty would just
be clutter.  Maybe create subdirectories only for modules that
have 'em in the source tree?

			regards, tom lane