Re: doc: Make logical replication examples executable in bulk and legal sgml.

On Sun, May 4, 2025 at 2:03 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> While responding to a "our documentation is buggy" complaint I got annoyed in my attempt to reproduce the behavior by
havingto surgically copy line-by-line the DDL and DML code involved.  Let's strive for a more copy-paste friendly
examplesetup.  No prompts and no interspersed command tags (they are ok if the script is one block and the output is
another).
>

Hi David,

I think I was the author of most of these examples, so I feel obliged
to post my 2c.

For the logical replication examples it is really important to be
aware if the psql is executing at the publisher or subscriber side;
that is the main reason why I had kept prompts in the examples (e.g.
it avoided having to say "On the publisher:" or "On the subscriber:"
for every example).

OTOH, I understand your issue that those prompts made it difficult to
simply cut/paste slabs of psql directly from the examples -- I've
heard this complaint a few times before from other people.

So, your patch which still keeps my prompts albeit as "comments", but
that now allows the execution of the bulk copy/paste, seems like a
reasonable compromise to me.

~~

BTW, I can understand the commented prompt for the bulk fragments like:
/* sub # */ CREATE SUBSCRIPTION sub1
/* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub1'
/* sub - */ PUBLICATION pub1;
/* sub # */ CREATE SUBSCRIPTION sub2
/* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub2'
/* sub - */ PUBLICATION pub2;
/* sub # */ CREATE SUBSCRIPTION sub3
/* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub3'
/* sub - */ PUBLICATION pub3a, pub3b;

~

But, for the SELECT statements, commenting the prompt like:
/* sub # */ SELECT * FROM t1;
 a |   b
---+-------
 1 | one
 2 | two
 3 | three
(3 rows)

doesn't help bulk execution at all because the result gets in the way
so you'll still end up surgically copying each SELECT. Since it fixes
nothing I assumed you just commented the SELECT prompts for
consistency with the other ones, right?

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