Re: Add A Glossary - Mailing list pgsql-hackers

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