Re: Doc patch, put RAISE USING keywords into a table

Hi,

The attached patch, raise_using_keyword_table.patch,
puts the pl/pgsql RAISE USING keywords into a table,
replacing a prose description.

Against HEAD.

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On 10/26/2012 09:58:05 AM, Karl O. Pinc wrote:

> The attached patch, raise_using_keyword_table.patch,
> puts the pl/pgsql RAISE USING keywords into a table,
> replacing a prose description.

I'm attaching a v2 of this patch:
raise_using_keyword_table-v2.patch

The use of the word "keyword" does not sit well
since these are not actual sql reserved key words.

V2 removes the word "keyword" from the table and
the surrounding text.

Regards,

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On 10/26/2012 10:23:56 AM, Karl O. Pinc wrote:
> On 10/26/2012 09:58:05 AM, Karl O. Pinc wrote:
>
> > The attached patch, raise_using_keyword_table.patch,
> > puts the pl/pgsql RAISE USING keywords into a table,
> > replacing a prose description.

Attached is: raise_using_keyword_table-v3.patch
It uses a variable list instead of a table.

I believe I prefer the table but this might
(or might not) be more consistent with the
style of other parts of the docs.

Regards,

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On Fri, 2012-10-26 at 16:23 -0500, Karl O. Pinc wrote:
> Attached is: raise_using_keyword_table-v3.patch
> It uses a variable list instead of a table.
>
> I believe I prefer the table but this might
> (or might not) be more consistent with the
> style of other parts of the docs.

I'm unsure whether splitting this out into a list (or table) is an
improvement. Other opinions?

This page is written as a narrative explanation of the RAISE feature,
but there is probably a desire to also have it serve as a reference page
in the style of the SQL command reference pages. But it might get ugly
if we try to have it be both.

On 11/17/2012 12:16:06 AM, Peter Eisentraut wrote:

> I'm unsure whether splitting this out into a list (or table) is an
> improvement. Other opinions?
>
> This page is written as a narrative explanation of the RAISE feature,
> but there is probably a desire to also have it serve as a reference
> page
> in the style of the SQL command reference pages.

Yes. I do want to be able to scan the page quickly
to pick out the keywords and their use. There is no reference page.

FWIW

There are lists and tables in narrative parts of the documentation.
The very next section, (PL/pgSQL) Trigger Procedures has a variablelist
of special variables and The SQL Language top-level chapter, which
claims to be narrative, has many tables.

Regards,

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On Fri, 2012-10-26 at 16:23 -0500, Karl O. Pinc wrote:
> On 10/26/2012 10:23:56 AM, Karl O. Pinc wrote:
> > On 10/26/2012 09:58:05 AM, Karl O. Pinc wrote:
> >
> > > The attached patch, raise_using_keyword_table.patch,
> > > puts the pl/pgsql RAISE USING keywords into a table,
> > > replacing a prose description.
>
> Attached is: raise_using_keyword_table-v3.patch
> It uses a variable list instead of a table.

I have committed this "list" version with some small modifications.