Further cleanup of RAISE discussion; in particular, remove example

that doesn't actually work.

diff --git a/doc/src/sgml/plsql.sgml b/doc/src/sgml/plsql.sgml
index dfc0c8d..0bc49b5 100644 (file)
--- a/doc/src/sgml/plsql.sgml
+++ b/doc/src/sgml/plsql.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.28 2001/05/08 02:26:09 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.29 2001/05/08 02:53:24 tgl Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -1309,20 +1309,29 @@ END LOOP;
 RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">variable</replaceable> <optional>...</optional></optional>;
 </synopsis>
 
-    Inside the format, <literal>%</literal> is replaced by the next argument's
-    external representation. Double <literal>%</literal>'s are output as <literal>%</literal>.
-    Possible levels are DEBUG (silently suppressed in production
-    running databases), NOTICE (written into the database log and forwarded to
-    the client application) and EXCEPTION (written into the database log and
+    Possible levels are DEBUG (write the message into the postmaster log),
+    NOTICE (write the message into the postmaster log and forward it to
+    the client application) and EXCEPTION (raise an error,
     aborting the transaction).
+    Inside the format string, <literal>%</literal> is replaced by the next
+    optional argument's external representation.
+    Write <literal>%%</literal> to emit a literal <literal>%</literal>.
+    Note that the optional arguments must presently
+    be simple variables, not expressions, and the format must be a simple
+    string literal.
    </para>
 
+   <!--
+   This example should work, but does not:
+       RAISE NOTICE ''Id number '' || key || '' not found!'';
+   Put it back when we allow non-string-literal formats.
+    -->
+
    <para>
 <programlisting>
-RAISE NOTICE ''Id number '' || key || '' not found!'';
 RAISE NOTICE ''Calling cs_create_job(%)'',v_job_id;
 </programlisting>
-    In this last example, v_job_id will replace the % in the
+    In this example, the value of v_job_id will replace the % in the
     string.
    </para>
 
@@ -1330,7 +1339,7 @@ RAISE NOTICE ''Calling cs_create_job(%)'',v_job_id;
 <programlisting>
 RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
 </programlisting>
-    This will abort the transaction and write to the database log.
+    This will abort the transaction with the given error message.
    </para>
   </sect2>