Thread: PL/SQL-to-PL/pgSQL-HOWTO
Hi,
Here's the HOWTO I wrote. This is what it has:
- The basics of how to port from Oracle to PostgreSQL
- Several examples of functions in many degrees of complexity
- Several tips for working with PL/pgSQL including a table of number
of quotes needed to accomplish this or that (many get confused with
escaping quotes)
- Code for three instr functions that behave exactly like Oracle's
I am not a DocBook expert, so I apologize if I made mistakes somewhere
or if I did not add some tags that could have made your life easier. I
really strived to make a quality document.
The document, with exception of parts quoted from other sources
(including the PostgreSQL documentation), is licensed under the GNU Free
Documentation License, and I would be glad it is of any help.
If you have any other documentation that you'd like help with, please
let me know.
Sincerely,
-Roberto Mello
--
Computer Science Utah State University
Space Dynamics Laboratory Web Developer
USU Free Software & GNU/Linux Club http://fslc.usu.edu
My home page - http://www.brasileiro.net/roberto
Attachment
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
> 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?
- Thomas
> > 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