public inbox for [email protected]
help / color / mirror / Atom feedSimplify COMMENT and SECURITY LABEL documentation
8+ messages / 3 participants
[nested] [flat]
* Simplify COMMENT and SECURITY LABEL documentation
@ 2021-06-01 06:58 Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
0 siblings, 1 reply; 8+ messages in thread
From: Peter Eisentraut @ 2021-06-01 06:58 UTC (permalink / raw)
To: pgsql-docs
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 protected]>
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
Attachments:
[text/plain] 0001-doc-Simplify-COMMENT-and-SECURITY-LABEL-documentatio.patch (2.2K, 2-0001-doc-Simplify-COMMENT-and-SECURITY-LABEL-documentatio.patch)
download | inline diff:
From d5072256b1faabe516eb58990d6f89fa1a3bdd9f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <[email protected]>
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
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
@ 2021-06-01 13:52 ` Tom Lane <[email protected]>
2021-06-01 15:56 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 8+ messages in thread
From: Tom Lane @ 2021-06-01 13:52 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: pgsql-docs
Peter Eisentraut <[email protected]> writes:
> ... 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.
+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
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
@ 2021-06-01 15:56 ` Alvaro Herrera <[email protected]>
2021-06-01 16:25 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-02 15:05 ` Re: Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
0 siblings, 2 replies; 8+ messages in thread
From: Alvaro Herrera @ 2021-06-01 15:56 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; pgsql-docs
On 2021-Jun-01, Tom Lane wrote:
> Peter Eisentraut <[email protected]> writes:
> > ... 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.
>
> +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?
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."
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-01 15:56 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
@ 2021-06-01 16:25 ` Tom Lane <[email protected]>
1 sibling, 0 replies; 8+ messages in thread
From: Tom Lane @ 2021-06-01 16:25 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; pgsql-docs
Alvaro Herrera <[email protected]> writes:
> On 2021-Jun-01, Tom Lane wrote:
>> +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?
> The glossary uses "reside in".
> ...
> 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.
Yeah, having a standard phrasing would be good.
> I do notice now that I used the term "belong to" elsewhere in the
> glossary. That could use some cleanup.
Hmm, I like "belong to" better than these others. Maybe we should
standardize on that?
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-01 15:56 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
@ 2021-06-02 15:05 ` Peter Eisentraut <[email protected]>
2021-06-02 15:08 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-02 19:32 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
1 sibling, 2 replies; 8+ messages in thread
From: Peter Eisentraut @ 2021-06-02 15:05 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; Tom Lane <[email protected]>; +Cc: pgsql-docs
On 01.06.21 17:56, Alvaro Herrera wrote:
>> +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?
>
> The glossary uses "reside in".
I like that.
> 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.
I think "belong to" is a stronger relationship, like a column belongs to
a table. Kind of like DEPENDENCY_INTERNAL vs. DEPENDENCY_NORMAL.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-01 15:56 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
2021-06-02 15:05 ` Re: Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
@ 2021-06-02 15:08 ` Tom Lane <[email protected]>
1 sibling, 0 replies; 8+ messages in thread
From: Tom Lane @ 2021-06-02 15:08 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; pgsql-docs
Peter Eisentraut <[email protected]> writes:
> On 01.06.21 17:56, Alvaro Herrera wrote:
>> The glossary uses "reside in".
> I like that.
> I think "belong to" is a stronger relationship, like a column belongs to
> a table. Kind of like DEPENDENCY_INTERNAL vs. DEPENDENCY_NORMAL.
Hmm, okay. I can support "reside in".
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-01 15:56 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
2021-06-02 15:05 ` Re: Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
@ 2021-06-02 19:32 ` Alvaro Herrera <[email protected]>
2021-06-05 07:19 ` Re: Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
1 sibling, 1 reply; 8+ messages in thread
From: Alvaro Herrera @ 2021-06-02 19:32 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs
On 2021-Jun-02, Peter Eisentraut wrote:
> On 01.06.21 17:56, Alvaro Herrera wrote:
> > > +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?
> >
> > The glossary uses "reside in".
>
> I like that.
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
Attachments:
[text/x-diff] reside.patch (1.0K, 2-reside.patch)
download | inline diff:
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>.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Simplify COMMENT and SECURITY LABEL documentation
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Re: Simplify COMMENT and SECURITY LABEL documentation Tom Lane <[email protected]>
2021-06-01 15:56 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
2021-06-02 15:05 ` Re: Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-02 19:32 ` Re: Simplify COMMENT and SECURITY LABEL documentation Alvaro Herrera <[email protected]>
@ 2021-06-05 07:19 ` Peter Eisentraut <[email protected]>
0 siblings, 0 replies; 8+ messages in thread
From: Peter Eisentraut @ 2021-06-05 07:19 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs
On 02.06.21 21:32, Alvaro Herrera wrote:
> On 2021-Jun-02, Peter Eisentraut wrote:
>
>> On 01.06.21 17:56, Alvaro Herrera wrote:
>>>> +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?
>>>
>>> The glossary uses "reside in".
>>
>> I like that.
>
> So I would adjust the glossary as in the attached patch.
done and done
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2021-06-05 07:19 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-06-01 06:58 Simplify COMMENT and SECURITY LABEL documentation Peter Eisentraut <[email protected]>
2021-06-01 13:52 ` Tom Lane <[email protected]>
2021-06-01 15:56 ` Alvaro Herrera <[email protected]>
2021-06-01 16:25 ` Tom Lane <[email protected]>
2021-06-02 15:05 ` Peter Eisentraut <[email protected]>
2021-06-02 15:08 ` Tom Lane <[email protected]>
2021-06-02 19:32 ` Alvaro Herrera <[email protected]>
2021-06-05 07:19 ` Peter Eisentraut <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox