public inbox for [email protected]  

help / color / mirror / Atom feed

From: Tom Lane <[email protected]>
To: Zheng Li <[email protected]>
Cc: [email protected]
Cc: Peter Smith <[email protected]>
Subject: Re: pub/sub - specifying optional parameters without values.
Date: Sun, 29 Jan 2023 16:36:39 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <167328582545.1136.8620247763467087383.pgcf@coridan.postgresql.org>
References: <CAHut+PvwjZfdGt2R8HTXgSZft=jZKymrS8KUg31pS7zqaaWKKw@mail.gmail.com>
	<CAHut+Pt_GEKrRQuqKKJu6v1g61_BEGKx8TNuhYN_euDmZwqRfA@mail.gmail.com>
	<167328582545.1136.8620247763467087383.pgcf@coridan.postgresql.org>

Zheng Li <[email protected]> writes:
> The behavior is due to the following code
> https://github.com/postgres/postgres/blob/master/src/backend/commands/define.c#L113

Yeah, so you can grep for places that have this behavior by looking
for defGetBoolean calls ... and there are quite a few.  That leads
me to the conclusion that we'd better invent a fairly stylized
documentation solution that we can plug into a lot of places,
rather than thinking of slightly different ways to say it and
places to say it.  I'm not necessarily opposed to Peter's desire
to fix replication-related commands first, but we have more to do
later.

I'm also not that thrilled with putting the addition up at the top
of the relevant text.  This behavior is at least two decades old,
so if we've escaped documenting it at all up to now, it can't be
that important to most people.

I also notice that ALTER SUBSCRIPTION has fully three different
sub-sections with about equal claims on this note, if we're going
to stick it directly into the affected option lists.

That all leads me to propose that we add the new text at the end of
the Parameters <refsect1> in the affected man pages.  So about
like the attached.  (I left out alter_publication.sgml, as I'm not
sure it needs its own copy of this text --- it doesn't describe
individual parameters at all, just refer to CREATE PUBLICATION.)

			regards, tom lane



Attachments:

  [text/x-diff] v3-0001-clarify-behavior-of-specifying-a-parameter-with-n.patch (2.0K, ../[email protected]/2-v3-0001-clarify-behavior-of-specifying-a-parameter-with-n.patch)
  download | inline diff:
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index ad93553a1d..964fcbb8ff 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -277,6 +277,13 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
     </listitem>
    </varlistentry>
   </variablelist>
+
+  <para>
+   When specifying a parameter of type <type>boolean</type>, the
+   <literal>=</literal> <replaceable class="parameter">value</replaceable>
+   part can be omitted, which is equivalent to
+   specifying <literal>TRUE</literal>.
+  </para>
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index e229384e6f..370dac2ccf 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -217,6 +217,13 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
    </varlistentry>
 
   </variablelist>
+
+  <para>
+   When specifying a parameter of type <type>boolean</type>, the
+   <literal>=</literal> <replaceable class="parameter">value</replaceable>
+   part can be omitted, which is equivalent to
+   specifying <literal>TRUE</literal>.
+  </para>
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index eba72c6af6..51c45f17c7 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -354,6 +354,13 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     </listitem>
    </varlistentry>
   </variablelist>
+
+  <para>
+   When specifying a parameter of type <type>boolean</type>, the
+   <literal>=</literal> <replaceable class="parameter">value</replaceable>
+   part can be omitted, which is equivalent to
+   specifying <literal>TRUE</literal>.
+  </para>
  </refsect1>
 
  <refsect1 id="sql-createsubscription-notes" xreflabel="Notes">

view thread (4+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected]
  Subject: Re: pub/sub - specifying optional parameters without values.
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox