[Doc] Glossary Term Definitions Edits
Hello. I started reading through the Glossary[^1] terms to learn from the
definitions, and to double check them against what I'd written elsewhere. I
found myself making edits. :)
I've put the edits together into a patch. My goal was to focus on wording
simplifications that are smoother to read, without big changes.
I realized I should check with others though, so this is a mid-point
check-in. For now I went through terms from "A" through "I".
Here's a recap of the changes:
- Changed places like “to make” to use the verb directly, i.e. “make”
- When describing options for a command, changed to “option of” instead
of “option to”
- “system- or user-supplied”, removed the dash after system. Or I’d
suggest system-supplied or user-supplied, to hyphenate both.
- Changed “will access” to “access”
- Changed “helps to prevent” to “helps prevent”
- Changed “volume of records has been written” to “volume of records
were written”
- “It is required that this user exist” changed to “This user is
required to exist...” (I’d also suggest “This user must exist before”) as a
simplification, but that’s a bigger difference from what’s there now.
- Changed “operating-system” to remove the hyphen, which is how it’s
written elsewhere in the Glossary.
- Many examples of “an SQL”. I changed those to “a SQL...”. For example
I changed “An SQL command which” to “A SQL command that”. I'm not an
English major so maybe I'm missing something here.
- I often thought “that” was easier to read than “which”, and there are
several examples in the patch. For example “Space in data pages that…”
replaced “Space in data pages which…”
- Simplifications like: “There also exist two secondary forks” to “There
are two secondary forks”
I was able to build the documentation locally and preview the HTML version.
If these types of changes are helpful, and can continue a consistent style
through all the terms and provide a new (larger) v2 patch.
Thanks for taking a look.
Andrew Atkinson
Attachments:
glossary_terms_grammar_edits_v1.patchapplication/octet-stream; name=glossary_terms_grammar_edits_v1.patchDownload
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index fe8def41d0..5f077c70e0 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -52,12 +52,12 @@
<glossterm linkend="glossary-table">tables</glossterm>
and other <glossterm linkend="glossary-relation">relations</glossterm>
to help the <glossterm linkend="glossary-planner">query planner</glossterm>
- to make decisions about how to execute
+ make decisions about how to execute
<glossterm linkend="glossary-query">queries</glossterm>.
</para>
<para>
(Don't confuse this term with the <literal>ANALYZE</literal> option
- to the <xref linkend="sql-explain"/> command.)
+ of the <xref linkend="sql-explain"/> command.)
</para>
<para>
For more information, see
@@ -175,7 +175,7 @@
<glossdef>
<para>
Process within an <glossterm linkend="glossary-instance">instance</glossterm>,
- which runs system- or user-supplied code.
+ which runs system or user-supplied code.
Serves as infrastructure for several features in
<productname>PostgreSQL</productname>, such as
<glossterm linkend="glossary-replication">logical replication</glossterm>
@@ -227,7 +227,7 @@
<glossterm>Bloat</glossterm>
<glossdef>
<para>
- Space in data pages which does not contain current row versions,
+ Space in data pages that does not contain current row versions,
such as unused (free) space or outdated row versions.
</para>
</glossdef>
@@ -256,9 +256,9 @@
<glossterm>Buffer Access Strategy</glossterm>
<glossdef>
<para>
- Some operations will access a large number of
+ Some operations access a large number of
<glossterm linkend="glossary-data-page">pages</glossterm>. A
- <firstterm>Buffer Access Strategy</firstterm> helps to prevent these
+ <firstterm>Buffer Access Strategy</firstterm> helps prevent these
operations from evicting too many pages from
<glossterm linkend="glossary-shared-memory">shared buffers</glossterm>.
</para>
@@ -320,7 +320,7 @@
<para>
A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
defined on a <glossterm linkend="glossary-relation">relation</glossterm>
- which restricts the values allowed in one or more
+ that restricts the values allowed in one or more
<glossterm linkend="glossary-attribute">attributes</glossterm>. The
check constraint can make reference to any attribute of the same row in
the relation, but cannot reference other rows of the same relation or
@@ -350,7 +350,7 @@
are necessary to reach a checkpoint as defined above.
This process is initiated when predefined conditions are met,
such as a specified amount of time has passed, or a certain volume
- of records has been written; or it can be invoked by the user
+ of records were written; or it can be invoked by the user
with the command <command>CHECKPOINT</command>.
</para>
<para>
@@ -396,12 +396,11 @@
The operating system user that owns the
<glossterm linkend="glossary-data-directory">data directory</glossterm>
and under which the <literal>postgres</literal> process is run.
- It is required that this user exist prior to creating a new
+ This user is required to exist prior to creating a new
<glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
</para>
<para>
- On operating systems with a <literal>root</literal> user,
- said user is not allowed to be the cluster owner.
+ The user <literal>root</literal> is not allowed to be the cluster owner.
</para>
</glossdef>
</glossentry>
@@ -424,7 +423,7 @@
The act of finalizing a
<glossterm linkend="glossary-transaction">transaction</glossterm> within
the <glossterm linkend="glossary-database">database</glossterm>, which
- makes it visible to other transactions and assures its
+ makes it visible to other transactions and ensures its
<glossterm linkend="glossary-durability">durability</glossterm>.
</para>
<para>
@@ -468,13 +467,13 @@
<glossterm>Consistency</glossterm>
<glossdef>
<para>
- The property that the data in the
+ The property that data in the
<glossterm linkend="glossary-database">database</glossterm>
- is always in compliance with
+ is always compliant with
<glossterm linkend="glossary-constraint">integrity constraints</glossterm>.
- Transactions may be allowed to violate some of the constraints
- transiently before it commits, but if such violations are not resolved
- by the time it commits, such a transaction is automatically
+ Transactions may allow constraints to be violated
+ temporarily, but violations must be resolved before the transaction
+ commits or it will be automatically
<glossterm linkend="glossary-rollback">rolled back</glossterm>.
This is one of the <acronym>ACID</acronym> properties.
</para>
@@ -549,7 +548,7 @@
</para>
<para>
See also <glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>,
- the operating-system owner of a cluster,
+ the operating system owner of a cluster,
and <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>,
the <productname>PostgreSQL</productname> owner of a cluster.
</para>
@@ -619,7 +618,7 @@
<glossterm>Datum</glossterm>
<glossdef>
<para>
- The internal representation of one value of an <acronym>SQL</acronym>
+ The internal representation of one value of a <acronym>SQL</acronym>
data type.
</para>
</glossdef>
@@ -629,7 +628,7 @@
<glossterm>Delete</glossterm>
<glossdef>
<para>
- An <acronym>SQL</acronym> command which removes
+ A <acronym>SQL</acronym> command that removes
<glossterm linkend="glossary-tuple">rows</glossterm> from a given
<glossterm linkend="glossary-table">table</glossterm>
or <glossterm linkend="glossary-relation">relation</glossterm>.
@@ -692,7 +691,7 @@
<glossterm>File segment</glossterm>
<glossdef>
<para>
- A physical file which stores data for a given
+ A physical file that stores data for a given
<glossterm linkend="glossary-relation">relation</glossterm>.
File segments are limited in size by a configuration value
(typically 1 gigabyte),
@@ -785,7 +784,7 @@
<para>
Each of the separate segmented file sets in which a relation is stored.
The <firstterm>main fork</firstterm> is where the actual data resides.
- There also exist two secondary forks for metadata:
+ There are two secondary forks for metadata:
the <glossterm linkend="glossary-fsm">free space map</glossterm>
and the <glossterm linkend="glossary-vm">visibility map</glossterm>.
<glossterm linkend="glossary-unlogged">Unlogged relations</glossterm>
@@ -838,7 +837,7 @@
<glossterm>Grant</glossterm>
<glossdef>
<para>
- An <acronym>SQL</acronym> command that is used to allow a
+ A <acronym>SQL</acronym> command that is used to allow a
<glossterm linkend="glossary-user">user</glossterm> or
<glossterm linkend="glossary-role">role</glossterm> to access
specific objects within the <glossterm linkend="glossary-database">database</glossterm>.
@@ -898,7 +897,7 @@
<glossterm>Insert</glossterm>
<glossdef>
<para>
- An <acronym>SQL</acronym> command used to add new data into a
+ A <acronym>SQL</acronym> command used to add new data into a
<glossterm linkend="glossary-table">table</glossterm>.
</para>
<para>
@@ -1385,7 +1384,7 @@
A <glossterm linkend="glossary-relation">relation</glossterm> transmitted
from a <glossterm linkend="glossary-backend">backend process</glossterm>
to a <glossterm linkend="glossary-client">client</glossterm> upon the
- completion of an <acronym>SQL</acronym> command, usually a
+ completion of a <acronym>SQL</acronym> command, usually a
<command>SELECT</command> but it can be an
<command>INSERT</command>, <command>UPDATE</command>, or
<command>DELETE</command> command if the <literal>RETURNING</literal>
@@ -1867,8 +1866,8 @@
<glossterm>Trigger</glossterm>
<glossdef>
<para>
- A <glossterm linkend="glossary-function">function</glossterm> which can
- be defined to execute whenever a certain operation (<command>INSERT</command>,
+ A <glossterm linkend="glossary-function">function</glossterm> that
+ executes whenever a certain operation (<command>INSERT</command>,
<command>UPDATE</command>, <command>DELETE</command>,
<command>TRUNCATE</command>) is applied to a
<glossterm linkend="glossary-relation">relation</glossterm>.
@@ -1942,7 +1941,7 @@
<glossterm>Update</glossterm>
<glossdef>
<para>
- An <acronym>SQL</acronym> command used to modify
+ A <acronym>SQL</acronym> command used to modify
<glossterm linkend="glossary-tuple">rows</glossterm>
that may already exist in a specified <glossterm linkend="glossary-table">table</glossterm>.
It cannot create or remove rows.
On Sat, 14 Oct 2023, 5:20 pm Andrew Atkinson, <andyatkinson@gmail.com>
wrote:
- Many examples of “an SQL”. I changed those to “a SQL...”. For
example I changed “An SQL command which” to “A SQL command that”. I'm not
an English major so maybe I'm missing something here.It would depend on how you pronounce SQL. For those that say es-que-el,
"An" is the correct article. If you say sequel then it's "a". We've
standardised our docs to use "an SQL", so any changes we make would be the
opposite way.
David
Show quoted text
On 2023-10-14 06:16 +0200, Andrew Atkinson write:
- When describing options for a command, changed to “option of” instead
of “option to”
I think "option to" is not wrong (maybe less common). I've seen this
in other texts and took it as "the X option [that applies] to Y".
- “system- or user-supplied”, removed the dash after system. Or I’d
suggest system-supplied or user-supplied, to hyphenate both.
That's a suspended hyphen and is common usage.
- Changed “volume of records has been written” to “volume of records
were written”
"Has been" means that something happened just now. This is perfectly
fine when talking about checkpoints IMO.
- Many examples of “an SQL”. I changed those to “a SQL...”. For example
I changed “An SQL command which” to “A SQL command that”. I'm not an
English major so maybe I'm missing something here.
Depends on how you pronounce SQL (ess-cue-el or sequel). "An SQL"
is more common in the docs whereas "a SQL" is more common in code
comments.
--
Erik
It would depend on how you pronounce SQL.
Got it, makes sense.
We've standardised our docs
Makes sense. This "a vs. an" could be a nice thing to add to a
"conventions" or "doc standards" if it's not there already. I checked
https://www.postgresql.org/docs/current/notation.html and
https://wiki.postgresql.org/wiki/Main_Page Is there a docs page that has
that information? If there's an existing page where it could be added, I'd
be happy to add it.
That's a suspended hyphen and is common usage.
Sounds good, reset it back.
"Has been" means that something happened just now.
Sounds good, reset it back. "has been" is also used in the materialized
term, "has been pre-computed".
I think "option to" is not wrong
Ok, don't feel strongly. Reset it back.
That's a suspended hyphen and is common usage.
Ok, reset it back.
Curious what people think about this. I thought the first phrase was
possibly redundant.
- On operating systems with a <literal>root</literal> user,
- said user is not allowed to be the cluster owner.
+ The user <literal>root</literal> is not allowed to be the cluster
owner.
I reviewed the definitions of assure vs. ensure, and I think ensure fits
better, but I also noticed elsewhere the word “assurances” is used, as in
an assurance about durability.
- makes it visible to other transactions and assures its
+ makes it visible to other transactions and ensures its
Re: that/which, I put this into ChatGPT :) and apparently there is a
“relative clause” vs. non-relative clause. My understanding was a
non-relative clause would typically be inside commas, and could be removed
without changing the meaning.
Since this section is talking about Bloat, and the space in data pages with
non-current row versions is part of bloat, I don’t think it could be
removed. So I think it’s a “relative clause” and “that” makes more sense.
This is another situation though where if there’s English majors or
documentation experts, I’m happy to learn why I’m wrong. :)
- Space in data pages which does not contain current row versions,
+ Space in data pages that does not contain current row versions,
Smaller patch attached!
Thanks.
On Sat, Oct 14, 2023 at 12:55 AM Erik Wienhold <ewie@ewie.name> wrote:
Show quoted text
On 2023-10-14 06:16 +0200, Andrew Atkinson write:
- When describing options for a command, changed to “option of”
instead
of “option to”
I think "option to" is not wrong (maybe less common). I've seen this
in other texts and took it as "the X option [that applies] to Y".- “system- or user-supplied”, removed the dash after system. Or I’d
suggest system-supplied or user-supplied, to hyphenate both.That's a suspended hyphen and is common usage.
- Changed “volume of records has been written” to “volume of records
were written”"Has been" means that something happened just now. This is perfectly
fine when talking about checkpoints IMO.- Many examples of “an SQL”. I changed those to “a SQL...”. For
example
I changed “An SQL command which” to “A SQL command that”. I'm not an
English major so maybe I'm missing something here.Depends on how you pronounce SQL (ess-cue-el or sequel). "An SQL"
is more common in the docs whereas "a SQL" is more common in code
comments.--
Erik
Attachments:
glossary_terms_grammar_edits_v2.patchapplication/octet-stream; name=glossary_terms_grammar_edits_v2.patchDownload
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index fe8def41d0..994425a056 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -52,7 +52,7 @@
<glossterm linkend="glossary-table">tables</glossterm>
and other <glossterm linkend="glossary-relation">relations</glossterm>
to help the <glossterm linkend="glossary-planner">query planner</glossterm>
- to make decisions about how to execute
+ make decisions about how to execute
<glossterm linkend="glossary-query">queries</glossterm>.
</para>
<para>
@@ -227,7 +227,7 @@
<glossterm>Bloat</glossterm>
<glossdef>
<para>
- Space in data pages which does not contain current row versions,
+ Space in data pages that does not contain current row versions,
such as unused (free) space or outdated row versions.
</para>
</glossdef>
@@ -256,9 +256,9 @@
<glossterm>Buffer Access Strategy</glossterm>
<glossdef>
<para>
- Some operations will access a large number of
+ Some operations access a large number of
<glossterm linkend="glossary-data-page">pages</glossterm>. A
- <firstterm>Buffer Access Strategy</firstterm> helps to prevent these
+ <firstterm>Buffer Access Strategy</firstterm> helps prevent these
operations from evicting too many pages from
<glossterm linkend="glossary-shared-memory">shared buffers</glossterm>.
</para>
@@ -320,7 +320,7 @@
<para>
A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
defined on a <glossterm linkend="glossary-relation">relation</glossterm>
- which restricts the values allowed in one or more
+ that restricts the values allowed in one or more
<glossterm linkend="glossary-attribute">attributes</glossterm>. The
check constraint can make reference to any attribute of the same row in
the relation, but cannot reference other rows of the same relation or
@@ -396,12 +396,11 @@
The operating system user that owns the
<glossterm linkend="glossary-data-directory">data directory</glossterm>
and under which the <literal>postgres</literal> process is run.
- It is required that this user exist prior to creating a new
+ This user is required to exist prior to creating a new
<glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
</para>
<para>
- On operating systems with a <literal>root</literal> user,
- said user is not allowed to be the cluster owner.
+ The user <literal>root</literal> is not allowed to be the cluster owner.
</para>
</glossdef>
</glossentry>
@@ -424,7 +423,7 @@
The act of finalizing a
<glossterm linkend="glossary-transaction">transaction</glossterm> within
the <glossterm linkend="glossary-database">database</glossterm>, which
- makes it visible to other transactions and assures its
+ makes it visible to other transactions and ensures its
<glossterm linkend="glossary-durability">durability</glossterm>.
</para>
<para>
@@ -468,13 +467,13 @@
<glossterm>Consistency</glossterm>
<glossdef>
<para>
- The property that the data in the
+ The property that data in the
<glossterm linkend="glossary-database">database</glossterm>
- is always in compliance with
+ is always compliant with
<glossterm linkend="glossary-constraint">integrity constraints</glossterm>.
- Transactions may be allowed to violate some of the constraints
- transiently before it commits, but if such violations are not resolved
- by the time it commits, such a transaction is automatically
+ Transactions may allow constraints to be violated
+ temporarily, but violations must be resolved before the transaction
+ commits or it will be automatically
<glossterm linkend="glossary-rollback">rolled back</glossterm>.
This is one of the <acronym>ACID</acronym> properties.
</para>
@@ -549,7 +548,7 @@
</para>
<para>
See also <glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>,
- the operating-system owner of a cluster,
+ the operating system owner of a cluster,
and <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>,
the <productname>PostgreSQL</productname> owner of a cluster.
</para>
@@ -629,7 +628,7 @@
<glossterm>Delete</glossterm>
<glossdef>
<para>
- An <acronym>SQL</acronym> command which removes
+ An <acronym>SQL</acronym> command that removes
<glossterm linkend="glossary-tuple">rows</glossterm> from a given
<glossterm linkend="glossary-table">table</glossterm>
or <glossterm linkend="glossary-relation">relation</glossterm>.
@@ -692,7 +691,7 @@
<glossterm>File segment</glossterm>
<glossdef>
<para>
- A physical file which stores data for a given
+ A physical file that stores data for a given
<glossterm linkend="glossary-relation">relation</glossterm>.
File segments are limited in size by a configuration value
(typically 1 gigabyte),
@@ -785,7 +784,7 @@
<para>
Each of the separate segmented file sets in which a relation is stored.
The <firstterm>main fork</firstterm> is where the actual data resides.
- There also exist two secondary forks for metadata:
+ There are two secondary forks for metadata:
the <glossterm linkend="glossary-fsm">free space map</glossterm>
and the <glossterm linkend="glossary-vm">visibility map</glossterm>.
<glossterm linkend="glossary-unlogged">Unlogged relations</glossterm>
@@ -1867,8 +1866,8 @@
<glossterm>Trigger</glossterm>
<glossdef>
<para>
- A <glossterm linkend="glossary-function">function</glossterm> which can
- be defined to execute whenever a certain operation (<command>INSERT</command>,
+ A <glossterm linkend="glossary-function">function</glossterm> that
+ executes whenever a certain operation (<command>INSERT</command>,
<command>UPDATE</command>, <command>DELETE</command>,
<command>TRUNCATE</command>) is applied to a
<glossterm linkend="glossary-relation">relation</glossterm>.