On 30.03.20 19:10, Corey Huinker wrote:
On Sun, Mar 29, 2020 at 5:29 AM Jürgen Purtz <juer...@purtz.de
<mailto:juer...@purtz.de>> 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
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>
