err.. booting's broken?

docs/manual/BODY.adoc

@@ -1,5 +1,5 @@
 include::USER.adoc[]
 include::DEV.adoc[]
-include::FAQ.adoc[]
 include::BOOT.adoc[]
 include::FOOT.adoc[]
+include::FAQ.adoc[]

docs/manual/HEAD.adoc

@@ -26,7 +26,7 @@ A lot of research went into how low-level boot operations take place when writin
 
 
 === What is BDisk?
-BDisk refers to both a live distribution I use in my own uses (for rescue situations, recovery, etc.) but foremost and most importantly, it also refers to the tool I use for building that distribution. The latter is what this project and documentation refer to when the word “BDisk” is used.
+BDisk refers to both a live distribution I use in my own uses (for rescue situations, recovery, etc.) but foremost and most importantly, it also refers to the tool I use for building that distribution. In other words, it's both a complete GNU/Linux distribution you can run entirely from USB/CD/DVD/etc. (without needing to install it to your hard drive)... and also the name of a tool to create a custom GNU/Linux install. The latter is what this project and documentation refer to when the word “BDisk” is used.
 
 When I rewrote BDisk in Python 3.x (Version 0.x-2.x of BDisk was written in Bash, and horribly inelegant and rigid. I should take the time to note that I am still quite new to Python so expect there to be plenty of optimizations to be made and general WTF-ery from seasoned Python developers), one of my main goals was to make it as easy to use as possible. This is surprisingly hard to do- it’s quite challenging to try to approach software you’ve written with the mindset of someone other than you.
 
@@ -34,11 +34,11 @@ It’s my hope that by releasing this utility (and documenting it), you can use
 
 
 === Copyright/Licensing
-BDisk is GPLv3-licensed. This means that you can use it for business reasons, personal reasons, modify it, etc. Please be sure to familiarize yourself with the full set of terms. You can find the full license in `docs/LICENSE`.
+The BDisk code is https://www.gnu.org/licenses/gpl-3.0.en.html[GPLv3-licensed]. This means that you can use it for business reasons, personal reasons, modify it, etc. Please be sure to familiarize yourself with the full set of terms. You can find the full license in `docs/LICENSE`.
 
 image::https://www.gnu.org/graphics/gplv3-127x51.png[GPLv3,align="center"]
 
-This document (and all other associated author-generated documentation) are released under the http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons CC-BY-SA 4.0] copyright.
+This document, and all other associated author-generated documentation, are released under the http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons CC-BY-SA 4.0] copyright. It's essentially the GPL for non-software, so similar terms apply.
 
 image::https://i.creativecommons.org/l/by-sa/4.0/88x31.png[CC-BY-SA_4.0,align="center"]
 

docs/manual/boot/HOWTO.adoc

@@ -14,7 +14,7 @@ Simply put a blank CD/DVD-R (or RW, RW+, etc.) in your optical media drive. Find
 ==== USB
 You'll most likely want to https://svwh.dl.sourceforge.net/project/usbwriter/USBWriter-1.3.zip[download] a program caled https://sourceforge.net/projects/usbwriter/[USBWriter]. Unzip it (or just open it via double-clicking) and copy the `USBWriter.exe` program somewhere you'll remember- your desktop, for instance.
 
-Next, make sure your USB stick is inserted in your computer and https://support.microsoft.com/en-us/help/17418/windows-7-create-format-hard-disk-partition[formatted/"initialized"] already.
+Next, make sure your USB thumbdrive is inserted in your computer and https://support.microsoft.com/en-us/help/17418/windows-7-create-format-hard-disk-partition[formatted/"initialized"] already.
 
 WARNING: Formatting a disk/partition will *destroy* any and all data on that device! Make sure there is nothing on your USB drive you want to keep, as formatting BDisk to it *will* delete any data on it.
 
@@ -36,17 +36,17 @@ We'll need to get a little messy with this one.
 
 Open Applications => Utilities => Terminal. A black box should pop up.
 
-Insert your USB stick now (if you haven't already) and run the following command:
+Insert your USB thumbdrive now (if you haven't already) and run the following command:
 
  diskutil list
 
 You should see an entry, probably near the bottom, that looks something like this:
 
- ...
+ (...)
  /dev/disk42 (external, physical):
     #:                       TYPE NAME                    SIZE       IDENTIFIER
     0:                                                   *8.2 GB     disk42
- ...
+ (...)
 
 CAUTION: *Be sure* to find the disk that matches the size of your thumbdrive! If you use the wrong disk identifier, it will break your OS X/macOS install at best and delete all your data at worst!
 
@@ -77,7 +77,7 @@ One last step. Still in Terminal:
 You can then close Terminal.
 
 ==== Booting
-The instructions here don't differ too much than from Windows, though it's always the same key. For OS X/macOS hardware, I believe it's the *c* key or the *b* key. From it being in a shutdown state, power on your Macbook Pro (or whatever it is you have) and hold the *c* key if it's CD/DVD. The *b* key should bring up a boot menu that will let you select a USB device to boot from (I believe the *"b" menu* will let you boot from a CD/DVD as well).
+The instructions here don't differ too much than from Windows, though it's always the same key. From it being in a shutdown state, power on your Macbook Pro (or whatever it is you have) and hold the *Option* key (or the *Alt* key on non-Apple keyboards). The *Option/Alt* key should bring up a boot menu that will let you select a USB device to boot from.
 
 Strangely enough, you should still be able to _boot_ a BDisk Mini CD/DVD, you just can't *burn* one. I'm tempted to make a cheap dig at Apple, but I'll refrain.
 
@@ -88,20 +88,18 @@ Easy. Most (if not all) of https://wiki.archlinux.org/index.php/Optical_disc_dri
 ==== USB
 Very similar to OS X/macOS in approach. First open a terminal emulator- the ways of navigating to it depends on your window manager/desktop environment, but it's usually under a System or Utilities menu.
 
-Now we need to find which disk our USB thumbdrive is.
+Now we need to find which disk our USB thumbdrive is. Insert your USB thumbdrive now, if you haven't already, and run in the terminal:
 
  sudo fdisk -l
 
 You should see a device matching your USB thumbdrive's size. In our example, I use */dev/sdz* as it's unlikely you have that many disks attached to a system, but be sure to replace this in the following commands with the proper disk ID you find.
 
- ...
+ (...)
-
  Disk /dev/sdz: 7.6 GiB, 8178892800 bytes, 15974400 sectors
  Units: sectors of 1 * 512 = 512 bytes
  Sector size (logical/physical): 512 bytes / 512 bytes
  I/O size (minimum/optimal): 512 bytes / 512 bytes
-
+ (...)
- ...
 
 CAUTION: *Be sure* to find the disk that matches the size of your thumbdrive! If you use the wrong disk identifier, it will break your GNU/Linux install (or possibly Windows install if you're dual-booting, etc.) at best and delete all your data at worst!
 

docs/manual/faq/ALTERNATIVES.adoc

@@ -0,0 +1,74 @@
+== I don't like BDisk. Are there any other alternatives?
+First, I'm sorry to hear that BDisk doesn't suit your needs. If you want any features you think are missing or encounter any bugs, please report them!
+
+But yes; there are plenty of alternatives!
+
+NOTE: Only *currently maintained projects* are listed here.
+
+=== https://wiki.archlinux.org/index.php/archboot[Archboot]
+Written in Bash
+[frame="topbot",options="header,footer"]
+|======================
+|Pros|Cons
+|Highly featureful|Arch-only live media
+|Includes an assisted Arch install script|Inaccessible to non-Arch users
+|Can create tarballs too|Not very customizable by default
+|Supports hybrid ISOs|Infrequent stable releases
+|Supports PXE-booting infrastructure|Requires a systemd build host
+|Supports SecureBoot|Not a secure setup by default
+|Supports GRUB2's "ISO-loopback" mode|Builds a much larger image
+|Official Arch project|Some graphical bugs
+||Much more disk space is necessary for the tool itself
+||*Only* runs in RAM, so not ideal for RAM-constrained systems
+||Based on/requires an Arch build host
+||Requires an x86_64 build host
+||Has a large amount of dependencies
+||Manual intervention required for build process
+||Minimal documentation
+||
+|======================
+
+=== https://wiki.archlinux.org/index.php/archiso[Archiso]
+Written in Bash.
+[frame="topbot",options="header,footer"]
+|======================
+|Pros|Cons
+|Used to build the official Arch ISO|Requires an x86_64 build host
+|Supports custom local on-disk repositories|Not very featureful as far as customization goes
+|Supports arbitrary file placement in finished image|Requires an Arch build host
+|Supports hybrid ISOs|Has odd quirks with package selection
+|Supports Secureboot|Manual intervention required for build process
+|Official Arch project|Does not start networking by default
+|Can run in RAM or from media|Very minimal environment
+||Arch-only live meda
+||Documentation is lacking
+||
+|======================
+
+=== Debian's https://wiki.debian.org/Simple-CDD[Simple-CDD]
+Written in Bash.
+[frame="topbot",options="header,footer"]
+|======================
+|Pros|Cons
+||
+||
+|======================
+
+=== Fedora's https://fedoraproject.org/wiki/Livemedia-creator-_How_to_create_and_use_a_Live_CD[Livemedia-creator]
+Written in Bash.
+[frame="topbot",options="header,footer"]
+|======================
+|Pros|Cons
+||
+||
+|======================
+
+=== https://github.com/rhinstaller/livecd-tools[LiveCD Tools]
+Written in Bash.
+[frame="topbot",options="header,footer"]
+|======================
+|Pros|Cons
+||
+||
+|======================
+

docs/manual/faq/INDEX.adoc

@@ -1,3 +1,2 @@
 include::WHYARCH.adoc[]
-
+include::ALTERNATIVES.adoc[]
-

docs/manual/faq/WHYARCH.adoc

@@ -1,7 +1,5 @@
 == Why Arch Linux?
 Because it's a very easy-to-use, simple, https://wiki.archlinux.org/[well-documented] distro. It's no-frills and incredibly flexible/customizable, and can be made rather slim (and is out of the box, in fact). It's also very friendly to run as a chroot inside any other distro or as a chroot host to any other distro.
 
-Plus they have tarballs all ready for chroot easily accessible.
+Plus they release monthly tarball snapshots that are fairly small and create quick bootstrap environments.
-
-
 

docs/manual/user/GETTING_STARTED.adoc

@@ -58,7 +58,7 @@ These are required Python modules:
 ==== Optional
 While not strictly necessary, these will greatly enhance your BDisk usage. I've included some reasons why you might want to install them.
 
-NOTE: If you do not wish to install any of these or cannot install them, be sure to disable the relevant options in the `build.ini` file (we'll talk about that later).
+NOTE: If you do not wish to install any of these or cannot install them, be sure to disable the relevant options in the `build.ini` file (we'll talk about that later). The default `extra/dist.build.ini` should be sane enough to not require any of these.
 
 * https://git-scm.com/[git]
 ** For autodetection of version, automatically making commits for your project, etc.
@@ -77,3 +77,4 @@ These are optional Python modules:
 ** For branding iPXE environments per your `build.ini`.
 * https://pypi.python.org/pypi/pyOpenSSL[PyOpenSSL]
 ** To set up a PKI when building iPXE; used to create trusted/verified images.
+

docs/manual/user/IMPORTANT_CONCEPTS.adoc

@@ -2,12 +2,15 @@
 If this is your first foray into building live distros, there are some terms and concepts we need to understand first. This will simplify the process later on.
 
 === Terms
-
 An *operating system* is what your programs (email client, web browser, etc.) run on.
 
-There are two basic types of booting systems that communicate between the *hardware* (the physical computer itself and its components) and the operating system: https://en.wikipedia.org/wiki/BIOS[*BIOS*] (Basic Input/Output System) which has been around for quite some time and the newer https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface[*UEFI*] (Unified Extensible Firmware Interface). Don't worry, you don't need to memorize what they're acronyms for and there won't be an exam- just remember that BIOS is an older technology and UEFI is the newer one- and that they operate differently.
+There are two basic types of booting systems that communicate between the *hardware* (the physical computer itself and its components) and the operating system: https://en.wikipedia.org/wiki/BIOS[*BIOS*] (Basic Input/Output System) which has been around for quite some time and the newer https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface[*UEFI*] (Unified Extensible Firmware Interface). Don't worry, you don't need to memorize what they're acronyms for and there won't be an exam -- just remember that BIOS is an older technology and UEFI is the newer one (and that they operate differently).
 
 *GNU/Linux*, sometimes just referred to as _Linux_ (And there is a difference between the terminologies, but it's nuanced. You are welcome to https://www.gnu.org/gnu/linux-and-gnu.en.html[read up on it] though!), is an example of an operating system. Other examples include _Windows_, _macOS_ (previously _OS X_), _iOS_, _Android_, and a whole slew of others.
 
-A *live distro*, *live CD*, *live DVD*, *live USB*, and the like are a way of booting an operating system without installing it on the hard drive- this means the computer doesn't even need a hard drive installed, or it doesn't matter if the operating system is broken. Typically they are Linux-based, but there are several Windows-based live releases out there (usually they're focused on rescuing broken Windows systems, so they're not very flexible).
+A *live distro*, *live CD*, *live DVD*, *live USB*, and the like are a way of booting an operating system without installing it on the hard drive- this means the computer doesn't even need a hard drive installed, or it doesn't matter if the installed operating system is broken. Typically they are Linux-based, but there are several Windows-based live releases out there (usually they're focused on rescuing broken Windows systems, so they're not very flexible).
 
+=== Why live media is necessary
+"But Brent," I hear you ask in a voice which most likely is nothing close to what you actually sound like and entirely in my head, "Why would I need a live CD/USB/etc.? And why BDisk?"
+
+Elementary, my dear imaginary reader! I touch on some reasons why one might want live media in the beginning of the User Manual, but 

extra/templates/iPXE/EMBED.j2

@@ -1,6 +1,7 @@
 #!ipxe
 
-dhcp
+#dhcp
+ifconf
 ## TODO: signed kernel and initrd
 #imgtrust --permanent
 #imgverify vmlinuz path/to/vmlinuz.sig