Minor documentation updates

Some minor things after looking at these parts.

The dib-run-parts element doesn't do any of the copying any more, so
these comments are wrong.

The reason for the multiple mounts in the bind mount was non-obvious
to modern eyes (as util-linux has handled this for some time).

Formatting fix for the rst

Change-Id: Idb4c9ff32c49aced2c68a5c905bf7a8b2832a5a2

diskimage_builder/lib/common-functions

@@ -14,9 +14,9 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-# This is the "internal" version of dib-run-parts.  Note the currently
+# This is the "internal" verison of dib-run-parts.  If you modify
-# this is copied by the dib-run-parts element into the chroot.  If you
+# this, be aware that it needs to run both inside and outside the
-# modify this, be aware that it needs to run in both contexts.
+# chroot environment, so it needs to be very generic.
 DIB_RUN_PARTS=${_LIB}/dib-run-parts
 
 function tmpfs_check() {

diskimage_builder/lib/img-functions

@@ -67,19 +67,20 @@ function run_d_in_target () {
     # mount it into the target and then execute run-parts in a chroot
     if [ -d ${TMP_HOOKS_PATH}/$1.d ] ; then
       sudo mkdir $TMP_MOUNT_PATH/tmp/in_target.d
+      # Copy dib-run-parts to be visible inside chroot.  Note we leave
+      # this here because in the future we might like to use a
+      # different in-chroot runner that doesn't rely on the chroot
+      # having bash/glibc/etc (containers, micro-images, etc).
+      sudo cp ${DIB_RUN_PARTS} ${TMP_HOOKS_PATH}
+      # Note that bind mounting R/O is a two step process, and it
+      # wasn't until later util-linux that "bind,ro" worked as a
+      # single step, see
+      #  https://git.kernel.org/cgit/utils/util-linux/util-linux.git/commit/?id=9ac77b8a78452eab0612523d27fee52159f5016a
       sudo mount --bind ${TMP_HOOKS_PATH} $TMP_MOUNT_PATH/tmp/in_target.d
-      # Copy in dib-run-parts to run inside chroot.  Note, in the
-      # future, we might like to use a diffrent dib-run-parts for
-      # running inside the chroot that doesn't rely on bash.  For now
-      # they're the same.  Note also this gets cleaned up with the dir
-      # delete below.
-      sudo cp ${DIB_RUN_PARTS} ${TMP_MOUNT_PATH}/tmp/in_target.d
       sudo mount -o remount,ro,bind ${TMP_HOOKS_PATH} $TMP_MOUNT_PATH/tmp/in_target.d
       check_break before-$1 run_in_target bash
       [ -z "$break_outside_target" ] && in_target_arg="run_in_target" || in_target_arg=
       trap "check_break after-error $in_target_arg ${break_cmd:-bash}" ERR
-      # NOTE: this is the dib-run-parts copied into the chroot by the
-      # dib-run-parts element.
       run_in_target /tmp/in_target.d/dib-run-parts /tmp/in_target.d/$1.d
       trap - ERR
       check_break after-$1 run_in_target bash

doc/source/developer/developing_elements.rst

@@ -116,11 +116,11 @@ The phases are:
 ``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:
+  image.  Some examples of use would be
 
-    Run ``chkconfig`` to disable unneeded services
+    * Run ``chkconfig`` to disable unneeded services
-
+    * Clean the cache left by the package manager to reduce the size
-    Clean the cache left by the package manager to reduce the size of the image.
+      of the image.
 
   * runs: **in chroot**
 
@@ -154,7 +154,7 @@ The phases are:
   settings to use the image build environment HTTP proxy are removed here in
   the dpkg element.
 
-  * runs: outside chroot
+  * runs: **outside chroot**
   * inputs:
 
     * ``$ARCH=i386|amd64|armhf|arm64``