a manpage: slosh(1), installed, shipped, and held to the source

The distributables were a bare binary and a directory of Markdown, which
is fine until somebody types 'man slosh' -- the unix-traditional place
to ask. docs/slosh.1 is hand-written man(7), pure ASCII roff, no
toolchain: the synopsis, the options, the session commands, the default
keys, the mouse (including the new drag-past-an-edge scrolling), where
the configuration lives, what SLOSH_* means in a pane's environment,
files, exit status. The prose docs stay the long form; the page says so
and points at them.

'make install' puts it under PREFIX/share/man/man1 (and uninstall takes
it away), the release tarballs carry it beside the LICENSE -- a tarball
is what a packager starts from -- and the Homebrew formula installs it
when the commit it is building has one, guarded because the formula must
be able to build commits older than the page.

Prose about a program drifts unless something holds them together, so
test_docs.py holds the page to the source the way it already holds the
site to docs/nav: every option main.c's parser compares against and
every word command must appear in the page, every SLOSH_* variable the
code reads or sets must be documented, the roff must be pure ASCII (it
travels through implementations that never heard of preconv), and where
groff exists the page must lint clean at CHECKSTYLE=3 with -ww. Adding
a flag without documenting it is now a failing test, which is the only
kind of documentation policy that survives contact with a deadline.

1 files changed, 10 insertions, 6 deletions

diff --git a/Makefile b/Makefile
index d6dadc6..dd79e46 100644
--- a/Makefile
+++ b/Makefile
@@ -362,8 +362,9 @@ macos-dist: ## signed, notarized macOS build on the builder mac (REF=<tag> for a
 # out, and because both resolve the same tag the three names agree.
 DIST          ?= dist
 # Each tarball carries the binary plus the paperwork a redistributed build must
-# ship (see THIRD-PARTY-LICENSES: libghostty-vt and stb_image are linked in).
-REL_DOCS      := README.md LICENSE THIRD-PARTY-LICENSES
+# ship (see THIRD-PARTY-LICENSES: libghostty-vt and stb_image are linked in),
+# and the manpage, because a tarball is what a packager starts from.
+REL_DOCS      := README.md LICENSE THIRD-PARTY-LICENSES docs/slosh.1
 # The target triples we cross-build. The arch label in the artifact name is the
 # part before the first '-' (x86_64, aarch64).
 LINUX_TARGETS := x86_64-linux-musl aarch64-linux-musl
@@ -407,20 +408,23 @@ release: release-linux ## full release: linux tarballs + signed macOS zip + SHA2
 	$(Q)cat $(DIST)/SHA256SUMS
 
 # ── installation ────────────────────────────────────────────────────────────
-# For packagers (Homebrew's formula calls exactly this) and for anyone doing
+# For packagers (Homebrew's formula mirrors this layout) and for anyone doing
 # `sudo make install`. DESTDIR is the staging root a package manager wants;
 # PREFIX is where the files will finally live. The binary is the only thing
 # slosh needs to run -- the rest is example configuration you may copy into
-# ~/.config/slosh, so it goes to share/ and nothing reads it from there.
+# ~/.config/slosh, so it goes to share/ and nothing reads it from there. The
+# manpage goes where man(1) already looks, which is the whole point of one.
 PREFIX   ?= /usr/local
 DESTDIR  ?=
 BINDIR   := $(DESTDIR)$(PREFIX)/bin
 SHAREDIR := $(DESTDIR)$(PREFIX)/share/slosh
 DOCDIR   := $(DESTDIR)$(PREFIX)/share/doc/slosh
+MANDIR   := $(DESTDIR)$(PREFIX)/share/man/man1
 
 install: $(BIN) ## install to $PREFIX (default /usr/local, honours DESTDIR)
-	$(Q)install -d $(BINDIR) $(SHAREDIR) $(DOCDIR)
+	$(Q)install -d $(BINDIR) $(SHAREDIR) $(DOCDIR) $(MANDIR)
 	$(Q)install -m 755 $(BIN) $(BINDIR)/slosh
+	$(Q)install -m 644 docs/slosh.1 $(MANDIR)/slosh.1
 	$(Q)install -m 644 config/config.kdl config/example.layout $(SHAREDIR)/
 	$(Q)for d in themes chrome shaders; do \
 	  install -d $(SHAREDIR)/$$d; \
@@ -431,7 +435,7 @@ install: $(BIN) ## install to $PREFIX (default /usr/local, honours DESTDIR)
 	$(call say,[INST],$(BINDIR)/slosh)
 
 uninstall: ## remove what install put there
-	$(Q)rm -f $(BINDIR)/slosh
+	$(Q)rm -f $(BINDIR)/slosh $(MANDIR)/slosh.1
 	$(Q)rm -rf $(SHAREDIR) $(DOCDIR)
 	$(call say,[RM],$(BINDIR)/slosh)