Subject: [PATCH v2] Clarify that COMMENT and SECURITY LABEL can be set to NULL in the synopses

From: Dagfinn Ilmari Mannsåker <[email-masked]>
Date: Tue, 31 Jan 2023 16:05:20 +0000

This was only mentioned in the description of the text/label, which
are marked as being in quotes in the synopsis, which can cause
confusion (as witnessed on IRC).

Also separate the literal and NULL case in the parameter list, per
suggestion from Tom Lane.
---
 doc/src/sgml/ref/comment.sgml        | 16 ++++++++++++----
 doc/src/sgml/ref/security_label.sgml | 16 ++++++++++++----
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 7499da1d62..470a6d0b5c 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -66,7 +66,7 @@
   TRIGGER <replaceable class="parameter">trigger_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
   TYPE <replaceable class="parameter">object_name</replaceable> |
   VIEW <replaceable class="parameter">object_name</replaceable>
-} IS '<replaceable class="parameter">text</replaceable>'
+} IS { '<replaceable class="parameter">text</replaceable>' | NULL }
 
 <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
 
@@ -263,11 +263,19 @@
     </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">text</replaceable></term>
+    <term><literal>'</literal><replaceable class="parameter">text</replaceable><literal>'</literal></term>
     <listitem>
      <para>
-      The new comment, written as a string literal; or <literal>NULL</literal>
-      to drop the comment.
+      The new comment, written as a string literal.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>NULL</literal></term>
+    <listitem>
+     <para>
+      Write <literal>NULL</literal> to drop the comment.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml
index 20a839ff0c..e4eee77932 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -44,7 +44,7 @@
   TABLESPACE <replaceable class="parameter">object_name</replaceable> |
   TYPE <replaceable class="parameter">object_name</replaceable> |
   VIEW <replaceable class="parameter">object_name</replaceable>
-} IS '<replaceable class="parameter">label</replaceable>'
+} IS { '<replaceable class="parameter">label</replaceable>' | NULL }
 
 <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
 
@@ -178,11 +178,19 @@
     </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">label</replaceable></term>
+    <term><literal>'</literal><replaceable class="parameter">label</replaceable><literal>'</literal></term>
     <listitem>
      <para>
-      The new security label, written as a string literal; or <literal>NULL</literal>
-      to drop the security label.
+      The new security label, written as a string literal.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>NULL</literal>></term>
+    <listitem>
+     <para>
+      Write <literal>NULL</literal> to drop the security label.
      </para>
     </listitem>
    </varlistentry>
-- 
2.34.1

--=-=-=--