On Thu, May 16, 2024 at 3:11 PM David Rowley <dgrowle...@gmail.com> wrote: > > On Thu, 16 May 2024 at 12:29, Peter Smith <smithpb2...@gmail.com> wrote: > > There are lots of subscription options listed on the CREATE > > SUBSCRIPTION page [1]. > > > > Although these boolean options are capable of accepting different > > values like "1|0", "on|off", "true|false", here they are all described > > only using values "true|false". > > If you want to do this, what's the reason to limit it to just this one > page of the docs?
Yeah, I had a vested interest in this one place because I've been reviewing the other thread [1] that was mentioned above. If that other thread chooses "true|false" then putting "true|false" adjacent to another "on|off" will look silly. But if that other thread adopts the existing 'failover=on|off' values then it will diverge even further from being consistent with the CREATE SUBSCRIPTION page. Unfortunately, that other thread cannot take it upon itself to make this change because it has nothing to do with the 'failover' option, So I saw no choice but to post an independent patch for this. I checked all the PUBLICATION/SUBSCRIPTION reference pages and this was the only inconsistent value that I found. But I might be mistaken. > > If the following is anything to go by, it doesn't seem we're very > consistent about this over the entire documentation. > > doc$ git grep "<literal>on</literal>" | wc -l > 122 > > doc$ git grep "<literal>true</literal>" | wc -l > 222 > > And: > > doc$ git grep "<literal>off</literal>" | wc -l > 102 > > doc$ git grep "<literal>false</literal>" | wc -l > 162 > Hmm. I'm not entirely sure if those stats are meaningful because I'm not saying option values should avoid "on|off" -- the point was I just suggesting they should be used consistent with where they are described. For example, the CREATE SUBSCRIPTION page describes every boolean option value as "true|false", so let's use "true|false" in every other docs place where those are mentioned. OTOH, other options on other pages may be described as "on|off" which is fine by me, but then those should similarly be using "on|off" again wherever they are mentioned. > I think unless we're going to standardise on something then there's > not much point in adjusting individual cases. IMO, there could be an > endless stream of follow-on patches as a result of accepting this. > Standardisation might be ideal, but certainly, I'm not going to attempt to make a giant patch that impacts the entire documentation just for this one small improvement. It seems a shame if "perfect" becomes the enemy of "good"; How else do you suggest I can make the ALTER SUBSCRIPTION page better? If this one-line change is rejected then the most likely outcome is nothing will ever happen to change it. ====== Kind Regards, Peter Smith. Fujitsu Australia
