Nix is declarative. Reading a Nix expression reveals what the system should become, and Nix itself handles how to get there. But neither the code nor the build system captures why a particular configuration exists, or why alternatives were rejected.

Why was fish chosen over zsh or bash? Why does the desktop profile enable this specific set of services? Why was a particular package pinned to an older version? The code shows the decision, but not the reasoning behind it. Without this context, future changes risk undoing intentional tradeoffs or repeating previously rejected approaches.

This repository uses literate programming to preserve intent. Configuration lives in Org mode documents where prose surrounds code. Each decision—from high-level architecture to individual package overrides—is accompanied by its rationale: why this approach was chosen, and why alternatives were not.

Configurations are documented with the problem that motivated them, the alternatives considered, and the reasoning behind the final choice. For temporary workarounds, the conditions for removal are also noted.

This project uses po4a to manage translations.

• gettext
• po4a >= 0.74 (required for Org mode support)

Configure the target language, location for generated po files, and documents to translate as follows. The -k 0 option forces output of translated files even if the translation is incomplete (default threshold is 80%).

[po4a_langs] ja
[po4a_paths] po/dotfiles.pot $lang:po/$lang.po
[type: org] README.org $lang:README.$lang.org opt:"-k 0"
[type: org] configuration.org $lang:configuration.$lang.org opt:"-k 0"
[type: org] applications/emacs/init.org $lang:applications/emacs/init.$lang.org opt:"-k 0"
[type: org] applications/emacs/early-init.org $lang:applications/emacs/early-init.$lang.org opt:"-k 0"

For detailed information about po4a.cfg configuration, see man po4a.

When documents are updated and you need to create/update po files, run the following command. This generates template (pot) and po files for each language at the paths configured in po4a.cfg.

po4a --no-translations po4a.cfg

Edit the target language po using a po editor. Popular options include Emacs po-mode, poedit, GNOME’s Gtranslator, and KDE’s Lokalize.

After completing translations, generate files with the following command. Since po files are also updated at this time, in practice you only need to run this command.

po4a po4a.cfg