public inbox for [email protected]
help / color / mirror / Atom feedFrom: Jürgen Purtz <[email protected]>
To: Corey Huinker <[email protected]>
Cc: Justin Pryzby <[email protected]>
Cc: Alvaro Herrera <[email protected]>
Cc: Roger Harkavy <[email protected]>
Cc: [email protected]
Cc: Fabien COELHO <[email protected]>
Cc: Michael Paquier <[email protected]>
Subject: Re: Add A Glossary
Date: Tue, 31 Mar 2020 16:13:00 +0200
Message-ID: <[email protected]> (raw)
In-Reply-To: <CADkLM=eHCVmL8JnmaW2h+XXLRpKzkLrq6WXMbKB7giJCuS=jXA@mail.gmail.com>
References: <CADkLM=fwtE-TCU7sRnvaE74z12kOp_A+CdUwMr7aZt39pXbh6A@mail.gmail.com>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<CADkLM=eHCVmL8JnmaW2h+XXLRpKzkLrq6WXMbKB7giJCuS=jXA@mail.gmail.com>
On 30.03.20 19:10, Corey Huinker wrote:
>
>
> On Sun, Mar 29, 2020 at 5:29 AM Jürgen Purtz <[email protected]
> <mailto:[email protected]>> wrote:
>
> On 27.03.20 21:12, Justin Pryzby wrote:
> > On Fri, Mar 20, 2020 at 11:32:25PM +0100, Jürgen Purtz wrote:
> >>>> + <glossterm>Archiver</glossterm>
> >>> Can you change that to archiver process ?
> >> I prefer the short term without the addition of 'process' -
> concerning
> >> 'Archiver' as well as the other cases. But I'm not an native
> English
> >> speaker.
> > I didn't like it due to lack of context.
> >
> > What about "wal archiver" ?
> >
> > It occured to me when I read this.
> >
> https://www.postgresql.org/message-id/20200327.163007.128069746774242774.horikyota.ntt%40gmail.com
> >
> "WAL archiver" is ok for me. In the current documentation we have 2
> places with "WAL archiver" and 4 with "archiver"-only
> (high-availability.sgml, monitoring.sgml).
>
> "backend process" is an exception to the other terms because the
> standalone term "backend" is sensibly used in diverse situations.
>
> Kind regards, Jürgen
>
>
> I've taken Alvarao's fixes and done my best to incorporate the
> feedback into a new patch, which Roger's (tech writer) reviewed yesterday.
>
> The changes are too numerous to list, but the highlights are:
>
> New definitions:
> * All four ACID terms
> * Vacuum (split off from Autovacuum)
> * Tablespace
> * WAL Archiver (replaces Archiver)
>
> Changes to existing terms:
> * Implemented most wording changes recommended by Justin
> * all remaining links were either made into xrefs or edited out of
> existence
>
> * de-tagged most second uses of of a term within a definition
>
>
> Did not do
> * Addressed the " Process" suffix suggested by Justin. There isn't
> consensus on these changes, and I'm neutral on the matter
> * change the Cast definition. I think it's important to express
> that a cast has a FROM datatype as well as a TO
> * anything host/server related as I couldn't see a consensus reached
>
> Other thoughts:
> * Trivial definitions that are just see-other-definition are ok
> with me, as the goal of this glossary is to aid in discovery of
> term meanings, so knowing that two terms are interchangable is
> itself helpful
>
>
> It is my hope that this revision represents the final _structural_
> change to the glossary. New definitions and edits to existing
> definitions will, of course, go on forever.
Please find some minor suggestions in the attachment. They are based on
Corey's last patch 0001-glossary-v4.patch.
Kind regards, Jürgen
Attachments:
[text/x-patch] 0001-glossary-v4-01.patch (8.9K, 3-0001-glossary-v4-01.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index eab14f3c9b..623922a4c3 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -36,10 +36,10 @@
</glossentry>
<glossentry id="glossary-analytic">
- <glossterm>Analytic</glossterm>
+ <glossterm>Analytic Function</glossterm>
<glossdef>
<para>
- A <glossterm>Function</glossterm> whose computed value can reference
+ A type of <glossterm>Function</glossterm>s whose result may be based on
values found in nearby <glossterm>Row</glossterm>s of the same
<glossterm>Result Set</glossterm>.
</para>
@@ -59,12 +59,12 @@
into smaller components.
</para>
<para>
+ <!-- better wording ??? '... cannot be partially processed; ...' -->
In reference to an operation: an event that cannot be completed in
part; it must either entirely succeed or entirely fail. For
example, a series of <acronym>SQL</acronym> statements can be
combined into a <glossterm>Transaction</glossterm>, and that
- transaction is said to be atomic.
- <glossterm>Atomic</glossterm>.
+ transaction is said to be <glossterm>Atomic</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -73,7 +73,7 @@
<glossterm>Atomicity</glossterm>
<glossdef>
<para>
- One of the <acronym>ACID</acronym> properties. This is the state of
+ One of the <acronym>ACID</acronym> properties. This is the state of
being <glossterm>Atomic</glossterm> in the operational/transactional sense.
</para>
</glossdef>
@@ -152,7 +152,7 @@
A process that continuously writes dirty pages from
<glossterm>Shared Memory</glossterm> to the file system.
It wakes up periodically, but
- works only for a short period in order to distribute expensive
+ works only for a short period in order to distribute its expensive
<acronym>I/O</acronym> activity over time, instead of generating fewer
larger <acronym>I/O</acronym> peaks which could block other processes.
</para>
@@ -220,7 +220,7 @@
Record</glossterm>s to the file system and creates a special
checkpoint record. This process is initiated when predefined
conditions are met, such as a specified amount of time has passed, or
- a certain volume of records have been collected.
+ a certain volume of records has been collected.
</para>
</glossdef>
</glossentry>
@@ -303,7 +303,7 @@
<glossdef>
<para>
An established line of communication between a client process
- and a server process. If the two involved processes reside on the
+ and a <glossterm>Backend Process</glossterm>. If the two involved processes reside on the
same <glossterm>Server</glossterm>, then the connection can either use
<acronym>TCP/IP</acronym> or Unix-domain sockets. Otherwise,
only <acronym>TCP/IP</acronym> can be used.
@@ -470,7 +470,7 @@
A type of <glossterm>Constraint</glossterm> defined on one or more
<glossterm>Column</glossterm>s in a <glossterm>Table</glossterm> which
requires the value(s) in those <glossterm>Column</glossterm>s to
- identify exactly one <glossterm>Row</glossterm> in the specified
+ identify exactly one <glossterm>Row</glossterm> in another (or the same)
<glossterm>Table</glossterm>.
</para>
</glossdef>
@@ -643,7 +643,7 @@
<glossterm>Isolation</glossterm>
<glossdef>
<para>
- One of the <acronym>ACID</acronym> properties. This means that concurrently running
+ One of the <acronym>ACID</acronym> properties. This means that concurrently running
<glossterm>Transaction</glossterm>s affect the database exactly as if they had been
executed sequentially.
</para>
@@ -795,6 +795,7 @@
<glossterm>Partition</glossterm>
<glossdef>
<para>
+ In reference to a <glossterm>Table</glossterm>:
A <glossterm>Table</glossterm> that can be queried directly,
or via a partitioned table, which is a collection of
sub-tables, each capable of holding one defined
@@ -802,9 +803,8 @@
table in the collection.
</para>
<para>
- When referring to an <glossterm>Analytic</glossterm>
- <glossterm>Function</glossterm>: a partition is a definition
- that identifies which neighboring
+ In reference to a <glossterm>Analytic Function</glossterm>:
+ a partition is a definition that identifies which neighboring
<glossterm>Row</glossterm>s can be considered by the
function.
</para>
@@ -865,13 +865,13 @@
<glossentry id="glossary-record">
<glossterm>Record</glossterm>
<glossdef>
- <para>
- See <glossterm>Tuple</glossterm>.
- </para>
<para>
A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm>
or other <glossterm>Relation</glossterm>.
</para>
+ <para>
+ See <glossterm>Tuple</glossterm>.
+ </para>
</glossdef>
</glossentry>
@@ -880,6 +880,7 @@
<glossdef>
<para>
A means of restricting data in one <glossterm>Relation</glossterm>
+ by a <glossterm>Foreign Key</glossterm>
so that it must have matching data in another
<glossterm>Relation</glossterm>.
</para>
@@ -905,7 +906,7 @@
<glossterm>Replica</glossterm>
<glossdef>
<para>
- A <glossterm>Database</glossterm> that is paired with a
+ A <glossterm>Database</glossterm> that is paired with a
<glossterm>Master</glossterm>
database and is maintaining a copy of some or
all of the Master <glossterm>Database</glossterm>'s data. The primary
@@ -934,7 +935,7 @@
<glossterm>Result Set</glossterm>
<glossdef>
<para>
- A data structure transmitted from a <glossterm>Server</glossterm> to
+ A data structure transmitted from a <glossterm>Backend Process</glossterm> to
client program upon the completion of a <acronym>SQL</acronym>
command, usually a <command>SELECT</command> but it can be an
<command>INSERT</command>, <command>UPDATE</command>, or
@@ -1068,8 +1069,8 @@
<glossterm>Select</glossterm>
<glossdef>
<para>
- The command used to query a <glossterm>Database</glossterm>. Normally,
- <command>SELECT</command>s are not expected to modify the
+ The <acronym>SQL</acronym> command used to query a <glossterm>Database</glossterm>.
+ Normally, <command>SELECT</command>s are not expected to modify the
<glossterm>Database</glossterm> in any way, but it is possible that
<glossterm>Function</glossterm>s invoked within the query could have
side effects that do modify data.
@@ -1333,7 +1334,8 @@
<glossdef>
<para>
The condition of having no duplicate values in the same
- <glossterm>Relation</glossterm>. Often used in the concept of
+ <glossterm>Column</glossterm> of a <glossterm>Relation</glossterm>.
+ Often used in the concept of
<glossterm>Unique Index</glossterm>es.
</para>
</glossdef>
@@ -1361,9 +1363,9 @@
<glossterm>Update</glossterm>
<glossdef>
<para>
- A command used to modify <glossterm>Row</glossterm>s that may already
- exist in a specified <glossterm>Table</glossterm>. It cannot create
- or remove rows.
+ A <acronym>SQL</acronym> command used to modify <glossterm>Row</glossterm>s
+ that may already exist in a specified <glossterm>Table</glossterm>.
+ It cannot create or remove rows.
</para>
<para>
For more information, see
@@ -1402,7 +1404,7 @@
<glossdef>
<para>
The process of removing outdated <acronym>MVCC</acronym>
- <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
+ <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
<glossterm>Index</glossterm>. This can be initiated through the use of
the <command>VACUUM</command> command, but can also be handled automatically
via <glossterm>Autovacuum</glossterm> processes.
@@ -1436,7 +1438,7 @@
<glossterm>WAL Archiver</glossterm>
<glossdef>
<para>
- A process that saves copies of <glossterm>WAL File</glossterm>s,
+ A process that saves copies of <glossterm>WAL File</glossterm>s
for the purposes of creating backups or keeping
<glossterm>Replica</glossterm>s current.
</para>
@@ -1461,7 +1463,7 @@
<glossterm>WAL File</glossterm>s is renamed and reused.
</para>
<para>
- The sequence of <glossterm>WAL Record</glossterm>s
+ The sequence of <glossterm>WAL Record</glossterm>s
represents the sequence of changes that have taken place in the
<glossterm>Cluster</glossterm>.
</para>
@@ -1522,7 +1524,7 @@
<glossdef>
<para>
This process writes <glossterm>WAL Record</glossterm>s from
- <glossterm>Shared Memory</glossterm> to
+ <glossterm>Shared Memory</glossterm> to
<glossterm>WAL File</glossterm>s.
</para>
<para>
view thread (97+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: Add A Glossary
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox