summaryrefslogtreecommitdiff
path: root/doc/euandre.org.en.7tutorial.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.7tutorial.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.7tutorial.adoc103
1 files changed, 103 insertions, 0 deletions
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].