From ee76824bd773ca91a0e76af61d96547ff4b196ba Mon Sep 17 00:00:00 2001
From: Tim Bielawa <tbielawa@redhat.com>
Date: Tue, 27 Sep 2016 08:14:18 -0700
Subject: Add a manpage for atomic-openshift-installer

---
 utils/Makefile                                     |  21 +++
 utils/docs/man/man1/atomic-openshift-installer.1   | 186 +++++++++++++++++++++
 .../man1/atomic-openshift-installer.1.asciidoc.in  | 167 ++++++++++++++++++
 3 files changed, 374 insertions(+)
 create mode 100644 utils/docs/man/man1/atomic-openshift-installer.1
 create mode 100644 utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in

diff --git a/utils/Makefile b/utils/Makefile
index 79c27626a..078d6f184 100644
--- a/utils/Makefile
+++ b/utils/Makefile
@@ -25,6 +25,12 @@ NAME := oo-install
 TESTPACKAGE := oo-install
 SHORTNAME := ooinstall
 
+# This doesn't evaluate until it's called. The -D argument is the
+# directory of the target file ($@), kinda like `dirname`.
+ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
+MANPAGES := docs/man/man1/atomic-openshift-installer.1
+VERSION := 1.3
+
 sdist: clean
 	python setup.py sdist
 	rm -fR $(SHORTNAME).egg-info
@@ -35,6 +41,21 @@ clean:
 	@rm -fR build dist rpm-build MANIFEST htmlcov .coverage cover ooinstall.egg-info oo-install
 	@rm -fR $(NAME)env
 
+
+# To force a rebuild of the docs run 'touch' on any *.in file under
+# docs/man/man1/
+docs: $(MANPAGES)
+
+# Regenerate %.1.asciidoc if %.1.asciidoc.in has been modified more
+# recently than %.1.asciidoc.
+%.1.asciidoc: %.1.asciidoc.in
+	sed "s/%VERSION%/$(VERSION)/" $< > $@
+
+# Regenerate %.1 if %.1.asciidoc or VERSION has been modified more
+# recently than %.1. (Implicitly runs the %.1.asciidoc recipe)
+%.1: %.1.asciidoc
+	$(ASCII2MAN)
+
 viewcover:
 	xdg-open cover/index.html
 
diff --git a/utils/docs/man/man1/atomic-openshift-installer.1 b/utils/docs/man/man1/atomic-openshift-installer.1
new file mode 100644
index 000000000..8800b5d13
--- /dev/null
+++ b/utils/docs/man/man1/atomic-openshift-installer.1
@@ -0,0 +1,186 @@
+'\" t
+.\"     Title: atomic-openshift-installer
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 09/27/2016
+.\"    Manual: atomic-openshift-installer
+.\"    Source: atomic-openshift-utils 1.3
+.\"  Language: English
+.\"
+.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/27/2016" "atomic\-openshift\-utils 1\&.3" "atomic\-openshift\-installer"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+atomic-openshift-installer \- Interactive OpenShift Container Platform installer
+.SH "SYNOPSIS"
+.sp
+atomic\-openshift\-installer [OPTIONS] COMMAND [OPTS]
+.SH "DESCRIPTION"
+.sp
+\fBatomic\-openshift\-installer\fR makes the process for installing OSE or AEP easier by interactively gathering the data needed to run on each host\&. It can also be run in unattended mode if provided with a configuration file\&.
+.SH "OPTIONS"
+.sp
+The following options are common to all commands\&.
+.PP
+\fB\-u\fR, \fB\-\-unattended\fR
+.RS 4
+Run installer in
+\fBunattended\fR
+mode\&. You will not be prompted to answer any questions\&.
+.RE
+.PP
+\fB\-c\fR, \fB\-\-configuration\fR \fIPATH\fR
+.RS 4
+Provide an alternate
+\fIPATH\fR
+to an
+\fIinstaller\&.cfg\&.yml\fR
+file\&.
+.RE
+.PP
+\fB\-a\fR \fIDIRECTORY\fR, \fB\-\-ansible\-playbook\-directory\fR \fIDIRECTORY\fR
+.RS 4
+Manually set the
+\fIDIRECTORY\fR
+to look for Ansible playbooks in\&.
+.RE
+.PP
+\fB\-\-ansible\-log\-path\fR \fIPATH\fR
+.RS 4
+Specify the
+\fIPATH\fR
+of the directory to save Ansible logs in\&.
+.RE
+.PP
+\fB\-v\fR, \fB\-\-verbose\fR
+.RS 4
+Run the installer with more verbosity\&.
+.RE
+.PP
+\fB\-d\fR, \fB\-\-debug\fR
+.RS 4
+Enable installer debugging\&. Logs are saved in
+\fI/tmp/installer\&.txt\fR\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Show the usage help and exit\&.
+.RE
+.SH "COMMANDS"
+.sp
+\fBatomic\-openshift\-installer\fR has three modes of operation:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fBinstall\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fBuninstall\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fBupgrade\fR
+.RE
+.sp
+The options specific to each command are described in the following sections\&.
+.SH "INSTALL"
+.sp
+The \fBinstall\fR command will guide you throgh steps required to install an OpenShift Container Platform\&. After all of the required information has been collected (target hosts, storage options, high\-availability) the installation will begin\&.
+.PP
+\fB\-f\fR, \fB\-\-force\fR
+.RS 4
+Forces an installation\&. This means that hosts with existing installations will be reinstalled if required\&.
+.RE
+.PP
+\fB\-\-gen\-inventory\fR
+.RS 4
+Generate an Ansible inventory file and exit\&. The default location for the inventory file is
+\fI~/\&.config/openshift/hosts\fR\&.
+.RE
+.SH "UNINSTALL"
+.sp
+The \fBuninstall\fR command will uninstall OpenShift Container Platform from your target hosts\&. This command has no additional options\&.
+.SH "UPGRADE"
+.sp
+The \fBupgrade\fR command will upgrade a cluster of hosts to a newer version of the OpenShift Container Platform\&.
+.PP
+\fB\-l\fR, \fB\-\-latest\-minor\fR
+.RS 4
+Upgrade to the latest minor version\&. For example, if you are running version
+\fB3\&.2\&.1\fR
+then this could upgrade you to
+\fB3\&.2\&.2\fR\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-next\-major\fR
+.RS 4
+Upgrade to the latest major version\&. For example, if you are running version
+\fB3\&.2\fR
+then this could upgrade you to
+\fB3\&.3\fR\&.
+.RE
+.SH "FILES"
+.sp
+\fB~/\&.config/openshift/installer\&.cfg\&.yml\fR \(em Installer configuration file\&. Can be used to generate an inventory later or start an unattended installation\&.
+.sp
+\fB~/\&.config/openshift/hosts\fR \(em Generated Ansible inventory file\&. Used to run the Ansible playbooks for install, uninstall, and upgrades\&.
+.sp
+\fB/tmp/ansible\&.log\fR \(em The default location of the ansible log file\&.
+.sp
+\fB/tmp/installer\&.txt\fR \(em The location of the log file for debugging the installer\&.
+.SH "AUTHOR"
+.sp
+Red Hat OpenShift Productization team
+.sp
+For a complete list of contributors, please visit the GitHub charts page\&.
+.SH "COPYRIGHT"
+.sp
+Copyright \(co 2016 Red Hat, Inc\&.
+.sp
+\fBatomic\-openshift\-installer\fR is released under the terms of the ASL 2\&.0 license\&.
+.SH "SEE ALSO"
+.sp
+\fBansible\fR(1), \fBansible\-playbook\fR(1)
+.sp
+\fBThe openshift\-ansible GitHub Project\fR \(em https://github\&.com/openshift/openshift\-ansible/
+.sp
+\fBThe atomic\-openshift\-installer Documentation\fR \(em https://docs\&.openshift\&.com/container\-platform/3\&.3/install_config/install/quick_install\&.html
diff --git a/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
new file mode 100644
index 000000000..d695b98b6
--- /dev/null
+++ b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
@@ -0,0 +1,167 @@
+atomic-openshift-installer(1)
+=============================
+:man source:   atomic-openshift-utils
+:man version:  %VERSION%
+:man manual:   atomic-openshift-installer
+
+
+NAME
+----
+atomic-openshift-installer - Interactive OpenShift Container Platform installer
+
+
+SYNOPSIS
+--------
+atomic-openshift-installer [OPTIONS] COMMAND [OPTS]
+
+
+DESCRIPTION
+-----------
+
+**atomic-openshift-installer** makes the process for installing OSE or
+AEP easier by interactively gathering the data needed to run on each
+host. It can also be run in unattended mode if provided with a
+configuration file.
+
+
+OPTIONS
+-------
+
+The following options are common to all commands.
+
+*-u*, *--unattended*::
+
+Run installer in **unattended** mode. You will not be prompted to
+answer any questions.
+
+
+*-c*, *--configuration* 'PATH'::
+
+Provide an alternate 'PATH' to an 'installer.cfg.yml' file.
+
+
+*-a* 'DIRECTORY', *--ansible-playbook-directory* 'DIRECTORY'::
+
+Manually set the 'DIRECTORY' to look for Ansible playbooks in.
+
+
+*--ansible-log-path* 'PATH'::
+
+Specify the 'PATH' of the directory to save Ansible logs in.
+
+
+*-v*, *--verbose*::
+
+Run the installer with more verbosity.
+
+
+*-d*, *--debug*::
+
+Enable installer debugging. Logs are saved in '/tmp/installer.txt'.
+
+
+*-h*, *--help*::
+
+Show the usage help and exit.
+
+
+COMMANDS
+--------
+
+**atomic-openshift-installer** has three modes of operation:
+
+* **install**
+* **uninstall**
+* **upgrade**
+
+The options specific to each command are described in the following
+sections.
+
+
+
+INSTALL
+-------
+
+The **install** command will guide you throgh steps required to
+install an OpenShift Container Platform. After all of the required
+information has been collected (target hosts, storage options,
+high-availability) the installation will begin.
+
+*-f*, *--force*::
+
+Forces an installation. This means that hosts with existing
+installations will be reinstalled if required.
+
+*--gen-inventory*::
+
+Generate an Ansible inventory file and exit. The default location for
+the inventory file is '~/.config/openshift/hosts'.
+
+
+UNINSTALL
+---------
+
+The **uninstall** command will uninstall OpenShift Container Platform
+from your target hosts. This command has no additional options.
+
+
+UPGRADE
+-------
+
+The **upgrade** command will upgrade a cluster of hosts to a newer
+version of the OpenShift Container Platform.
+
+*-l*, *--latest-minor*::
+
+Upgrade to the latest minor version. For example, if you are running
+version **3.2.1** then this could upgrade you to **3.2.2**.
+
+*-n*, *--next-major*::
+
+Upgrade to the latest major version. For example, if you are running
+version **3.2** then this could upgrade you to **3.3**.
+
+
+
+FILES
+-----
+
+*~/.config/openshift/installer.cfg.yml* -- Installer configuration
+ file. Can be used to generate an inventory later or start an
+ unattended installation.
+
+*~/.config/openshift/hosts* -- Generated Ansible inventory file. Used
+ to run the Ansible playbooks for install, uninstall, and upgrades.
+
+*/tmp/ansible.log* -- The default location of the ansible log file.
+
+*/tmp/installer.txt* -- The location of the log file for debugging the
+ installer.
+
+
+AUTHOR
+------
+
+Red Hat OpenShift Productization team
+
+For a complete list of contributors, please visit the GitHub charts
+page.
+
+
+
+COPYRIGHT
+---------
+Copyright © 2016 Red Hat, Inc.
+
+**atomic-openshift-installer** is released under the terms of the ASL
+2.0 license.
+
+
+
+SEE ALSO
+--------
+*ansible*(1), *ansible-playbook*(1)
+
+*The openshift-ansible GitHub Project* -- <https://github.com/openshift/openshift-ansible/>
+
+*The atomic-openshift-installer Documentation* -- <https://docs.openshift.com/container-platform/3.3/install_config/install/quick_install.html>
-- 
cgit v1.2.3


From d831377f61a1c605725cafeee774891899dbe90b Mon Sep 17 00:00:00 2001
From: Tim Bielawa <tbielawa@redhat.com>
Date: Tue, 27 Sep 2016 13:50:26 -0700
Subject: Addresses most comments from @adellape

---
 .../man1/atomic-openshift-installer.1.asciidoc.in  | 24 +++++++++++-----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
index d695b98b6..64e5d14a3 100644
--- a/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
+++ b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
@@ -7,7 +7,7 @@ atomic-openshift-installer(1)
 
 NAME
 ----
-atomic-openshift-installer - Interactive OpenShift Container Platform installer
+atomic-openshift-installer - Interactive OpenShift Container Platform (OCP) installer
 
 
 SYNOPSIS
@@ -18,8 +18,8 @@ atomic-openshift-installer [OPTIONS] COMMAND [OPTS]
 DESCRIPTION
 -----------
 
-**atomic-openshift-installer** makes the process for installing OSE or
-AEP easier by interactively gathering the data needed to run on each
+**atomic-openshift-installer** makes the process for installing OCP
+easier by interactively gathering the data needed to run on each
 host. It can also be run in unattended mode if provided with a
 configuration file.
 
@@ -42,12 +42,12 @@ Provide an alternate 'PATH' to an 'installer.cfg.yml' file.
 
 *-a* 'DIRECTORY', *--ansible-playbook-directory* 'DIRECTORY'::
 
-Manually set the 'DIRECTORY' to look for Ansible playbooks in.
+Manually set the 'DIRECTORY' in which to look for Ansible playbooks.
 
 
 *--ansible-log-path* 'PATH'::
 
-Specify the 'PATH' of the directory to save Ansible logs in.
+Specify the 'PATH' of the directory in which to save Ansible logs.
 
 
 *-v*, *--verbose*::
@@ -82,10 +82,10 @@ sections.
 INSTALL
 -------
 
-The **install** command will guide you throgh steps required to
-install an OpenShift Container Platform. After all of the required
-information has been collected (target hosts, storage options,
-high-availability) the installation will begin.
+The **install** command will guide you through steps required to
+install an OCP cluster. After all of the required information has been
+collected (target hosts, storage options, high-availability), the
+installation will begin.
 
 *-f*, *--force*::
 
@@ -101,15 +101,15 @@ the inventory file is '~/.config/openshift/hosts'.
 UNINSTALL
 ---------
 
-The **uninstall** command will uninstall OpenShift Container Platform
-from your target hosts. This command has no additional options.
+The **uninstall** command will uninstall OCP from your target
+hosts. This command has no additional options.
 
 
 UPGRADE
 -------
 
 The **upgrade** command will upgrade a cluster of hosts to a newer
-version of the OpenShift Container Platform.
+version of OCP.
 
 *-l*, *--latest-minor*::
 
-- 
cgit v1.2.3


From 20a07aed5d105fdb06377b62f2e88f067963135f Mon Sep 17 00:00:00 2001
From: Tim Bielawa <tbielawa@redhat.com>
Date: Wed, 28 Sep 2016 08:07:49 -0700
Subject: Update spec file to install manpage

---
 openshift-ansible.spec                           |  5 +++--
 utils/docs/man/man1/atomic-openshift-installer.1 | 18 +++++++++---------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/openshift-ansible.spec b/openshift-ansible.spec
index e57dbfb1b..5e297cb2a 100644
--- a/openshift-ansible.spec
+++ b/openshift-ansible.spec
@@ -87,6 +87,8 @@ pushd utils
 mv -f %{buildroot}%{_bindir}/oo-install %{buildroot}%{_bindir}/atomic-openshift-installer
 mkdir -p %{buildroot}%{_datadir}/atomic-openshift-utils/
 cp etc/ansible.cfg %{buildroot}%{_datadir}/atomic-openshift-utils/ansible.cfg
+mkdir -p %{buildroot}%{_mandir}/man1/
+cp -v docs/man/man1/atomic-openshift-installer.1 %{buildroot}%{_mandir}/man1/
 popd
 
 # Base openshift-ansible files
@@ -219,7 +221,7 @@ Atomic OpenShift Utilities includes
 %{python_sitelib}/ooinstall*
 %{_bindir}/atomic-openshift-installer
 %{_datadir}/atomic-openshift-utils/ansible.cfg
-
+%{_mandir}/man1/*
 
 %changelog
 * Mon Sep 26 2016 Scott Dodson <sdodson@redhat.com> 3.4.2-1
@@ -2384,4 +2386,3 @@ Atomic OpenShift Utilities includes
 
 * Mon Oct 19 2015 Troy Dawson <tdawson@redhat.com> 3.0.2-1
 - Initial Package
-
diff --git a/utils/docs/man/man1/atomic-openshift-installer.1 b/utils/docs/man/man1/atomic-openshift-installer.1
index 8800b5d13..4da82191b 100644
--- a/utils/docs/man/man1/atomic-openshift-installer.1
+++ b/utils/docs/man/man1/atomic-openshift-installer.1
@@ -2,12 +2,12 @@
 .\"     Title: atomic-openshift-installer
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 09/27/2016
+.\"      Date: 09/28/2016
 .\"    Manual: atomic-openshift-installer
 .\"    Source: atomic-openshift-utils 1.3
 .\"  Language: English
 .\"
-.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/27/2016" "atomic\-openshift\-utils 1\&.3" "atomic\-openshift\-installer"
+.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/28/2016" "atomic\-openshift\-utils 1\&.3" "atomic\-openshift\-installer"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -28,13 +28,13 @@
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
 .SH "NAME"
-atomic-openshift-installer \- Interactive OpenShift Container Platform installer
+atomic-openshift-installer \- Interactive OpenShift Container Platform (OCP) installer
 .SH "SYNOPSIS"
 .sp
 atomic\-openshift\-installer [OPTIONS] COMMAND [OPTS]
 .SH "DESCRIPTION"
 .sp
-\fBatomic\-openshift\-installer\fR makes the process for installing OSE or AEP easier by interactively gathering the data needed to run on each host\&. It can also be run in unattended mode if provided with a configuration file\&.
+\fBatomic\-openshift\-installer\fR makes the process for installing OCP easier by interactively gathering the data needed to run on each host\&. It can also be run in unattended mode if provided with a configuration file\&.
 .SH "OPTIONS"
 .sp
 The following options are common to all commands\&.
@@ -59,14 +59,14 @@ file\&.
 .RS 4
 Manually set the
 \fIDIRECTORY\fR
-to look for Ansible playbooks in\&.
+in which to look for Ansible playbooks\&.
 .RE
 .PP
 \fB\-\-ansible\-log\-path\fR \fIPATH\fR
 .RS 4
 Specify the
 \fIPATH\fR
-of the directory to save Ansible logs in\&.
+of the directory in which to save Ansible logs\&.
 .RE
 .PP
 \fB\-v\fR, \fB\-\-verbose\fR
@@ -124,7 +124,7 @@ Show the usage help and exit\&.
 The options specific to each command are described in the following sections\&.
 .SH "INSTALL"
 .sp
-The \fBinstall\fR command will guide you throgh steps required to install an OpenShift Container Platform\&. After all of the required information has been collected (target hosts, storage options, high\-availability) the installation will begin\&.
+The \fBinstall\fR command will guide you through steps required to install an OCP cluster\&. After all of the required information has been collected (target hosts, storage options, high\-availability), the installation will begin\&.
 .PP
 \fB\-f\fR, \fB\-\-force\fR
 .RS 4
@@ -138,10 +138,10 @@ Generate an Ansible inventory file and exit\&. The default location for the inve
 .RE
 .SH "UNINSTALL"
 .sp
-The \fBuninstall\fR command will uninstall OpenShift Container Platform from your target hosts\&. This command has no additional options\&.
+The \fBuninstall\fR command will uninstall OCP from your target hosts\&. This command has no additional options\&.
 .SH "UPGRADE"
 .sp
-The \fBupgrade\fR command will upgrade a cluster of hosts to a newer version of the OpenShift Container Platform\&.
+The \fBupgrade\fR command will upgrade a cluster of hosts to a newer version of OCP\&.
 .PP
 \fB\-l\fR, \fB\-\-latest\-minor\fR
 .RS 4
-- 
cgit v1.2.3