improve doc for outputs and hardware

Changed my mind about "installer" as a first-class concept, at least
in the current implementation. Not every documented output is an
installer

modules/outputs.nix

@@ -17,26 +17,42 @@ in
   ];
   options = {
     system.outputs = {
+      # the convention here is to mark an output as "internal" if
+      # it's not a complete system (kernel plus userland, or installer)
+      # but only part of one.
       kernel = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
+          kernel
+          ******
+
           Kernel vmlinux file (usually ELF)
         '';
       };
       dtb = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
+          dtb
+          ***
+
           Compiled device tree (FDT) for the target device
         '';
       };
       uimage = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
+          uimage
+          ******
+
           Combined kernel and FDT in uImage (U-Boot compatible) format
         '';
       };
       manifest = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
           Debugging aid. JSON rendition of config.filesystem, on
           which can run "nix-store -q --tree" on it and find
@@ -45,10 +61,10 @@ in
       };
       rootfs = mkOption {
         type = types.package;
+        internal = true;
         description = ''
           root filesystem (squashfs or jffs2) image
         '';
-        internal = true;
       };
     };
   };

modules/outputs/ubimage.nix

@@ -20,18 +20,17 @@ in {
 ubimage
 *******
 
-First-time installation of a UBIFS Liminix system presently can only
-be done from the U-Boot command line (or from a ramdisk-based recovery
-system: see "kexecboot" but we don't have detailed instructions for
-this process yet).
+This output provides a UBIFS filesystem image and a small U-Boot script
+to make the manual installation process very slightly simpler. You will
+need a serial connection and a network connection to a TFTP server
+containing the filesystem image it creates.
 
-These steps were tested on a Belkin RT3200 (also known as Linksys
-E8450).  Other devices may be set up differently, so use them as
-inspiration and don't just paste them blindly. Consult the Liminix
-manual for how to connect a serial cable to your device and get into
-U-Boot
+.. warning:: These steps were tested on a Belkin RT3200 (also known as
+             Linksys E8450).  Other devices may be set up differently,
+             so use them as inspiration and don't just paste them
+             blindly.
 
-1) determine which MTD device is being used for UBI and the partition name:
+1) determine which MTD device is being used for UBI, and the partition name:
 
 .. code-block:: console
 

modules/tftpboot.nix

@@ -17,11 +17,27 @@ in {
     tftpboot = mkOption {
       type = types.package;
       description = ''
-        Directory containing files needed for TFTP booting
+        tftpboot
+        ********
+
+        This output is intended for developing on a new device.
+        It assumes you have a serial connection and a
+        network connection to the device and that your
+        build machine is running a TFTP server.
+
+        The output is a directory containing kernel and
+        root filesystem image, and a script :file:`boot.scr` of U-Boot
+        commands that will load the images into memory and
+        run them directly,
+        instead of first writing them to flash. This saves
+        time and erase cycles.
+
+        It uses the Linux `phram <https://github.com/torvalds/linux/blob/master/drivers/mtd/devices/phram.c>`_ driver to emulate a flash device using a segment of physical RAM.
       '';
     };
     boot-scr = mkOption {
       type = types.package;
+      internal = true;
       description = ''
         U-Boot commands to load and boot a kernel and rootfs over TFTP.
         Copy-paste into the device boot monitor