From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Corey Huinker <corey.huinker@gmail.com>
Cc: Jürgen Purtz <juergen@purtz.de>
Cc: Roger Harkavy <rogerharkavy@gmail.com>
Cc: pgsql-hackers@postgresql.org, Fabien COELHO <coelho@cri.ensmp.fr>
Cc: Michael Paquier <michael@paquier.xyz>
Subject: Re: Add A Glossary
Date: Fri, 20 Mar 2020 14:51:44 -0300
Message-ID: <20200320175144.GA20645@alvherre.pgsql> (raw)
In-Reply-To: <CADkLM=dTFNCnx+bdoVCVbAn3v8ihvgUh-dQpin4ngrx=RMykFA@mail.gmail.com>
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
Attachments:
[text/x-diff] glossary-3.patch (7.7K, ../20200320175144.GA20645@alvherre.pgsql/2-glossary-3.patch)
download | inline diff:diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgmlindex 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>
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: pgsql-hackers@postgresql.org
Cc: alvherre@2ndquadrant.com, corey.huinker@gmail.com, juergen@purtz.de, rogerharkavy@gmail.com, coelho@cri.ensmp.fr, michael@paquier.xyz
Subject: Re: Add A Glossary
In-Reply-To: <20200320175144.GA20645@alvherre.pgsql>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox