Date: Tue, 16 Jun 2020 19:33:49 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: =?iso-8859-1?Q?J=FCrgen?= Purtz <juergen@purtz.de>,
	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>,
	Roger Harkavy <rogerharkavy@gmail.com>,
	pgsql-hackers@postgresql.org, Michael Paquier <michael@paquier.xyz>,
	Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: Add A Glossary
Message-ID: <20200617003349.GN20404@telsasoft.com>
References: <c1e06008-2132-30f4-9b38-877e8683d418@purtz.de>
 <20200617000926.GA11060@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20200617000926.GA11060@alvherre.pgsql>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk

On Tue, Jun 16, 2020 at 08:09:26PM -0400, Alvaro Herrera wrote:
> diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
> index 25b03f3b37..e29b55e5ac 100644
> --- a/doc/src/sgml/glossary.sgml
> +++ b/doc/src/sgml/glossary.sgml
> @@ -395,15 +395,15 @@
>      <para>
>       The base directory on the filesystem of a
>       <glossterm linkend="glossary-server">server</glossterm> that contains all
> -     data files and subdirectories associated with an
> -     <glossterm linkend="glossary-instance">instance</glossterm> (with the
> -     exception of <glossterm linkend="glossary-tablespace">tablespaces</glossterm>).
> +     data files and subdirectories associated with a
> +     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
> +     (with the exception of
> +     <glossterm linkend="glossary-tablespace">tablespaces</glossterm>).

and (optionally) WAL

> +  <glossentry id="glossary-db-cluster">
> +   <glossterm>Database cluster</glossterm>
> +   <glossdef>
> +    <para>
> +     A collection of databases and global SQL objects,
> +     and their common static and dynamic meta-data.

metadata

> @@ -1245,12 +1255,17 @@
>       <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.
> +     Each SQL object must reside in exactly one schema
> +     (though certain types of SQL objects exist outside schemas).

(except for global objects which ..)

>      <para>
>       The names of SQL objects of the same type in the same schema are enforced
>       to be unique.
>       There is no restriction on reusing a name in multiple schemas.
> +     For local objects that exist outside schemas, their names are enforced
> +     unique across the whole database.  For global objects, their names

I would say "unique within the database"

> +     are enforced unique across the whole
> +     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.

and "unique within the whole db cluster"

>        Most local objects belong to a specific
> -      <glossterm linkend="glossary-schema">schema</glossterm> in their containing database.
> +      <glossterm linkend="glossary-schema">schema</glossterm> in their
> +      containing database, such as
> +      <glossterm linkend="glossary-relation">all types of relations</glossterm>,
> +      <glossterm linkend="glossary-function">all types of functions</glossterm>,

Maybe say: >Relations< (all types), and >Functions< (all types)

>       used as the default one for all SQL objects, called <literal>pg_default</literal>.                                                                                                                                           
"the default" (remove "one")

-- 
Justin