catalyst-spec.5.txt: Clarify "within the loop" (squashfs)

When you build a livecd-stage2, you get an ISO, inside of which is
something like:

  # mount -o loop livecd.iso iso
  # tree iso
  iso/
  |-- # stuff from livecd/overlay
  |-- image.squashfs  # the compressed root filesystem
  |-- isolinux
  |   |-- # kernel
  |   |-- # and
  |   `-- # related help
  |-- livecd          # empty, probably just a marker
  `-- README.txt      # help for kernel command line options

Inside the image.squashfs (or image.*, as configured by
livecd/fstype) is the root filesystem:

  # mount -o loop iso/image.squashfs squashfs
  # ls squashfs
  bin   dev  home  media  opt   root  sbin  tmp  var
  boot  etc  lib   mnt    proc  run   sys   usr

So if you want to tweak the root filesystem, use livecd/root_overlay.
If you want to tweak the ISO filesystem, use livecd/overlay.

Signed-off-by: W. Trevor King <wking@tremily.us>

diff --git a/doc/catalyst-spec.5.txt b/doc/catalyst-spec.5.txt
index 10491d1164c7af1483c0f60eca0d5e01edba301d..4ec776d425bf5ef50ce368e0efb4b0b9c16d5a69 100644 (file)
--- a/doc/catalyst-spec.5.txt
+++ b/doc/catalyst-spec.5.txt
@@ -433,19 +433,21 @@ default motd even on official media.  This setting is supported by the
 `stage4` and `livecd` targets.
 
 *<target>/root_overlay*::
-This overlay is dropped onto the filesystem within the loop.  This can
-be used for such things as updating configuration files or adding
-anything else you would want within your target filesystem.  Files
-added here are available when `docache` is used.  We do not use this
-on the official media.  This setting is supported by the `stage4` and
-`livecd` targets.
+This overlay is dropped onto the filesystem within the loop
+(e.g. inside the soon-to-be squashfs).  This can be used for such
+things as updating configuration files or adding anything else you
+would want within your target filesystem.  Files added here are
+available when `docache` is used.  We do not use this on the official
+media.  This setting is supported by the `stage4` and `livecd`
+targets.
 
 *livecd/overlay*::
-This overlay is dropped onto the target filesystem and is outside any
-loop which has been configured (example: `/tmp/overlay-minimal`).
-This is typically used for adding the documentation, distfiles,
-snapshots, and stages to the official media.  These files will not be
-available if `docache` is enabled, as they are outside the loop.
+This overlay is dropped onto the target filesystem (i.e. the ISO) and
+is outside any loop (e.g. squashfs) which has been configured
+(example: `/tmp/overlay-minimal`).  This is typically used for adding
+the documentation, distfiles, snapshots, and stages to the official
+media.  These files will not be available if `docache` is enabled, as
+they are outside the loop.
 
 *<target>/xinitrc*::
 This is used by catalyst to copy the specified file to