[postgresql] docu: document postgresql-setup in --help a little

[Pavel Raiskup]

commit ca2964b709a7132089a66bacab11d9bd3203eee3
Author: Pavel Raiskup <praiskup at redhat.com>
Date:   Thu Jan 9 20:16:54 2014 +0100

    docu: document postgresql-setup in --help a little
    
    Also automatically generate manual page from the help output.
    
    Version: 9.3.2-4

 postgresql-setup |   36 +++++++++++++++++++++++++++++++++++-
 postgresql.spec  |    9 +++++++--
 2 files changed, 42 insertions(+), 3 deletions(-)
---
diff --git a/postgresql-setup b/postgresql-setup
index ca70b4d..80e2483 100644
--- a/postgresql-setup
+++ b/postgresql-setup
@@ -2,6 +2,8 @@
 #
 # postgresql-setup - Initialization and upgrade operations for PostgreSQL
 
+test x"$PGSETUP_DEBUG" != x && set -x
+
 # PGVERSION is the full package version, e.g., 9.0.2
 # Note: the specfile inserts the correct value during package build
 PGVERSION=xxxx
@@ -25,6 +27,34 @@ if [ x"$SERVICE_NAME" = x ]; then
     SERVICE_NAME=postgresql
 fi
 
+# Pathname of the RPM distribution README
+README_RPM_DIST=xxxx
+
+USAGE_STRING=$"
+Usage: $0 {initdb|upgrade} [SERVICE_NAME]
+
+Script is aimed to help sysadmin with basic database cluster administration.
+
+The SERVICE_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_RPM_DIST.  The 'postgresql'
+string is used when no SERVICE_NAME is explicitly passed.
+
+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 upgraded to newer PostgreSQL major version,
+                e.g. from 9.1 to 9.2.
+
+Environment:
+  PGSETUP_INITDB_OPTIONS  Options carried by this variable are passed to
+                          subsequent call of \`initdb\` binary (see man
+                          initdb(1)).  This variable is used also during
+                          'upgrade' mode because the new cluster is actually
+                          re-initialized from the old one.
+  PGSETUP_DEBUG           Set to '1' if you want to see debugging output."
+
 # this parsing technique fails for PGDATA pathnames containing spaces,
 # but there's not much I can do about it given systemctl's output format...
 PGDATA=`systemctl show -p Environment "${SERVICE_NAME}.service" |
@@ -209,8 +239,12 @@ case "$1" in
     upgrade)
         upgrade
         ;;
+    --version)
+        # note that this output is at least useful for help2man processing
+        echo "postgresql-setup $PGVERSION"
+        ;;
     *)
-        echo $"Usage: $0 {initdb|upgrade} [ service_name ]"
+        echo "$USAGE_STRING"
         exit 2
 esac
 
diff --git a/postgresql.spec b/postgresql.spec
index 6f4c83c..586b472 100644
--- a/postgresql.spec
+++ b/postgresql.spec
@@ -109,7 +109,7 @@ Patch4: postgresql-config-comment.patch
 Patch5: postgresql-var-run-socket.patch
 Patch6: postgresql-man.patch
 
-BuildRequires: perl(ExtUtils::MakeMaker) glibc-devel bison flex gawk
+BuildRequires: perl(ExtUtils::MakeMaker) glibc-devel bison flex gawk help2man
 BuildRequires: perl(ExtUtils::Embed), perl-devel
 BuildRequires: readline-devel zlib-devel
 BuildRequires: systemd-units
@@ -367,6 +367,8 @@ sed -e 's|^PGVERSION=.*$|PGVERSION=%{version}|' \
 	-e 's|^README_RPM_DIST=.*$|README_RPM_DIST=%{_pkgdocdir}/%(basename %{SOURCE8})|' \
 	<%{SOURCE9} >postgresql-setup
 touch -r %{SOURCE9} postgresql-setup
+chmod +x postgresql-setup
+help2man -N -m "Postgresql RPM-dist manual" ./postgresql-setup -o postgresql-setup.1
 
 # prep the startup check script, including insertion of some values it needs
 sed -e 's|^PGVERSION=.*$|PGVERSION=%{version}|' \
@@ -634,6 +636,7 @@ install -d -m 755 $RPM_BUILD_ROOT%{_libdir}/pgsql/tutorial
 cp -p src/tutorial/* $RPM_BUILD_ROOT%{_libdir}/pgsql/tutorial
 
 install -m 755 postgresql-setup $RPM_BUILD_ROOT%{_bindir}/postgresql-setup
+install -p -m 644 postgresql-setup.1 $RPM_BUILD_ROOT%{_mandir}/man1
 
 install -m 755 postgresql-check-db-dir $RPM_BUILD_ROOT%{_bindir}/postgresql-check-db-dir
 
@@ -1041,6 +1044,7 @@ fi
 %{_mandir}/man1/pg_receivexlog.*
 %{_mandir}/man1/pg_resetxlog.*
 %{_mandir}/man1/postgres.*
+%{_mandir}/man1/postgresql-setup.*
 %{_mandir}/man1/postmaster.*
 %{_datadir}/pgsql/postgres.bki
 %{_datadir}/pgsql/postgres.description
@@ -1126,11 +1130,12 @@ fi
 %endif
 
 %changelog
-* Mon Jan 13 2014 Pavel Raiskup <praiskup at redhat.com> - 9.3.2-4
+* Mon Jan 20 2014 Pavel Raiskup <praiskup at redhat.com> - 9.3.2-4
 - postgresql-setup(upgrade): don't stop old server when it can not be started
 - postgresql-setup(initdb, upgrade): add $PGSETUP_INITDB_OPTIONS
 - postgresql-setup: do not pretend 'sh' compatibility
 - move script generation to proper place
+- postgresql-setup: document a little and genrate manual page
 
 * Fri Jan 10 2014 Pavel Raiskup <praiskup at redhat.com> - 9.3.2-3
 - build with -O3 on ppc64 (private #1051075)