commit f7211d501d7b8c81946c2cb685d8ee61a1c40ada
Author: Frederick Grose <fgrose@sugarlabs.org>
Date:   Tue Mar 19 18:44:37 2013 -0400

    Correct misleading information on the overlay, syncronize usage
    statements with documentation in livecd-iso-to-disk.pod

diff --git a/tools/livecd-iso-to-disk.sh b/tools/livecd-iso-to-disk.sh
index 1a87869..8a4caa0 100755
--- a/tools/livecd-iso-to-disk.sh
+++ b/tools/livecd-iso-to-disk.sh
@@ -55,8 +55,8 @@ usage() {
                  such as from a CD-ROM, DVD, or download.  It could also be the
                  device node reference for the mount point of another LiveOS
                  filesystem, including the currently-running one (such as a
-                 booted Live CD/DVD/USB, where /dev/live references the running
-                 image device).
+                 booted Live CD/DVD/USB, where /run/initramfs/livedev
+                 references the booted device).
 
              <target device>
                  This should be the device partition name for the attached,
@@ -81,8 +81,8 @@ usage() {
     running LiveOS image, the device node reference for an attached device with
     an installed LiveOS image, or a file backed by a block device with an
     installed LiveOS image.  If the operating system supports persistent
-    overlays for saving system changes, a pre-sized overlay may be included with
-    the installation.
+    overlays for saving system changes, a pre-sized overlay may be specified
+    for creation during the installation.
 
     Unless you request the --format option, the installation does not destroy
     data outside of the LiveOS, syslinux, & EFI folders on your target device.
@@ -92,21 +92,34 @@ usage() {
     LiveOS images provide embedded filesystems through the Device-mapper
     component of the Linux kernel.  The embedded filesystems exist within files
     such as /LiveOS/squashfs.img (the default compressed storage) or
-    /LiveOS/ext3fs.img (an uncompressed version) on the primary volume partition
-    of the storage device.  In use, these are read-only filesystems. Optionally,
-    one may specify a persistent LiveOS overlay to hold image-change snapshots
-    (that use write-once, difference-tracking storage) in the
-    /LiveOS/overlay-<device_id> file, which, *one should note*, always grows in
-    size due to the storage mechanism.  (The fraction of allocated space that
-    has been consumed by system activity and changes may be displayed by issuing
-    the 'dmsetup status' command in a terminal session of a running LiveOS
-    image.)  One way to conserve the unrecoverable, overlay file space, is to
-    specify a persistent home folder for user files, which will be saved in a
-    /LiveOS/home.img filesystem image file.  This file space is encrypted by
-    default, but is not compressed.  (One may bypass encryption with the
-    --unencrypted-home installation option.)  Files in this home folder may be
-    erased to recover and reuse their storage space.  The home.img file is also
-    convenient for backing up or swapping user account files.
+    /LiveOS/ext3fs.img (an uncompressed version) on the primary volume
+    partition of the storage device.  In use, these are read-only filesystems.
+    On boot, a temporary, read-write root filesystem overlay is provided.
+    Optionally, one may specify a fixed-sized, persistent overlay storage pool
+    in a /LiveOS/overlay-<device_id> file, which will hold root filesystem
+    changes via allocate-once, copy-on-write storage.
+
+    Should the overlay storage space, whether temporary or persistent, be
+    totally consumed, the filesystem will be flagged 'Invalid' and, if that
+    filesystem is the booted root filesystem, it will crash with Input/output
+    or Bus errors.  If such a crash occurs while using temporary storage space
+    for the overlay, a simple reboot will rectify the situation.  With
+    persistent storage, the situation is more dire and will require appending
+    'rd.live.overlay.reset' to the kernel command line on boot-up.  This will
+    reset the storage overlay to its initial, unused state (all changes are
+    lost).
+
+    One may check the number of allocated sectors of the total overlay storage
+    by issuing the 'dmsetup status' command in a terminal session of a running
+    LiveOS image.  *One should note* though, the number of allocated sectors in
+    the overlay always grows, even though the apparent size of the virtual root
+    filesystem may go up and down.  One way to conserve the overlay file space,
+    is to specify persistent home folder storage for user files, which will be
+    saved in a /LiveOS/home.img filesystem image file.  This file space is
+    encrypted by default, but is not compressed.  (One may bypass encryption
+    with the --unencrypted-home installation option.)  Files in this home
+    folder may be erased to reuse their storage space.  The home.img file is
+    also convenient for backing up or swapping user account files.
 
     OPTIONS
 
@@ -120,11 +133,12 @@ usage() {
         storage device.
 
     --format
-        Formats the target device and creates an MS-DOS partition table (or GPT
-        partition table, if the --efi option is passed).
+        Creates an MS-DOS partition table (or GPT partition table, if the --efi
+        option is passed) and formats an ext4 filesystem on the target device.
 
     --msdos
-        Forces format to use msdos instead of ext4.
+        Forces format to make an fat32 file system instead of an ext4 formatted
+        one.
 
     --reset-mbr
         Sets the Master Boot Record (MBR) of the target storage device to the
@@ -183,7 +197,6 @@ usage() {
         Used when installing multiple image copies to signal configuration of
         the boot files for the image in the --livedir <dir> parameter.
 
-
     --livedir <dir>
         Used with multiple image installations to designate the directory <dir>
         for the particular image.
@@ -199,50 +212,47 @@ usage() {
 
     --swap-size-mb <size>
         Sets up a swap file of <size> mebibytes (integer values only) on the
-        target device.
+        target device.  A maximum <size> of 2047 MiB is permitted for
+        vfat-formatted devices.
 
     --overlay-size-mb <size>
         This option sets the overlay size in mebibytes (integer values only).
-        The overlay makes persistent storage available to the live operating
-        system, if the operating system supports it.  The persistent LiveOS
-        overlay holds image-change snapshots (using write-once, difference-
-        tracking  storage) in the /LiveOS/overlay-<device_id> file, which, *one
-        should note*, always grows in size due to the storage mechanism.  (The
-        fraction of allocated space that has been consumed may be displayed by
-        issuing the 'dmsetup status' command in a terminal session of a running
-        LiveOS installation.)  One way to conserve the unrecoverable, overlay
-        file space, is to specify a persistent home folder for user files, see
-        --home-size-mb below.  The target storage device must have enough free
-        space for the image and the overlay.  A maximum <size> of 2047 MiB is
-        permitted for vfat-formatted devices.  If there is insufficient room on
-        your device, you will be given information to help in adjusting your
-        settings.
+        The overlay is a fixed-sized, persistent storage pool of sectors in a
+        /LiveOS/overlay-<device_id> file, which will hold root filesystem
+        changes via allocate-once, copy-on-write storage.  (See the Description
+        section above for some important limitations of this storage.)  One way
+        to conserve the limited, overlay file space, is to specify a persistent
+        home folder for user files, see --home-size-mb below.  The target
+        storage device must have enough free space for the image and the
+        overlay.  A maximum <size> of 2047 MiB is permitted for vfat-formatted
+        devices.  If there is insufficient room on your device, you will be
+        given information to help in adjusting your settings.
 
     --home-size-mb <size>
         Sets the home directory size in mebibytes (integer values only).  A
         persistent home directory will be made in the /LiveOS/home.img
-        filesystem image file.  This file space is encrypted by default, but not
-        compressed  (one may bypass encryption with the --unencrypted-home
-        installation option).  Files in this home folder may be erased to
-        recover and reuse their storage space.  The target storage device must
-        have enough free space for the image, any overlay, and the home
-        directory.  Note that the --delete-home option must also be selected to
-        replace an existing persistent home with a new, empty one.  A maximum
-        <size> of 2047 MiB is permitted for vfat-formatted devices.  If there is
-        insufficient room on your device, you will be given information to help
-        in adjusting your settings.
+        filesystem image file.  This file space is encrypted by default, but
+        not compressed  (one may bypass encryption with the --unencrypted-home
+        installation option).  Files in this home folder may be erased to reuse
+        their storage space.  The target storage device must have enough free
+        space for the image, any overlay, and the home directory.  Note that
+        the --delete-home option must also be selected to replace an existing
+        persistent home with a new, empty one.  A maximum <size> of 2047 MiB is
+        permitted for vfat-formatted devices.  If there is insufficient room on
+        your device, you will be given information to help in adjusting your
+        settings.
 
     --delete-home
         To prevent unwitting deletion of user files, this option must be
         explicitly selected when the option --home-size-mb <size> is selected
-        and there is an existing persistent home directory on the target device.
+        and an existing persistent home filesystem is on the target device.
 
     --crypted-home   (default that only applies to new home-size-mb requests)
-        Specifies the default option to encrypt a new persistent home directory
-        if --home-size-mb <size> is specified.
+        Specifies the default option to encrypt a new persistent home
+        filesystem if --home-size-mb <size> is specified.
 
     --unencrypted-home
-        Prevents the default option to encrypt a new persistent home directory.
+        Prevents the default encryption of a new persistent home filesystem.
 
     CONTRIBUTORS