Re: Add A Glossary

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