Hi, While reviewing the synopsis for pg_createsubscriber I compared it with all the other synopses of the various Server Applications. In doing so I found some minor differences between them all. The differences are more apparent when you list everything together, like below:
[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...]
~~
e.g. The following inconsistencies are noted:
* When both long}short options are provided sometimes those are
ordered long|short and sometimes they are short|long.
* Mostly the pgdata directory is called 'datadir' but sometimes just
'directory'.
* Mostly the optarg is squished against the option switch (no
spacing). It is an artifact of the way these synopses are constructed.
* Sometimes the rendering looks different (eg 'options' versus
'replaceable' style).
* Sometimes the replaceable optargs named in the synopsis are not
given in the options list, or they are there but with different names.
//////////
So, here are a few modifications to make everything more uniform:
[1] initdb
- changed 'directory' to (more common) 'datadir' in the synopsis
- changed same in the options list
- changed order "[--pgdata | -D]" to be (more commonly used) "[-D | --pgdata]"
- removed the space in from of the optarg. (most others synopses don't do this)
[5] pg_createsubscriber
- in the options list 'directory' should be called 'datadir' to match
the synopsis
[8] pg_rewind
- remove spaces in the synopsis (most others synopses don't do this)
- change 'directory' to 'datadir' in the synopsis (for
--target-pgdata, and for --source-pgdata)
- change 'directory' to 'datadir' in the options (for --target-pgdata,
and for --source-pgdata)
[11] pg_upgrade
- change 'bindir' to 'oldbindir' and 'newbindir' in the options list
(to match the synopsis)
- change 'configdir' to 'oldconfigdir' and 'newconfigdir' in the
options list (to match the synopsis)
[12] pg_waldump
- This was using some different markup to the others (eg <option>
instead of <replaceable>) so the rendering did not appear the same.
[13] pg_walsummary
- Fixed a typo "found with" -> "found in"
- Change 'file' to 'filename' in the synopsis
- Add the missing entry in the options list to describe the
replaceable 'filename'.
~~~
Patch v1 is attached.
Thoughts?
======
[1] initdb - https://www.postgresql.org/docs/devel/app-initdb.html
[2] pg_archivecleanup -
https://www.postgresql.org/docs/devel/pgarchivecleanup.html
[3] pg_checksums - https://www.postgresql.org/docs/devel/app-pgchecksums.html
[4] pg_controldata -
https://www.postgresql.org/docs/devel/app-pgcontroldata.html
[5] pg_createsubscriber -
https://www.postgresql.org/docs/devel/app-pgcreatesubscriber.html
[6] pg_ctl - https://www.postgresql.org/docs/devel/app-pg-ctl.html
[7] pg_resetwal - https://www.postgresql.org/docs/devel/app-pgresetwal.html
[8] pg_rewind - https://www.postgresql.org/docs/devel/app-pgrewind.html
[9] pg_test_fsync - https://www.postgresql.org/docs/devel/pgtestfsync.html
[10] pg_test_timing - https://www.postgresql.org/docs/devel/pgtesttiming.html
[11] pg_upgrade - https://www.postgresql.org/docs/devel/pgupgrade.html
[12] pg_waldump - https://www.postgresql.org/docs/devel/pgwaldump.html
[13] pg_walsummary - https://www.postgresql.org/docs/devel/app-pgwalsummary.html
Kind Regards,
Peter Smith.
Fujitsu Australia
v1-0001-DOCS-Make-the-Server-Application-docs-synopses-mo.patch
Description: Binary data
