1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
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].
|
