On Wednesday, March 12, 2025, Peter Smith <
smithpb2250@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.
