PL/SQL-to-PL/pgSQL-HOWTO

On Sun, Feb 25, 2001 at 10:33:15AM -0700, Roberto Mello wrote:

Hi,

Here's the HOWTO I wrote. This is what it has:

In pgsql-hackers I was told to submit the HOWTO to pgsql-docs and
didn't know that this was a list. I apologize for those in the list for
the big sgml file you've received. I thought this was a submission address
for Thomas Lockhart.

Once again, my apologies,

-Roberto Mello

-- 
+----| http://fslc.usu.edu USU Free Software & GNU/Linux Club|------+
| Roberto Mello - Computer Science, USU - http://www.brasileiro.net |
|    http://www.sdl.usu.edu - Space Dynamics Lab, Web Developer     |

Friends encourage friends to use Win(e)dows - under Linux!

In pgsql-hackers I was told to submit the HOWTO to pgsql-docs and
didn't know that this was a list. I apologize for those in the list for
the big sgml file you've received. I thought this was a submission address
for Thomas Lockhart.

No need to apologize; afaik it is appropriate to submit content to this
list (it isn't *that* high traffic, and documentation-types should be
interested in this).

OTOH, I apologize for my ignorance here: what is the "GNU documentation
license"?

- Thomas

On Mon, Feb 26, 2001 at 06:29:55PM +0000, Thomas Lockhart wrote:

In pgsql-hackers I was told to submit the HOWTO to pgsql-docs and
didn't know that this was a list. I apologize for those in the list for
the big sgml file you've received. I thought this was a submission address
for Thomas Lockhart.

No need to apologize; afaik it is appropriate to submit content to this
list (it isn't *that* high traffic, and documentation-types should be
interested in this).

OTOH, I apologize for my ignorance here: what is the "GNU documentation
license"?

http://www.gnu.org/copyleft/fdl.html

Another interesting license is the Open Publication License:

http://opencontent.org/openpub/

Actually, that's a good question. We've had the regular go-arounds on
HACKERs regarding code licensing (short answer: it'll stay BSD for the
forseeable future), but never discussed documentation licenses. It
sort of came up when Bruce's book came out, but not much was said.

For code, we've been less selective about what's in contrib than the
core tree, isn't that the case? I count 12 occurences of files license
under the GPL in contrib. So, for doco, do we need to make the same
restriction?

Are there real differences in how docs should be licensed, compared to
software? Personally, I find the distinction between BSD and GPL like
licenses almost meaningless in the world of docs: either license allows
unlimited copying, and require crediting the original authors. THe
biggest difference is requiring the 'source code' to be provided. The
'source code' for a doc is easily recoverable from the distributed
'compiled' version, unlike the case for software.

So, what do people think?

Ross

Actually, that's a good question. We've had the regular go-arounds on
HACKERs regarding code licensing (short answer: it'll stay BSD for the
forseeable future), but never discussed documentation licenses. It
sort of came up when Bruce's book came out, but not much was said.

The conclusion was that the docs are licensed under the same license as
the source code (simply: do whatever you want, but preserve the
BSD-style copyright notice available with the source code).

afaict, that actually did not happen for Bruce's book (no copyright
notices other than Addison Wesley). But presumably A-W will not try to
push their apparent copyright on our docs ;)

istm that a paragraph at the front with the copyright notices about
"Portions of this book are from... which is copyright..." might be
appropriate in most cases.

For code, we've been less selective about what's in contrib than the
core tree, isn't that the case? I count 12 occurences of files license
under the GPL in contrib. So, for doco, do we need to make the same
restriction?

This contribution is a standalone "article" in the DocBook sense, so
does not depend on other docs or pieces of docs. But it *does* raise
some encumbrances wrt keeping the source code available for a year after
the last formatted version is distributed. Not sure how we guarantee
that, since we don't have an official mechanism defined to preserve
tarballs etc for posterity :(

afaict, the FDL does not specifically allow one to replace a version
with a newer version, and asks that the original sources be kept intact,
at least to meet the 1 year source code rule.

otoh, someone probably has old tarballs saved (I used to, until my MO
drive failed).

- Thomas

On Mon, Feb 26, 2001 at 06:29:55PM +0000, Thomas Lockhart wrote:

No need to apologize; afaik it is appropriate to submit content to this
list (it isn't *that* high traffic, and documentation-types should be
interested in this).

Oh ok. I just didn't want to look like a jerk in my first post to the
DOCS list :) Thanks for letting me know.

OTOH, I apologize for my ignorance here: what is the "GNU documentation
license"?

It's a documentation license with the same spirit as the GPL
basically. I only licensed it under the GFDL because it was the only one I
knew of. If that poses a problem for inclusion into the PG docs (which are
BSD licensed? how does the BSD licenso apply to documentation?) please
let's discuss it so we can reach an agreement.
All I want is to help the PG docs to be better. Is there a
"Documentation-TODO" somewhere? I'd be happy to tackle something else when
I finish PL/pgSQL.
On that topic (PL/pgSQL) I wanted to know from Thomas if it's ok for
mo to break the topics in the PL/pgSQL docs. I find that the
"everything-under-description" approach is confusing to refer to. It's
hard to see the topics, etc. Breaking up the topics under "description"
would also allow we to add more specific and rich examples.
That's one of the reasons I like the lpd.dsl stylesheet. It creates
tables of contents with <sect2>'s listed. (look at
http://www.brasileiro.net/roberto/howto for an example).

Thoughts?

	-Roberto
-- 
+----| http://fslc.usu.edu USU Free Software & GNU/Linux Club|------+
  Roberto Mello - Computer Science, USU - http://www.brasileiro.net 
      http://www.sdl.usu.edu - Space Dynamics Lab, Web Developer    
Backup my hard drive?! I can't find the reverse switch!

Actually, that's a good question. We've had the regular go-arounds on
HACKERs regarding code licensing (short answer: it'll stay BSD for the
forseeable future), but never discussed documentation licenses. It
sort of came up when Bruce's book came out, but not much was said.

The conclusion was that the docs are licensed under the same license as
the source code (simply: do whatever you want, but preserve the
BSD-style copyright notice available with the source code).

afaict, that actually did not happen for Bruce's book (no copyright
notices other than Addison Wesley). But presumably A-W will not try to
push their apparent copyright on our docs ;)

That is a good point. My book clearly states the man pages are from the
PostgreSQL documentation, but doesn't mention the license applies to
those pages. I will address this with AW on the next printing.

-- 
  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

afaict, that actually did not happen for Bruce's book (no copyright
notices other than Addison Wesley). But presumably A-W will not try to
push their apparent copyright on our docs ;)

That is a good point. My book clearly states the man pages are from the
PostgreSQL documentation, ...

Yes it does. I didn't want to dwell on this so didn't go into detail on
how you checked with *everyone* before including them, have the
cross-reference to the originals in your book, etc etc. They are being
used in the way they are intended to be used!

... but doesn't mention the license applies to
those pages. I will address this with AW on the next printing.

Great!

- Thomas

Ross J. Reedstrom writes:

Actually, that's a good question. We've had the regular go-arounds on
HACKERs regarding code licensing (short answer: it'll stay BSD for the
forseeable future), but never discussed documentation licenses.

This is easy:

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose, without fee, and without a written agreement
^^^^^^^^^^^^^
is hereby granted, provided that the above copyright notice and this
paragraph and the following two paragraphs appear in all copies.

The 'source code' for a doc is easily recoverable from the distributed
'compiled' version, unlike the case for software.

Have you ever looked at a PS or PDF file lately? ;-)

--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/

Roberto Mello writes:

It's a documentation license with the same spirit as the GPL
basically. I only licensed it under the GFDL because it was the only one I
knew of. If that poses a problem for inclusion into the PG docs (which are
BSD licensed? how does the BSD licenso apply to documentation?) please

Like this:

: Permission to use, copy, modify, and distribute this software and its
: documentation for any purpose, without fee, and without a written agreement
^^^^^^^^^^^^^
: is hereby granted, provided that the above copyright notice and this
: paragraph and the following two paragraphs appear in all copies.

let's discuss it so we can reach an agreement.
All I want is to help the PG docs to be better. Is there a
"Documentation-TODO" somewhere? I'd be happy to tackle something else when
I finish PL/pgSQL.

Not really. You get to pick. But I can tell you a few things that I
would personally like to see done.

On that topic (PL/pgSQL) I wanted to know from Thomas if it's ok for
mo to break the topics in the PL/pgSQL docs. I find that the
"everything-under-description" approach is confusing to refer to. It's
hard to see the topics, etc. Breaking up the topics under "description"
would also allow we to add more specific and rich examples.

I say, whatever you say goes. ;-)

That's one of the reasons I like the lpd.dsl stylesheet. It creates
tables of contents with <sect2>'s listed. (look at
http://www.brasileiro.net/roberto/howto for an example).

We got that too now. Since Sunday, I think.

--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/

On Tue, Feb 27, 2001 at 04:44:16PM +0100, Peter Eisentraut wrote:

Ross J. Reedstrom writes:

Actually, that's a good question. We've had the regular go-arounds on
HACKERs regarding code licensing (short answer: it'll stay BSD for the
forseeable future), but never discussed documentation licenses.

This is easy:

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose, without fee, and without a written agreement
^^^^^^^^^^^^^
is hereby granted, provided that the above copyright notice and this
paragraph and the following two paragraphs appear in all copies.

Ah, good. Settled then.

The 'source code' for a doc is easily recoverable from the distributed
'compiled' version, unlike the case for software.

Have you ever looked at a PS or PDF file lately? ;-)

Actually, yes. Have you seen what pstoedit is capable of? I'm often astounded
how good it's output is.

As a test, I just ran the latest PDF I've got, which came from a journal
article. Used xpdf to create a postscript file, and pstoedit to make
a fig file from that. Granted, it's still a drawing format, but automated
extraction from the well documented fig format would be rather simple.

All of this is beside the point, in any case. What I meant was not
that the "source" was _automatically_ recoverable, but easily, in the
technical sense:

I can pay a typist (perhaps in a developing world document bodyshop:
such exist) to generate source code for me, since I've got the license to
copy, modify, and distribute it, regardless if it's FDL or BSD licensed.
If it's FDL, I don't have to pay the typist. But I can't add my own
chapter and not allow it to be copied, either.

But it's settled. BSD doco it is.

Ross

Roberto Mello writes:

Here's the HOWTO I wrote.

If you can agree that we ship our documentation under the BSD license, I'm
ready to integrate this into the existing PL/pgSQL chapter.

--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/

On Tue, Mar 06, 2001 at 06:19:06PM +0100, Peter Eisentraut wrote:

Roberto Mello writes:

Here's the HOWTO I wrote.

If you can agree that we ship our documentation under the BSD license, I'm
ready to integrate this into the existing PL/pgSQL chapter.

Yeah, I don't have any problem with that. I'll rewrite the license
line and send a new tar ball to you, with some corrected things.
Also, when is the deadline to submit documentation for the PG team?
With all the WAL fuss going on the hackers list it maybe at least one more
week?
I ask because I'd really like to revamp the PL/pgSQL docs, make it
much more detailed, with more examples, and better divisions. But I've
been swamped with school work. But next week is spring break so I'd have
time to work on it.
What do you say?

	-Roberto
-- 
+----| http://fslc.usu.edu USU Free Software & GNU/Linux Club|------+
  Roberto Mello - Computer Science, USU - http://www.brasileiro.net 
      http://www.sdl.usu.edu - Space Dynamics Lab, Web Developer    
"Hello, World!" 17 Errors, 31 Warnings....

Roberto Mello wrote:

I ask because I'd really like to revamp the PL/pgSQL docs, make it
much more detailed, with more examples, and better divisions. But I've
been swamped with school work. But next week is spring break so I'd have
time to work on it.
What do you say?

For the record, Roberto writes good docs. And he knows of what he
writes, having assisted for over a year in the OpenACS effort, porting
the rather complex ACS Orcale-centric code over to PostgreSQL.
--
Lamar Owen
WGCR Internet Radio
1 Peter 4:11

Also, when is the deadline to submit documentation for the PG team?
With all the WAL fuss going on the hackers list it maybe at least one more
week?
I ask because I'd really like to revamp the PL/pgSQL docs, make it
much more detailed, with more examples, and better divisions. But I've
been swamped with school work. But next week is spring break so I'd have
time to work on it.
What do you say?

Peter, is this OK with you? It will go into the programmer's doc, and we
can freeze that a bit later than some others. It is OK with me. Until
March 16?

- Thomas

Roberto Mello wrote:

I ask because I'd really like to revamp the PL/pgSQL docs, make it
much more detailed, with more examples, and better divisions. But I've
been swamped with school work. But next week is spring break so I'd have
time to work on it.
What do you say?

For the record, Roberto writes good docs. And he knows of what he
writes, having assisted for over a year in the OpenACS effort, porting
the rather complex ACS Orcale-centric code over to PostgreSQL.

Yes, I am very excited to get this. We need more Pl/PgSQL docs, and I
hear this one is really good.

-- 
  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

On Tue, Mar 06, 2001 at 06:19:06PM +0100, Peter Eisentraut wrote:

Roberto Mello writes:

Here's the HOWTO I wrote.

If you can agree that we ship our documentation under the BSD license, I'm
ready to integrate this into the existing PL/pgSQL chapter.

Yeah, I don't have any problem with that. I'll rewrite the license
line and send a new tar ball to you, with some corrected things.
Also, when is the deadline to submit documentation for the PG team?
With all the WAL fuss going on the hackers list it maybe at least one more
week?
I ask because I'd really like to revamp the PL/pgSQL docs, make it
much more detailed, with more examples, and better divisions. But I've
been swamped with school work. But next week is spring break so I'd have
time to work on it.
What do you say?

I think that will work. The best way to go is to contact Thomas
Lockhart/docs list and let them know you want to work on this. They can
warn you about cutoff times for each section of the documentation.

-- 
  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

Also, when is the deadline to submit documentation for the PG team?
With all the WAL fuss going on the hackers list it maybe at least one more
week?
I ask because I'd really like to revamp the PL/pgSQL docs, make it
much more detailed, with more examples, and better divisions. But I've
been swamped with school work. But next week is spring break so I'd have
time to work on it.
What do you say?

Peter, is this OK with you? It will go into the programmer's doc, and we
can freeze that a bit later than some others. It is OK with me. Until
March 16?

That's great. Seems we really need PlPgSQL docs beefed up, and this
will do that for us. I seem to remember Peter liking this idea too.

-- 
  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