Re: Documentation Edits for pg_createsubscriber

On Tue, Mar 11, 2025 at 8:20 AM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> Hi.
>
> With all the recent work on pg_createsubscriber I decided to take a look at it, namely the documentation.
>

I agree this page needs some improvement. Thanks for taking up this task.

> The 0001 patch is basically just fixing some typos and other minor edits.
>
> The 0002 includes some of the more editoralized (but still limited) changes.
>
> The main thing I noted is that our synopsis is simply wrong regarding the optionality of the --database option. I went with a fix that included only showing the two mandatory options and adding a paragraph to usage explaining that --database exists and how to use it. Our existing example also covers that common usage.
>
> I also noted that we've started including both the long and short forms of the options in our synopsis. I went with the "choose the short option as the only one" as exemplified by pg_upgrade. It seems quite noisy to include both in a synopsis that is fine with including 10+ other options under [options...].

I think the synopsis format is destined to change significantly in the
thread [1] ("Enhance 'pg_createsubscriber' to retrieve databases
automatically when no database is provided"). Maybe it is worth
checking that thread to see if what you have in mind is compatible
with that proposal.

FYI some months ago I posted a thread [2] ("DOCS: Make the Server
Application docs synopses more consistent"), but unfortunately, it
received no responses. Perhaps you can take a look at that thread and
we can try to bash all of these tool synopses until they become more
consistent.

...
> I removed the use of the word "switch" and replaced it with "option" for consistency.

Yes, +1 for this. You pipped me by a few days from posting a very
similar patch. It might be OK if "switch" was used only for boolean
flags and "option" was used for others, but the master SGML for this
page was an inconsistent muddle, so changing everything to "option" as
you have done is probably the best way to go.

======

Some other minor comments:

1.
I felt that all the sentences like "If this option is not
specified..." overuse the word "option" which is now everywhere. It
might be nicer to just name the options explicitly sometimes

e.g. --publication
CURRENT: If this option is not specified, a generated name is assigned
to the publication name.
SUGGEST: If --publication is not specified, a generated name is
assigned to the publication name.

e.g. --replication-slot
CURRENT: If this option is not specified, the subscription name is
assigned to the replication slot name.
SUGGEST: If this --replication-slot is not specified, the subscription
name is assigned to the replication slot name.

e.g. --subscription
CURRENT: If this option is not specified, a generated name is assigned
to the subscription name.
SUGGEST: If this --subscription is not specified, a generated name is
assigned to the subscription name.

======
[1] https://www.postgresql.org/message-id/flat/CAHv8RjKhA%3D_h5vAbozzJ1Opnv%3DKXYQHQ-fJyaMfqfRqPpnC2bA%40mail.gmail.com
[2] https://www.postgresql.org/message-id/flat/CAHut%2BPv%2B96CykSY6-uLKZWaa6to9x1DurmyJh8Jmu1_1P7hp4Q%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia