1 files changed, 94 insertions, 0 deletions
diff --git a/doc/euandre.org.en.7why.adoc b/doc/euandre.org.en.7why.adoc
new file mode 100644
index 0000000..2ba9b7c
--- /dev/null
+++ b/doc/euandre.org.en.7why.adoc
@@ -0,0 +1,94 @@
+= euandre.org(7why)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== DESCRIPTION
+
+Why the site is built this way rather than another.
+
+
+
+== Static in the strict sense
+
+Every page, feed and sitemap is a file on disk, and serving the site
+needs nothing but a web server.  Not "static" in the sense of a
+generator that ships a runtime and calls the output static: there is
+no database to migrate, no process to keep up, and no version of
+anything to keep patched.  A directory of files outlives the tooling
+that made it, which for a personal site measured in decades is the
+property worth having.
+
+
+
+== The rules are not here
+
+`mkdeps.sh` ends with `mkwb rules`, which writes the canonical rules
+into `deps.mk`.  Only what is this site's stays here --- its name, its
+languages, its port.
+
+A copy of the rules per site drifts, and did.  Two sites built the
+same way should differ in what they are, not in how they are made, and
+the way to hold that is for the shared half to have one home.  See
+*mkwb*(1).
+
+
+
+== One target per artifact
+
+The build is a rule per file rather than one program that walks the
+tree.  It costs processes --- the greater part of a build is spent
+starting them --- and buys the thing that matters more: an incremental
+build that rebuilds what changed and nothing else, and a `-j` that
+needs no coordination.  A page that is wrong can be deleted and made
+again by itself.
+
+
+
+== Translations as catalogues, not copies
+
+The English source is the master and `po/` holds one catalogue per
+language, from which *po4a*(1) writes the rest.  A second copy of a
+page drifts from the first the moment either is edited, and nothing
+notices; a catalogue with a stale entry says so.
+
+The translated masters are therefore build products and are not kept
+in the repository.
+
+
+
+== Prune by name, then extract
+
+Deploying asks the server what it has, subtracts what the build wrote,
+and removes only the difference.  Wholesale replacement would be
+simpler, but there is a moment in the middle of it when the site is
+missing, and `/srv` is root's, so the directory cannot be swapped
+underneath anyway.  Naming what goes means it can be read before it
+goes.
+
+
+
+== SEE ALSO
+
+*euandre.org*(0), *euandre.org*(7README), *mkwb*(1), *po4a*(1)
+
+
+
+== AUTHORS
+
+mailto:eu@euandre.org[EuAndreh] and contributors.
+
+
+
+== BUGS
+
+* Report bugs to the mailto:~euandreh/public-inbox@lists.sr.ht[mailing list].
+  Use the subject "[euandre.org] BUG or TASK: <description>".
+* Browse bugs https://euandre.org/git/euandre.org/TODOs.html[online].
+* https://euandre.org/git/euandre.org/[Homepage].
+* https://lists.sr.ht/~euandreh/public-inbox?search=%5Beuandre%2Eorg%5D[Comments and discussions].