[Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>]

Hi Hackers,

A user on IRC was confused about how to delete a security label using
the `SECURITY LABLEL ON … IS …` command, and looking at the docs I can
see why.

The synopsis just says `IS 'label'`, which implies that it can only be a
string. It's not until you read the description for `label` that you
see "or `NULL` to drop the security label."  I propose making the
synopsis say `IS { 'label' | NULL }` to make it clear that it can be
NULL as well.  The same applies to `COMMENT ON … IS …`, which I've also
changed similarly in the attached.

- ilmari

Attachments:

0001-Clarify-that-COMMENT-and-SECURITY-LABEL-can-be-set-t.patch (text/x-diff, 1.9K) download
From cb02bd9aae85a48355dede9dd13db809f6ada35b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Tue, 31 Jan 2023 16:05:20 +0000
Subject: [PATCH] Clarify that COMMENT and SECURITY LABEL can be set to NULL in
 the synopses

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).
---
 doc/src/sgml/ref/comment.sgml        | 2 +-
 doc/src/sgml/ref/security_label.sgml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 7499da1d62..f5daea7a7e 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>
 
diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml
index 20a839ff0c..3df5ed2e9c 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>
 
-- 
2.34.1