MIME-Version: 1.0
References: <CAHut+PtnA4DB_pcv4TDr4NjUSM1=P2N_cuZx5DX09k7LVmaqUA@mail.gmail.com>
 <CALDaNm3P69h4SqcZaPF7Swmw21=NPLEuqnxd8wmAaya0kR86fw@mail.gmail.com>
In-Reply-To: <CALDaNm3P69h4SqcZaPF7Swmw21=NPLEuqnxd8wmAaya0kR86fw@mail.gmail.com>
From: Peter Smith <smithpb2250@gmail.com>
Date: Mon, 16 Dec 2024 08:22:39 +1100
Message-ID: <CAHut+PubBnQwB3rObk7bACp9qh4XSQ4mvpCoag=JbV8vimHxgQ@mail.gmail.com>
Subject: Re: DOCS: pg_createsubscriber wrong link?
To: vignesh C <vignesh21@gmail.com>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Content-Type: multipart/mixed; boundary="000000000000881e0f062955aba5"
Archived-At: <https://www.postgresql.org/message-id/CAHut%2BPubBnQwB3rObk7bACp9qh4XSQ4mvpCoag%3DJbV8vimHxgQ%40mail.gmail.com>
Precedence: bulk

--000000000000881e0f062955aba5
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Fri, Dec 13, 2024 at 8:31=E2=80=AFPM vignesh C <vignesh21@gmail.com> wro=
te:
>
> On Fri, 13 Dec 2024 at 10:58, Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > Hi,
> >
> > While reviewing the pg_createsubscriber [1] docs I found a potentially
> > wrong linkend.
> >
> > This sentence:
> > "For smaller databases, initial data synchronization is recommended."
> >
> > links to [2] ("29.4.5. Initial Data Synchronization").
> >
> > This seems to have been deliberately changed (commit [3])
> >
> > FROM: <link linkend=3D"logical-replication">initial data synchronizatio=
n</link>
> >
> > TO: <link linkend=3D"logical-replication-row-filter-initial-data-sync">=
initial
> > data synchronization</link>
> >
> > Although the title "Initial Data Synchronization" seems at face value
> > to be relevant, this particular link target is a sub-section of "Row
> > Filters", so I don't see why this would be the intended link from the
> > pg_createsubscriber. AFAICT, the original discussion and commit
> > message does not explain.
>
> I also felt that the link was directed to the wrong page.
>

Thanks.

> > Here is a new patch giving an alternate link which IMO might be more
> > appropriate.
>
> How about we change the below:
>     more the time when the logical replica will be available. For smaller
> -   databases, <link linkend=3D"logical-replication-row-filter-initial-da=
ta-sync">
> -   initial data synchronization</link> is recommended.
> +   databases, initial data synchronization is recommended. For details, =
see the
> +   <command>CREATE SUBSCRIPTION</command> <link
> linkend=3D"sql-createsubscription-params-with-copy-data">
> +   <literal>copy_data</literal></link> option.
> +
> to:
> For smaller databases, it is recommended to set up <link
> linkend=3D"logical-replication">logical replication</link> with <link
> linkend=3D"sql-createsubscription-params-with-copy-data">initial data
> synchronization</link>.
>

Hi Vignesh.

I took parts of your suggestion:

- I changed the 1st sentence's wording as suggested.
- I included a "logical replication" link as suggested, but I put it
earlier, where it was first mentioned on this page.
- I kept my 2nd sentence with the "copy_data" link as-is. That's
because if this docs page was in hardcopy format, doing it your way
the reader would have no clue about the link target.

Please see patch v2.

=3D=3D=3D=3D=3D=3D
Kind Regards,
Peter Smith.
Fujitsu Australia

--000000000000881e0f062955aba5
Content-Type: application/octet-stream; 
	name="v2-0001-DOCS-Fix-wrong-linkend-on-pg_createsubscriber-pag.patch"
Content-Disposition: attachment; 
	filename="v2-0001-DOCS-Fix-wrong-linkend-on-pg_createsubscriber-pag.patch"
Content-Transfer-Encoding: base64
Content-ID: <f_m4q42t3l0>
X-Attachment-Id: f_m4q42t3l0

RnJvbSAxOThhMWQwOTJiZjE2NjNkNjVjYTg5NzQyMzJjYWM2MWYwMGVlOWMwIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBQZXRlciBTbWl0aCA8cGV0ZXIuYi5zbWl0aEBmdWppdHN1LmNv
bT4KRGF0ZTogTW9uLCAxNiBEZWMgMjAyNCAwODoxNjoxMiArMTEwMApTdWJqZWN0OiBbUEFUQ0gg
djJdIERPQ1M6IEZpeCB3cm9uZyBsaW5rZW5kIG9uIHBnX2NyZWF0ZXN1YnNjcmliZXIgcGFnZS4K
Ci0tLQogZG9jL3NyYy9zZ21sL3JlZi9wZ19jcmVhdGVzdWJzY3JpYmVyLnNnbWwgfCAxMCArKysr
KysrLS0tCiAxIGZpbGUgY2hhbmdlZCwgNyBpbnNlcnRpb25zKCspLCAzIGRlbGV0aW9ucygtKQoK
ZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yZWYvcGdfY3JlYXRlc3Vic2NyaWJlci5zZ21sIGIv
ZG9jL3NyYy9zZ21sL3JlZi9wZ19jcmVhdGVzdWJzY3JpYmVyLnNnbWwKaW5kZXggZjhhMzkxMS4u
YTIzODhjZSAxMDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL3JlZi9wZ19jcmVhdGVzdWJzY3JpYmVy
LnNnbWwKKysrIGIvZG9jL3NyYy9zZ21sL3JlZi9wZ19jcmVhdGVzdWJzY3JpYmVyLnNnbWwKQEAg
LTQ5LDcgKzQ5LDggQEAgUG9zdGdyZVNRTCBkb2N1bWVudGF0aW9uCiAgIDxwYXJhPgogICAgPGFw
cGxpY2F0aW9uPnBnX2NyZWF0ZXN1YnNjcmliZXI8L2FwcGxpY2F0aW9uPiBjcmVhdGVzIGEgbmV3
IGxvZ2ljYWwKICAgIHJlcGxpY2EgZnJvbSBhIHBoeXNpY2FsIHN0YW5kYnkgc2VydmVyLiAgQWxs
IHRhYmxlcyBpbiB0aGUgc3BlY2lmaWVkCi0gICBkYXRhYmFzZSBhcmUgaW5jbHVkZWQgaW4gdGhl
IGxvZ2ljYWwgcmVwbGljYXRpb24gc2V0dXAuICBBIHBhaXIgb2YKKyAgIGRhdGFiYXNlIGFyZSBp
bmNsdWRlZCBpbiB0aGUgPGxpbmsgbGlua2VuZD0ibG9naWNhbC1yZXBsaWNhdGlvbiI+bG9naWNh
bAorICAgcmVwbGljYXRpb248L2xpbms+IHNldHVwLiAgQSBwYWlyIG9mCiAgICBwdWJsaWNhdGlv
biBhbmQgc3Vic2NyaXB0aW9uIG9iamVjdHMgYXJlIGNyZWF0ZWQgZm9yIGVhY2ggZGF0YWJhc2Uu
ICBJdAogICAgbXVzdCBiZSBydW4gYXQgdGhlIHRhcmdldCBzZXJ2ZXIuCiAgIDwvcGFyYT4KQEAg
LTcwLDggKzcxLDExIEBAIFBvc3RncmVTUUwgZG9jdW1lbnRhdGlvbgogICAgc3BlbnQgc3luY2hy
b25pemluZyBkYXRhIGlzIHVzdWFsbHkgYSBsYXJnZSBhbW91bnQgb2YgY2hhbmdlcyB0byBiZSBh
cHBsaWVkCiAgICAodGhhdCB3ZXJlIHByb2R1Y2VkIGR1cmluZyB0aGUgaW5pdGlhbCBkYXRhIGNv
cHkpLCB3aGljaCBpbmNyZWFzZXMgZXZlbgogICAgbW9yZSB0aGUgdGltZSB3aGVuIHRoZSBsb2dp
Y2FsIHJlcGxpY2Egd2lsbCBiZSBhdmFpbGFibGUuIEZvciBzbWFsbGVyCi0gICBkYXRhYmFzZXMs
IDxsaW5rIGxpbmtlbmQ9ImxvZ2ljYWwtcmVwbGljYXRpb24tcm93LWZpbHRlci1pbml0aWFsLWRh
dGEtc3luYyI+Ci0gICBpbml0aWFsIGRhdGEgc3luY2hyb25pemF0aW9uPC9saW5rPiBpcyByZWNv
bW1lbmRlZC4KKyAgIGRhdGFiYXNlcywgaXQgaXMgcmVjb21tZW5kZWQgdG8gc2V0IHVwIGxvZ2lj
YWwgcmVwbGljYXRpb24gd2l0aCBpbml0aWFsIGRhdGEKKyAgIHN5bmNocm9uaXphdGlvbi4gIEZv
ciBkZXRhaWxzLCBzZWUgdGhlIDxjb21tYW5kPkNSRUFURSBTVUJTQ1JJUFRJT048L2NvbW1hbmQ+
CisgICA8bGluayBsaW5rZW5kPSJzcWwtY3JlYXRlc3Vic2NyaXB0aW9uLXBhcmFtcy13aXRoLWNv
cHktZGF0YSI+CisgICA8bGl0ZXJhbD5jb3B5X2RhdGE8L2xpdGVyYWw+PC9saW5rPiBvcHRpb24u
CisKICAgPC9wYXJhPgogIDwvcmVmc2VjdDE+CiAKLS0gCjEuOC4zLjEKCg==
--000000000000881e0f062955aba5--