MIME-Version: 1.0
References: <CAHut+PtnA4DB_pcv4TDr4NjUSM1=P2N_cuZx5DX09k7LVmaqUA@mail.gmail.com>
 <CALDaNm3P69h4SqcZaPF7Swmw21=NPLEuqnxd8wmAaya0kR86fw@mail.gmail.com> <CAHut+PubBnQwB3rObk7bACp9qh4XSQ4mvpCoag=JbV8vimHxgQ@mail.gmail.com>
In-Reply-To: <CAHut+PubBnQwB3rObk7bACp9qh4XSQ4mvpCoag=JbV8vimHxgQ@mail.gmail.com>
From: vignesh C <vignesh21@gmail.com>
Date: Tue, 17 Dec 2024 14:44:15 +0530
Message-ID: <CALDaNm07RpyXu665XohQva+n99-4K3k3BkawjU2sN5JToaG0YQ@mail.gmail.com>
Subject: Re: DOCS: pg_createsubscriber wrong link?
To: Peter Smith <smithpb2250@gmail.com>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CALDaNm07RpyXu665XohQva%2Bn99-4K3k3BkawjU2sN5JToaG0YQ%40mail.gmail.com>
Precedence: bulk

On Mon, 16 Dec 2024 at 02:53, Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Fri, Dec 13, 2024 at 8:31=E2=80=AFPM vignesh C <vignesh21@gmail.com> w=
rote:
> >
> > 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 potentiall=
y
> > > 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 synchronizat=
ion</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 small=
er
> > -   databases, <link linkend=3D"logical-replication-row-filter-initial-=
data-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.

Thanks for the updated version. The v2 version patch looks great and
applies cleanly to both the HEAD and PG17 branches.

Regards,
Vignesh