Enhance create subscription reference manual

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]https://www.postgresql.org/docs/devel/sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-SLOT-NAME
- "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, 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”.

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]https://www.postgresql.org/docs/devel/sql-explain.html 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.