Subject: Simplify COMMENT and SECURITY LABEL documentation

From: Peter Eisentraut <[email-masked]>
Date: Tue, 1 Jun 2021 08:58:26 +0200

The COMMENT ref page says (and SECURITY LABEL similarly):

     The name of the object to be commented.  Names of tables,
     aggregates, collations, ..., and views can be schema-qualified.

and it lists all such possible object types.  I find this tedious to 
read.  (And there are omissions.  For example materialized views are not 
listed.)  I wonder if it would be more practical to just write:

     The name of the object to be commented.  Names of objects that live
     in schemas (tables, functions, etc.) can be schema-qualified.

There are also examples at the end that cover this if there is any doubt.

Patch attached.  Thoughts?
From d5072256b1faabe516eb58990d6f89fa1a3bdd9f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <[email-masked]>
Date: Tue, 1 Jun 2021 08:50:40 +0200
Subject: [PATCH] doc: Simplify COMMENT and SECURITY LABEL documentation

Just say that objects that live in schemas can be schema-qualified.
Don't list all possible such objects.  The existing lists weren't
complete anyway.
---
 doc/src/sgml/ref/comment.sgml        | 6 ++----
 doc/src/sgml/ref/security_label.sgml | 5 ++---
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index eda91b4e24..2cd47f65cc 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -129,10 +129,8 @@ <title>Parameters</title>
     <term><replaceable class="parameter">trigger_name</replaceable></term>
     <listitem>
      <para>
-      The name of the object to be commented.  Names of tables,
-      aggregates, collations, conversions, domains, foreign tables, functions,
-      indexes, operators, operator classes, operator families, procedures, routines, sequences,
-      statistics, text search objects, types, and views can be
+      The name of the object to be commented.  Names of objects that live in
+      schemas (tables, functions, etc.) can be
       schema-qualified. When commenting on a column,
       <replaceable class="parameter">relation_name</replaceable> must refer
       to a table, view, composite type, or foreign table.
diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml
index 9b87bcd519..64606bf1fa 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -99,9 +99,8 @@ <title>Parameters</title>
     <term><replaceable class="parameter">routine_name</replaceable></term>
     <listitem>
      <para>
-      The name of the object to be labeled.  Names of tables,
-      aggregates, domains, foreign tables, functions, procedures, routines, sequences, types, and
-      views can be schema-qualified.
+      The name of the object to be labeled.  Names of objects that live in
+      schemas (tables, functions, etc.) can be schema-qualified.
      </para>
     </listitem>
    </varlistentry>
-- 
2.31.1

---

From: Tom Lane <[email-masked]>
Date: Tue, 01 Jun 2021 09:52:42 -0400

Peter Eisentraut <[email-masked]> writes:
> ...  I wonder if it would be more practical to just write:

>      in schemas (tables, functions, etc.) can be schema-qualified.

+1 for the concept, but I feel that "live in" is a bit too informal
for this context.  I'm too caffeine-deprived to instantly come up
with le mot juste; but perhaps "exist within" would be an improvement?

			regards, tom lane

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 1 Jun 2021 11:56:09 -0400

> with le mot juste; but perhaps "exist within" would be an improvement?

The glossary uses "reside in".

  <glossentry id="glossary-schema">
   <glossterm>Schema</glossterm>
   <glossdef>
    <para>
     A schema is a namespace for
     <glossterm linkend="glossary-sql-object">SQL objects</glossterm>,
     which all reside in the same
     <glossterm linkend="glossary-database">database</glossterm>.
     Each SQL object must reside in exactly one schema.
    </para>

I suppose that we should either use the same term that the glossary
uses, or alternatively fix the glossary to use whatever term we decide
to use here.

I do notice now that I used the term "belong to" elsewhere in the
glossary.  That could use some cleanup.

   <glossterm>SQL object</glossterm>
    <glossdef>
     <para>
      Any object that can be created with a <command>CREATE</command>
      command.  Most objects are specific to one database, and are commonly
      known as <firstterm>local objects</firstterm>.
     </para>
     <para>
      Most local objects belong to a specific
      <glossterm linkend="glossary-schema">schema</glossterm> in their
      containing database, such as
      <glossterm linkend="glossary-relation">relations</glossterm> (all types),
      <glossterm linkend="glossary-function">routines</glossterm> (all types),
      data types, etc.
      The names of such objects of the same type in the same schema
      are enforced to be unique.
     </para>
     <para>
      There also exist local objects that do not belong to schemas; some examples are
      <glossterm linkend="glossary-extension">extensions</glossterm>,
      <glossterm linkend="glossary-cast">data type casts</glossterm>, and
      <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>.
      The names of such objects of the same type are enforced to be unique
      within the database.
     </para>

-- 
Álvaro Herrera                            39°49'30"S 73°17'W
"No renuncies a nada. No te aferres a nada."

---

From: Tom Lane <[email-masked]>
Date: Tue, 01 Jun 2021 12:25:49 -0400

> ...

Yeah, having a standard phrasing would be good.

> glossary.  That could use some cleanup.

Hmm, I like "belong to" better than these others.  Maybe we should
standardize on that?

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 2 Jun 2021 17:05:10 +0200

> The glossary uses "reside in".

I like that.

> glossary.  That could use some cleanup.

I think "belong to" is a stronger relationship, like a column belongs to 
a table.  Kind of like DEPENDENCY_INTERNAL vs. DEPENDENCY_NORMAL.

---

From: Tom Lane <[email-masked]>
Date: Wed, 02 Jun 2021 11:08:47 -0400

> a table.  Kind of like DEPENDENCY_INTERNAL vs. DEPENDENCY_NORMAL.

Hmm, okay.  I can support "reside in".

			regards, tom lane

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 2 Jun 2021 15:32:36 -0400

> > The glossary uses "reside in".

So I would adjust the glossary as in the attached patch.

-- 
Álvaro Herrera       Valdivia, Chile
"Ed is the standard text editor."
      http://groups.google.com/group/alt.religion.emacs/msg/8d94ddab6a9b0ad3
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 41f3e5ee86..c8d0440e80 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -1448,7 +1448,7 @@
       known as <firstterm>local objects</firstterm>.
      </para>
      <para>
-      Most local objects belong to a specific
+      Most local objects reside in a specific
       <glossterm linkend="glossary-schema">schema</glossterm> in their
       containing database, such as
       <glossterm linkend="glossary-relation">relations</glossterm> (all types),
@@ -1458,7 +1458,7 @@
       are enforced to be unique.
      </para>
      <para>
-      There also exist local objects that do not belong to schemas; some examples are
+      There also exist local objects that do not reside in schemas; some examples are
       <glossterm linkend="glossary-extension">extensions</glossterm>,
       <glossterm linkend="glossary-cast">data type casts</glossterm>, and
       <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>.

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 5 Jun 2021 09:19:03 +0200

> So I would adjust the glossary as in the attached patch.

done and done