Re: Simplify COMMENT and SECURITY LABEL documentation

On 2021-Jun-01, Tom Lane wrote:

> Peter Eisentraut <peter(dot)eisentraut(at)enterprisedb(dot)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."