Changed layout of README.txt slightly for better match with Wiki version.

When changes need to be made to README.txt and its Wiki version at
http://docs.slackware.com/slackware:liveslak I want to be able to
diff the two easily.

1 files changed, 201 insertions, 138 deletions

diff --git a/README.txt b/README.txt
index dff32a6..6d25257 100644
--- a/README.txt
+++ b/README.txt
@@ -19,23 +19,38 @@ In order to protect your sensitive private data in case you lose your USB stick
 
 The reasons I had for creating the Slackware Live Edition are as follows:
 
- - Provide a Live version of Slackware proper; i.e. show Slackware as it is, but without having to install it.  No hiding of kernel messages scrolling across the screen at boot; no custom wallpapers, etcetera.  Meant for educational, evaluation and demonstration purposes.
- - The target should be slackware-current, the bleeding edge.  Many people want to know what Slackware's development edition looks like but are hesitant to install slackware-current for fear that it breaks stuff and causes productivity loss.
- - Provide a way to generate a Live ISO with just a mirror of Slackware's packages as the source, fully scripted and deterministic.
- - Still be able to customize its content.  For instance provide stripped-down or minimalist versions of Slackware but also allow for the inclusion of 3rd party packages.
- - Option to create a bootable USB stick running Slackware Live (which is different from 'dd'-ing the hybrid ISO to a USB stick!)
- - KISS: Keep It Simple Stupid!
+  - Provide a Live version of Slackware proper; i.e. show Slackware as it is, but without having to install it.  No hiding of kernel messages scrolling across the screen at boot; no custom wallpapers, etcetera.  Meant for educational, evaluation and demonstration purposes.
+  - The target should be slackware-current, the bleeding edge.  Many people want to know what Slackware's development edition looks like but are hesitant to install slackware-current for fear that it breaks stuff and causes productivity loss.
+  - Provide a way to generate a Live ISO with just a mirror of Slackware's packages as the source, fully scripted and deterministic.
+  - Still be able to customize its content.  For instance provide stripped-down or minimalist versions of Slackware but also allow for the inclusion of 3rd party packages.
+  - Option to create a bootable USB stick running Slackware Live (which is different from 'dd'-ing the hybrid ISO to a USB stick!)
+  - KISS: Keep It Simple Stupid!
 
 
 ==== ISO variants ====
 
 
 The "liveslak" scripts can generate a variety of Slackware flavors:
- - a complete 64bit Slackware-current Live Edition (in a 2.6 GB ISO);
- - a slimmed-down XFCE ISO (700 MB) with XDM as the graphical login manager.  It fits on a CDROM medium or a 1 GB USB stick;
- -  a ISO image (3.1 GB) of Slackware64-current containing Plasma 5 instead of KDE 4, with an addition of several other packages from the alienBOB repositories: vlc, libreoffice, calibre, qbittorrent, ffmpeg, chromium, openjdk, veracrypt.
- - a Mate variant (1.7 GB) where KDE 4 has been replaced by Mate (a Gnome 2 fork);
- - a Cinnamon flavour (a fork of the Gnome 3 Shell replacing Slackware's KDE 4).
+  - a complete 64bit Slackware-current Live Edition (in a 2.6 GB ISO);
+  - a slimmed-down XFCE ISO (700 MB) with XDM as the graphical login manager.  It fits on a CDROM medium or a 1 GB USB stick;
+  -  a ISO image (3.1 GB) of Slackware64-current containing Plasma 5 instead of KDE 4, with an addition of several other packages from the alienBOB repositories: vlc, libreoffice, calibre, qbittorrent, ffmpeg, chromium, openjdk, veracrypt.
+  - a Mate variant (1.7 GB) where KDE 4 has been replaced by Mate (a Gnome 2 fork);
+  - a Cinnamon flavour (a fork of the Gnome 3 Shell replacing Slackware's KDE 4).
+  - a "Custom" variant which you can give your own name, its own package list and custom post-install configuration.
+
+
+===== Downloading ISO images =====
+
+
+Common download locations are:
+  * AlienBOB's's http://bear.alienbase.nl/mirrors/slackware-live/ (%%rsync://bear.alienbase.nl/mirrors/slackware-live/%%)
+  * Darren's http://slackware.uk/people/alien-slacklive/ (%%rsync://slackware.uk/people/alien-slacklive/%%)
+  * Willy's http://repo.ukdw.ac.id/slackware-live/
+  * Ryan's https://seattleslack.ryanpcmcquen.org/mirrors/slackware-live/
+  * Shasta's http://ftp.slackware.pl/pub/slackware-live/ (%%rsync://ftp.slackware.pl/slackware-live/%%)
+
+
+===== Enduser Documentation =====
 
 
 ==== Using the ISO image ====
@@ -55,7 +70,7 @@ A script is available which allows you to transfer the ISO image content to a US
 
 The USB stick will be erased and re-formatted when running this script!  Before inflicting any irreversible damage, the script will show you a prompt at which point you can evaluate whether it is safe to continue.
 
-This script, called 'iso2usb.sh', accepts the following parameters:
+This script, called 'iso2usb.sh', accepts the following parameters: <code>
   -c|--crypt size|perc       Add a LUKS encrypted /home ; parameter is the
                              requested size of the container in kB, MB, GB,
                              or as a percentage of free space.
@@ -73,16 +88,16 @@ This script, called 'iso2usb.sh', accepts the following parameters:
                              of a directory (for use on FAT filesystem).
   -P|--persistfile           Use an unencrypted 'persistence' file instead
                              of a directory (for use on FAT filesystem).
-
+</code>
 Examples:
 
- * Create a USB version of Slackware Live, where the USB stick is known to the system as '/dev/sdX. Note - the value for the output parameter is the device name of the stick and not one of its partitions!
+  * Create a USB version of Slackware Live, where the USB stick is known to the system as '/dev/sdX. Note - the value for the output parameter is the device name of the stick and not one of its partitions!
     # ./iso2usb.sh -i ~/download/slackware64-live-14.2.iso -o /dev/sdX
- * Create a USB Live like above, but this time adding an encrypted /home filesystem with 750 MB of space, and at the same time increase the wait time on boot to 15 seconds (useful for slow USB media that fail to start the Live OS otherwise):
+  * Create a USB Live like above, but this time adding an encrypted /home filesystem with 750 MB of space, and at the same time increase the wait time on boot to 15 seconds (useful for slow USB media that fail to start the Live OS otherwise):
     # ./iso2usb.sh -i slackware64-live-current.iso -o /dev/sdX -c 750M -w 15
- * Create a USB Live with an encrypted /home (allocating 30% of the stick's free space for /home) and where the persistent data will be stored in a container file instead of a directory:
+  * Create a USB Live with an encrypted /home (allocating 30% of the stick's free space for /home) and where the persistent data will be stored in a container file instead of a directory:
     # ./iso2usb.sh -i slackware64-live-current.iso -o /dev/sdX -c 30% -P
- * Create a USB Live with both the /home and the persistent data encrypted (the persistence filesystem will be 300 MB in size):
+  * Create a USB Live with both the /home and the persistent data encrypted (the persistence filesystem will be 300 MB in size):
     # ./iso2usb.sh -i slackware64-live-current.iso -o /dev/sdX -c 30% -C 300M
 
 You might have noticed that the "-P" parameter does not accept a size parameter.  This is because the unencrypted container file is created as a 'sparse' file that starts at zero size and is allowed to grow dynmically to a maximum of 90% of the initial free space on the Linux partition of the USB stick.
@@ -189,21 +204,24 @@ rescue => After initialization, you will be dropped in a
 
 
 The Live ISO contains four directories in the root of its filesystem:
- * EFI/
- * boot/
- * liveslak/
- * rootcopy/
+  * EFI/
+  * boot/
+  * liveslak/
+  * rootcopy/
 
 The USB variant with persistence may have an additional directory in the root:
- * persistence/
+  * persistence/
+
+  * The EFI/ directory contains the Grub configuration used when you boot the Live OS on a computer with UEFI.
+  * The boot/ directory contains the syslinux configuration used when the Live OS boots on a computer with a BIOS.  This directory also contains the kernel and initrd files which are used to actually boot the OS.
+  * The liveslak/ directory contains all the squashfs modules which are used to assemble the filesystem of the Live OS.  It contains three subdirectories:
+    * addons/ - modules which are stored in this directory will always be added t the Live filesystem unless you prevent that with a "noload=" boot parameter;
+    * optional/ - modules in this directory will not be added to the filesystem of the Live OS unless you force this with a "load=" boot parameter;
+    * system/ - this directory contains all the modules which were created by the "make_slackware_live.sh" script.  All these modules are numbered and the Live init script will use that to re-assemble the Live filesystem in the exact same order as they were created initially.
+    * rootcopy/ - this directory is empty by default.  Anything you (the user of the ISO) add to this directory will be copied verbatim into the filesystem by the init script when the Live OS boots.  You can use this feature for instance if you do not want to create a separate squashfs module file for your application configuration files.
+
 
- * The EFI/ directory contains the Grub configuration used when you boot the Live OS on a computer with UEFI.
- * The boot/ directory contains the syslinux configuration used when the Live OS boots on a computer with a BIOS.  This directory also contains the kernel and initrd files which are used to actually boot the OS.
- * The liveslak/ directory contains all the squashfs modules which are used to assemble the filesystem of the Live OS.  It contains three subdirectories:
-   * addons/ - modules which are stored in this directory will always be added t the Live filesystem unless you prevent that with a "noload=" boot parameter;
-   * optional/ - modules in this directory will not be added to the filesystem of the Live OS unless you force this with a "load=" boot parameter;
-   * system/ - this directory contains all the modules which were created by the "make_slackware_live.sh" script.  All these modules are numbered and the Live init script will use that to re-assemble the Live filesystem in the exact same order as they were created initially.
-   * rootcopy/ - this directory is empty by default.  Anything you (the user of the ISO) add to this directory will be copied verbatim into the filesystem by the init script when the Live OS boots.  You can use this feature for instance if you do not want to create a separate squashfs module file for your application configuration files.
+===== Developer Documentation =====
 
 
 ==== Scripts and tools ====
@@ -215,7 +233,7 @@ The USB variant with persistence may have an additional directory in the root:
 The first script:
 
 The script "make_slackware_live.sh" creates an ISO file as its output which contains the Live OS.
-Thanks to Linux kernel 4.x and the squashfs-tools package in Slackware, the process of creating a Slackware Live ISO requires *no* (re)compilation of Slackware content or installing 3rd party packages.
+Thanks to Linux kernel 4.x and the squashfs-tools package in Slackware, the process of creating a Slackware Live ISO requires **no** (re)compilation of Slackware content or installing 3rd party packages.
 
 The script's inner workings can be subdivided into several distinct stages.  For the full Slackware ISO the process stages are as follows:
 
@@ -225,15 +243,15 @@ The script's inner workings can be subdivided into several distinct stages.  For
 
 Stage one:
 
- * The script reads a package sequence for the Live variant and installs all packages in this sequence to subdirectories of a temporary directory tree.
- * Every Slackware package set (a, ap, d, ... , y) or package list (min, xbase, xapbase, ...) is installed into a separate 'root' directory.
- * Each of those root directories is "squashed" (using squashfs) into a separate squashfs module.  Such a module is a single archive file containing the compressed directory structure of the installed packages.
- * These module files are subsequently loop-mounted and then combined together into a single read-only directory structure using an "overlay mount".  The overlayfs is relatively new; earlier Live distros have been using aufs and unionfs to achieve similar functionality, but those were not part of any stock kernel source and therefore custom kernels had to be compiled for such a Live distro.
- * This "overlay assembly" is the filesystem that will be booted as the filesystem of the Live OS.
- * On 'top' of this series of overlayed read-only filesystems, a writable filesystem is added by the "make_slackware_live.sh" script.  This writable filesystem is used to store all the customizations to our distro that we want to be applied when Slackware Live boots up.  See the next section for more detail.
- * Note that when you boot the Live OS later on, another writable overlay will be used so capture any write operations performed by the OS.  You will perceive the Live OS as a real OS that can write and remove files.  That writable filesystem will be:
-   * a RAM-based filesystem when the Live OS runs without persistence.
-   * a directory or a loop-mounted container file on your USB stick, if you use a USB stick with persistence.
+  * The script reads a package sequence for the Live variant and installs all packages in this sequence to subdirectories of a temporary directory tree.
+  * Every Slackware package set (a, ap, d, ... , y) or package list (min, xbase, xapbase, ...) is installed into a separate 'root' directory.
+  * Each of those root directories is "squashed" (using squashfs) into a separate squashfs module.  Such a module is a single archive file containing the compressed directory structure of the installed packages.
+  * These module files are subsequently loop-mounted and then combined together into a single read-only directory structure using an "overlay mount".  The overlayfs is relatively new; earlier Live distros have been using aufs and unionfs to achieve similar functionality, but those were not part of any stock kernel source and therefore custom kernels had to be compiled for such a Live distro.
+  * This "overlay assembly" is the filesystem that will be booted as the filesystem of the Live OS.
+  * On 'top' of this series of overlayed read-only filesystems, a writable filesystem is added by the "make_slackware_live.sh" script.  This writable filesystem is used to store all the customizations to our distro that we want to be applied when Slackware Live boots up.  See the next section for more detail.
+  * Note that when you boot the Live OS later on, another writable overlay will be used so capture any write operations performed by the OS.  You will perceive the Live OS as a real OS that can write and remove files.  That writable filesystem will be:
+    * a RAM-based filesystem when the Live OS runs without persistence.
+    * a directory or a loop-mounted container file on your USB stick, if you use a USB stick with persistence.
 
 
 == Configure the Live filesystem with useful out-of-the-box defaults ==
@@ -241,16 +259,16 @@ Stage one:
 
 Stage two:
 
- * Some filesystem initialization is done when the overlay has been assembled:
-   * 'root' and 'live' user accounts are created,
-   * an initial environment for the accounts is configured,
-   * the desktop environment is pre-configured for first use,
-   * the liveslak scripts "makemod" and "iso2usb.sh" are copied to "/usr/local/sbin/" in the ISO for your convenience,
-   * if the Live system contains a huge kernel (all ISO variants except XFCE) then the "setup2hd" script and the Slackware installer files are copied to "/usr/local/sbin" and "/usr/share/liveslak" respectively,
-   * slackpkg is configured,
-   * a locate database is created,
-   * etc...
- * All these modifications are written to the writable filesystem that was created in the previous section. This filesystem will also be stored on the ISO as a squashfs module and when the Live OS boots, it will be mounted read-only just like all the other modules. Its name will be "0099-slackware_zzzconf-current-x86_64.sxz" or more generically "0099-slackware_zzzconf-$SLACKVERSION}-${ARCH}.sxz"
+  * Some filesystem initialization is done when the overlay has been assembled:
+    * 'root' and 'live' user accounts are created,
+    * an initial environment for the accounts is configured,
+    * the desktop environment is pre-configured for first use,
+    * the liveslak scripts "makemod" and "iso2usb.sh" are copied to "/usr/local/sbin/" in the ISO for your convenience,
+    * if the Live system contains a huge kernel (all ISO variants except XFCE) then the "setup2hd" script and the Slackware installer files are copied to "/usr/local/sbin" and "/usr/share/liveslak" respectively,
+    * slackpkg is configured,
+    * a locate database is created,
+    * etc...
+  * All these modifications are written to the writable filesystem that was created in the previous section. This filesystem will also be stored on the ISO as a squashfs module and when the Live OS boots, it will be mounted read-only just like all the other modules. Its name will be "0099-slackware_zzzconf-current-x86_64.sxz" or more generically "0099-slackware_zzzconf-$SLACKVERSION}-${ARCH}.sxz"
 
 
 == Configure the boot stage of the Live OS ==
@@ -258,8 +276,8 @@ Stage two:
 
 Stage three:
 
- * an initrd is generated, containing a modified "init" script (other Live distros call it a "linuxrc script") which re-assembles the overlay filesystem on boot and configures the Live OS according to the boot parameters (language, keyboard, timezone, runlevel, ...)
- * a slackware generic kernel plus the above initrd are added to a syslinux (for BIOS computers) and a grub2 (for UEFI computers) configuration.
+  * an initrd is generated, containing a modified "init" script (other Live distros call it a "linuxrc script") which re-assembles the overlay filesystem on boot and configures the Live OS according to the boot parameters (language, keyboard, timezone, runlevel, ...)
+  * a slackware generic kernel plus the above initrd are added to a syslinux (for BIOS computers) and a grub2 (for UEFI computers) configuration.
 
 
 == Create the ISO image ==
@@ -267,8 +285,8 @@ Stage three:
 
 Stage four:
 
- * a bootable ISO file is created using mkisofs.
- * the "isohybrid" command is run on the ISO so that you can "dd" or "cp" the ISO to a USB stick and thus create a bootable USB media.
+  * a bootable ISO file is created using mkisofs.
+  * the "isohybrid" command is run on the ISO so that you can "dd" or "cp" the ISO to a USB stick and thus create a bootable USB media.
 
 Done! You can find the ISO file and its MD5 checksum in the /tmp directory.
 
@@ -292,9 +310,9 @@ The iso2usb.sh script only supports creating and configuring an encrypted /home,
 == Using a container file for storing persistence data ==
 
 A second type of encrypted container exists, which can be used for storing your persistence data.  The Live init script will check if it needs to enable persistence in this order:
- # is the USB filesystem writable?  If so,
-   # does a directory /persistence exist? If so, use that; if not,
-   # does a file /persistence.img exist?  If so, mount the file and if it is an encrypted container, ask for a passphrase during boot.
+  - is the USB filesystem writable?  If so,
+    - does a directory /persistence exist? If so, use that; if not,
+    - does a file /persistence.img exist?  If so, mount the file and if it is an encrypted container, ask for a passphrase during boot.
 
 == Adding USB wait time ==
 
@@ -311,10 +329,10 @@ The "makemod" script allows you to create a Slackware Live module easily, with a
 Usage:
   # makemod <packagename|directory> modulename.sxz
 
- * The first parameter is either the full path to a Slackware package, or else a directory.
-   * If a packagename is supplied as first parameter, it will be installed into a temporary directory using Slackware's "installpkg". The content of the temporary directory will be squashed into a module by the "squashfs" program.
-   * If a directoryname is supplied, its content will be squashed into a module by the "squashfs" program..
- * The second parameter is the full pathname of the output module which will be created.
+  * The first parameter is either the full path to a Slackware package, or else a directory.
+    * If a packagename is supplied as first parameter, it will be installed into a temporary directory using Slackware's "installpkg". The content of the temporary directory will be squashed into a module by the "squashfs" program.
+    * If a directoryname is supplied, its content will be squashed into a module by the "squashfs" program..
+  * The second parameter is the full pathname of the output module which will be created.
 
 You can copy the module you just created (minding the filename conventions for a Slackware Live module, see paragraph "Slackware Live module format") to either the optional/ or to the addon/ directory of your Live OS. If you copy it to the optional/ or addon/ directory of the liveslak sources then "make_slackware_live.sh" will use the module when creating the ISO image.
 
@@ -341,39 +359,38 @@ Liveslak is a directory tree containing scripts, bitmaps and configuration files
 
 
 The toplevel 'liveslak' directory contains the following subdirectories:
- * EFI/ - contains the skeleton for boot support on UEFI computers.  Some of the UEFI configuration files are dynamically generated by the "make_slackware_live.sh" script.
- * addons/ - squashfs modules placed in this directory will be loaded into the Live filesystem when the OS boots.
- * graphics/ - squashfs modules for proprietary GPU support (Nvidia) can be placed here. The module(s) will be copied to addons/ by the "make_slackware_live.sh" script for any Live Desktop Environment (except pure Slackware) that might profit from proprietary driver support.
- * local64/ , local/ - these directories can contain Slackware packages considered 'local' i.e. not belonging to any repository.  The package(s) will be converted to squashfs module(s) by the "make_slackware_live.sh" script, copied to the "addons/" subdirectory in the ISO and loaded into the Live filesystem when the OS boots.
- * optional/ - squashfs modules placed in this directory will not automatically be loaded into the Live filesystem when the OS boots.  You need to pass "load=[mod]" boot parameter to load any of these.
- * pkglists/ - definition files of 3rd party repositories (*.conf) and the package lists to be used from those repositories (*.lst) must be placed in this directory.
- * skel/ - contains compressed tarballs (whose filenames must match wildcard "skel*.txz"). These files will be extracted to the "/etc/skel" directory in the Live filesystem.
- * syslinux/  - contains the skeleton for boot support on BIOS computers.  Some of its files are dynamically generated by the "make_slackware_live.sh" script.
- * xdm/ - graphical Slackware theme for the XDM graphical session manager for those ISO variants which do not ship with GDM, KDM or SDDM.
+  * EFI/ - contains the skeleton for boot support on UEFI computers.  Some of the UEFI configuration files are dynamically generated by the "make_slackware_live.sh" script.
+  * addons/ - squashfs modules placed in this directory will be loaded into the Live filesystem when the OS boots.
+  * graphics/ - squashfs modules for proprietary GPU support (Nvidia) can be placed here. The module(s) will be copied to addons/ by the "make_slackware_live.sh" script for any Live Desktop Environment (except pure Slackware) that might profit from proprietary driver support.
+  * local64/ , local/ - these directories can contain Slackware packages considered 'local' i.e. not belonging to any repository.  The package(s) will be converted to squashfs module(s) by the "make_slackware_live.sh" script, copied to the "addons/" subdirectory in the ISO and loaded into the Live filesystem when the OS boots.
+  * optional/ - squashfs modules placed in this directory will not automatically be loaded into the Live filesystem when the OS boots.  You need to pass "load=[mod]" boot parameter to load any of these.
+  * pkglists/ - definition files of 3rd party repositories (*.conf) and the package lists to be used from those repositories (*.lst) must be placed in this directory.
+  * skel/ - contains compressed tarballs (whose filenames must match wildcard "skel*.txz"). These files will be extracted to the "/etc/skel" directory in the Live filesystem.
+  * syslinux/  - contains the skeleton for boot support on BIOS computers.  Some of its files are dynamically generated by the "make_slackware_live.sh" script.
+  * xdm/ - graphical Slackware theme for the XDM graphical session manager for those ISO variants which do not ship with GDM, KDM or SDDM.
 
 The toplevel 'liveslak' directory contains the following files:
- * blueSW-128px.png , blueSW-64px.png - these are bitmaps of the Slackware "Blue S" logo, used for the "live" user icon and in the XDM theme.
- * grub.tpl - the template file which is used to generate the grub menu for UEFI boot.
- * iso2usb.sh - this script creates a bootable USB version wih persistence from a Slackware Live ISO.
- * languages - this file contains the input configuration for language support.  One language per line contains the following fields: "code:name:kbd:tz:locale:xkb".  Example: "nl:nederlands:nl:Europe/Amsterdam:nl_NL.utf8:"
-   * code = 2-letter language code
-   * name = descriptive name of the language
-   * kbd = name of the console keyboard mapping for this language
-   * tz = timezone for the language's native country
-   * locale = the locale used in the country
-   * xkb = optional custom X keyboard variant for the language
- * liveinit - this is the "init" script which is copied into the initrd image for the Live OS.  Together with the Slackware generic kernel, the initrd is what boots the computer. The "init" script assembles the Live filesystem from its squashfs modules.
- * make_slackware_live.conf - the configuration file for the "make_slackware_live.sh" script.  You can define defaults for many script parameters here so that you do not have to edit the script itself.
- * make_slackware_live.sh - the script that generates the Live ISO.
- * makemod - this script creates a squashfs module out of a Slackware package (or out of a directory tree).
- * menu.tpl - template which is used to generate the syslinux boot menu for BIOS computers.
+  * blueSW-128px.png , blueSW-64px.png - these are bitmaps of the Slackware "Blue S" logo, used for the "live" user icon and in the XDM theme.
+  * grub.tpl - the template file which is used to generate the grub menu for UEFI boot.
+  * iso2usb.sh - this script creates a bootable USB version wih persistence from a Slackware Live ISO.
+  * languages - this file contains the input configuration for language support.  One language per line contains the following fields: "code:name:kbd:tz:locale:xkb".  Example: "nl:nederlands:nl:Europe/Amsterdam:nl_NL.utf8:"
+    * code = 2-letter language code
+    * name = descriptive name of the language
+    * kbd = name of the console keyboard mapping for this language
+    * tz = timezone for the language's native country
+    * locale = the locale used in the country
+    * xkb = optional custom X keyboard variant for the language
+  * liveinit - this is the "init" script which is copied into the initrd image for the Live OS.  Together with the Slackware generic kernel, the initrd is what boots the computer. The "init" script assembles the Live filesystem from its squashfs modules.
+  * make_slackware_live.conf - the configuration file for the "make_slackware_live.sh" script.  You can define defaults for many script parameters here so that you do not have to edit the script itself.
+  * make_slackware_live.sh - the script that generates the Live ISO.
+  * makemod - this script creates a squashfs module out of a Slackware package (or out of a directory tree).
+  * menu.tpl - template which is used to generate the syslinux boot menu for BIOS computers.
 
 
 === Generate the ISO ===
 
 
-The liveslak's "make_slackware_live.sh" script accepts optional parameters to tweak the process of Live OS generation:
-
+The liveslak's "make_slackware_live.sh" script accepts optional parameters to tweak the process of Live OS generation: <code>
  -h                 This help.
  -d desktoptype     SLACKWARE (full Slack), KDE4 (basic KDE4),
                     XFCE (basic XFCE), PLASMA5 (full Plasma5 replaces KDE4),
@@ -390,6 +407,7 @@ The liveslak's "make_slackware_live.sh" script accepts optional parameters to tw
  -v                 Show debug/error output.
  -H <hostname>      Hostname of the Live OS (default: darkstar).
  -R <runlevel>      Runlevel to start with (default: 4).
+</code>
 
 The script uses package repositories to create a Live ISO.  The packages will be installed into a temporary directory.
 
@@ -408,6 +426,51 @@ for MATE, you will find:
 Which means that most of the Slackware package series (excepting kde and kdei) will be installed from their tagfiles, and on top of that two package lists are installed from the pkglists/ subdirectory: slackextra and mate.  Lastly, "slackpkg+" will be installed from a local directory.
 
  
+==== Using the Customization Feature of the Live OS ====
+
+You can create your own custom Live OS by changing its characteristics in the configuration file "make_slackware_live.conf". Among the things you can change are:
+
+  * The name of the Desktop variant (the script itself knows SLACKWARE, PLASMA5, XFCE, MATE and CINNAMON),
+  * The list(s) of packages used for your custom distribution,
+  * The name of the distribution (by default that is "slackware"),
+  * And finally you can define a function "custom_config()" where you can add all your costom post-installation steps that are not covered in the "make_slackware_live.sh" script itself.
+
+This is the section in ''make_slackware_live.conf'' which deals with these customizations. Two variables are required if you want to create your own custom Live OS: ''LIVEDE'' and ''SEQ_CUSTOM'', the rest is optional (but useful nevertheless): <code>
+# REQUIRED:
+# Define a new name for your own variant of Slackware Live Edition:
+#LIVEDE="CINELERRA"
+
+# REQUIRED:
+# Define your own custom package sequence for a custom Live ISO.
+# In this example you would need to create two files "pkglists/cinelerra.conf"
+# and "pkglists/cinelerra.lst" defining the package location and package list
+# respectively):
+#SEQ_CUSTOM="min,xbase,xapbase,xfcebase,cinelerra"
+
+# OPTIONAL:
+# Your custom distro name (will reflect in boot screen & filenames):
+#DISTRO="cinelerra"
+
+# OPTIONAL:
+# Marker used for finding the Slackware Live files:
+#MARKER="CINELERRA"
+
+# OPTIONAL:
+# The filesystem label of the ISO:
+#MEDIALABEL="CINELERRA"
+
+# OPTIONAL:
+# The ISO main directory:
+#LIVEMAIN="cinelerra"
+
+# OPTIONAL:
+# Add your own Live OS customizations to the function custom_config() :
+#custom_config() {
+#  # Add your own stuff here which is not covered in the main script:
+#}
+</code>
+
+
 ==== Internals of Slackware Live Edition ====
 
 
@@ -429,32 +492,32 @@ The init script of an initrd is what prepares the root filesystem even before th
 
 What does the 'liveslak' init script do?
 
- * It parses any boot parameters you entered (or were passed by syslinux/grub) and tries to make sense of them.
- * It does some initialization just like the Slackware init (start udev, wait a bit for USB media to settle, load kernel modules, load custom keyboard mapping, initialize RAID etc) before it gets to the Slackware Live section.
- * A RAM based filesystem is created which forms the base of all the rest.
- * Using tools like 'blkid' and 'mount', the init script tries to locate the Live media.  It uses blkid to search for the Live media's default filesystem label.  If that fails (because you changed the label) it will use blkid to find all filesystem partitions available and mount them mount these one by one until the Live partition is found.
- * With the Live media located, the next step is to loop-mount the squashfs modules one by one and add them to the overlay filesystem in the correct order.  If you specified the 'toram' boot parameter, then a module will first be copied into RAM before loop-mounting it.  This allows you to remove the boot media after booting since the complete OS will run from RAM.
- * Modules will be loaded in order:
-   * first the system modules (core modules in the system/ subdirectory)
-   * then the addon modules (in the addon/ directory).  If you do not want an addon to be loaded, you can specify "noload=modulename" on the syslinux/grub boot commandline
-   * last, the optional modules (in the optional/ subdirectory).  By default an optional module is not loaded unless you force it by adding "load=modulename" to the boot commandline.
- * Next, persistence will be configured if the Live OS was booted from a writable media such as a USB stick.  The init script will first look for a directory in the root of the Live partition of the USB stick  called "persistence" and use that to store persistent changes to the Live filesystem.  If that directory does not exist but a file "persistence.img" is found, then that file will be loop-mounted and persistent changes to the Live filesystem will be written to this container file.  The "persistence.img" container can be LUKS-encrypted in which case the init script will ask you for a passphrase to unlock it before mounting.
- * The overlay filesystem is then finalized by adding the writable toplevel directory structure (either persistent or volatile).
- * The complete RAM filesystem which underpins the overlay is made available to the user of the Live OS as "/mnt/live"
- * The filesystem of the Live media is made available to the user of the Live OS as "/mnt/livemedia".  If the media is a USB stick then you will have write access to "/mnt/livemedia".
- * With the root filesystem assembled, the Live OS is configured before it actually boots:
-   * if you specified "swap" on the boot commandline, any available swap partition will be added to "/etc/fstab" in the Live OS.
-   * if you specified a custom keyboard layout for the console (and optionally another for X) by using the "kbd" and "xkb" boot parameters then these will be confifured in "/etc/rc.d/rc.keymap" and "/etc/X11/xorg.conf.d/30-keyboard.conf" in the Live OS.
-   * Same for any custom locale which was specified with the "locale" parameter, this will get added to "/etc/profile.d/lang.sh".
-   * If timezone and hardware clock were specified in the "tz" parameter, these will be configured in "/etc/localtime" and "/etc/hardwareclock".
-   * The boot parameters "livepw" and "rootpw" allow you to specify custom passwords for the 'live' and 'root' users; the defaults for these two are simply 'live' and 'root'.  This is achieved by running the "chpasswd" command in the chrooted overlay so that a plain text password can be given as input.
-   * The "hostname" boot parameter can be used to change the Live OS' hostname from its default "darkstar".  Configuration is written to "/etc/HOSTNAME" and "/etc/NetworkManager/NetworkManager.conf".
-   * If the "blacklist" boot parameter was specified, then the kernel modules mentioned as argument(s) will be added to a modprobe blacklist file "/etc/modprobe.d/BLACKLIST-live.conf".
-   * The "/var/lib/alsa/asound.state" file in the Live OS is removed to allow correct sound configuration on any computer where the Live media is booted.
-   * The complete content of the /rootcopy directory on the Live partition (may be empty) is copied to the filesystem root of the Live OS, potentially 'overwriting' files in the Live OS.  Use the /rootcopy to add customization to your Live OS when you run it off a USB stick.
-   * And lastly but very importantly, any LUKS-encrypted container files are unlocked (init will ask you for the passphrase) and the filesystem(s) contained therein will be mounted in the Live OS. Currently, a LUKS-encrypted /home is supported.  The files "/etc/fstab" and "/etc/crypttab" will be updated so that the Live OS will do the mounting and unmounting.
- * The init script will end by telling the kernel to swith to our new root filesystem (the overlay) and start the Slackware init program (PID 1, /sbin/init).
- * From this moment onward, you are booting a 'normal' Slackware system and the fact that this is actually running in RAM and not from your local harddisk is not noticeable.
+  * It parses any boot parameters you entered (or were passed by syslinux/grub) and tries to make sense of them.
+  * It does some initialization just like the Slackware init (start udev, wait a bit for USB media to settle, load kernel modules, load custom keyboard mapping, initialize RAID etc) before it gets to the Slackware Live section.
+  * A RAM based filesystem is created which forms the base of all the rest.
+  * Using tools like 'blkid' and 'mount', the init script tries to locate the Live media.  It uses blkid to search for the Live media's default filesystem label.  If that fails (because you changed the label) it will use blkid to find all filesystem partitions available and mount them mount these one by one until the Live partition is found.
+  * With the Live media located, the next step is to loop-mount the squashfs modules one by one and add them to the overlay filesystem in the correct order.  If you specified the 'toram' boot parameter, then a module will first be copied into RAM before loop-mounting it.  This allows you to remove the boot media after booting since the complete OS will run from RAM.
+  * Modules will be loaded in order:
+    * first the system modules (core modules in the system/ subdirectory)
+    * then the addon modules (in the addon/ directory).  If you do not want an addon to be loaded, you can specify "noload=modulename" on the syslinux/grub boot commandline
+    * last, the optional modules (in the optional/ subdirectory).  By default an optional module is not loaded unless you force it by adding "load=modulename" to the boot commandline.
+  * Next, persistence will be configured if the Live OS was booted from a writable media such as a USB stick.  The init script will first look for a directory in the root of the Live partition of the USB stick  called "persistence" and use that to store persistent changes to the Live filesystem.  If that directory does not exist but a file "persistence.img" is found, then that file will be loop-mounted and persistent changes to the Live filesystem will be written to this container file.  The "persistence.img" container can be LUKS-encrypted in which case the init script will ask you for a passphrase to unlock it before mounting.
+  * The overlay filesystem is then finalized by adding the writable toplevel directory structure (either persistent or volatile).
+  * The complete RAM filesystem which underpins the overlay is made available to the user of the Live OS as "/mnt/live"
+  * The filesystem of the Live media is made available to the user of the Live OS as "/mnt/livemedia".  If the media is a USB stick then you will have write access to "/mnt/livemedia".
+  * With the root filesystem assembled, the Live OS is configured before it actually boots:
+    * if you specified "swap" on the boot commandline, any available swap partition will be added to "/etc/fstab" in the Live OS.
+    * if you specified a custom keyboard layout for the console (and optionally another for X) by using the "kbd" and "xkb" boot parameters then these will be confifured in "/etc/rc.d/rc.keymap" and "/etc/X11/xorg.conf.d/30-keyboard.conf" in the Live OS.
+    * Same for any custom locale which was specified with the "locale" parameter, this will get added to "/etc/profile.d/lang.sh".
+    * If timezone and hardware clock were specified in the "tz" parameter, these will be configured in "/etc/localtime" and "/etc/hardwareclock".
+    * The boot parameters "livepw" and "rootpw" allow you to specify custom passwords for the 'live' and 'root' users; the defaults for these two are simply 'live' and 'root'.  This is achieved by running the "chpasswd" command in the chrooted overlay so that a plain text password can be given as input.
+    * The "hostname" boot parameter can be used to change the Live OS' hostname from its default "darkstar".  Configuration is written to "/etc/HOSTNAME" and "/etc/NetworkManager/NetworkManager.conf".
+    * If the "blacklist" boot parameter was specified, then the kernel modules mentioned as argument(s) will be added to a modprobe blacklist file "/etc/modprobe.d/BLACKLIST-live.conf".
+    * The "/var/lib/alsa/asound.state" file in the Live OS is removed to allow correct sound configuration on any computer where the Live media is booted.
+    * The complete content of the /rootcopy directory on the Live partition (may be empty) is copied to the filesystem root of the Live OS, potentially 'overwriting' files in the Live OS.  Use the /rootcopy to add customization to your Live OS when you run it off a USB stick.
+    * And lastly but very importantly, any LUKS-encrypted container files are unlocked (init will ask you for the passphrase) and the filesystem(s) contained therein will be mounted in the Live OS. Currently, a LUKS-encrypted /home is supported.  The files "/etc/fstab" and "/etc/crypttab" will be updated so that the Live OS will do the mounting and unmounting.
+    * The init script will end by telling the kernel to swith to our new root filesystem (the overlay) and start the Slackware init program (PID 1, /sbin/init).
+  * From this moment onward, you are booting a 'normal' Slackware system and the fact that this is actually running in RAM and not from your local harddisk is not noticeable.
 
 
 === Slackware Live module format ===
@@ -463,19 +526,19 @@ What does the 'liveslak' init script do?
 A Slackware Live module contains a directory tree, which has been 'squashed' into a compressed archive file by the program "squashfs".  The compression algorithm used is "xz" which explains the choice of the module's file extension ".sxz" meaning "squashed with xz".
 
 Slackware Live Edition expects its modules to adhere to a particularly loose filename convention:
- * The filename format is "NNNN-modname-*.sxz", where 'N' is a digit and 'modname' must not contain a dash '-'.
- * The "modname" part is what you must specify in the boot parameters "load" and "noload".
- * Anything may be part of the '*' but most commonly used is "${VERSION}-${ARCH}".  The core modules in Slackware Live use the Slackware release as ${VERSION} and the Slackware architecture as ${ARCH}.  For the modules in addons/ and optional/ subdirectories, ${VERSION} would commonly be the version of the program that is being made available in the module.
- * The four digits of a modulename have a meaning.  Some ranges are claimed by the core OS, so please do not use them. Their prefixes are based on the package source:
+  * The filename format is "NNNN-modname-*.sxz", where 'N' is a digit and 'modname' must not contain a dash '-'.
+  * The "modname" part is what you must specify in the boot parameters "load" and "noload".
+  * Anything may be part of the '*' but most commonly used is "${VERSION}-${ARCH}".  The core modules in Slackware Live use the Slackware release as ${VERSION} and the Slackware architecture as ${ARCH}.  For the modules in addons/ and optional/ subdirectories, ${VERSION} would commonly be the version of the program that is being made available in the module.
+  * The four digits of a modulename have a meaning.  Some ranges are claimed by the core OS, so please do not use them. Their prefixes are based on the package source: <code>
     0000 = contains the Slackware /boot directory
     0010-0019 = packages installed from a Slackware tagfile (a,ap,d, ... , y series)
     0020-0029 = packages installed from a package list as found in the ./pkglists subdirectory of the liveslak sources (min, xbase, xapbase, xfcebase etc)
     0030-0039 = a 'local' package, i.e. a package found in subdirectory ./local or ./local64 (depending on architecture)
-    0099 = liveslak configuration module (contaning all the customizations that change the installed packages into a usable Live OS)
- * Other ranges are free to be used. Note that order in which the filesystem of the Live OS is assembled by overlaying the squashed directory trees depends on the module numbering.  So if you have modules that you want to have loaded in specific order, just ensure that their filenames have ascending numbers.
+    0099 = liveslak configuration module (contaning all the customizations that change the installed packages into a usable Live OS) </code>
+  * Other ranges are free to be used. Note that order in which the filesystem of the Live OS is assembled by overlaying the squashed directory trees depends on the module numbering.  So if you have modules that you want to have loaded in specific order, just ensure that their filenames have ascending numbers.
 
-Example of a core module: 0099-slackware_zzzconf-14.2-x86_64.sxz
-Example of an optional module: 0060-nvidia-352.79_4.4.1-current-x86_64.sxz
+  - Example of a core module: 0099-slackware_zzzconf-14.2-x86_64.sxz
+  - Example of an optional module: 0060-nvidia-352.79_4.4.1-current-x86_64.sxz
 
 
 === BIOS boot ===
@@ -484,10 +547,10 @@ Example of an optional module: 0060-nvidia-352.79_4.4.1-current-x86_64.sxz
 Slackware Live Edition uses syslinux to boot the Linux kernel on BIOS computers. To be precise, the "isolinux" variant is installed to the ISO image and the "extlinux" variant is installed into the Linux partition of the USB Live version.
 
 Syslinux shows a graphical boot menu with a nice Slackware-themed background and several options:
- * Start (SLACKWARE | PLASMA5 | XFCE | MATE) Live (depending on which of the ISOs you boot)
- * Non-US Keyboard selection
- * Non-US Language selection
- * Memory test with memtest86+
+  * Start (SLACKWARE | PLASMA5 | XFCE | MATE) Live (depending on which of the ISOs you boot)
+  * Non-US Keyboard selection
+  * Non-US Language selection
+  * Memory test with memtest86+
 
 You can select a keyboard mapping that matches your computer's.  Also you can boot Slackware in another language than US English.
 If you stick to US English interface language you will probably still want to change the timezone because it will default to UTC.  You have to specify a custom timezone manually by adding "tz=YourGeography/YourLocation" because the syslinux bootmenu does not offer you a selection of timezones.  Syslinux allows you to edit the boot commandline by pressing <TAB>.  Press <ENTER> to boot after you made your changes or <ESC> to discard your edit and return to the menu.
@@ -498,19 +561,19 @@ If you stick to US English interface language you will probably still want to ch
 
 On UEFI computers, Grub2 handles the boot and it will show a menu similar (and similarly themed) to the Syslinux menu:
 
- * Start (SLACKWARE | PLASMA5 | XFCE | MATE) Live (depending on which of the ISOs you boot)
- * Non-US Keyboard selection
- * Non-US Language selection
- * Non-US Timezone selection
- * Memory test with memtest86+
- * Help on boot parameters
+  * Start (SLACKWARE | PLASMA5 | XFCE | MATE) Live (depending on which of the ISOs you boot)
+  * Non-US Keyboard selection
+  * Non-US Language selection
+  * Non-US Timezone selection
+  * Memory test with memtest86+
+  * Help on boot parameters
 
 Editing a Grub menu before booting it is possible by pressing the "e" key.  After making your changes to the boot commandline, press <F10> to boot.  To discard your changes, press <ESC>.
 
 Another difference between Syslinux and Grub2 menus: in Grub2 you can select a non-US keyboard, language and/or timezone and you will return to the main menu every time.  You still have to select "Start SLACKWARE Live" to boot the computer.  In the Syslinux menu, only the keyboard selection menu will return you to the main menu.  Any non-US *language* selection on the other hand will boot you into Slackware Live immediately; without returning to the main menu.  This is a limitation of syslinux which would require exponentially more menu files to construc  a menu with more choices.  Grub2 supports variables which make it easy to modify a menu entry's characteristics.
 
 
-==== Other Slackware based Live distros ====
+===== Other Slackware based Live distros =====
 
 
 Naturally, there have been many who went before me, and since I started as a n00b in Linux Live land, I have learnt a lot about how a Live distro works from playing with these other Slackware-based Live distros.  Allow me to name them, and show respect:
@@ -542,7 +605,7 @@ Website: http://www.salixos.org/download.html
 Salix is a distribution based on Slackware with its own philosophy of "one tool per task" reducing the number of packages a lot, compared to its parent Slackware distro.  Salix has implemented dependency checking in its package management tool.  Live editions of Salix are available in several editions, each built around and focused on a different Desktop Environment or Window Manager.  Live editions are available for XFCE and MATE.
 
 
-==== Slackel ====
+=== Slackel ===
 
 
 Website: http://www.slackel.gr/
@@ -550,7 +613,7 @@ Website: http://www.slackel.gr/
 Slackel is a Greek distro based on both Slackware and Salix.  It comes in three flavors, each of which has a Live variant: KDE4, Openbox and Fluxbox.  The Live scripts are a modification of Salix-Live.
 
 
-==== SlackEX ====
+=== SlackEX ===
 
 
 Website: http://slackex.exton.net/
@@ -558,13 +621,13 @@ Website: http://slackex.exton.net/
 A website offering Live versions based on many regular Linux distributions.  The SlackEX version is loosely based on Slackware with a custom kernel and some tools that are not part of Slackware itself.  I was unable to find the sources for this live distro.
 
 
-==== Liveslak Sources ====
+===== Liveslak Sources =====
 
 
-Slackware Live Edition is created by the 'liveslak' scripts developed and maintained by Eric Hameleers aka Alien BOB <alien@slackware.com>.
+Slackware Live Edition is created by the 'liveslak' scripts developed and maintained by Eric Hameleers aka Alien BOB [[alien@slackware.com]].
 
- * Git repository: git://taper.alienbase.nl/liveslak.git
- * Git repository (browsable): http://taper.alienbase.nl/cgit/liveslak/
- * Download mirror: http://www.slackware.com/~alien/liveslak/
+  * Git repository: %%git://taper.alienbase.nl/liveslak.git%%
+  * Git repository (browsable): http://taper.alienbase.nl/cgit/liveslak/
+  * Download mirror: http://www.slackware.com/~alien/liveslak/