Literate Emacs configuration

A literate configuration explains the decisions around executable Lisp instead of leaving them to be reverse-engineered later.

A literate configuration explains decisions around executable Lisp. Each section can hold prose that justifies a setting, followed by the block that applies it:

* Interface

Wrap prose visually; do not modify file line endings.

#+begin_src emacs-lisp :tangle init-generated.el
(add-hook 'org-mode-hook #'visual-line-mode)
#+end_src

The simplest startup strategy tangles the blocks manually, then loads the generated file from init.el:

(load (expand-file-name "init-generated.el" user-emacs-directory)
      'noerror)

Advantages and costs

Advantages include rationale kept beside code, section-level organization, and reusable blocks. Costs are equally concrete: another build step, harder startup debugging, and the temptation to narrate trivial settings that need no explanation.

The disciplines that keep it workable: keep a small bootstrap that stays readable without Org, tangle deterministically, and test the generated file with a clean Emacs before trusting it.

When startup fails

The generated file, not the beautiful prose around it, is what Emacs executes. If startup breaks, run emacs -Q to get a clean session, load the generated file incrementally, enable toggle-debug-on-error, and inspect the *Messages* buffer. Because the tangled output is the real program, debugging always returns to it rather than to the narrative that produced it.

Summary. Keeping your Emacs setup as an Org document puts rationale beside code and organizes it by section. The cost is another build step and harder startup debugging, so keep the bootstrap small and tangle deterministically.