Horton

Thread

Commits

  1. doc: Simplify COMMENT and SECURITY LABEL documentation

  2. doc: Make terminology in glossary consistent

  1. Simplify COMMENT and SECURITY LABEL documentation

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-06-01T06:58:26Z

    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?

  2. Re: Simplify COMMENT and SECURITY LABEL documentation

    Tom Lane <tgl@sss.pgh.pa.us> — 2021-06-01T13:52:42Z

    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

  3. Re: Simplify COMMENT and SECURITY LABEL documentation

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-06-01T15:56:09Z

    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."

  4. Re: Simplify COMMENT and SECURITY LABEL documentation

    Tom Lane <tgl@sss.pgh.pa.us> — 2021-06-01T16:25:49Z

    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

  5. Re: Simplify COMMENT and SECURITY LABEL documentation

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-06-02T15:05:10Z

    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.

  6. Re: Simplify COMMENT and SECURITY LABEL documentation

    Tom Lane <tgl@sss.pgh.pa.us> — 2021-06-02T15:08:47Z

    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

  7. Re: Simplify COMMENT and SECURITY LABEL documentation

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-06-02T19:32:36Z

    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

  8. Re: Simplify COMMENT and SECURITY LABEL documentation

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-06-05T07:19:03Z

    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