Hi.
With all the recent work on pg_createsubscriber I decided to take a look at it, namely the documentation.
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 tweaked the wording of config-file and felt it worth pointing out the caveat regarding the port setting.
It took me a bit, and reading implementation code, to understand what was meant by "Additional recovery parameters are added to avoid ...". I decided that detail seemed unnecessary for the user-facing documentation - supposedly they will never see the recovery file if everything works OK (and if they do the various empty string settings should be reasonably self-evident). If we do want to keep it I'll try to find a better wording.
I removed the use of the word "switch" and replaced it with "option" for consistency.
There might be some items in 0001 that belong in 0002 and vice-versa; the final patch would just be a single one in any case.
I also dropped the bit about "intended for large databases, use normal logical replication for small ones". If you already have a standby why not use this even for small ones? Maybe the simplicity of normal replication is more important than how long an overnight process to copy the data tables might take. We've explained how the two options compare to each other but we tend not to, for good reason, include such conclusions/recommendations in the technical/reference documentation.
David J.
