On 2020-Mar-20, Corey Huinker wrote:
> > Jürgen mentioned off-list that the man page doesn't build. I was going to
> > look into that, but if anyone has more familiarity with that, I'm listening.
> Looking at this some more, I'm not sure anything needs to be done for man
> pages.
Yeah, I don't think he was saying that we needed to do anything to
produce a glossary man page; rather that the "make man" command failed.
I tried it here, and indeed it failed. But on further investigation,
after a "make maintainer-clean" it no longer failed. I'm not sure what
to make of it, but it seems that this patch needn't concern itself with
that.
I gave a read through the first few actual definitions. It's a much
slower work than I thought! Attached you'll find the first few edits
that I propose.
Looking at the definition of "Aggregate" it seemed weird to have it
stand as a verb infinitive. I looked up other glossaries, found this
one
https://www.gartner.com/en/information-technology/glossary?glossaryletter=T
and realized that when they do verbs, they put the present participle
(-ing) form. So I changed it to "Aggregating", and split out the
"Aggregate function" into its own term.
In Atomic, there seemed to be excessive use of <glossterm> in the
definitions. Style guides seem to suggest to do that only the first
time you use a term in a definition. I removed some markup.
I'm not sure about some terms such as "analytic" and "backend server".
I put them in XML comments for now.
The other changes should be self-explanatory.
It's hard to review work from a professional tech writer. I'm under the
constant impression that I'm ruining somebody's perfect end product,
making a fool of myself.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 612ce6e5f4..05fca33d9b 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -6,25 +6,34 @@
systems in general.
</para>
<glosslist>
- <glossentry id="glossary-aggregate">
- <glossterm>Aggregate</glossterm>
+ <glossentry id="glossary-aggregating">
+ <glossterm>Aggregating</glossterm>
<glossdef>
<para>
- To combine a collection of data values into a single value, whose
- value may not be of the same type as the original values.
- <glossterm>Aggregate</glossterm> <glossterm>Functions</glossterm>
- combine multiple <glossterm>Rows</glossterm> that share a common set
- of values into one <glossterm>Row</glossterm>, which means that the
- only data visible in the values in common, and the aggregates of the
- non-common data.
+ 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.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ A <glossterm>Function</glossterm> that combines multiple input values,
+ for example by counting, averaging or adding them all together,
+ yielding a single output value.
</para>
<para>
For more information, see
<xref linkend="functions-aggregate"/>.
</para>
+ <para>
+ See also <glossterm>Window Function</glossterm>.
</glossdef>
</glossentry>
+<!--
<glossentry id="glossary-analytic">
<glossterm>Analytic</glossterm>
<glossdef>
@@ -39,13 +48,15 @@
</para>
</glossdef>
</glossentry>
+-->
<glossentry id="glossary-archiver">
<glossterm>Archiver</glossterm>
<glossdef>
<para>
- A process that backs up <glossterm>WAL Files</glossterm> in order to
- reclaim space on the file system.
+ A process that saves aside copies of <glossterm>WAL Files</glossterm>,
+ for the purposes of creating backup copies or keeping
+ <glossterm>Replicas</glossterm> current.
</para>
<para>
For more information, see
@@ -59,16 +70,15 @@
<glossdef>
<para>
In reference to the value of an <glossterm>Attribute</glossterm> or
- <glossterm>Datum</glossterm>: cannot be broken down into smaller
- components.
+ <glossterm>Datum</glossterm>: the property that it cannot be broken down
+ into smaller components.
</para>
<para>
In reference to an operation: An event that cannot be completed in
part: it must either entirely succeed or entirely fail. A series of
<acronym>SQL</acronym> statements can be combined into a
<glossterm>Transaction</glossterm>, and that
- <glossterm>transaction</glossterm> is said to be
- <glossterm>Atomic</glossterm>.
+ transaction is said to be atomic.
</para>
</glossdef>
</glossentry>
@@ -112,6 +122,7 @@
</glossdef>
</glossentry>
+<!--
<glossentry id="glossary-backend-server">
<glossterm>Backend Server</glossterm>
<glossdef>
@@ -120,6 +131,7 @@
</para>
</glossdef>
</glossentry>
+-->
<glossentry id="glossary-background-worker">
<glossterm>Background Worker</glossterm>
@@ -142,8 +154,9 @@
<glossterm>Background Writer</glossterm>
<glossdef>
<para>
- Writes continuously dirty pages from <glossterm>Shared
- Memory</glossterm> to the file system. It starts periodically, but
+ A process that continuously writes dirty pages from
+ <glossterm>Shared Memory</glossterm> to the file system.
+ It starts periodically, but
works only for a short period in order to distribute expensive
<acronym>I/O</acronym> activity over time instead of generating fewer
large <acronym>I/O</acronym> peaks which could block other processes.
@@ -218,10 +231,9 @@
<glossterm>Checkpoint</glossterm>
<glossdef>
<para>
- A <link linkend="sql-checkpoint"> Checkpoint</link> is a point in time
- when all older dirty pages of the <glossterm>Shared
- Memory</glossterm>, all older <glossterm>WAL records</glossterm>, and
- a special <glossterm>Checkpoint record</glossterm> have been written
+ A point in time when all older dirty pages of the
+ <glossterm>Shared Memory</glossterm>, all older <glossterm>WAL records</glossterm>,
+ and a special <glossterm>Checkpoint record</glossterm> have been written
and flushed to disk.
</para>
</glossdef>
@@ -543,8 +555,8 @@
<glossdef>
<para>
A <glossterm>Relation</glossterm> that contains data derived from a
- <glossterm>Table</glossterm> (or <glossterm>Relation</glossterm> such
- as a <glossterm>Materialized View</glossterm>). It's internal
+ <glossterm>Table</glossterm> (or other kind of <glossterm>Relation</glossterm>
+ such as a <glossterm>Materialized View</glossterm>). Its internal
structure supports very fast retrieval of and access to the original
data.
</para>
@@ -815,7 +827,7 @@
<glossterm>Record</glossterm>
<glossdef>
<para>
- See <link linkend="sql-revoke">Tupple</link>.
+ See <glossterm>Tuple</glossterm>.
</para>
<para>
A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm>
@@ -944,7 +956,7 @@
<glossterm>Row</glossterm>
<glossdef>
<para>
- See <link linkend="sql-revoke">Tupple</link>.
+ See <glossterm>Tuple</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -1194,9 +1206,9 @@
<glossterm>Session</glossterm> or a
<glossterm>Transaction</glossterm>, as defined at creation time. The
data in them is not visible to other <glossterm>Sessions</glossterm>,
- and is not <glossterm>Logged</glossterm>. <glossterm>Temporary
- Tables</glossterm> are most often used to store intermediate data for
- a multi-step data transformation.
+ and is not <glossterm>Logged</glossterm>.
+ <glossterm>Temporary Tables</glossterm> are often used to store
+ intermediate data for a multi-step data transformation.
</para>
<para>
For more information, see
@@ -1227,8 +1239,9 @@
<para>
A <glossterm>Function</glossterm> which can be defined to execute
whenever a certain operation (<command>INSERT</command>,
- <command>UPDATE</command>, or <command>DELTE</command>) is applied to
- that <glossterm>Relation</glossterm>. A <glossterm>Trigger</glossterm>
+ <command>UPDATE</command>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm>Relation</glossterm>.
+ A <glossterm>Trigger</glossterm>
executes within the same <glossterm>Transaction</glossterm> as the
statement which invoked it, and if the <glossterm>Function</glossterm>
fails then the invoking statement also fails.
@@ -1249,8 +1262,8 @@
the <glossterm>Tuple</glossterm> is found, in which case the
<glossterm>Tuple</glossterm> is often called a
<glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may
- also be defined by the structure of a <glossterm>Result
- Set</glossterm>.
+ also be defined by the structure of a
+ <glossterm>Result Set</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -1260,7 +1273,7 @@
<glossdef>
<para>
The condition of having no matching values in the same
- <glossterm>Relation</glossterm>. Most often used in the concept of
+ <glossterm>Relation</glossterm>. Often used in the concept of
<glossterm>Unique Indexes</glossterm>.
</para>
</glossdef>
