Thread: Enhance create subscription reference manual
Currently the manual explains create subscription's "failover"
parameter as follows:
<para>
Since no connection is made when this option is
<literal>false</literal>, no tables are subscribed. To initiate
replication, you must manually create the replication slot, enable
the failover if required, enable the subscription, and refresh the
subscription. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
While translating it into Japanese, we were little confused what "the
failover" actually means because we thought it might refer to the
failover operation or the failover parameter in the command. After a
discussion in the translation team, we concluded that it must refer to
the failover parameter. If we were correct, it would be nice to add
<literal> tag to "failover" to make it clear that it refers to a
failover parameter. Attached is the patch to do that.
Best reagards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 740b7d9421..4eed0f3d0f 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
Since no connection is made when this option is
<literal>false</literal>, no tables are subscribed. To initiate
replication, you must manually create the replication slot, enable
- the failover if required, enable the subscription, and refresh the
+ the <literal>failover</literal> if required, enable the subscription, and refresh the
subscription. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
On Wed, 02 Oct 2024 12:15:50 +0900 (JST) Tatsuo Ishii <ishii@postgresql.org> wrote: > Currently the manual explains create subscription's "failover" > parameter as follows: > > <para> > Since no connection is made when this option is > <literal>false</literal>, no tables are subscribed. To initiate > replication, you must manually create the replication slot, enable > the failover if required, enable the subscription, and refresh the > subscription. See > <xref linkend="logical-replication-subscription-examples-deferred-slot"/> > for examples. > </para> > > While translating it into Japanese, we were little confused what "the > failover" actually means because we thought it might refer to the > failover operation or the failover parameter in the command. After a > discussion in the translation team, we concluded that it must refer to > the failover parameter. If we were correct, it would be nice to add > <literal> tag to "failover" to make it clear that it refers to a > failover parameter. Attached is the patch to do that. I agreed with adding <literal> tag to "failover" since it is done in the description on "slot_name" parameter. How about also rewrite it to "enable the failover option" rather than simply "enable the failover" to clarify that the parameter is refereed to. We could also use "enable the failover parameter". I think both make sense, but it seems that "failover option" is preferred in the slot_name description. Regards, Yugo Nagata -- Yugo Nagata <nagata@sraoss.co.jp>
>> Currently the manual explains create subscription's "failover"
>> parameter as follows:
>>
>> <para>
>> Since no connection is made when this option is
>> <literal>false</literal>, no tables are subscribed. To initiate
>> replication, you must manually create the replication slot, enable
>> the failover if required, enable the subscription, and refresh the
>> subscription. See
>> <xref linkend="logical-replication-subscription-examples-deferred-slot"/>
>> for examples.
>> </para>
>>
>> While translating it into Japanese, we were little confused what "the
>> failover" actually means because we thought it might refer to the
>> failover operation or the failover parameter in the command. After a
>> discussion in the translation team, we concluded that it must refer to
>> the failover parameter. If we were correct, it would be nice to add
>> <literal> tag to "failover" to make it clear that it refers to a
>> failover parameter. Attached is the patch to do that.
>
> I agreed with adding <literal> tag to "failover" since it is done in the
> description on "slot_name" parameter.
>
> How about also rewrite it to "enable the failover option" rather than simply
> "enable the failover" to clarify that the parameter is refereed to.
>
> We could also use "enable the failover parameter". I think both make sense, but
> it seems that "failover option" is preferred in the slot_name description.
But a few lines above we have:
<para>
This clause specifies optional parameters for a subscription.
</para>
<para>
The following parameters control what happens during subscription creation:
So it seems "paramter" is more consistent than "option" here.
Best reagards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp
On Wed, 02 Oct 2024 14:52:58 +0900 (JST) Tatsuo Ishii <ishii@postgresql.org> wrote: > >> Currently the manual explains create subscription's "failover" > >> parameter as follows: > >> > >> <para> > >> Since no connection is made when this option is > >> <literal>false</literal>, no tables are subscribed. To initiate > >> replication, you must manually create the replication slot, enable > >> the failover if required, enable the subscription, and refresh the > >> subscription. See > >> <xref linkend="logical-replication-subscription-examples-deferred-slot"/> > >> for examples. > >> </para> > >> > >> While translating it into Japanese, we were little confused what "the > >> failover" actually means because we thought it might refer to the > >> failover operation or the failover parameter in the command. After a > >> discussion in the translation team, we concluded that it must refer to > >> the failover parameter. If we were correct, it would be nice to add > >> <literal> tag to "failover" to make it clear that it refers to a > >> failover parameter. Attached is the patch to do that. > > > > I agreed with adding <literal> tag to "failover" since it is done in the > > description on "slot_name" parameter. > > > > How about also rewrite it to "enable the failover option" rather than simply > > "enable the failover" to clarify that the parameter is refereed to. > > > > We could also use "enable the failover parameter". I think both make sense, but > > it seems that "failover option" is preferred in the slot_name description. > > But a few lines above we have: > > <para> > This clause specifies optional parameters for a subscription. > </para> > > <para> > The following parameters control what happens during subscription creation: > > So it seems "paramter" is more consistent than "option" here. For consistency, using "parameter" seems better. If we consider this, should we rewrite other places using "option" to use "parameter"? For example, I can find uses of "option" in the "connect", "slot_name", and "binary" descriptions in the CREATE SUBSCRIPTION document. Also, the "public" parameter in CREATE PUBLICATION doc, "vacuum_index_cleanup" and "vacuum_truncate" storage parameters in CREATE TABLE doc might be also targets to be rewritten. I am not sure if this covers all, though. Regards, Yugo Nagata > > Best reagards, > -- > Tatsuo Ishii > SRA OSS K.K. > English: http://www.sraoss.co.jp/index_en/ > Japanese:http://www.sraoss.co.jp -- Yugo NAGATA <nagata@sraoss.co.jp>
>> > I agreed with adding <literal> tag to "failover" since it is done in the >> > description on "slot_name" parameter. >> > >> > How about also rewrite it to "enable the failover option" rather than simply >> > "enable the failover" to clarify that the parameter is refereed to. >> > >> > We could also use "enable the failover parameter". I think both make sense, but >> > it seems that "failover option" is preferred in the slot_name description. >> >> But a few lines above we have: >> >> <para> >> This clause specifies optional parameters for a subscription. >> </para> >> >> <para> >> The following parameters control what happens during subscription creation: >> >> So it seems "paramter" is more consistent than "option" here. > > For consistency, using "parameter" seems better. > > If we consider this, should we rewrite other places using "option" to use "parameter"? > For example, I can find uses of "option" in the "connect", "slot_name", and "binary" > descriptions in the CREATE SUBSCRIPTION document. Not sure. In some places I think "option" is an abbreviation of "optional parameter". So using "option" there does not seem to be inconsistent or incorrect. See following example in create subscription manual: This clause specifies optional parameters for a subscription. : : connect (boolean) : : Since no connection is made when this option is false, no tables are subscribed. > Also, the "public" parameter in CREATE PUBLICATION doc, You mean "publish"? > "vacuum_index_cleanup" and > "vacuum_truncate" storage parameters in CREATE TABLE doc might be also targets to be > rewritten. I am not sure if this covers all, though. I would like to hear opinions from native English speakers. Best reagards, -- Tatsuo Ishii SRA OSS K.K. English: http://www.sraoss.co.jp/index_en/ Japanese:http://www.sraoss.co.jp
On Wed, 02 Oct 2024 16:25:35 +0900 (JST) Tatsuo Ishii <ishii@postgresql.org> wrote: > > Also, the "public" parameter in CREATE PUBLICATION doc, > > You mean "publish"? Yes. Sorry for the typo. > > > "vacuum_index_cleanup" and > > "vacuum_truncate" storage parameters in CREATE TABLE doc might be also targets to be > > rewritten. I am not sure if this covers all, though. > > I would like to hear opinions from native English speakers. +1 Regards, Yugo Nagata -- Yugo NAGATA <nagata@sraoss.co.jp>
On Wed, Oct 2, 2024 at 6:17 PM Yugo NAGATA <nagata@sraoss.co.jp> wrote: > > > > > I would like to hear opinions from native English speakers. > > +1 > Hi, You can look up the definitions of the words "option" versus "parameter". They do have different meanings, like: - An "option" is a modifier that affects how a command behaves. It is usually optional (hence the name?) so it typically has a default value. - A "parameter" is input required for the command to work. A parameter possible values can be freely user-specified, whereas option values are fixed (boolean, enum etc). Chat-GPT can explain the difference better than me: ------ is postgres subscription failover a parameter or an option? ChatGPT said: In PostgreSQL, subscription failover would typically be considered an option rather than a parameter. Here’s why: Option: It modifies the behavior of the subscription. Enabling or configuring failover adjusts how the subscription behaves when a failover occurs in a high-availability setup. This feature is optional and alters the default behavior of a subscription. Parameter: In PostgreSQL, parameters usually refer to specific inputs or configurations required for a function, command, or feature to work. For instance, specifying a connection string, user, or host would be considered parameters. ------ ~~~ Unfortunately, it gets a bit muddled in the Postgres docs, because the CREATE SUBSCRIPTION docs page refers to all these as "subscription parameters" -- "WITH ( subscription_parameter [= value] [, ... ] ) " regardless of whether they are options or parameters. e.g. IMO the "slot_name" really is a parameter, because it can take a user-specified value. e.g. IMO "failover" really is an option, even though this page refers to it in some places as a parameter. You can see how confused the current docs are because "failover" is called by both terms even within the same paragraph! [1] - "failover parameter specified in the subscription" - "subscription's failover option" ~~~ What to do? Ideally, the docs should have consistent and correct usage of the words "option" and "parameter" everywhere. But in practice, I guess most people probably are reading those words as synonyms anyway so using them wrongly isn't impacting the understanding badly. Anyway, since you are already fixing something for "failover", then it would be good to fix the correct term everywhere for that one (e.g. call it an "option"), or at least call it an option everywhere on the CREATE SUBSCRIPTION page. ====== [1] https://www.postgresql.org/docs/devel/sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-SLOT-NAME Kind Regards, Peter Smith. Fujitsu Australia
On Wednesday, October 2, 2024, Peter Smith <smithpb2250@gmail.com> wrote:
You can see how confused the current docs are because "failover" is
called by both terms even within the same paragraph! [1]
- "failover parameter specified in the subscription"
- "subscription's failover option"
~~~
What to do? Ideally, the docs should have consistent and correct usage
of the words "option" and "parameter" everywhere. But in practice, I
guess most people probably are reading those words as synonyms anyway
so using them wrongly isn't impacting the understanding badly.
Anyway, since you are already fixing something for "failover", then it
would be good to fix the correct term everywhere for that one (e.g.
call it an "option"), or at least call it an option everywhere on the
CREATE SUBSCRIPTION page.
The distinction between required and optional is not relevant for our documentation. The descriptions tell you that.
If you wish to know whether to call something an option or a parameter look at the syntax placeholder. In this case, it is named: “subscription_parameter” so parameter is the correct term to choose on this page, for these things. For explain you call them options because the placeholder is “option”.
David J.
On Wednesday, October 2, 2024, Peter Smith <smithpb2250@gmail.com> wrote:
`
- "subscription's failover option"
Feels like this one refers to the stored catalog value, which is neither a parameter nor an option but an attribute. Though in some cases we are using “property” as well. An in this usage option sorta works too but parameter really doesn’t - a parameter refers to the command syntax parts, not the resultant table attributes.
David J.
On Thu, Oct 3, 2024 at 10:01 AM David G. Johnston <david.g.johnston@gmail.com> wrote: > > On Wednesday, October 2, 2024, Peter Smith <smithpb2250@gmail.com> wrote: >> >> >> >> You can see how confused the current docs are because "failover" is >> called by both terms even within the same paragraph! [1] >> - "failover parameter specified in the subscription" >> - "subscription's failover option" >> >> ~~~ >> >> What to do? Ideally, the docs should have consistent and correct usage >> of the words "option" and "parameter" everywhere. But in practice, I >> guess most people probably are reading those words as synonyms anyway >> so using them wrongly isn't impacting the understanding badly. >> >> Anyway, since you are already fixing something for "failover", then it >> would be good to fix the correct term everywhere for that one (e.g. >> call it an "option"), or at least call it an option everywhere on the >> CREATE SUBSCRIPTION page. > > > The distinction between required and optional is not relevant for our documentation. The descriptions tell you that. > > If you wish to know whether to call something an option or a parameter look at the syntax placeholder. In this case, itis named: “subscription_parameter” so parameter is the correct term to choose on this page, for these things. For explainyou call them options because the placeholder is “option”. > OK. If that is the "rule" that the documentation uses then it is fine. The same term can be consistently used everywhere the 'thing' is referred to. ~ IIUC you were referring to the EXPLAIN docs page [1] as an "option" example: ------ EXPLAIN [ ( option [, ...] ) ] statement where option can be one of: ------ but that page also seems to have a muddle of different terms used to describe the same "option". ====== [1] https://www.postgresql.org/docs/devel/sql-explain.html Kind Regards, Peter Smith. Fujitsu Australia
On Wed, 2 Oct 2024 17:09:42 -0700 "David G. Johnston" <david.g.johnston@gmail.com> wrote: > On Wednesday, October 2, 2024, Peter Smith <smithpb2250@gmail.com> wrote: > > > ` > > - "subscription's failover option" > > > > Feels like this one refers to the stored catalog value, which is neither a > parameter nor an option but an attribute. Though in some cases we are > using “property” as well. An in this usage option sorta works too but > parameter really doesn’t - a parameter refers to the command syntax parts, > not the resultant table attributes. Thank you for your explanation. If I understand correctly, whether something is an option of a parameter should be determined by the syntax placeholder, so "failover" is a parameter in this case (it is an "optional" parameter, though). However, when we refer to the stored catalog value, we should call it an option or a property and calling it parameter is not suitable. If so, I feel that "the failover" in the following statement means the catalog value (or the failover feature itself), so we should not rewrite this to "the failover parameter". > To initiate replication, you must manually create the replication slot, > enable the failover if required, enable the subscription, and refresh the > subscription. Instead, should we use "failover option"? Or, if it would mean to the failover feature rather than the parameter, is it not proper to add <literal> tag to this "failover"? Regards, Yugo Nagata -- Yugo Nagata <nagata@sraoss.co.jp>
> parameter in this case (it is an "optional" parameter, though). However, > when we refer to the stored catalog value, we should call it an option or > a property and calling it parameter is not suitable. Not sure. The stored catalog value of a subscription can be changed ALTER SUBSCRIPTION. In the ALTER SUBSCRIPTION manual, the placeholders for these properties are "parameter". So I think we should use "parameter" in this case at least for the stored catalog values of subscriptions. > If so, I feel that "the failover" in the following statement means > the catalog value (or the failover feature itself), so we should not > rewrite this to "the failover parameter". My conclusion is we should rewrite it as "the failover parameter" for the reason above. >> To initiate replication, you must manually create the replication slot, >> enable the failover if required, enable the subscription, and refresh the >> subscription. > > Instead, should we use "failover option"? Yes. because "enable the failover" actually means an operation using ALTER SUBSCRIPTION IMO. > Or, if it would mean to the failover > feature rather than the parameter, is it not proper to add <literal> tag to this > "failover"? I don't think so. Best reagards, -- Tatsuo Ishii SRA OSS K.K. English: http://www.sraoss.co.jp/index_en/ Japanese:http://www.sraoss.co.jp
On Thu, 03 Oct 2024 12:23:34 +0900 (JST) Tatsuo Ishii <ishii@postgresql.org> wrote: > > parameter in this case (it is an "optional" parameter, though). However, > > when we refer to the stored catalog value, we should call it an option or > > a property and calling it parameter is not suitable. > > Not sure. The stored catalog value of a subscription can be changed > ALTER SUBSCRIPTION. In the ALTER SUBSCRIPTION manual, the placeholders > for these properties are "parameter". So I think we should use > "parameter" in this case at least for the stored catalog values of > subscriptions. > > > If so, I feel that "the failover" in the following statement means > > the catalog value (or the failover feature itself), so we should not > > rewrite this to "the failover parameter". > > My conclusion is we should rewrite it as "the failover parameter" for > the reason above. > > >> To initiate replication, you must manually create the replication slot, > >> enable the failover if required, enable the subscription, and refresh the > >> subscription. > > > > Instead, should we use "failover option"? > > Yes. because "enable the failover" actually means an operation using > ALTER SUBSCRIPTION IMO. After reading the above, I think you would prefer "failover parameter" to "failover option". However, after all, I'm fine with either any way. If we use "the failover parameter", I would read "enable the failover parameter" as "enable the failover parameter on executing ALTER SUBSCRIPTION command". Otherwise in the "failover option" case, I would read "enable the failover option" as "enable the subscription's failover option by executing ALTER SUBSCRIPTION command". Regards, Yugo Nagata > > > Or, if it would mean to the failover > > feature rather than the parameter, is it not proper to add <literal> tag to this > > "failover"? > > I don't think so. > > Best reagards, > -- > Tatsuo Ishii > SRA OSS K.K. > English: http://www.sraoss.co.jp/index_en/ > Japanese:http://www.sraoss.co.jp -- Yugo NAGATA <nagata@sraoss.co.jp>
On Thu, Oct 3, 2024 at 8:53 AM Tatsuo Ishii <ishii@postgresql.org> wrote: > > > parameter in this case (it is an "optional" parameter, though). However, > > when we refer to the stored catalog value, we should call it an option or > > a property and calling it parameter is not suitable. > > Not sure. The stored catalog value of a subscription can be changed > ALTER SUBSCRIPTION. In the ALTER SUBSCRIPTION manual, the placeholders > for these properties are "parameter". So I think we should use > "parameter" in this case at least for the stored catalog values of > subscriptions. > > > If so, I feel that "the failover" in the following statement means > > the catalog value (or the failover feature itself), so we should not > > rewrite this to "the failover parameter". > > My conclusion is we should rewrite it as "the failover parameter" for > the reason above. > > >> To initiate replication, you must manually create the replication slot, > >> enable the failover if required, enable the subscription, and refresh the > >> subscription. > > > > Instead, should we use "failover option"? > Sounds reasonable to me. Would you like to propose the patch with the changes you have in mind? -- With Regards, Amit Kapila.
Hi Amit, > On Thu, Oct 3, 2024 at 8:53 AM Tatsuo Ishii <ishii@postgresql.org> wrote: >> >> > parameter in this case (it is an "optional" parameter, though). However, >> > when we refer to the stored catalog value, we should call it an option or >> > a property and calling it parameter is not suitable. >> >> Not sure. The stored catalog value of a subscription can be changed >> ALTER SUBSCRIPTION. In the ALTER SUBSCRIPTION manual, the placeholders >> for these properties are "parameter". So I think we should use >> "parameter" in this case at least for the stored catalog values of >> subscriptions. >> >> > If so, I feel that "the failover" in the following statement means >> > the catalog value (or the failover feature itself), so we should not >> > rewrite this to "the failover parameter". >> >> My conclusion is we should rewrite it as "the failover parameter" for >> the reason above. >> >> >> To initiate replication, you must manually create the replication slot, >> >> enable the failover if required, enable the subscription, and refresh the >> >> subscription. >> > >> > Instead, should we use "failover option"? >> > > Sounds reasonable to me. Would you like to propose the patch with the > changes you have in mind? Thanks for the comment. I would like to propose the patch. But I am not sure which you feel resonable with "the failover parameter" or "the failover option"? Best reagards, -- Tatsuo Ishii SRA OSS K.K. English: http://www.sraoss.co.jp/index_en/ Japanese:http://www.sraoss.co.jp
On Fri, Oct 18, 2024 at 9:46 AM Tatsuo Ishii <ishii@postgresql.org> wrote: > > Hi Amit, > > > On Thu, Oct 3, 2024 at 8:53 AM Tatsuo Ishii <ishii@postgresql.org> wrote: > >> > >> > parameter in this case (it is an "optional" parameter, though). However, > >> > when we refer to the stored catalog value, we should call it an option or > >> > a property and calling it parameter is not suitable. > >> > >> Not sure. The stored catalog value of a subscription can be changed > >> ALTER SUBSCRIPTION. In the ALTER SUBSCRIPTION manual, the placeholders > >> for these properties are "parameter". So I think we should use > >> "parameter" in this case at least for the stored catalog values of > >> subscriptions. > >> > >> > If so, I feel that "the failover" in the following statement means > >> > the catalog value (or the failover feature itself), so we should not > >> > rewrite this to "the failover parameter". > >> > >> My conclusion is we should rewrite it as "the failover parameter" for > >> the reason above. > >> > >> >> To initiate replication, you must manually create the replication slot, > >> >> enable the failover if required, enable the subscription, and refresh the > >> >> subscription. > >> > > >> > Instead, should we use "failover option"? > >> > > > > Sounds reasonable to me. Would you like to propose the patch with the > > changes you have in mind? > > Thanks for the comment. I would like to propose the patch. But I am > not sure which you feel resonable with "the failover parameter" or > "the failover option"? > "the failover option". -- With Regards, Amit Kapila.