From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Subject: Re: Add A Glossary
To: Alvaro Herrera <alvherre@2ndquadrant.com>, Erik Rijkers <er@xs4all.nl>,
 Laurenz Albe <laurenz.albe@cybertec.at>, Fabien COELHO
 <coelho@cri.ensmp.fr>, Peter Eisentraut <peter.eisentraut@2ndquadrant.com>,
 Corey Huinker <corey.huinker@gmail.com>
Cc: Justin Pryzby <pryzby@telsasoft.com>,
 Roger Harkavy <rogerharkavy@gmail.com>, pgsql-hackers@postgresql.org,
 Michael Paquier <michael@paquier.xyz>
References: <20200515000017.GA12687@alvherre.pgsql>
Message-ID: <774bb48d-cd3d-17ee-77e9-937519bf9c6e@purtz.de>
Date: Sun, 17 May 2020 08:15:48 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.7.0
MIME-Version: 1.0
In-Reply-To: <20200515000017.GA12687@alvherre.pgsql>
Content-Type: multipart/mixed;
 boundary="------------92E61ABA9AC206F97B7C3526"
Content-Language: en-US
Precedence: bulk

This is a multi-part message in MIME format.
--------------92E61ABA9AC206F97B7C3526
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 8bit

On 15.05.20 02:00, Alvaro Herrera wrote:
> Thanks everybody.  I have compiled together all the suggestions and the
> result is in the attached patch.  Some of it is of my own devising.
>
> * I changed "instance", and made "cluster" be mostly a synonym of that.
In my understanding, "instance" and "cluster" should be different 
things, not only synonyms. "instance" can be the term for permanently 
fluctuating objects (processes and RAM) and "cluster" can denote the 
more static objects (directories and files). What do you think? If you 
agree, I would create a patch.
> * I removed "global SQL object" and made "SQL object" explain it.
+1., but see the (huge) different spellings in patch.

bloat: changed 'current row' to 'relevant row' because not only the 
youngest one is relevant (non-bloat).

data type casts: Are you sure that they are global? In pg_cast 
'relisshared' is 'false'.

--

Jürgen Purtz


--------------92E61ABA9AC206F97B7C3526
Content-Type: text/x-patch; charset=UTF-8;
 name="0002-glossfixes-purtz.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="0002-glossfixes-purtz.patch"

diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 8bb1ea5d87..75f0dc9a8c 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -179,7 +179,7 @@
    <glossterm>Bloat</glossterm>
    <glossdef>
     <para>
-     Space in data pages which does not contain current row versions,
+     Space in data pages which does not contain relevant row versions,
      such as unused (free) space or outdated row versions.
     </para>
    </glossdef>
@@ -1388,23 +1388,27 @@
     <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>.
+      command. Most objects are specific to one schema within
+      one database, and are commonly
+      known as <firstterm>local SQL objects</firstterm>.
+     </para>
+     <para>
+      Some of the SQL objects do not belong to a single schema but
+      are known in all schemas of a database. Examples are
+      <glossterm linkend="glossary-extension">extensions</glossterm> like
+      <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>, and
+      <glossterm linkend="glossary-cast">data type casts</glossterm>.
+     </para>
+     <para>
+      Some others even belong to the complete cluster and are
+      known in all databases and all its schemas.
       <glossterm linkend="glossary-role">Roles</glossterm>,
       <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
       replication origins, subscriptions for logical replication, and
-      databases themselves are not local SQL objects since they exist
-      entirely outside of any specific database;
-      they are called <firstterm>global objects</firstterm>.
+      all <firstterm>database names</firstterm> exist
+      entirely outside of any specific database.
+      They are called <firstterm>global SQL objects</firstterm>.
      </para>
-     <para>
-      Most local objects belong to a specific
-      <glossterm linkend="glossary-schema">schema</glossterm> in their containing database.
-      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>.
-    </para>
     <para>
       For more information, see
       <xref linkend="manage-ag-overview"/>.

--------------92E61ABA9AC206F97B7C3526--