Re: Enhance create subscription reference manual

On Thu, Oct 3, 2024 at 10:01 AM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> On Wednesday, October 2, 2024, Peter Smith <smithpb2250(at)gmail(dot)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] 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