Date: Tue, 31 Mar 2020 13:07:40 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Corey Huinker <corey.huinker@gmail.com>
Cc: =?iso-8859-1?Q?J=FCrgen?= Purtz <juergen@purtz.de>,
	Alvaro Herrera <alvherre@2ndquadrant.com>,
	Roger Harkavy <rogerharkavy@gmail.com>,
	pgsql-hackers@postgresql.org, Fabien COELHO <coelho@cri.ensmp.fr>,
	Michael Paquier <michael@paquier.xyz>
Subject: Re: Add A Glossary
Message-ID: <20200331180740.GG14618@telsasoft.com>
References: 
 <CADkLM=fwtE-TCU7sRnvaE74z12kOp_A+CdUwMr7aZt39pXbh6A@mail.gmail.com>
 <20200320001122.GA19602@alvherre.pgsql>
 <20200320195841.GA13662@telsasoft.com>
 <64b49f34-eaf6-6de2-e951-0eb8d4afabc2@purtz.de>
 <20200327201200.GV20103@telsasoft.com>
 <ff6028d0-ff04-6d11-c41b-2bddb41777d0@purtz.de>
 <CADkLM=eHCVmL8JnmaW2h+XXLRpKzkLrq6WXMbKB7giJCuS=jXA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CADkLM=eHCVmL8JnmaW2h+XXLRpKzkLrq6WXMbKB7giJCuS=jXA@mail.gmail.com>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk

On Mon, Mar 30, 2020 at 01:10:19PM -0400, Corey Huinker wrote:
> +   <glossentry id="glossary-aggregating">
> +    <glossterm>Aggregating</glossterm>
> +    <glossdef>
> +     <para>
> +      The act of combining a collection of data (input) values into
> +      a single output value, which may not be of the same type as the
> +      input values.

I think we maybe already tried to address this ; but could we define a noun
form ?  But not "aggregate" since it's the same word as the verb form.  I think
it would maybe be best to merge with "aggregate function", below.

> +   <glossentry id="glossary-consistency">
> +    <glossterm>Consistency</glossterm>
> +    <glossdef>
> +     <para>
> +      One of the <acronym>ACID</acronym> properties. This means that the database
> +      is always in compliance with its own rules such as <glossterm>Table</glossterm>
> +      structure, <glossterm>Constraint</glossterm>s,

I don't think the definition of "compliance" is good.  The state of being
consistent means an absense of corruption more than that an absense of data
integrity issues (which could be caused by corruption).

> +   <glossentry id="glossary-datum">
> +    <glossterm>Datum</glossterm>
> +    <glossdef>
> +     <para>
> +      The internal representation of a <acronym>SQL</acronym> data type.

Could you say "..used by PostgreSQL" ?

> +    <glossterm>File Segment</glossterm>
> +    <glossdef>
> +     <para>
> +       A physical file which stores data for a given
> +       <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> object.
> +       <glossterm>File Segment</glossterm>s are limited in size by a
> +       configuration value and if that size is exceeded, it will be split
> +       into multiple physical files.

Say "if an object exceeds that size, then it will be stored across multiple
physical files".

> +      which handles parts of an <acronym>SQL</acronym> query to take
...
> +      A <acronym>SQL</acronym> command used to add new data into a

I mentioned before, please be consistent: "A SQL or An SQL".

> +     </para>
> +     <para>
> +      Many <glossterm>Instance</glossterm>s can run on the same server as

Say "multiple" not many.

> +   <glossentry id="glossary-join">
> +    <glossterm>Join</glossterm>
> +    <glossdef>
> +     <para>
> +      A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
> +      combining data from multiple <glossterm>Relation</glossterm>s.

Could you add a link to the docs ?

> +   <glossentry id="glossary-log-writer">
> +    <glossterm>Log Writer</glossterm>
> +    <glossdef>
> +     <para>
> +      If activated and parameterized, the

I still don't know what parameterized means here.

> +   <glossentry id="glossary-system-catalog">
> +    <glossterm>System Catalog</glossterm>
> +    <glossdef>
> +     <para>
> +      A collection of <glossterm>Table</glossterm>s and
> +      <glossterm>View</glossterm>s which describe the structure of all
> +      <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm>

I would say "... a PostgreSQL >Database<"

> +      and the <glossterm>Global SQL Object</glossterm>s of the
> +      <glossterm>Cluster</glossterm>. The <glossterm>System
> +      Catalog</glossterm> resides in the schema
> +      <literal>pg_catalog</literal>. Main parts are mirrored as
> +      <glossterm>View</glossterm>s in the <glossterm>Schema</glossterm>
> +      <literal>information_schema</literal>.

I wouldn't say "mirror":  Some information is also exposed as >Views< in the
>information_schema< >Schema<.

> +   <glossentry id="glossary-tablespace">
> +    <glossterm>Tablespace</glossterm>
> +    <glossdef>
> +     <para>
> +      A named location on the server filesystem. All <glossterm>SQL Object</glossterm>s
> +      which require storage beyond their definition in the
> +      <glossterm>System Catalog</glossterm>
> +      must belong to a single tablespace.

Remove "single" as it sounds like we only support one.

> +    <glossterm>Transaction</glossterm>
> +    <glossdef>
> +     <para>
> +      A combination of commands that must act as a single
> +      <glossterm>Atomic</glossterm> command: they all succeed or all fail
> +      as a single unit, and their effects are not visible to other
> +      <glossterm>Session</glossterm>s until
> +      the <glossterm>Transaction</glossterm> is complete.

s/complete/commited/ ?


> +   <glossentry id="glossary-unique">
> +    <glossterm>Unique</glossterm>
> +    <glossdef>
> +     <para>
> +      The condition of having no duplicate values in the same
> +      <glossterm>Relation</glossterm>. Often used in the concept of

s/concept/context/

> +    <glossterm>Vacuum</glossterm>
> +    <glossdef>
> +     <para>
> +      The process of removing outdated <acronym>MVCC</acronym>

Maybe say "tuples which were deleted or obsoleted by an UPDATE".
But maybe you're trying to use generic language.

-- 
Justin