summaryrefslogtreecommitdiff
path: root/doc/euandre.org.en.7recipes.adoc
diff options
context:
space:
mode:
authorEuAndreh <eu@euandre.org>2026-09-10 12:00:04 -0300
committerEuAndreh <eu@euandre.org>2026-09-10 12:00:13 -0300
commit9ec6794d8f04b7970e1401cae1d0d20321de3204 (patch)
treeeee45364e8ba422cfcebd452eaa50cb82fa918ea /doc/euandre.org.en.7recipes.adoc
parentName the i18n stamp a sentinel (diff)
downloadeuandre.org-9ec6794d8f04b7970e1401cae1d0d20321de3204.tar.gz
euandre.org-9ec6794d8f04b7970e1401cae1d0d20321de3204.tar.xz
Carry the pages every repository carries
The eight English section pages were missing, and with them the root CHANGELOG.adoc and TODOs.adoc: what changed between two releases and what is known to be left are not things a reader can work out from the tree. 7README, 7CHANGELOG and 7TODOs are symlinks to the root documents, as they are everywhere else. 0 links the rest, 7tutorial writes one page start to finish, 7recipes has the tasks that come after that, and 7why says why the site is built this way. 3 is a reference page for a library, and a website has none; it says so, and exists because a reader who knows where to look in one repository should know where to look in all of them. README.adoc gains the manpage title and NAME section the 7README symlink needs to render, its prose unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KxLpaNQThKfMG3ecCJptP9
Diffstat (limited to '')
-rw-r--r--doc/euandre.org.en.7recipes.adoc107
1 files changed, 107 insertions, 0 deletions
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].