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@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
Attachments:
raise_using_keyword_table.patchtext/x-patch; charset=us-ascii; name=raise_using_keyword_table.patchDownload
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 07fba57..c31d0c2 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3274,20 +3274,55 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
You can attach additional information to the error report by writing
<literal>USING</> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
- class="parameter">expression</replaceable> items. The allowed
- <replaceable class="parameter">option</replaceable> keywords are
- <literal>MESSAGE</>, <literal>DETAIL</>, <literal>HINT</>, and
- <literal>ERRCODE</>, while each <replaceable
- class="parameter">expression</replaceable> can be any string-valued
- expression.
- <literal>MESSAGE</> sets the error message text (this option can't
+ class="parameter">expression</replaceable> items. Each
+ <replaceable class="parameter">expression</replaceable> can be any
+ string-valued expression. The allowed <replaceable
+ class="parameter">option</replaceable> keywords are:
+ </para>
+
+ <table id="using-keywords">
+ <title>RAISE USING Keywords</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Keyword</entry>
+ <entry>Purpose</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>MESSAGE</literal></entry>
+ <entry>Error message text</entry>
+ </row>
+
+ <row>
+ <entry><literal>DETAIL</literal></entry>
+ <entry>Detailed error message</entry>
+ </row>
+
+ <row>
+ <entry><literal>HINT</literal></entry>
+ <entry>Hint message</entry>
+ </row>
+
+ <row>
+ <entry><literal>ERRCODE</literal></entry>
+ <entry>Error code (SQLSTATE) to report</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><literal>MESSAGE</> can't
be used in the form of <command>RAISE</> that includes a format
- string before <literal>USING</>).
- <literal>DETAIL</> supplies an error detail message, while
- <literal>HINT</> supplies a hint message.
- <literal>ERRCODE</> specifies the error code (SQLSTATE) to report,
- either by condition name as shown in <xref linkend="errcodes-appendix">,
- or directly as a five-character SQLSTATE code.
+ string before <literal>USING</>.
+ </para>
+
+ <para><literal>ERRCODE</> may be specified either by condition name,
+ as shown in <xref linkend="errcodes-appendix">, or directly as a
+ five-character SQLSTATE code.
</para>
<para>
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@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
Attachments:
raise_using_keyword_table-v2.patchtext/x-patch; charset=us-ascii; name=raise_using_keyword_table-v2.patchDownload
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 07fba57..d44eb06 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3274,20 +3274,55 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
You can attach additional information to the error report by writing
<literal>USING</> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
- class="parameter">expression</replaceable> items. The allowed
- <replaceable class="parameter">option</replaceable> keywords are
- <literal>MESSAGE</>, <literal>DETAIL</>, <literal>HINT</>, and
- <literal>ERRCODE</>, while each <replaceable
- class="parameter">expression</replaceable> can be any string-valued
- expression.
- <literal>MESSAGE</> sets the error message text (this option can't
+ class="parameter">expression</replaceable> items. Each
+ <replaceable class="parameter">expression</replaceable> can be any
+ string-valued expression. The allowed <replaceable
+ class="parameter">option</replaceable>s are:
+ </para>
+
+ <table id="using-options">
+ <title>RAISE USING Options</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Purpose</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>MESSAGE</literal></entry>
+ <entry>Error message text</entry>
+ </row>
+
+ <row>
+ <entry><literal>DETAIL</literal></entry>
+ <entry>Detailed error message</entry>
+ </row>
+
+ <row>
+ <entry><literal>HINT</literal></entry>
+ <entry>Hint message</entry>
+ </row>
+
+ <row>
+ <entry><literal>ERRCODE</literal></entry>
+ <entry>Error code (SQLSTATE) to report</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><literal>MESSAGE</> can't
be used in the form of <command>RAISE</> that includes a format
- string before <literal>USING</>).
- <literal>DETAIL</> supplies an error detail message, while
- <literal>HINT</> supplies a hint message.
- <literal>ERRCODE</> specifies the error code (SQLSTATE) to report,
- either by condition name as shown in <xref linkend="errcodes-appendix">,
- or directly as a five-character SQLSTATE code.
+ string before <literal>USING</>.
+ </para>
+
+ <para><literal>ERRCODE</> may be specified either by condition name,
+ as shown in <xref linkend="errcodes-appendix">, or directly as a
+ five-character SQLSTATE code.
</para>
<para>
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@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
Attachments:
raise_using_keyword_table-v3.patchtext/x-patch; charset=us-ascii; name=raise_using_keyword_table-v3.patchDownload
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 07fba57..7091845 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3274,22 +3274,52 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
You can attach additional information to the error report by writing
<literal>USING</> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
- class="parameter">expression</replaceable> items. The allowed
- <replaceable class="parameter">option</replaceable> keywords are
- <literal>MESSAGE</>, <literal>DETAIL</>, <literal>HINT</>, and
- <literal>ERRCODE</>, while each <replaceable
- class="parameter">expression</replaceable> can be any string-valued
- expression.
- <literal>MESSAGE</> sets the error message text (this option can't
- be used in the form of <command>RAISE</> that includes a format
- string before <literal>USING</>).
- <literal>DETAIL</> supplies an error detail message, while
- <literal>HINT</> supplies a hint message.
- <literal>ERRCODE</> specifies the error code (SQLSTATE) to report,
- either by condition name as shown in <xref linkend="errcodes-appendix">,
- or directly as a five-character SQLSTATE code.
+ class="parameter">expression</replaceable> items. Each
+ <replaceable class="parameter">expression</replaceable> can be any
+ string-valued expression. The allowed <replaceable
+ class="parameter">option</replaceable>s are:
</para>
+ <variablelist id="raise-using-options">
+
+ <varlistentry>
+ <term><literal>MESSAGE</literal></term>
+
+ <listitem>
+ <para>Error message text. <literal>MESSAGE</> can't be
+ used in the form of <command>RAISE</> that includes a
+ format string before <literal>USING</>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>DETAIL</literal></term>
+
+ <listitem>
+ <para>Detailed error message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>HINT</literal></term>
+
+ <listitem>
+ <para>Hint message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ERRCODE</literal></term>
+
+ <listitem>
+ <para>Error code (SQLSTATE) to report.
+ <literal>ERRCODE</> may be specified either by condition
+ name, as shown in <xref linkend="errcodes-appendix">, or
+ directly as a five-character SQLSTATE code.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
<para>
This example will abort the transaction with the given error message
and hint:
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@meme.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.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers