README.md: refactor

cleans up README.md, generates it from README.md.in with `make README.md`
to easily include help output of each script

Author: classabbyamp

.gitattributes

@@ -0,0 +1 @@
+README.md linguist-generated=true

Makefile

@@ -34,6 +34,15 @@ COMPRESSOR_THREADS:=2
 
 all:
 
+README.md: README.md.in build-x86-images.sh mklive.sh mkrootfs.sh mkplatformfs.sh mkimage.sh mknet.sh
+	printf '<!-- DO NOT EDIT, generated by make README.md -->\n\n' > README.md
+	cat README.md.in >> README.md
+	for script in build-x86-images mklive mkrootfs mkplatformfs mkimage mknet; do \
+		printf '### %s.sh\n\n```\n' "$${script}" >> README.md ; \
+		"./$${script}.sh" -h >> README.md ; \
+		printf '```\n\n' >> README.md ; \
+	done
+
 checksum: dist
 	cd distdir-$(DATECODE)/ && sha256 * > sha256sum.txt
 

README.md

@@ -0,0 +1,90 @@
+# The Void Linux live image/rootfs generator and installer
+
+## Overview
+
+This repository contains several utilities:
+
+* [*mklive.sh*](#mklivesh) - The Void Linux live image generator for x86
+* [*build-x86-images.sh*](#build-x86-imagessh) - Wrapper script to generate bootable
+  and installable live images for x86
+* [*mkrootfs.sh*](#mkrootfssh) - The Void Linux rootfs generator for all platforms
+* [*mkplatformfs.sh*](#mkplatformfssh) - The Void Linux filesystem tool to produce
+  a rootfs for a particular platform
+* [*mkimage.sh*](#mkimagesh) - The Void Linux image generator for ARM platforms
+* [*mknet.sh*](#mknetsh) - Script to generate netboot tarballs for Void
+* *installer.sh* - The Void Linux el-cheapo installer for x86
+* *release.sh* - interacts with GitHub CI to generate and sign images for releases
+
+### Workflow
+
+#### Generating x86 live ISOs
+
+To generate a live ISO like the officially-published ones, use
+[*build-x86-images.sh*](#build-x86-imagessh). To generate a more basic live ISO
+(which does not include things like `void-installer`), use [*mklive.sh*](#mklivesh).
+
+#### Generating ROOTFS tarballs
+
+ROOTFS tarballs contain a basic Void Linux root filesystem without a kernel.
+These can be useful for doing a [chroot install](https://docs.voidlinux.org/installation/guides/chroot.html)
+or for [chroots and containers](https://docs.voidlinux.org/config/containers-and-vms/chroot.html).
+
+Use [*mkrootfs.sh*](#mkrootfssh) to generate a Void Linux ROOTFS.
+
+#### Generating platform-specific tarballs
+
+Platform-specific ROOTFS tarballs, or PLATFORMFS tarballs, contain a basic Void
+Linux root filesystem including a kernel. These are commonly used for bootstrapping
+ARM systems or other environments that require platform-specific kernels, like
+Raspberry Pis.
+
+First create a ROOTFS for the desired architecture, then use
+[*mkplatformfs.sh*](#mkplatformfssh) to generate a Void Linux PLATFORMFS.
+
+#### Generating ARM images
+
+Platform-specific filesystem images contain a basic filesystem layout (`/` and
+`/boot` partitions), ready to be copied to the target drive with `dd`. despite
+the naming, they are not traditional "live" images like those available on x86
+platforms, and do not need installation like live ISOs.
+
+To generate these images, first create a PLATFORMFS for the desired platform,
+then use [*mkimage.sh*](#mkimagesh) to generate the image.
+
+## Dependencies
+
+Note that void-mklive is not guaranteed to work on distributions other than Void
+Linux, or in containers.
+
+* Compression type for the initramfs image (by default: liblz4 for lz4, xz)
+* xbps>=0.45
+* qemu-user-static binaries (for mkrootfs)
+* bash
+
+## Kernel Command-line Parameters
+
+`void-mklive`-based live images support several kernel command-line arguments
+that can change the behavior of the live system:
+
+- `live.autologin` will skip the initial login screen on `tty1`.
+- `live.user` will change the username of the non-root user from the default
+  `anon`. The password remains `voidlinux`.
+- `live.shell` sets the default shell for the non-root user in the live environment.
+- `live.accessibility` enables accessibility features like the console screenreader
+  `espeakup` in the live environment.
+- `console` can be set to `ttyS0`, `hvc0`, or `hvsi0` to enable `agetty` on that
+  serial console.
+- `locale.LANG` will set the `LANG` environment variable. Defaults to `en_US.UTF-8`.
+- `vconsole.keymap` will set the console keymap. Defaults to `us`.
+
+### Examples:
+
+- `live.autologin live.user=foo live.shell=/bin/bash` would create the user `foo`
+  with the default shell `/bin/bash` on boot, and log them in automatically on `tty1`
+- `live.shell=/bin/bash` would set the default shell for the `anon` user to `/bin/bash`
+- `console=ttyS0 vconsole.keymap=cf` would enable `ttyS0` and set the keymap in
+  the console to `cf`
+- `locale.LANG=fr_CA.UTF-8` would set the live system's language to `fr_CA.UTF-8`
+
+## Usage
+