Hi, thanks for the review.
I tried to take your comments into account:
- added a missing comma
- still left a verbose version ;)
- made the last sentence more complete (according to the 2nd option).
Attached you will find new patch version fix_doc_raise_v4.patch,
please check it out.
Thanks again for review and comments.
Regards, Igor Gnatyuk
ср, 10 июл. 2024 г. в 23:36, Laurenz Albe <[email protected]>:
>
> On Wed, 2024-05-22 at 18:34 +0300, Igor Gnatyuk wrote:
> > fix_doc_raise_v3-bios.patch. Please check it out.
>
> I think the patch is fine.
>
> > + <para>
> > + <replaceable class="parameter">condition_name</replaceable> and
> > + <replaceable class="parameter">sqlstate</replaceable> specify
> > + error condition name and the five-character SQLSTATE code respectively.
> > + See <xref linkend="errcodes-appendix"/> for more information.
> > + </para>
>
> There should be a comma before "respectively".
>
> > You can attach additional information to the error report by writing
> > <literal>USING</literal> followed by <replaceable
> > class="parameter">option</replaceable> = <replaceable
> > - class="parameter">expression</replaceable> items. Each
> > + class="parameter">expression</replaceable> or
> > + <replaceable class="parameter">option</replaceable> :=
> > + <replaceable class="parameter">expression</replaceable>
> > + items, where
> > <replaceable class="parameter">expression</replaceable> can be any
> > string-valued expression.
>
> I think that is unnecessarily verbose. The original wording was fine;
> everybody can see from the syntax diagram that you can also use :=
>
> But I won't fight over it.
>
> > + In the <command>RAISE</command> command syntax with
> > + <replaceable class="parameter">condition_name</replaceable> or
> > + <replaceable class="parameter">sqlstate</replaceable> you can
> > + additionally use the <literal>USING</literal> clause too.
> > + A variation of the example above:
>
> I think that the final sentence should be more complete.
> Suggestions:
>
> Here is a variation of the above example:
>
> A variation of the above example is:
>
> Yours,
> Laurenz Albe
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f..df316e5757 100644
*** a/doc/src/sgml/plpgsql.sgml
--- b/doc/src/sgml/plpgsql.sgml
***************
*** 3805,3814 **** CALL transaction_test2();
raise errors.
<synopsis>
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ... </optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> <replaceable class="parameter">condition_name</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> SQLSTATE '<replaceable class="parameter">sqlstate</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE ;
</synopsis>
--- 3805,3814 ----
raise errors.
<synopsis>
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ... </optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> <replaceable class="parameter">condition_name</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> SQLSTATE '<replaceable class="parameter">sqlstate</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE ;
</synopsis>
***************
*** 3852,3862 **** RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
</programlisting>
</para>
<para>
You can attach additional information to the error report by writing
<literal>USING</literal> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
! class="parameter">expression</replaceable> items. Each
<replaceable class="parameter">expression</replaceable> can be any
string-valued expression. The allowed <replaceable
class="parameter">option</replaceable> key words are:
--- 3852,3881 ----
</programlisting>
</para>
+ <para>
+ <replaceable class="parameter">condition_name</replaceable> and
+ <replaceable class="parameter">sqlstate</replaceable> specify
+ error condition name and the five-character SQLSTATE code, respectively.
+ See <xref linkend="errcodes-appendix"/> for more information.
+ </para>
+
+ <para>
+ The example below shows <replaceable class="parameter">condition_name</replaceable>
+ and <replaceable class="parameter">sqlstate</replaceable> options usage:
+ <programlisting>
+ RAISE division_by_zero;
+ RAISE SQLSTATE '22012';
+ </programlisting>
+ </para>
+
<para>
You can attach additional information to the error report by writing
<literal>USING</literal> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
! class="parameter">expression</replaceable> or
! <replaceable class="parameter">option</replaceable> :=
! <replaceable class="parameter">expression</replaceable>
! items, where
<replaceable class="parameter">expression</replaceable> can be any
string-valued expression. The allowed <replaceable
class="parameter">option</replaceable> key words are:
***************
*** 3925,3939 **** RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</para>
<para>
! There is a second <command>RAISE</command> syntax in which the main argument
! is the condition name or SQLSTATE to be reported, for example:
! <programlisting>
! RAISE division_by_zero;
! RAISE SQLSTATE '22012';
! </programlisting>
! In this syntax, <literal>USING</literal> can be used to supply a custom
! error message, detail, or hint. Another way to do the earlier
! example is
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
--- 3944,3954 ----
</para>
<para>
! In the <command>RAISE</command> command syntax with
! <replaceable class="parameter">condition_name</replaceable> or
! <replaceable class="parameter">sqlstate</replaceable> you can
! additionally use the <literal>USING</literal> clause too.
! A variation of the above example is:
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
