Update README formatting and content

This orders the phase subdirectories by execution order, adds
subheadings, and fixes some markdown formatting issues. This also
replaces all double-spaces after full-stops with single spaces.

Change-Id: I2d5526cbe4a902067fa9cad1456c35d13f81e183

README.md

@@ -142,7 +142,7 @@ element adds support for mellanox infiniband hardware to both the deploy
 ramdisk and the built images.
 
 Images must specify a base distribution image element. Currently base
-distribution elements exist for fedora, rhel, and ubuntu.  Other
+distribution elements exist for fedora, rhel, and ubuntu. Other
 distributions may be added in future, the infrastructure deliberately
 makes few assumptions about the exact operating system in use.
 The base image has opensshd running (a new key generated on first boot)
@@ -206,21 +206,59 @@ Conform to the following conventions:
   and not remounted into the filesystem image - if the mount point is needed
   again, your element will need to remount it at that point.
 
+### Phase Subdirectories ###
+
 Make as many of the following subdirectories as you need, depending on what
-part of the process you need to customise:
+part of the process you need to customise. The subdirectories are executed in
+the order given here. Scripts within the subdirectories should be named with a
+two-digit numeric prefix, and are executed in numeric order.
 
 * root.d: Create or adapt the initial root filesystem content. This is where
   alternative distribution support is added, or customisations such as
   building on an existing image. 
 
-  Runs outside the chroot on the host environment.
-  
   Only one element can use this at a time unless particular care is taken not
   to blindly overwrite but instead to adapt the context extracted by other
   elements.
 
+ * runs: outside chroot
  * inputs: $ARCH=i386|amd64|armhf $TARGET\_ROOT=/path/to/target/workarea
 
+* extra-data.d: pull in extra data from the host environment that hooks may
+  need during image creation. This should copy any data (such as SSH keys,
+  http proxy settings and the like) somewhere under $TMP\_HOOKS\_PATH.
+
+ * runs: outside chroot
+ * inputs: $TMP\_HOOKS\_PATH
+ * outputs: None
+
+* pre-install.d: Run code in the chroot before customisation or packages are
+  installed. A good place to add apt repositories.
+
+ * runs: in chroot
+
+* install.d: Runs after pre-install.d in the chroot. This is a good place to
+  install packages, chain into configuration management tools or do other
+  image specific operations.
+
+ * runs: in chroot
+
+* post-install.d: Run code in the chroot. This is a good place to perform
+  tasks you want to handle after the OS/application install but before the
+  first boot of the image. Some examples of use would be: Run chkconfig
+  to disable unneeded services and clean the cache left by the package
+  manager to reduce the size of the image.
+
+ * runs: in chroot
+
+* block-device.d: customise the block device that the image will be made on
+  (e.g. to make partitions). Runs after the target tree has been fully
+  populated but before the cleanup hook runs.
+
+ * runs: outside chroot
+ * inputs: $IMAGE\_BLOCK\_DEVICE={path} $TARGET\_ROOT={path}
+ * outputs: $IMAGE\_BLOCK\_DEVICE={path}
+
 * finalise.d: Perform final tuning of the root filesystem. Runs in a chroot
   after the root filesystem content has been copied into the mounted
   filesystem: this is an appropriate place to reset SELinux metadata, install
@@ -229,45 +267,29 @@ part of the process you need to customise:
   filesystem metadata and image itself. For most operations, post-install.d
   is preferred.
 
+ * runs: in chroot
+
 * cleanup.d: Perform cleanup of the root filesystem content. For
   instance, temporary settings to use the image build environment HTTP proxy
-  are removed here in the dpkg element. Runs outside the chroot on the host
+  are removed here in the dpkg element.
-  environment.
 
+ * runs: outside chroot
  * inputs: $ARCH=i386|amd64|armhf $TARGET\_ROOT=/path/to/target/workarea
 
-* block-device.d: customise the block device that the image will be made on
+### Environment Variables ###
-  (e.g. to make partitions). Runs outside the chroot, after the target tree
-  has been fully populated but before the cleanup hook runs.
 
- * outputs: $IMAGE\_BLOCK\_DEVICE={path}
+To set environment variables for other hooks, add a file to environment.d.
- * inputs: $IMAGE\_BLOCK\_DEVICE={path} $TARGET\_ROOT={path}
+This directory contains bash script snippets that are sourced before running
+scripts in each phase.
 
-* extra-data.d: pull in extra data from the host environment that hooks may
-  need during image creation. This should copy any data (such as SSH keys,
-  http proxy settings and the like) somewhere under $TMP\_HOOKS\_PATH.
 
- * outputs: None
+### Dependencies ###
- * inputs: $TMP\_HOOKS\_PATH
 
-* pre-install.d: Run code in the chroot before customisation or packages are
+Each element has a file named element-deps: a plain text, newline separated
-  installed. A good place to add apt repositories.
+list of elements which will be added to the list of elements built into the
+image at image creation time.
 
-* install.d: Runs after pre-install.d in the chroot. This is a good place to
+### First-boot files ###
-  install packages, chain into configuration management tools or do other
-  image specific operations.
-
-* post-install.d: Run code in the chroot. This is a good place to perform
-  tasks you want to handle after the OS/application install but before the
-  first boot of the image. Some examples of use would be: Run chkconfig
-  to disable unneeded services and clean the cache left by the package
-  manager to reduce the size of the image.
-
-* environment.d: Bash script snippets that are sourced before running scripts
-  in each phase. Use this to set an environment variable for other hooks.
-
-* element-deps : A plain text, newline separated list of elements which will
-  be added to the list of elements built into the image at image creation time.
 
 * first-boot.d: **DEPRECATED** Runs inside the image before
   rc.local. Scripts from here are good for doing per-instance
@@ -275,6 +297,8 @@ part of the process you need to customise:
   future release of diskimage-builder. The os-refresh-config element in
   tripleo-image-elements is recommended as a replacement.**
 
+### Ramdisk Elements ###
+
 Ramdisk elements support the following files in their element directories:
 
 * binary-deps.d : text files listing executables required to be fed into the 
@@ -304,13 +328,16 @@ possible approach to this would be to label elements as either a "driver",
 
 - Driver-specific elements should only contain the necessary bits for that
   driver:
+
       elements/
          driver-mellanox/
             init           - modprobe line
             install.d/
                10-mlx      - package installation
 
-- An element that installs and configures Nova might be a bit more complex:
+- An element that installs and configures Nova might be a bit more complex,
+  containing several scripts across several phases:
+
       elements/
          service-nova/
             source-repository-nova - register a source repository
@@ -329,6 +356,7 @@ possible approach to this would be to label elements as either a "driver",
   set of elements which express a distinct configuration of the same software
   components. For example, if one were to bake a region-specific SSL cert into
   the images deployed in each region, one might express it like this:
+
       elements/
          config-az1/
             first-boot.d/
@@ -340,20 +368,20 @@ possible approach to this would be to label elements as either a "driver",
 In this way, depending on the hardware and in which availability zone it is
 to be deployed, an image would be composed of:
 
-  zero or more driver-elements
+ * zero or more driver-elements
-  one or more service-elements
+ * one or more service-elements
-  zero or more config-elements
+ * zero or more config-elements
 
 It should be noted that this is merely a naming convention to assist in
 managing elements. Diskimage-builder is not, and should not be, functionally
 dependent upon specific element names.
 
-- diskimage-builder has the ability to retrieve source code for an element and
+diskimage-builder has the ability to retrieve source code for an element and
-  place it into a directory on the target image during the extra-data phase. The
+place it into a directory on the target image during the extra-data phase. The
-  default location/branch can then be overridden by the process running
+default location/branch can then be overridden by the process running
-  diskimage-builder, making it possible to use the same element to track more
+diskimage-builder, making it possible to use the same element to track more
-  then one branch of a git repository or to get source for a local cache. See
+then one branch of a git repository or to get source for a local cache. See
-  elements/source-repositories/README.md for more information.
+elements/source-repositories/README.md for more information.
 
 Debugging elements
 ------------------