Re: Documentation patch for ALTER SUBSCRIPTION

> On Feb 5, 2020, at 7:56 AM, Alvaro Herrera <alvherre(at)2ndquadrant(dot)com> wrote:
>
> On 2020-Feb-05, Amit Kapila wrote:
>
>> It is possible that one might not understand how this option works by
>> reading the already existing text in docs, but I think writing in a
>> different language the same thing also doesn't seem advisable. I
>> think if we want to explain it better, then maybe a succinct example
>> at the end of the page might be helpful.
>
> For reference, the complete varlistentry is:
>
> <term><literal>REFRESH PUBLICATION</literal></term>
> <listitem>
> <para>
> Fetch missing table information from publisher. This will start
> replication of tables that were added to the subscribed-to publications
> since the last invocation of <command>REFRESH PUBLICATION</command> or
> since <command>CREATE SUBSCRIPTION</command>. <!-- [2] -->
> </para>
>
> <para>
> <replaceable>refresh_option</replaceable> specifies additional options for the
> refresh operation. The supported options are:
>
> <variablelist>
> <varlistentry>
> <term><literal>copy_data</literal> (<type>boolean</type>)</term>
> <listitem>
> <para>
> Specifies whether the existing data in the publications that are
> being subscribed to should be copied once the replication starts.
> The default is <literal>true</literal>. <!-- [1] -->
> </para>
> </listitem>
> </varlistentry>
> </variablelist>
> </para>
> </listitem>
>
> I tend to agree with David that this is ambiguous enough to warrant a
> few words. Maybe his proposed wording is too verbose; how about just
> adding "(Previously subscribed tables are not copied.)" where the [1]
> appears? Alternatively, we could add "Tables that were already present
> in the subscription are not modified in any way." where [2] appears, but
> that seems less clear to me.
>
> An example would not be bad if it showed that existing data is not
> copied. But examples are actually just syntactical examples, so you'd
> have to resort to a comment explaining that existing tables are not
> copied by the shown syntax. You might as well just add the words in the
> reference docs …

I would be happy with the suggestion [1]; it would have clarified my specific question.

Thanks,

David