advanced_install: tweaks per pier review

Author: sosiouxme

install_config/install/advanced_install.adoc

@@ -2328,7 +2328,7 @@ concern for the install restarting *docker* on the host.
 ----
 # atomic install --system \
     --storage=ostree \
-    --set INVENTORY_FILE=/path/to/inventory \//<1>
+    --set INVENTORY_FILE=/path/to/inventory \ <1>
 ifdef::openshift-enterprise[]
     registry.access.redhat.com/openshift3/ose-ansible:v3.7
 endif::[]
@@ -2338,11 +2338,12 @@ endif::[]
 ----
 <1> Specify the location on the local host for your inventory file.
 +
-This command initiates the cluster installation using the inventory file specified and the `root` user's
-SSH configuration, logging to the terminal as well as *_/var/log/ansible.log_*. The first time this is executed, the image is imported into
+This command initiates the cluster installation by using the inventory file specified and the `root` user's
+SSH configuration. It logs the output on the terminal and also saves it in the *_/var/log/ansible.log_* file.
+The first time this command is run, the image is imported into
 link:https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/content_management_guide/managing_ostree_content[OSTree]
-storage (system containers use this instead of *docker* daemon storage).
-Later executions re-use the stored image.
+storage (system containers use this rather than *docker* daemon storage).
+On subsequent runs, it reuses the stored image.
 +
 If for any reason the installation fails, before re-running the installer, see
 xref:installer-known-issues[Known Issues] to check for any specific instructions
@@ -2351,22 +2352,22 @@ or workarounds.
 [[running-the-advanced-installation-system-container-other-playbooks]]
 ==== Running Other Playbooks
 
-To run any other playbooks (for example, to run the
-xref:configuring-cluster-pre-install-checks[pre-install checks]
-before proceeding to install) using the containerized installer, you can
-specify a playbook with the `PLAYBOOK_FILE` environment variable. The
-default value is *_/usr/share/ansible/openshift-ansible/playbooks/byo/config.yml_*, which is the main cluster
-installation playbook, but you can set it to the path of another playbook
-inside the container.
+You can use the `PLAYBOOK_FILE` environment variable to specify other playbooks
+you want to run by using the containerized installer. The default value of the `PLAYBOOK_FILE` is
+*_/usr/share/ansible/openshift-ansible/playbooks/byo/config.yml_*, which is the
+main cluster installation playbook, but you can set it to the path of another
+playbook inside the container.
 
-For example:
+For example, to run the
+xref:configuring-cluster-pre-install-checks[pre-install checks] playbook before
+installation, use the following command:
 
 ----
 # atomic install --system \
     --storage=ostree \
     --set INVENTORY_FILE=/path/to/inventory \
-    --set PLAYBOOK_FILE=/usr/share/ansible/openshift-ansible/playbooks/byo/openshift-checks/pre-install.yml \//<1>
-    --set OPTS="-v" \//<2>
+    --set PLAYBOOK_FILE=/usr/share/ansible/openshift-ansible/playbooks/byo/openshift-checks/pre-install.yml \ <1>
+    --set OPTS="-v" \ <2>
 ifdef::openshift-enterprise[]
     registry.access.redhat.com/openshift3/ose-ansible:v3.7
 endif::[]
@@ -2386,9 +2387,8 @@ The installer image can also run as a *docker* container anywhere that *docker*
 
 [WARNING]
 ====
-This method should not be used to run the installer on one of the hosts being configured,
-as the install typically restarts *docker* on the host, which would disrupt the installer
-container's own execution.
+This method must not be used to run the installer on one of the hosts being configured,
+as the install may restart *docker* on the host, disrupting the installer container execution.
 ====
 
 [NOTE]
@@ -2399,60 +2399,55 @@ run with different entry points and contexts, so runtime parameters are not the
 
 At a minimum, when running the installer as a *docker* container you must provide:
 
-* SSH key(s) so that Ansible can reach your hosts.
+* SSH key(s), so that Ansible can reach your hosts.
 * An Ansible inventory file.
-* The location of an Ansible playbook to run against that inventory.
+* The location of the Ansible playbook to run against that inventory.
 
 Here is an example of how to run an install via *docker*.
 Note that this must be run by a non-`root` user with access to *docker*.
 
 ----
-$ docker run -t -u `id -u` \
-    -v $HOME/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa:Z \
-    -v $HOME/ansible/hosts:/tmp/inventory:Z \
-    -e INVENTORY_FILE=/tmp/inventory \
-    -e PLAYBOOK_FILE=playbooks/byo/config.yml \
-    -e OPTS="-v" \
+$ docker run -t -u `id -u` \ <1>
+    -v $HOME/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa:Z \ <2>
+    -v $HOME/ansible/hosts:/tmp/inventory:Z \ <3>
+    -e INVENTORY_FILE=/tmp/inventory \ <3>
+    -e PLAYBOOK_FILE=playbooks/byo/config.yml \ <4>
+    -e OPTS="-v" \ <5>
 ifdef::openshift-enterprise[]
     registry.access.redhat.com/openshift3/ose-ansible:v3.7
 endif::[]
 ifdef::openshift-origin[]
     docker.io/openshift/origin-ansible:v3.7
 endif::[]
 ----
-
-The following is a detailed explanation of the options used in the command above.
-
-* `-u `id -u`` makes the container run with the same UID as the current
+<1> `-u `id -u`` makes the container run with the same UID as the current
 user, which allows that user to use the SSH key inside the container (SSH
 private keys are expected to be readable only by their owner).
-
-* `-v $HOME/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa:Z` mounts your
+<2> `-v $HOME/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa:Z` mounts your
 SSH key (`$HOME/.ssh/id_rsa`) under the container user's `$HOME/.ssh`
 (*_/opt/app-root/src_* is the `$HOME` of the user in the container). If
 you mount the SSH key into a non-standard location you can add an
 environment variable with `-e ANSIBLE_PRIVATE_KEY_FILE=/the/mount/point`
 or set `ansible_ssh_private_key_file=/the/mount/point` as a variable in
 the inventory to point Ansible at it.
 +
-Note that the SSH key is mounted with the `:Z` flag: this is
+Note that the SSH key is mounted with the `:Z` flag. This is
 required so that the container can read the SSH key under
-its restricted SELinux context; this also means that your
+its restricted SELinux context. This also means that your
 original SSH key file will be re-labeled to something like
 `system_u:object_r:container_file_t:s0:c113,c247`. For more details
 about `:Z` please check the `docker-run(1)` man page. Keep this in mind
-when providing these volume mount specifications because this could
+when providing these volume mount specifications because this might
 have unexpected consequences: for example, if you mount (and therefore
 re-label) your whole `$HOME/.ssh` directory it will block the host's
 *sshd* from accessing your public keys to login. For this reason you
 may want to use a separate copy of the SSH key (or directory), so that
 the original file labels remain untouched.
-
-* `-v $HOME/ansible/hosts:/tmp/inventory:Z` and `-e INVENTORY_FILE=/tmp/inventory`
+<3> `-v $HOME/ansible/hosts:/tmp/inventory:Z` and `-e INVENTORY_FILE=/tmp/inventory`
 mount a static Ansible inventory file into the container as
 *_/tmp/inventory_* and set the corresponding environment variable to
 point at it. As with the SSH key, the inventory file SELinux labels may
-need to be relabeled via the `:Z` flag to allow reading in the container,
+need to be relabeled by using the `:Z` flag to allow reading in the container,
 depending on the existing label (for files in a user `$HOME` directory
 this is likely to be needed). So again you may prefer to copy the
 inventory to a dedicated location before mounting it.
@@ -2461,14 +2456,12 @@ The inventory file can also be downloaded from a web server if you specify
 the `INVENTORY_URL` environment variable, or generated dynamically using
 `DYNAMIC_SCRIPT_URL` to specify an executable script that provides a
 dynamic inventory.
-
-* `-e PLAYBOOK_FILE=playbooks/byo/config.yml` specifies the playbook
+<4> `-e PLAYBOOK_FILE=playbooks/byo/config.yml` specifies the playbook
 to run (in this example, the BYO installer) as a relative path from the
 top level directory of *openshift-ansible* content. The full path from the
 RPM can also be used, as well as the path to any other playbook file in
 the container.
-
-* `-e OPTS="-v"` supplies arbitrary command line options (in this case,
+<5> `-e OPTS="-v"` supplies arbitrary command line options (in this case,
 `-v` to increase verbosity) to the `ansible-playbook` command that runs
 inside the container.