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