Thread: 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

On Sat, May 3, 2025 at 9:33 PM 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 having to surgically copy line-by-line the DDL and DML code involved.  Let's strive for a more copy-paste friendly example setup.  No prompts and no interspersed command tags (they are ok if the script is one block and the output is another).
>

That's a valid point. Since this is not a correctness issue, I am less
inclined to backpatch. What do you or others think?

On Fri, May 23, 2025 at 10:52 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Thursday, May 22, 2025, Amit Kapila <amit.kapila16@gmail.com> wrote:
>>
>> On Sat, May 3, 2025 at 9:33 PM 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
byhaving to 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).
>> >
>>
>> That's a valid point. Since this is not a correctness issue, I am less
>> inclined to backpatch. What do you or others think?
>
>
> Agreed, this would not be back-patched.
>

Yesterday, I pushed the patch. Thanks for working on this.

--
With Regards,
Amit Kapila.