[Doc] Glossary Term Definitions Edits

From: Andrew Atkinson <andyatkinson(at)gmail(dot)com>
To: pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: [Doc] Glossary Term Definitions Edits
Date: 2023-10-14 04:16:56
Message-ID: CAG6XLEmG8kASYk2AaM6rq0KaDi86eibhz8D4cMpNsy0VxyueRQ@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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

[^1]: https://www.postgresql.org/docs/current/glossary.html

Attachment Content-Type Size
glossary_terms_grammar_edits_v1.patch application/octet-stream 9.1 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Hayato Kuroda (Fujitsu) 2023-10-14 05:15:27 RE: [PoC] pg_upgrade: allow to upgrade publisher node
Previous Message Amit Kapila 2023-10-14 04:13:35 Re: SLRU optimization - configurable buffer pool and partitioning the SLRU lock