Re: Enhance create subscription reference manual

On Wed, Oct 2, 2024 at 6:17 PM Yugo NAGATA <nagata(at)sraoss(dot)co(dot)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