Re: PGDOCS - add more links in the pub/sub reference pages

On Tue, Oct 10, 2023 at 11:33 PM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
>
> On Tue, Oct 10, 2023 at 11:40 AM vignesh C <vignesh21(at)gmail(dot)com> wrote:
> >
> > On Tue, 10 Oct 2023 at 08:47, Peter Smith <smithpb2250(at)gmail(dot)com> wrote:
> > > PSA v3.
> >
> > Few more instances in other logical replication related pages:
> > 1) Another instance was in alter_subscription.sgml:
> > Fetch missing table information from publisher. This will start
> > replication of tables that were added to the subscribed-to publications
> > since <command>CREATE SUBSCRIPTION</command> or
> > the last invocation of <command>REFRESH PUBLICATION</command>.
> >
>
> Do we want each and every occurrence of the commands to have
> corresponding links? I am not against it if we think that is useful
> for users but asking as I am not aware of the general practice we
> follow in this regard. Does anyone else have any opinion on this
> matter?
>

The goal of the patch was to use a consistent approach for all the
pub/sub pages. Otherwise, there was a mixture and no apparent reason
why some commands had links while some did not.

The rules this patch is using are:
- only including inter-page links to other pub/sub commands
- if the same pub/sub linkend occurs multiple times in the same block
of text, then only give a link for the first one

~~

What links are "useful to users" is subjective, and the convenience
probably also varies depending on how much scrolling is needed to get
to the "See Also" part at the bottom. I felt a consistent linking
approach is better than having differences based on some arbitrary
judgement of usefulness.

AFAICT some other PG DOCS pages strive to do the same. For example,
the ALTER TABLE page [1] mentions the "CREATE TABLE" command 10 times
and 8 of those have links. (the missing ones don't look any different
to me so seem like accidental omissions).

======
[1] https://www.postgresql.org/docs/devel/sql-altertable.html

Kind Regards,
Peter Smith.
Fujitsu Australia