docs: adjust --help output and warning hints

* postgresql-check-db-dir.in: Just fix typos.
* postgresql-setup.in: Reorganize --help.
* TODO: Adjust after some time.

1 files changed, 27 insertions, 19 deletions

diff --git a/postgresql-setup.in b/postgresql-setup.in
index 9581a2d..ed6b4be 100644
--- a/postgresql-setup.in
+++ b/postgresql-setup.in
@@ -33,33 +33,40 @@ SU=@SU@
 PGPORT_DEF=5432
 
 USAGE_STRING=$"\
-Usage: $0 MODE [OPTION...] [--unit UNIT_NAME]
+Usage: $0 MODE_OPTION [--unit=[UNIT_NAME]] [OPTION...]
 
 Script is aimed to help sysadmin with basic database cluster administration.
+Usually, \"postgresql-setup --initdb\" and \"postgresql-setup --upgrade\" is
+enough, however there are other options described below.
 
-The UNIT_NAME is used for selection of proper unit configuration file; For more
-info and howto/when use this script please look at the docu file
-$README_DIST.  The 'postgresql'
-string is used when no UNIT_NAME is explicitly passed.
+For more info and howto/when use this script please look at the documentation
+file $README_DIST.
 
 Available operation mode:
   --initdb      Create a new PostgreSQL database cluster.  This is usually the
                 first action you perform after PostgreSQL server installation.
-  --upgrade     Upgrade PostgreSQL database cluster to be usable with new
-                server.  Use this if you upgraded your PostgreSQL server to
-                newer major version (currently from $PREVMAJORVERSION \
-to $PGMAJORVERSION).
+  --upgrade     Upgrade database cluster for new major version of PostgreSQL
+                server.  This installation is configured to perform upgrade
+                from $PREVMAJORVERSION.X to $PGMAJORVERSION.X.
 
 Options:
-  --unit        unit ID of PostgreSQL to run against
-  --port        port where the server will listen for connections
-  --datadir     specify absolute path to DB data directory
-  --systemd-config  auto-generate system'd configuration for not yet configured
-                units, this requires --datadir option set
-
-  --help        show this help
-  --version     show version of this package
-  --debug       show basic debugging information
+  --unit=UNIT_NAME           The UNIT_NAME is used to select proper systemd's
+                             unit configuration.  For example, if you want to
+                             work with unit 'postgresql@com_example.service',
+                             you should use 'postgresql@com_example' (without
+                             trailing .service string).  When no UNIT_NAME is
+                             explicitly passed, the 'postgresql' string is used
+                             by default.
+  --port=PORT                port where the server will listen for connections
+  --datadir=PATH             specify absolute path to DB data directory
+  --new-systemd-unit         Pre-generate system'd configuration in drop-in
+                             directory if the unit is not yet configured,
+                             requires non-default --unit specified and explicit
+                             --datadir and --port.
+Other options:
+  --help                     show this help
+  --version                  show version of this package
+  --debug                    show basic debugging information
 
 Environment:
   PGSETUP_INITDB_OPTIONS     Options carried by this variable are passed to
@@ -71,7 +78,8 @@ Environment:
                              subsequent call of \`pg_upgrade\`.  For more info
                              about possible options please look at man
                              pg_upgrade(1).
-  PGSETUP_DEBUG              Set to '1' if you want to see debugging output."
+  PGSETUP_DEBUG              Set to '1' if you want to see very verbose shell
+                             debugging output."
 
 
 die()     { echo >&2 $"FATAL: $@" ; exit 1 ; }