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.

3 files changed, 45 insertions, 26 deletions

diff --git a/TODO b/TODO
index 6a7e291..989138c 100644
--- a/TODO
+++ b/TODO
@@ -1,11 +1,22 @@
-* Testsuite
-    - check that none of @PATTERN@ is un-expanded in generated files
+* testsuite
+    - check bash "static" analysis
 
-* --upgrade
-    - 'echo -n' breaks the error messages from 'restorecon'
+* root-testsuite (future)
+    - check that --port is required for @ units
+    - check that the --port option in '--{initdb,upgrade} --port XXX' is ignored
+      (and user warned) when port is already specified somewhere else (systemd
+      or postgresql.conf)
+
+* warn about privileged port usage
 
 * bash-completion script
 
+* coloring?
+
 * make the README.rpm-dist manual page as it allows user showing the content
   in formatting based on its own preference.  It allows also easier templating
   (too-long lines, etc).
+
+* build system
+    - generate the binary scripts outside '$(srcdir)' as maintainer tends to
+      edit generated file instead its '*.in' parent
diff --git a/postgresql-check-db-dir.in b/postgresql-check-db-dir.in
index 188c7de..2d19a1b 100644
--- a/postgresql-check-db-dir.in
+++ b/postgresql-check-db-dir.in
@@ -17,7 +17,7 @@ service_name="$1"
 if [ -z "$PGDATA" ]; then
     echo $"You try to start '$service_name' service"
     echo $"but the required \$PGDATA environment variable is not set."
-    echo $"You should use the @userunitsdir@/$service_name.d/ANYTHING.conf"
+    echo $"You should use the @userunitsdir@/$service_name.service.d/ANYTHING.conf"
     echo $"configuration file to set \$PGDATA.  For more info see"
     echo $"the @README_DIST@ file."
 
@@ -58,7 +58,7 @@ then
     elif [ x`cat "$PGDATA/PG_VERSION"` = x"$PREVMAJORVERSION" ]
     then
         echo $"An old version of the database format was found."
-        echo $"Use \"postgresql-setup upgrade\" to upgrade to version $PGMAJORVERSION."
+        echo $"Use \"postgresql-setup --upgrade\" to upgrade to version $PGMAJORVERSION."
         echo $"See $PGDOCDIR/README.rpm-dist for more information."
         exit 1
     else
@@ -70,7 +70,7 @@ then
 else
     # No existing PGDATA! Warn the user to initdb it.
     echo $"\"$PGDATA\" is missing or empty."
-    echo $"Use \"postgresql-setup initdb\" to initialize the database cluster."
+    echo $"Use \"postgresql-setup --initdb\" to initialize the database cluster."
     echo $"See $PGDOCDIR/README.rpm-dist for more information."
     exit 1
 fi
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 ; }