diff options
| author | EuAndreh <eu@euandre.org> | 2026-09-10 12:00:04 -0300 |
|---|---|---|
| committer | EuAndreh <eu@euandre.org> | 2026-09-10 12:00:13 -0300 |
| commit | 9ec6794d8f04b7970e1401cae1d0d20321de3204 (patch) | |
| tree | eee45364e8ba422cfcebd452eaa50cb82fa918ea /doc/euandre.org.en.7recipes.adoc | |
| parent | Name the i18n stamp a sentinel (diff) | |
| download | euandre.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 'doc/euandre.org.en.7recipes.adoc')
| -rw-r--r-- | doc/euandre.org.en.7recipes.adoc | 107 |
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]. |
