Thread: 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?
Attachment
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
Attachment
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