Simplify COMMENT and SECURITY LABEL documentation
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?
Attachments:
0001-doc-Simplify-COMMENT-and-SECURITY-LABEL-documentatio.patchtext/plain; charset=UTF-8; name=0001-doc-Simplify-COMMENT-and-SECURITY-LABEL-documentatio.patch; x-mac-creator=0; x-mac-type=0Download+4-8
Peter Eisentraut <peter.eisentraut@enterprisedb.com> 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
On 2021-Jun-01, Tom Lane wrote:
Peter Eisentraut <peter.eisentraut@enterprisedb.com> 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."
Alvaro Herrera <alvherre@alvh.no-ip.org> 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
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.
Peter Eisentraut <peter.eisentraut@enterprisedb.com> 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
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:
reside.patchtext/x-diff; charset=us-asciiDownload+2-2
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