On Wednesday, March 12, 2025, Peter Smith <smithpb2...@gmail.com> wrote:
>
>
> I've made some updates and attached the v2 patch.
Thanks. Full review later.
Pg_controldata
- TODO. The page structure looks strange. There should be an "Options"
> section to describe -D, -V, and -?
Agreed.
>
> [7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
>
> - TODO. Looks a bit strange with "[options...]" not shown first.
Yeah, need to fix that.
>
> [8] pg_rewind [option...] { -D | --target-pgdata } directory
>
> - TODO. Was it OK to make the "[-D datadir]" optional like all others?
> The page does not mention PGDATA.
My take on this is that the presence of environment variables doesn’t
impact whether a given CLI option is shown optional or mandatory. We are,
in effect, communicating that “datadir” must be specified for this
command. And then choosing one of the ways of specifying it. The reader
can use the indicated short-form -D, the long-form —pgdata if it exists, or
the DATADIR environment variable (this applies to any option, not just
datadir) as they desire. In short, most/all of these should show “-D
datadir” without [ ].
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
> newconfigdir [option...]
> - made all the option to be optional because the page says they can
> all use environment variable defaults.
See note above regarding environment variables.
> - TODO. Looks a bit strange with "[options...]" not shown first.
Should be moved.
>
> OTHER QUESTIONS
> - Should we use class="parameter" for all the <replaceable> tags?
> Currently, some do, but most do not.
>
>
I’d probably document that they should have that class but leave the bulk
cleanup of existing content for a separate patch.
~~~
>
> BTW, the scope of this thread is originally only the *server*
> application pages, but all the *client* applications might be impacted
> if we applied the same rules there.
>
Yeah, noticed that yesterday. I don’t see a reason why the same policy
shouldn’t apply to both subsets. I wouldn’t require everything has to be
changed right now though. Perfectly happy to ask for people specifically
familiar with these applications to modify the pages under the new policy
and try to divvy up the work. Then pickup what doesn’t get done.
David J.
