README.md: small improvements

1 files changed, 51 insertions, 52 deletions

diff --git a/README.md b/README.md
index 3d8e09e..debe210 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Packer templates for network boot using OpenSLX-NG
 
-This repository provides a build system based on a Makefile and Packer/Ansible
+This repository provides a build system based on GNU Make and Packer/Ansible
 templates to create clean operating system images - using Packer to generate
 the base system and Ansible to further install software stacks. This repository
 contains a set of templates for CentOS and Ubuntu distributions as well as
@@ -36,14 +36,14 @@ substantially.  Note: VMware Player and VirtualBox are supported to build base
 images, i.e. simple unattended installations, they are not yet supported for
 the provisioning steps.
 
-## Usage
+## Preliminaries
 
 The file `base.json` contains default variables (VM, SSH) common to all
 templates and is always included during packer builds. This file controls the
 VM's hardware configuration, in particular the number of CPUs (`cpus`), the
 amount of RAM in bytes (`memory`) and the virtual disk size in bytes
 (`disk_size`). Adjust these as needed. The SSH variables specify the user
-connecting to the VM (`ssh_username`) and the time packer will try to connect
+connecting to the VM (`ssh_username`) and how long packer will try to connect
 to be VM before aborting a build (`ssh_timeout`). Note that the root password
 is expected to be specified as the `ROOTPW` environment variable, as explained
 later.
@@ -52,7 +52,7 @@ later.
 
 Distribution templates are saved in the root directory of this repository, e.g.
 `centos-7-x86_64.json`. To see a list of currently maintained distributions,
-refer to `make help` and look for 'Base image targets'.
+refer to `make help` and look for *Base image targets*.
 
 The kickstart/preseed configuration files needed for unattended installations
 (UAI) during the packer builds are stored in the `http` folder. The Packer
@@ -75,9 +75,9 @@ thereby looks for the `packer-templates/ansible-prov` directory or in the path
 specified by the environment variable `ANSIBLE_DIR_PROV`. Within the
 provisioning directory, it further looks for Ansible playbooks named
 `setup-*.yml`, e.g. `setup-flavor.yml`. Calling `make help` will list the
-playbooks detected under the section 'Provisioning images targets'.
+playbooks detected under the section *Provisioning images targets*.
 
-Note that the build system will *copy* the base image and only run the
+Note that the build system will **copy** the base image and only run the
 playbooks on these copies. This avoids generating the (same) base images for
 different provisioning run. However, the same `ROOTPW` must be used throughout
 various provisioning builds. Ansible will not be able to connect to the base
@@ -86,7 +86,7 @@ always symlinked to e.g. `flavor.latest`. These build directories also contain
 a copy of the ansible directory (`ANSIBLE_DIR_PROV`) used for that particular
 build.
 
-## Usage: Makefile
+## Usage
 
 A Makefile to build packer templates is provided for convenience. It
 automatically detects JSON files in the root directory and assumes them to be
@@ -99,7 +99,46 @@ VirtualBox and VMware builders are also supported to build base images, there
 is no support for the provisioning steps yet. If you still want to use either
 one, you can force it with the environment variable `BUILDER`.
 
-### Debugging
+#### Example for CentOS 7
+
+This example uses the template maintained in this repository
+`centos-7-x86_64.json`. This assumes `ROOTPW` is already in the environment:
+
+##### Generating base image
+
+```shell
+$ make centos-7-x86_64/base
+```
+
+##### Provision base image
+
+Assuming there is an Ansible playbook under `$(ANSIBLE_DIR_PROV)/setup-flavor.yml`:
+
+```shell
+$ make centos-7-x86_64/flavor
+```
+
+##### Generate boot files
+
+The ansible playbook generating the network boot files are maintained in
+another repository:
+```shell
+$ git clone https://git.openslx.org/openslx-ng/ansible-dracut
+```
+
+The Makefile looks in this repository's root directory for `ansible-dracut`.
+The path to `ansible-dracut` can also be specified via the environment variable
+`ANSIBLE_DIR_CORE`.  Once setup, you can generate boot files by appending
+`/boot` to your target (both base and provisioned targets are supported).
+
+```shell
+$ make centos-7-x86_64/flavor/boot
+```
+This generates the disk image under `centos-7-x86_64/flavor/rootfs-image` and
+the boot files under `centos-7-x86_64/flavor/boot/`.
+
+
+## Debugging
 
 For Packer builds on your local machine, you can use the environment variable
 `WINDOW` to control if the VM is started headlessly (default) or not
@@ -139,48 +178,10 @@ port in the stdout output, look for this line:
 ```
 Use a VNC viewer to connect to the VM using this port.
 
-### Example for CentOS 7
-
-This example uses the template maintained in this repository
-`centos-7-x86_64.json`. This assumes `ROOTPW` is already in the environment:
-
-#### Generating base image
-
-```shell
-$ make centos-7-x86_64/base
-```
-
-#### Provision base image
-
-Assuming there is an Ansible playbook under `$(ANSIBLE_DIR_PROV)/setup-flavor.yml`:
-
-```shell
-$ make centos-7-x86_64/flavor
-```
-
-#### Generate boot files
-
-The ansible playbook generating the network boot files are maintained in
-another repository:
-```shell
-$ git clone https://git.openslx.org/openslx-ng/ansible-dracut
-```
-
-The Makefile looks in this repository's root directory for `ansible-dracut`.
-The path to `ansible-dracut` can also be specified via the environment variable
-`ANSIBLE_DIR_CORE`.  Once setup, you can generate boot files by appending
-`/boot` to your target (both base and provisioned targets are supported).
-
-```shell
-$ make centos-7-x86_64/flavor/boot
-```
-This generates the disk image under `centos-7-x86_64/flavor/rootfs-image` and
-the boot files under `centos-7-x86_64/flavor/boot/`.
-
 ## TL;DR
 0) Export root password:
 ```shell
-$ export ROOTPW="s0mer4nd0mp4$$w0rd"
+$ export ROOTPW="s0mer4nd0mp455w0rd"
 ```
 1) Build base image:
 ```shell
@@ -190,8 +191,6 @@ $ make centos-7-x86_64/base
 ```shell
 $ make centos-7-x86_64/base/boot
 ```
-
-## Results Produces:
-* kernel & initramfs in centos-7-x86_64/base/boot/
-* main qcow2 image under centos-7-x86_64/base/rootfs-image
-
+##### Generates
+* kernel & initramfs in `centos-7-x86_64/base/boot/`
+* root filesystem as qcow2 image in `centos-7-x86_64/base/rootfs-image`