Improve man pages structure

There are too many options in ipa-*-install scripts which makes it
difficult to read. This patch adds subsections to install script
online help and man pages to improve readability. No option has
been changed.

To further improve man pages:

1) All man pages were changed to have the same header and top-center
   title to provide united look.

2) Few typos in man pages have been fixed

https://fedorahosted.org/freeipa/ticket/1687

1 files changed, 69 insertions, 55 deletions

diff --git a/install/tools/ipa-server-install b/install/tools/ipa-server-install
index e8a48fad2..cb51b1daf 100755
--- a/install/tools/ipa-server-install
+++ b/install/tools/ipa-server-install
@@ -40,6 +40,7 @@ from ConfigParser import RawConfigParser
 import random
 import tempfile
 import nss.error
+from optparse import OptionGroup
 
 from ipaserver.install import dsinstance
 from ipaserver.install import krbinstance
@@ -103,88 +104,101 @@ def parse_options():
     # Guaranteed to give a random 200k range below the 2G mark (uint32_t limit)
     namespace = random.randint(1, 10000) * 200000
     parser = IPAOptionParser(version=version.VERSION)
-    parser.add_option("-r", "--realm", dest="realm_name",
+
+    basic_group = OptionGroup(parser, "basic options")
+    basic_group.add_option("-r", "--realm", dest="realm_name",
                       help="realm name")
-    parser.add_option("-n", "--domain", dest="domain_name",
+    basic_group.add_option("-n", "--domain", dest="domain_name",
                       help="domain name")
-    parser.add_option("-p", "--ds-password", dest="dm_password",
+    basic_group.add_option("-p", "--ds-password", dest="dm_password",
                       sensitive=True, help="admin password")
-    parser.add_option("-P", "--master-password",
+    basic_group.add_option("-P", "--master-password",
                       dest="master_password", sensitive=True,
                       help="kerberos master password (normally autogenerated)")
-    parser.add_option("-a", "--admin-password",
+    basic_group.add_option("-a", "--admin-password",
                       sensitive=True, dest="admin_password",
                       help="admin user kerberos password")
-    parser.add_option("-d", "--debug", dest="debug", action="store_true",
+    basic_group.add_option("--hostname", dest="host_name", help="fully qualified name of server")
+    basic_group.add_option("--ip-address", dest="ip_address",
+                      type="ip", ip_local=True,
+                      help="Master Server IP Address")
+    basic_group.add_option("-N", "--no-ntp", dest="conf_ntp", action="store_false",
+                      help="do not configure ntp", default=True)
+    basic_group.add_option("--idstart", dest="idstart", default=namespace, type=int,
+                      help="The starting value for the IDs range (default random)")
+    basic_group.add_option("--idmax", dest="idmax", default=0, type=int,
+                      help="The max value value for the IDs range (default: idstart+199999)")
+    basic_group.add_option("--no_hbac_allow", dest="hbac_allow", default=False,
+                      action="store_true",
+                      help="Don't install allow_all HBAC rule")
+    basic_group.add_option("--no-ui-redirect", dest="ui_redirect", action="store_false",
+                      default=True, help="Do not automatically redirect to the Web UI")
+    basic_group.add_option("-d", "--debug", dest="debug", action="store_true",
                       default=False, help="print debugging information")
-    parser.add_option("", "--selfsign", dest="selfsign", action="store_true",
+    basic_group.add_option("-U", "--unattended", dest="unattended", action="store_true",
+                      default=False, help="unattended (un)installation never prompts the user")
+    parser.add_option_group(basic_group)
+
+    cert_group = OptionGroup(parser, "certificate system options")
+    cert_group.add_option("", "--selfsign", dest="selfsign", action="store_true",
                       default=False, help="Configure a self-signed CA instance rather than a dogtag CA")
-    parser.add_option("", "--external-ca", dest="external_ca", action="store_true",
+    cert_group.add_option("", "--external-ca", dest="external_ca", action="store_true",
                       default=False, help="Generate a CSR to be signed by an external CA")
-    parser.add_option("", "--external_cert_file", dest="external_cert_file",
+    cert_group.add_option("", "--external_cert_file", dest="external_cert_file",
                       help="File containing PKCS#10 certificate")
-    parser.add_option("", "--external_ca_file", dest="external_ca_file",
+    cert_group.add_option("", "--external_ca_file", dest="external_ca_file",
                       help="File containing PKCS#10 of the external CA chain")
-    parser.add_option("--hostname", dest="host_name", help="fully qualified name of server")
-    parser.add_option("--ip-address", dest="ip_address",
-                      type="ip", ip_local=True,
-                      help="Master Server IP Address")
-    parser.add_option("--setup-dns", dest="setup_dns", action="store_true",
+    cert_group.add_option("--no-pkinit", dest="setup_pkinit", action="store_false",
+                      default=True, help="disables pkinit setup steps")
+    cert_group.add_option("--dirsrv_pkcs12", dest="dirsrv_pkcs12",
+                      help="PKCS#12 file containing the Directory Server SSL certificate")
+    cert_group.add_option("--http_pkcs12", dest="http_pkcs12",
+                      help="PKCS#12 file containing the Apache Server SSL certificate")
+    cert_group.add_option("--pkinit_pkcs12", dest="pkinit_pkcs12",
+                      help="PKCS#12 file containing the Kerberos KDC SSL certificate")
+    cert_group.add_option("--dirsrv_pin", dest="dirsrv_pin", sensitive=True,
+                      help="The password of the Directory Server PKCS#12 file")
+    cert_group.add_option("--http_pin", dest="http_pin", sensitive=True,
+                      help="The password of the Apache Server PKCS#12 file")
+    cert_group.add_option("--pkinit_pin", dest="pkinit_pin",
+                      help="The password of the Kerberos KDC PKCS#12 file")
+    cert_group.add_option("--subject", action="callback", callback=subject_callback,
+                      type="string",
+                      help="The certificate subject base (default O=<realm-name>)")
+    parser.add_option_group(cert_group)
+
+    dns_group = OptionGroup(parser, "DNS options")
+    dns_group.add_option("--setup-dns", dest="setup_dns", action="store_true",
                       default=False, help="configure bind with our zone")
-    parser.add_option("--forwarder", dest="forwarders", action="append",
+    dns_group.add_option("--forwarder", dest="forwarders", action="append",
                       type="ip", help="Add a DNS forwarder")
-    parser.add_option("--no-forwarders", dest="no_forwarders", action="store_true",
+    dns_group.add_option("--no-forwarders", dest="no_forwarders", action="store_true",
                       default=False, help="Do not add any DNS forwarders, use root servers instead")
-    parser.add_option("--reverse-zone", dest="reverse_zone", help="The reverse DNS zone to use")
-    parser.add_option("--no-reverse", dest="no_reverse", action="store_true",
+    dns_group.add_option("--reverse-zone", dest="reverse_zone", help="The reverse DNS zone to use")
+    dns_group.add_option("--no-reverse", dest="no_reverse", action="store_true",
                       default=False, help="Do not create reverse DNS zone")
-    parser.add_option("--zonemgr", action="callback", callback=zonemgr_callback,
+    dns_group.add_option("--zonemgr", action="callback", callback=zonemgr_callback,
                       type="string",
                       help="DNS zone manager e-mail address. Defaults to root")
-    parser.add_option("--zone-notif", dest="zone_notif",
+    dns_group.add_option("--zone-notif", dest="zone_notif",
                       action="store_true", default=False,
                       help="Let name server receive notification when a new zone is added." \
                            "Zone refresh is turned off when zone notification is enabled")
-    parser.add_option("--zone-refresh", dest="zone_refresh",
+    dns_group.add_option("--zone-refresh", dest="zone_refresh",
                       default=DNS_ZONE_REFRESH, type="int",
                       help="A delay between checks for new DNS zones. Defaults to %d" \
                               % DNS_ZONE_REFRESH)
-    parser.add_option("-U", "--unattended", dest="unattended", action="store_true",
-                      default=False, help="unattended installation never prompts the user")
-    parser.add_option("", "--uninstall", dest="uninstall", action="store_true",
-                      default=False, help="uninstall an existing installation")
-    parser.add_option("-N", "--no-ntp", dest="conf_ntp", action="store_false",
-                      help="do not configure ntp", default=True)
-    parser.add_option("--no-pkinit", dest="setup_pkinit", action="store_false",
-                      default=True, help="disables pkinit setup steps")
-    parser.add_option("--dirsrv_pkcs12", dest="dirsrv_pkcs12",
-                      help="PKCS#12 file containing the Directory Server SSL certificate")
-    parser.add_option("--http_pkcs12", dest="http_pkcs12",
-                      help="PKCS#12 file containing the Apache Server SSL certificate")
-    parser.add_option("--pkinit_pkcs12", dest="pkinit_pkcs12",
-                      help="PKCS#12 file containing the Kerberos KDC SSL certificate")
-    parser.add_option("--dirsrv_pin", dest="dirsrv_pin", sensitive=True,
-                      help="The password of the Directory Server PKCS#12 file")
-    parser.add_option("--http_pin", dest="http_pin", sensitive=True,
-                      help="The password of the Apache Server PKCS#12 file")
-    parser.add_option("--pkinit_pin", dest="pkinit_pin",
-                      help="The password of the Kerberos KDC PKCS#12 file")
-    parser.add_option("--no-host-dns", dest="no_host_dns", action="store_true",
+    dns_group.add_option("--no-host-dns", dest="no_host_dns", action="store_true",
                       default=False,
                       help="Do not use DNS for hostname lookup during installation")
+    parser.add_option_group(dns_group)
+
+    uninstall_group = OptionGroup(parser, "uninstall options")
+    uninstall_group.add_option("", "--uninstall", dest="uninstall", action="store_true",
+                      default=False, help="uninstall an existing installation. The uninstall can " \
+                                          "be run with --unattended option")
+    parser.add_option_group(uninstall_group)
 
-    parser.add_option("--idstart", dest="idstart", default=namespace, type=int,
-                      help="The starting value for the IDs range (default random)")
-    parser.add_option("--idmax", dest="idmax", default=0, type=int,
-                      help="The max value value for the IDs range (default: idstart+199999)")
-    parser.add_option("--subject", action="callback", callback=subject_callback,
-                      type="string",
-                      help="The certificate subject base (default O=<realm-name>)")
-    parser.add_option("--no_hbac_allow", dest="hbac_allow", default=False,
-                      action="store_true",
-                      help="Don't install allow_all HBAC rule")
-    parser.add_option("--no-ui-redirect", dest="ui_redirect", action="store_false",
-                      default=True, help="Do not automatically redirect to the Web UI")
     options, args = parser.parse_args()
     safe_options = parser.get_safe_opts(options)