DOCS: Avoid using abbreviation "aka"
While checking some recently pushed changes [1]https://github.com/postgres/postgres/commit/ddd5f4f54a026db6a6692876d0d44aef902ab686#diff-29c2d2e0480177b04f9c3d82c1454f8c00a11b8e761a9c9f5f4f6d61e6f19252 I noticed
documentation [2]https://www.postgresql.org/docs/devel/logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION that includes the abbreviation "aka".
IMO it is preferable to avoid informal abbreviations like "aka" in the
documents, because not everyone will understand the meaning.
Furthermore, I think this is reinforced by the fact this was the
*only* example of "aka" that I could find in all of the .sgml. Indeed,
assuming that "aka" is short for "also known as" then the sentence
still doesn't seem correct even after those words are substituted.
HEAD
For the synchronization to work, it is mandatory to have a physical
replication slot between the primary and the standby aka
primary_slot_name should be configured on the standby, and
hot_standby_feedback must be enabled on the standby.
SUGGESTION
For the synchronization to work, it is mandatory to have a physical
replication slot between the primary and the standby (i.e.,
primary_slot_name should be configured on the standby), and
hot_standby_feedback must be enabled on the standby.
~
I found that the "aka" was introduced in v86-0001 [3][1] /messages/by-id/OS0PR01MB5716E581B4227DDEB4DE6C30944F2@OS0PR01MB5716.jpnprd01.prod.outlook.com. So my
replacement text above restores to something similar to how it was in
v85-0001.
PSA a patch for the same.
----------
[1]: https://github.com/postgres/postgres/commit/ddd5f4f54a026db6a6692876d0d44aef902ab686#diff-29c2d2e0480177b04f9c3d82c1454f8c00a11b8e761a9c9f5f4f6d61e6f19252
[2]: https://www.postgresql.org/docs/devel/logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION
[3]: [1] /messages/by-id/OS0PR01MB5716E581B4227DDEB4DE6C30944F2@OS0PR01MB5716.jpnprd01.prod.outlook.com
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-Replace-aka-in-docs.patchapplication/octet-stream; name=v1-0001-Replace-aka-in-docs.patchDownload
From 975b7fbb47ec32f20f30b2956065f7d25a6d5948 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Thu, 29 Feb 2024 16:42:14 +1100
Subject: [PATCH v1] Replace aka in docs
---
doc/src/sgml/logicaldecoding.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 930c0fa..8f13780 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -377,9 +377,9 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
<varname>sync_replication_slots</varname></link>
on the standby, the failover slots can be synchronized periodically in
the slotsync worker. For the synchronization to work, it is mandatory to
- have a physical replication slot between the primary and the standby aka
+ have a physical replication slot between the primary and the standby (i.e.,
<link linkend="guc-primary-slot-name"><varname>primary_slot_name</varname></link>
- should be configured on the standby, and
+ should be configured on the standby), and
<link linkend="guc-hot-standby-feedback"><varname>hot_standby_feedback</varname></link>
must be enabled on the standby. It is also necessary to specify a valid
<literal>dbname</literal> in the
--
1.8.3.1
On Thu, Feb 29, 2024 at 04:51:50PM +1100, Peter Smith wrote:
HEAD
For the synchronization to work, it is mandatory to have a physical
replication slot between the primary and the standby aka
primary_slot_name should be configured on the standby, and
hot_standby_feedback must be enabled on the standby.SUGGESTION
For the synchronization to work, it is mandatory to have a physical
replication slot between the primary and the standby (i.e.,
primary_slot_name should be configured on the standby), and
hot_standby_feedback must be enabled on the standby.
I agree that this is not a good practice in user-visible docs, and
that your suggested is more pleasant to read.
--
Michael
On Thu, Feb 29, 2024 at 12:02 PM Michael Paquier <michael@paquier.xyz> wrote:
On Thu, Feb 29, 2024 at 04:51:50PM +1100, Peter Smith wrote:
HEAD
For the synchronization to work, it is mandatory to have a physical
replication slot between the primary and the standby aka
primary_slot_name should be configured on the standby, and
hot_standby_feedback must be enabled on the standby.SUGGESTION
For the synchronization to work, it is mandatory to have a physical
replication slot between the primary and the standby (i.e.,
primary_slot_name should be configured on the standby), and
hot_standby_feedback must be enabled on the standby.I agree that this is not a good practice in user-visible docs, and
that your suggested is more pleasant to read.
+1. LGTM as well.
--
With Regards,
Amit Kapila.
On Thu, 2024-02-29 at 16:51 +1100, Peter Smith wrote:
While checking some recently pushed changes [1] I noticed
documentation [2] that includes the abbreviation "aka".IMO it is preferable to avoid informal abbreviations like "aka" in the
documents, because not everyone will understand the meaning.
Furthermore, I think this is reinforced by the fact this was the
*only* example of "aka" that I could find in all of the .sgml. Indeed,
assuming that "aka" is short for "also known as" then the sentence
still doesn't seem correct even after those words are substituted.
+1
Yours,
Laurenz Albe
On Thu, Feb 29, 2024 at 02:42:08PM +0530, Amit Kapila wrote:
+1. LGTM as well.
This has been introduced by ddd5f4f54a02, so if you wish to fix it
yourself, please feel free. If you'd prefer that I take care of it,
I'm OK to do so as well.
--
Michael
On Fri, Mar 1, 2024 at 4:25 AM Michael Paquier <michael@paquier.xyz> wrote:
On Thu, Feb 29, 2024 at 02:42:08PM +0530, Amit Kapila wrote:
+1. LGTM as well.
This has been introduced by ddd5f4f54a02, so if you wish to fix it
yourself, please feel free. If you'd prefer that I take care of it,
I'm OK to do so as well.
I wanted to wait for two or three days to see if any other fixes in
docs, typos, or cosmetic stuff are reported in this functionality then
I can combine and push them. However, there is no harm in pushing them
separately, so if you want to go ahead please feel free to do so.
--
With Regards,
Amit Kapila.
On Fri, Mar 01, 2024 at 11:08:21AM +0530, Amit Kapila wrote:
I wanted to wait for two or three days to see if any other fixes in
docs, typos, or cosmetic stuff are reported in this functionality then
I can combine and push them. However, there is no harm in pushing them
separately, so if you want to go ahead please feel free to do so.
Nah, feel free to :)
--
Michael
On Fri, Mar 1, 2024 at 11:29 AM Michael Paquier <michael@paquier.xyz> wrote:
On Fri, Mar 01, 2024 at 11:08:21AM +0530, Amit Kapila wrote:
I wanted to wait for two or three days to see if any other fixes in
docs, typos, or cosmetic stuff are reported in this functionality then
I can combine and push them. However, there is no harm in pushing them
separately, so if you want to go ahead please feel free to do so.Nah, feel free to :)
Pushed.
--
With Regards,
Amit Kapila.