3 files changed, 25 insertions(+), 1 deletions(-)

M .gitignore
M README.md
A screenshot.png

@@ 4,6 4,7 @@
 !.build.yml
 !.travis.yml
 !gh_rsa.enc
+!screenshot.png
 !LICENSE
 !.clang-format
 !*Makefile

@@ 3,9 3,32 @@ EFI boot manager; or, well, an EFI bootorder [compiler](//twitter.com/nabijaczle
 
 ## [Manpage](//git.sr.ht/~nabijaczleweli/klapki-man#NAME)
 
+[![screenshot of OVMF Boot Manager Nenu, showing an entry called "zoot", four similar entries starting with "Debian GNU/Linux" grouped by two kernel versions, the bottom entry of each version being suffixed with "(graphical)", then "Linux Boot Manager"](screenshot.png)](screenshot.png)
+
+### What?
+
+You need to boot Linux somehow, but running EFI-side code is a tad excessive for that
+(plus, GRUB is, hm, [suboptimal](https://nabijaczleweli.xyz/content/blogn_t/005-low-curse-zfs-on-root.html#bootloader) in general,
+ and sd-boot isn't versatile enough for my taste and the hook integration is questionable at best).
+
+klapki stores neither code nor data (well, except the kernel and initrds) on the ESP
+(which I think makes it secure-boot-compatible, but I haven't managed to ever use secure boot yet, so)
+and instead generates entries for the host's kernels and manages them during their lifetime from the host itself.
+
+Because of this, entries for each host can be trivially placed anywhere in the boot order (in the screenshot they're at `{bootpos 1}`, preceded by the "zoot" entry).
+
+As seen in the screenshot, boot variants ("graphical" in that case) are also supported, generating another entry per kernel;
+OVMF doesn't show it, but the difference can be seen from this listing of `/etc/klapki/cmdline` used to generate those entries;
+the [description](//git.sr.ht/~nabijaczleweli/klapki.deb/tree/50de836242adb578bc1bb6c288ddc450c4a4765c/debian/description) is a tad verbose to match convention:
+```sh
+#!/bin/sh
+echo root=ZFS=zoot/root
+[ "$2" = "graphical" ] || echo console=ttyS0
+```
+
 ### Building
 
-You'll need `libssl-dev` and `libefi{var,boot}-dev`, and `make` should hopefully Just Work™ if you have a C++17-capable compiler.
+You'll need `libssl-dev` and `libefi{var,boot}-dev`, to initialise the submodules, and `make` should hopefully Just Work™ if you have a C++17-capable compiler.
 
 Note that `klapki` uses Linux-specific [`memfd`](//manpages.debian.org/buster/manpages-dev/memfd_create.2.en.html)
 and [`sendfile()`](//manpages.debian.org/buster/manpages-dev/sendfile.2.en.html) interfaces, and as such building it will fail on other systems.