Обсуждение: Revamped PL/pgSQL Documentation

    Hi all,

    I just finished (hopefully) the revamping of the PL/pgSQL docs. The
reviewed version (sent to Peter already) features:

    - Better structure
    - Many more examples (at least one for each structure)
    - More sections
    - A section explaining the advantages of using PL/pgSQL
    - A section explaining how to work with records
    - etc.

    I have an HTML output at http://www.brasileiro.net/postgres (it's
lacking the GET DIAGNOSTICS paragraph, but I'll make another output
later).
    The tarball with the SGML source code is available at the same
address.
    And don't forget the CookBook! Some recipes have been submitted
already (including in PL/Tcl and PL/Perl). What are you waiting to submit
yours? http://www.brasileiro.net/postgres

    Hope everyone likes the new docs. I sure put a lot of effort into
them. Now I better get my homework done :)

    -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
Girlfriend? Yep! A 200 MHz K6 with 512 Kb Cache...

Roberto Mello writes:

>     I just finished (hopefully) the revamping of the PL/pgSQL docs. The
> reviewed version (sent to Peter already) features:

I need a patch against the version you worked off, otherwise we overwrite
the changes that have been made by others meanwhile.  Given the size of
the document I can't easily make this out myself.

Could you also please reformat the source with one space indents (no
tabs)?

Very nice job, however.

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

On Fri, Mar 16, 2001 at 06:31:38PM +0100, Peter Eisentraut wrote:
>
> I need a patch against the version you worked off, otherwise we overwrite
> the changes that have been made by others meanwhile.  Given the size of
> the document I can't easily make this out myself.

    I just did this. Noticed last night, after I had sent the e-mail
already.
    Before sending you the tarball I have a question (and this was asked
me by a reader as well):

    The declarations syntax is listed as follows:

           
name [ CONSTANT ] type [ NOT NULL ] [ DEFAULT | := value ];
           

           
The part that confuses me is the end.  I assume that if you specify
DEFAULT you must specify a value.  Am I right in understanding that
notation as meaning:

name [ CONSTANT ] type [ NOT NULL ] [ DEFAULT value | := value ];

or perhaps it could be written like this:

name [ CONSTANT ] type [ NOT NULL ] [ { DEFAULT | := } value ];
           

> Could you also please reformat the source with one space indents (no
> tabs)?

    For _every_ line? Or you mean the <programlisting> sections? I am
using Emacs and PSGML so it indents it for me. I don't know how I could
change that or exactly what do you want me to change.
    When I do a <TAB> in Emacs, it indents one space after the previous
element. Isn't that the way it's supposed to be?

    Oh, another question: from the file I have (plsql.sglm)), how do I
generate HTML output? I can do it with Jade for <article>s, but can't
seemto find the jade switches for chapters.

> Very nice job, however.

    Thanks :)

    -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
Any non-trivial program contains at least one bug.

----- End forwarded message -----

--
+----| 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
Ad astra, per ardua nostra.

Roberto Mello <rmello@cc.usu.edu> writes:
> The part that confuses me is the end.  I assume that if you specify
> DEFAULT you must specify a value.  Am I right in understanding that
> notation as meaning:

> name [ CONSTANT ] type [ NOT NULL ] [ DEFAULT value | := value ];

> or perhaps it could be written like this:

> name [ CONSTANT ] type [ NOT NULL ] [ { DEFAULT | := } value ];

Use the source, Luke ... a quick look into plpgsql's gram.y shows that
the latter is correct, ie, 'DEFAULT' and ':=' are interchangeable
introducers for an initialization expression.

            regards, tom lane

Roberto Mello writes:

>     The declarations syntax is listed as follows:
>
> name [ CONSTANT ] type [ NOT NULL ] [ DEFAULT | := value ];

This is correct, at least according to the parser file.  Maybe DEFAULT
means to use the type's default value.  Should probably be documented.
;-)

> > Could you also please reformat the source with one space indents (no
> > tabs)?
>
>     For _every_ line?

To be precise, the content of each block element.  E.g.,

<chapter>
 <title>foo</title>

 <para>
  content
 </para>

 <sect1>
  <title>...

> Or you mean the <programlisting> sections?

Verbatim environments should not be indented, especially the closing tags.
Otherwise you get spurious empty lines in the output.

> I am using Emacs and PSGML so it indents it for me. I don't know how I
> could change that or exactly what do you want me to change.

The locale variables at the bottom of each file should adjust this.  Maybe
you haven't turned them on?  Or you could set up Emacs as described in the
Developer's Guide.

>     When I do a <TAB> in Emacs, it indents one space after the previous
> element. Isn't that the way it's supposed to be?

Well, in the source I have from you it seems to insert a tab character.

>     Oh, another question: from the file I have (plsql.sglm)), how do I
> generate HTML output? I can do it with Jade for <article>s, but can't
> seemto find the jade switches for chapters.

In the declaration (<!DOCTYPE...) you replace article or book by whatever
your top level element is.  No special switches should be required for
either one.  But you need to insert that declaration for processing.

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