11 files changed, 485 insertions, 1 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
new file mode 100644
index 0000000..0617ca4
--- /dev/null
+++ b/CHANGELOG.adoc
@@ -0,0 +1,26 @@
+= euandre.org(7CHANGELOG)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+////
+Entry template:
+== Unreleased
+=== Added
+=== Changed
+=== Deprecated
+=== Removed
+=== Fixed
+=== Security
+////
+
+Changelog for https://euandre.org.
+
+
+
+== Unreleased
diff --git a/README.adoc b/README.adoc
index d4d9297..9ec3858 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,4 +1,14 @@
-= euandre.org
+= euandre.org(7README)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== DESCRIPTION
 
 The source of https://euandre.org: a personal website of articles,
 notes, pastebins, podcasts, screencasts and slide decks, in six
diff --git a/TODOs.adoc b/TODOs.adoc
new file mode 100644
index 0000000..24da024
--- /dev/null
+++ b/TODOs.adoc
@@ -0,0 +1,41 @@
+= euandre.org(7TODOs)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== Tasks
+
+
+
+
+
+== Bugs
+
+
+
+
+
+== Improvements
+
+
+
+
+
+== Questions
+
+
+
+
+
+== Decisions
+
+
+
+
+
+== Ideas
diff --git a/doc/euandre.org.en.0.adoc b/doc/euandre.org.en.0.adoc
new file mode 100644
index 0000000..6d461c4
--- /dev/null
+++ b/doc/euandre.org.en.0.adoc
@@ -0,0 +1,58 @@
+= euandre.org(0)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== DESCRIPTION
+
+The manual for the repository that builds https://euandre.org.  It is
+a website, not a program: there is nothing here to install on a PATH,
+and what the pages describe is how the site is written and built.
+
+*euandre.org*(7README)::
+  What the site is, what builds it, and the licences it carries.
+
+*euandre.org*(7tutorial)::
+  Adding a page, from the empty file to the built HTML.
+
+*euandre.org*(7recipes)::
+  The tasks that come up once the shape is familiar: a translation, a
+  slide deck, a redirect, a deploy.
+
+*euandre.org*(7why)::
+  Why the site is built this way rather than another.
+
+*euandre.org*(7CHANGELOG), *euandre.org*(7TODOs)::
+  What has changed, and what is known to be left.
+
+The build rules are not this repository's own.  `mkdeps.sh` ends with
+`mkwb rules`, which writes them into `deps.mk`; what is kept here is
+only what is this site's --- its name, its languages, its port.  For
+the rules themselves see *mkwb*(1).
+
+
+
+== SEE ALSO
+
+*mkwb*(1), *adocg*(1), *po4a*(1), *eslaides*(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].
diff --git a/doc/euandre.org.en.3.adoc b/doc/euandre.org.en.3.adoc
new file mode 100644
index 0000000..3d28bb1
--- /dev/null
+++ b/doc/euandre.org.en.3.adoc
@@ -0,0 +1,42 @@
+= euandre.org(3)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== DESCRIPTION
+
+This repository builds a website.  It ships no library, so there is no
+API to document here, and this page exists because every project in
+the fleet carries the same set of pages --- a reader who knows where
+to look in one knows where to look in all of them.
+
+The code the site does lean on lives elsewhere and documents itself
+there: *mkwb*(3) for the builder, *adocg*(3) for the markup, and the
+compiler chain beneath it --- *pacag*(3), *tatug*(3), *cutiag*(3).
+
+
+
+== SEE ALSO
+
+*mkwb*(3), *adocg*(3), *euandre.org*(0)
+
+
+
+== 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].
diff --git a/doc/euandre.org.en.7CHANGELOG.adoc b/doc/euandre.org.en.7CHANGELOG.adoc
new file mode 120000
index 0000000..e59a806
--- /dev/null
+++ b/doc/euandre.org.en.7CHANGELOG.adoc
@@ -0,0 +1 @@
+../CHANGELOG.adoc
\ No newline at end of file
diff --git a/doc/euandre.org.en.7README.adoc b/doc/euandre.org.en.7README.adoc
new file mode 120000
index 0000000..a7ab0b1
--- /dev/null
+++ b/doc/euandre.org.en.7README.adoc
@@ -0,0 +1 @@
+../README.adoc
\ No newline at end of file
diff --git a/doc/euandre.org.en.7TODOs.adoc b/doc/euandre.org.en.7TODOs.adoc
new file mode 120000
index 0000000..b499888
--- /dev/null
+++ b/doc/euandre.org.en.7TODOs.adoc
@@ -0,0 +1 @@
+../TODOs.adoc
\ No newline at end of file
diff --git a/doc/euandre.org.en.7recipes.adoc b/doc/euandre.org.en.7recipes.adoc
new file mode 100644
index 0000000..aa26a89
--- /dev/null
+++ b/doc/euandre.org.en.7recipes.adoc
@@ -0,0 +1,107 @@
+= euandre.org(7recipes)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== DESCRIPTION
+
+Tasks that come up once the shape is familiar.  For the first page
+written start to finish, see *euandre.org*(7tutorial).
+
+
+
+== Build only what changed
+
+`make` is incremental and every artifact is its own target, so this is
+the default rather than a trick.  After adding or removing a file,
+regenerate the rules first --- they are a build product too:
+
+....
+$ sh mkdeps.sh > deps.mk
+$ make
+....
+
+
+
+== Check the site over
+
+....
+$ make check
+....
+
+Seventeen consistency checks: links that go nowhere, pages missing
+from an index, a feed entry without its page, and so on.  They read
+the built tree, so build first.
+
+
+
+== Regenerate the translations
+
+....
+$ make i18n
+....
+
+po4a writes the translated masters from `po/`.  The catalogues are the
+source; the translated `.adoc` files under `src/content/<lang>/` are
+not kept in the repository, which is why the build makes them.
+
+
+
+== Add a slide deck
+
+A deck is an `.eslaides` file under `src/content/`; *eslaides*(1)
+renders it to PostScript and ghostscript to PDF.  Both land beside the
+source, and `sh mkdeps.sh > deps.mk` is what notices the new file.
+
+
+
+== Serve the built site
+
+....
+$ make install
+$ make run
+....
+
+`install` unpacks what `all` already packed, so what is served next
+door and what would be deployed across a network are the same bytes.
+
+
+
+== Deploy
+
+....
+$ make upload
+....
+
+It asks the server what it has, subtracts what `all` wrote, and
+removes the difference before extracting the new tree --- so a page
+that stays is never taken from under a reader, and there is no moment
+when the site is missing.  Every step lands in a file naming what it
+holds, so what is about to be removed can be read before it is.
+
+
+
+== SEE ALSO
+
+*euandre.org*(7tutorial), *euandre.org*(0), *mkwb*(1), *eslaides*(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].
diff --git a/doc/euandre.org.en.7tutorial.adoc b/doc/euandre.org.en.7tutorial.adoc
new file mode 100644
index 0000000..0c99b39
--- /dev/null
+++ b/doc/euandre.org.en.7tutorial.adoc
@@ -0,0 +1,103 @@
+= euandre.org(7tutorial)
+
+
+
+== NAME
+
+euandre.org - a personal website in six languages, built from asciidoc
+
+
+
+== DESCRIPTION
+
+Writing one article, from nothing to a page on disk.  It assumes the
+tools are installed and `make` runs; everything else is here.
+
+
+
+== A first article
+
+Articles live under a collection, dated:
+
+....
+src/content/en/blog/2026/09/10/a-first-article.adoc
+....
+
+The path is the URL, and the three levels below the collection are the
+date.  Nothing registers the file anywhere --- `mkdeps.sh` finds it
+with `find`, so creating it is the whole of adding it.
+
+The file opens with its title and then says what it says:
+
+[source,asciidoc]
+....
+= A first article
+
+The first paragraph is the summary the indexes and the feed quote, so
+write it as one.
+
+== A section
+
+Prose, `code`, and the rest of *adocg*(7).
+....
+
+
+
+== Building it
+
+The rules are generated, so regenerate them, then build:
+
+....
+$ sh mkdeps.sh > deps.mk
+$ make
+....
+
+The page lands beside its source as
+`src/content/en/blog/2026/09/10/a-first-article.html`, and the
+collection index, the feed and the sitemap pick it up because the
+rules that build them were regenerated too.
+
+Read it before publishing it:
+
+....
+$ make install
+$ make run
+....
+
+
+
+== Where the other languages come from
+
+They are not written; they are translated.  The English file is the
+master, and `po/` holds one catalogue per language:
+
+....
+$ make i18n
+....
+
+writes the translated masters under `src/content/<lang>/`, which the
+next `sh mkdeps.sh > deps.mk` then finds like any other page.  A
+change to the English source propagates rather than drifting, which is
+the point of keeping them as catalogues rather than as copies.
+
+
+
+== SEE ALSO
+
+*euandre.org*(7recipes), *euandre.org*(0), *mkwb*(1), *adocg*(7), *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].
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].