Обсуждение: DOCS: Avoid using abbreviation "aka"
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. 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]. 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] https://www.postgresql.org/message-id/OS0PR01MB5716E581B4227DDEB4DE6C30944F2%40OS0PR01MB5716.jpnprd01.prod.outlook.com Kind Regards, Peter Smith. Fujitsu Australia
Вложения
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.
On Thu, Mar 07, 2024 at 10:02:36AM +0530, Amit Kapila wrote: > Pushed. Thanks. -- Michael