docs: tidy up README

Sponsored-by: author

1 files changed, 34 insertions, 24 deletions

diff --git a/README.md b/README.md
index 1d1294e..14a00fb 100644
--- a/README.md
+++ b/README.md
@@ -60,12 +60,14 @@ Explanation:
   DHCP, it can provide a name. The author's home network setup
   automatically adds that hostname to the internal DNS. This avoids a
   manual DNS configuration step, and the author is lazy.
-* `drive`---the main drive to install to. This will have the EFI and
-  `/boot` partitions, and have GRUB installed. The rest of the drive
-  will be a physical volume for LVM2.
+  ([dnsmasq](https://dnsmasq.org/) is lovely.)
+* `drive`---the main drive to install to. This is where the EFI and
+  `/boot` partitions are created, and where GRUB gets installed. The
+  rest of the drive will be a physical volume for LVM2.
 * `extra_drives`---any additional physical volumes for LVM2. These
-  will not be partitioned.
-* `luks`---the password for full disk encryption for LVM2 physical
+  will not be partitioned, and will be used entirely as physical
+  volumes.
+* `luks`---the password for full disk encryption for all LVM2 physical
    volumes. If not set, LUKS is not used. This is a single, fixed
    password that is in cleartext. You are expected to change it after
    the system is installed and boots. If you'd rather use, say, a
@@ -76,14 +78,15 @@ Explanation:
   [`std.yml`][]) that it uses unconditionally, to set up a "standard
   system" that the author likes. You can provide additional playbooks,
   for additional configuration at installation time.
+* `ansible_vars`---variables to set for Ansible playbooks.
   - the `user_pub` variable contains an SSH public key that gets
     installed into the `root` user `authorized_keys` file on the
-    installed system
-* `ansible_vars`---variables to set for Ansible playbooks.
+    installed system by the standard playbook
 
 With all this configuration in a file, which you can keep in git, you
 can install a base system repeatedly to a specific computer, and do it
-the same way every time.
+the same way every time. If that's not something you do, then you may
+want to use the official Debian installer instead.
 
 (Caveat: **v-i** does nothing to configure your BIOS/UEFI. It can't.
 You have to manually configure it the way you want it to be. For
@@ -106,24 +109,25 @@ tedious.)
 
 The official [Debian installer][] is often referred to as _d-i_. It
 works quite well, for almost any hardware Debian can run on, and
-supports a lot of languages, and if flexible enough to be acceptable
+supports a lot of languages, and it's flexible enough to be acceptable
 for nearly every use case. Millions upon millions of people are
 satisfied users of it. It is a great achievement of Debian, and the
 people of the `debian-boot` team.
 
-However, the **v-i** author felt it could be improved upon for them:
+However, the **v-i** author felt it could be improved upon slightly
+for their use case:
 
 * d-i is not entirely easy to understand and modify. It requires
   building special [udeb][] packages for any software that's to be
   part of the installer environment, which makes it harder to make
-  changes without collaboration from maintainers of those packages.
-  The architecture of d-i is also a little non-linear. d-i also needs
-  to support a very wide variety of hardware and use cases, which has
+  changes without co-operation from maintainers of those packages. The
+  architecture of d-i is also a little non-linear. d-i also needs to
+  support a very wide variety of hardware and use cases, which has
   made it large and complex.
 
   **v-i** is happy with normal deb packages, and is a thin Python
   wrapper script around **vmdb2**, making it reasonably easy to
-  understand and change.
+  understand and change. Well, easy for its author.
 
 * d-i is primarily meant to be used interactively, but it does support
   [preseed files][] for automating an installation. Preseeding means
@@ -154,7 +158,8 @@ be finished using your configuration management system of choice.
 
 While **vmdb2** can, and does, run Ansible to configure the system
 being installed, in practice some things work better if most
-configuration is done to a running system. The goal of **v-i** is to
+configuration is done to a running system; if nothing else, some
+Ansible modules don't work well in a chroot. The goal of **v-i** is to
 get a system into that state as quickly and easily as possible. For
 example, the Ansible module to set a hostname on a system with systemd
 requires systemd to be running. That's awkward while the system is
@@ -164,6 +169,8 @@ Thus, **v-i** does the following:
 
 * delete any trace of LVM2 from all drives, wipe all SSDs, and
   generally reset the system to as close to a blank state as possible
+  - there is no question "are you sure?" to give the user a chance to
+    repent: as soon as you run **v-i**, you've lost all your data
 * create a partition table ("label") on the target drive
 * create EFI and boot partitions, needed to boot with UEFI and LUKS
 * create a physical volume for LVM2, and a logical volume for the root
@@ -189,7 +196,8 @@ archive. On subsequent runs, if the cache file exists, it's unpacked,
 instead of running the commands. This speeds things up a bit: running
 **v-i** without the cache file takes the author about 5 minutes; with
 the cache file it takes about 1.5 minutes. This matters if there is a
-need to do many installations.
+need to do many installations. It also matters if you're developing
+an installer and need to run it tens of times a day.
 
 
 ## Hacking
@@ -210,11 +218,8 @@ Also, to build an image to boot off for running the installer:
 * `installer.yml`---the Ansible playbook for creating the installer
   image
 
-You'll want to build your own installer image, if you want to log into
-it over SSH, so that you can install your own SSH key. If you log in
-via the Linux virtual console, you don't need that: there's no
-password for root (but SSH login for root doesn't work with
-passwords).
+See the tutorial about ways to add your SSH public key to the image so
+that you can log into the installer via SSH.
 
 You probably mostly only need to modify `v-i` and `std.yml`. The rest
 is to get you and your target machine into a state where you can run
@@ -242,10 +247,15 @@ we will see.
 
 Yes.
 
+### Why is BIOS (without UEFI) not supported?
+
+All of the author's PCs have UEFI, and the author doesn't care to do
+the work to add support for BIOS.
+
 ### What about multi-boot?
 
 **v-i** doesn't support installing more than one operating system on
-one computer.
+one computer. The author has no need for this.
 
 ### What about installing something else than Debian?
 
@@ -263,10 +273,10 @@ least the following steps in **vmdb2** code, and then change the
     cache tar archive
 * `apt`---install packages
   - whatever package manager the system has probably works
-  - you can probably run the package manager from a chroot step
+  - you can probably run the package manager from a **vmdb2** `chroot` step
 * `grub`---install boot loader
   - this chooses the appropriate Debian package automatically
-  - might possibly be doable as a chroot step
+  - might possibly be doable as a `shell` step
   - this is likely the trickiest bit: booting is _intricate_
 * `cryptsetup`---format a drive for full disk encryption
   - this just runs the `cryptsetup` program and tells the fstab step