doc updates... meanwhile, it doesn't boot, complaining about not finding the rootfs in the initrd. working on that in the background.

docs/manual/user/fslayout/BDISK.adoc

@@ -1,6 +1,30 @@
-== bdisk/
-This directory contains the "heart" of BDisk. It essentially is a Python module package. It contains several python "subpackages" split into different files that provide different functions for BDisk.
+=== bdisk/
+This directory contains the "heart" of BDisk. It essentially is a Python module package. It contains several python "subpackages" split into different files that provide different functions for BDisk. Chances are you won't ever need to touch anything in here.
 
-=== bchroot.py
+==== bchroot.py
 This file controls creation of the chroots -- the directories in which BDisk builds the actual system that is booted into.
 
+==== bdisk.py
+This file is a sort of "wrapper" -- it pulls all the other files in this directory together into a single usable python script. In other words, to build a BDisk distribution, you would simply run `bdisk/bdisk.py` -- that's it!
+
+==== bGPG.py
+This contaions functions having to do with GPG -- signing files, verifying other signatures, generating a key (if one wasn't specified), using a key (if one was specified), etc.
+
+==== bSSL.py
+Functions having to do with OpenSSL are stored here. This is used primarily for "mini" builds (via iPXE), they let you boot your BDisk distribution over the Internet. If an SSL key, CA certificate, etc. weren't defined and you want to build a mini image, this file contains functions that will build an SSL PKI (public key infrastructure) for you automatically.
+
+==== bsync.py
+This file has functions relating to copying your BDisk build to various resources. For instance, if you want your ISO available to download then this file would be used to copy your finished build to an HTTP server/root you specify.
+
+==== build.py
+This is responsible for building the "full" ISO, building UEFI support, etc.
+
+==== host.py
+These functions are used to perform "meta" tasks such as get information about the build host, find the `build.ini` file, and parse your configuration options.
+
+==== ipxe.py
+This file handles building the "mini" ISO via iPXE.
+
+==== prep.py
+This contains functions that download the base tarball releases, preps them for `bchroot.py`, builds necessary directory structures, and performs the overlay preparations.
+

docs/manual/user/fslayout/DOCS.adoc

@@ -0,0 +1,15 @@
+=== docs/
+This directory contains various documentation and other helpful text.
+
+==== COPYING
+This contains BDisk's license, the GPLv3.
+
+==== LICENSE
+This is simply a link to `COPYING`.
+
+==== manual/
+This directory contains the documentation source you're reading right now! It's written in http://asciidoc.org/[asciidoc^] (well, to be more precise it's written in/has some http://asciidoctor.org/[asciidoctor^]-isms). I'd recommend reading the rendered version, as the source (while perfectly human-readable) is written in a very modular fashion so it may be inconvenient to read each source file and following include directives.
+
+==== README
+This is a placeholder for common convention; it simply tells you to read the manual (and where to find it/build it).
+

docs/manual/user/fslayout/EXAMPLES.adoc

@@ -0,0 +1,3 @@
+=== examples/
+This directory contains example filesystem layouts for e.g. your webserver (for iPXE), or your PXE server via TFTP.
+

docs/manual/user/fslayout/EXTRA.adoc

@@ -0,0 +1,21 @@
+=== extra/
+This directory contains multiple "support files" for BDisk building.
+
+==== bdisk.png
+This file is used for bootloader graphics. If you change the name of the project, this can be named something different -- see <<_uxname,the section on uxname>>.
+
+==== bin/
+This directory contains sample code or extra tools that don't have anything to do with BDisk normal operation but are useful in building a BDisk distribution.
+
+==== dist.build.ini
+This is the "source-provided"/upstream example `build.ini`. It will be sourced for any missing configuration options or the like.
+
+==== external/
+This directory contains external source code for use with extra features in BDisk that would otherwise be inconvenient to fetch and build dynamically.
+
+==== pkg.build.ini
+This is the recommended default `build.ini` file for packagers of distro repositories to use when packaging BDisk for inclusion in a package manager.
+
+include::PREBUILD.adoc[]
+
+include::TEMPLATES.adoc[]

docs/manual/user/fslayout/OVERLAY.adoc

@@ -0,0 +1,13 @@
+=== overlay/
+This directory follows similar rules to the <<_pre_build_d,pre-build.d/>> directory, except it is applied *after* the chroots are prepared (as it is designed to be user-centric rather than core functionality). We'll go more into this later in-depth, as this is where most of your customizations will be done.
+
+For files that should be included in both chroots, simply recreate the path with the desired file. For instance, if you want a file `/etc/foo/bar.conf` to exist in both i686 and x86_64 versions, it would exist as the path `overlay/etc/foo/bar.conf`.
+
+It follows the following structure:
+
+==== i686/
+This contains modifications that should be applied to the i686 version only. If you wanted a file to exist only in the i686 version at `/etc/a/b.conf`, it would be placed in `overlay/i686/etc/a/b.conf`.
+
+==== x86_64/
+This contains modifications that should be applied to the x86_64 version only. If you wanted a file to exist only in the x86_64 version at `/etc/z/y.conf`, it would be placed in `overlay/x86_64/etc/z/y.conf`.
+

docs/manual/user/fslayout/PREBUILD.adoc

@@ -0,0 +1,13 @@
+==== pre-build.d/
+This file contains a "core" overlay. Generally these files shouldn't be modified unless you know what you're doing, but there are some interesting things you can do in here. Generally speaking, though, you'll want to place your modifications in the `overlay/` directory.
+
+For files that should be included in both chroots, simply recreate the path with the desired file. For instance, if you want a file `/etc/foo/bar.conf` to exist in both i686 and x86_64 versions, it would exist as the path `pre-build.d/etc/foo/bar.conf`.
+
+It follows the following structure:
+
+===== i686/
+This contains modifications that should be applied to the i686 version *only*. If you wanted a file to exist only in the i686 version at `/etc/a/b.conf`, it would be placed in `pre-build.d/i686/etc/a/b.conf`.
+
+===== x86_64/
+This contains modifications that should be applied to the x86_64 version *only*. If you wanted a file to exist only in the x86_64 version at `/etc/z/y.conf`, it would be placed in `pre-build.d/x86_64/etc/z/y.conf`.
+

docs/manual/user/fslayout/TEMPLATES.adoc

@@ -0,0 +1,45 @@
+==== templates/
+This directory contains dynamic templates used for dynamic configuration building and other such things. They are written in http://jinja.pocoo.org/[Jinja2^]. If you haven't used Jinja2 before, the http://jinja.pocoo.org/docs/dev/templates/[templating documentation^] will prove to be very useful.
+
+This allows you to customize low-level behaviour of BDisk without modifying the source.
+
+===== BIOS/
+The `isolinux.cfg.arch.j2` template controls boot options for the single-arch versions of BDisk. In other words if you only build an i686 or only an x86_64 version, this is the template that would be used for BIOS boot mode.
+
+The `isolinux.cfg.multi.j2` is used for multi-arch. It manages booting for both i686 and x86_64 versions.
+
+These files will let you change the behaviour of booting in BIOS systems. The menu colour, the menu entries, the menu default, etc.
+
+===== EFI/
+The files in here are https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/[systemd-boot^] configurations. The distributed defaults are:
+
+`base.conf.j2`, which controls the "main"/default entry.
+
+`loader.conf.j2`, the meta configuration file which tells the loader which entry to load by default and which entries to include.
+
+`ram.conf.j2` which allows BDisk to run entirely from RAM.
+
+`uefi1.conf.j2` which provides a UEFI shell (for older UEFI systems).
+
+`uefi2.conf.j2` which provides a UEFI shell (for newer UEFI systems).
+
+===== GPG.j2
+This file contains default parameters for the https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html[GPG key generation], if we need to automatically generate a key.
+
+===== iPXE/
+This directory holds templates for iPXE/mini builds.
+
+The `BIOS/` directory is similar to <<_bios, BIOS/>> mentioned above, but it only needs one configuration file and is a much more minimal design (since its entire purpose is to chainload to the iPXE loader).
+
+The `EFI/` directory is similar to <<_efi, EFI/>> above also, but needs fewer configuration files (its only purpose is to bootstrap iPXE).
+
+`EMBED.j2` is the iPXE http://ipxe.org/scripting[embedded script^] (http://ipxe.org/embed[more info^]). This is what chainloads the remote resources (kernel, intird, squashed filesystem images, and so forth).
+
+The `patches/` directory largely control branding of the mini ISO. They are in https://www.gnu.org/software/diffutils/manual/html_node/Unified-Format.html[unified diff^] (or "patch") format.
+
+===== VARS.txt.j2
+This template passes variables specified in the configuration and generated by BDisk to the chroot bash script.
+
+===== VERSION.txt.j2
+This template specifies a VERSION.txt file placed in various locations throughout the builds to help identify which version, build, etc. the ISO is.
+