From 5fb1809eb966ec04ce2ec8fa4f0c382092659f03 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 31 Jan 2023 14:32:24 -0500
Subject: [PATCH] Doc: clarify use of NULL to drop comments and security
 labels.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 cases in the parameter list, per
suggestion from Tom Lane.

Also add an example of dropping a security label.

Dagfinn Ilmari Mannsåker, with some tweaks by me

Discussion: https://postgr.es/m/87sffqk4zp.fsf@wibble.ilmari.org
---
 doc/src/sgml/ref/comment.sgml        | 16 +++++++++++----
 doc/src/sgml/ref/security_label.sgml | 29 +++++++++++++++++++++-------
 2 files changed, 34 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 138cf718ce..ab69bd68c8 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -66,7 +66,7 @@ COMMENT ON
   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">string_literal</replaceable> | NULL }
 
 <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
 
@@ -264,11 +264,19 @@ COMMENT ON
     </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">text</replaceable></term>
+    <term><replaceable class="parameter">string_literal</replaceable></term>
     <listitem>
      <para>
-      The new comment, written as a string literal; or <literal>NULL</literal>
-      to drop the comment.
+      The new comment contents, 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 e9688cce21..720f319c8b 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -44,7 +44,7 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON
   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">string_literal</replaceable> | NULL }
 
 <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
 
@@ -179,11 +179,19 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON
     </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">label</replaceable></term>
+    <term><replaceable class="parameter">string_literal</replaceable></term>
     <listitem>
      <para>
-      The new security label, written as a string literal; or <literal>NULL</literal>
-      to drop the security label.
+      The new setting of the 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>
@@ -194,12 +202,19 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON
   <title>Examples</title>
 
   <para>
-   The following example shows how the security label of a table might
-   be changed.
+   The following example shows how the security label of a table could
+   be set or changed:
 
 <programlisting>
 SECURITY LABEL FOR selinux ON TABLE mytable IS 'system_u:object_r:sepgsql_table_t:s0';
-</programlisting></para>
+</programlisting>
+
+   To remove the label:
+
+<programlisting>
+SECURITY LABEL FOR selinux ON TABLE mytable IS NULL;
+</programlisting>
+  </para>
  </refsect1>
 
  <refsect1>