[1] initdb [option...] [ --pgdata | -D ] directory
[2] pg_archivecleanup [option...] archivelocation oldestkeptwalfile
[3] pg_checksums [option...] [[ -D | --pgdata ]datadir]
[4] pg_controldata [option] [[ -D | --pgdata ]datadir]
[5] pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
[6] pg_ctl (the many synopses here don't give all the switch
alternatives, it would be too much...)
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
--pgdata ]datadir
[8] pg_rewind [option...] { -D | --target-pgdata } directory {
--source-pgdata=directory | --source-server=connstr }
[9] pg_test_fsync [option...]
[10] pg_test_timing [option...]
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
[12] pg_waldump [option...] [startseg [endseg]]
[13] pg_walsummary [option...] [file...]
Here are some guidelines we should add to [1].
I don't feel listing both short and long form args is a good use of space - and the { | } impairs readability. The short form combined with, usually, a decent replaceable name, shows the reader the common interactive usage and they can find the long forms in the Options section. Maybe use long forms for value-less options since those don't get the argname hint.
The non-space between option and its value reduces readability. IIUC a space in between doesn't impact correctness so I say go for readability. This becomes more pronounced with the first items since it is only marginally readable now because there is always a } or ] before the replaceable. Though this may involve fighting the markup a bit...I haven't experimented yet (pg_rewind managed it...).
The first listed command should probably only include mandatory options. When there are multiple combinations of mandatory options show multiple commands, one for each variant. Use examples to showcase idiomatic usage patterns with descriptions. There is room to argue exceptions to be listed also in Synopsis.
Establish the convention of datadir as the replaceable name. Possibly do the same for other common items.
We should have a reference page (near [1] listing DocBook elements and our guidelines for how/where to use them.
In any case, details aside, modifying [1] with whatever is agreed to (and making changes to conform) is something I agree should happen.
