La idea, en una frase

Donde antes tenías un fichero de código con comentarios, ahora tienes un documento con código dentro. El protagonista es la explicación; el código son los ejemplos. Y una herramienta extrae automáticamente todo el código a un fichero ejecutable. Eso es literate programming, una idea vieja de Donald Knuth, y org-mode la implementa de fábrica.

Aplicada a tu config de Emacs: escribes config.org, y de él se genera tu config.el de siempre.

Cómo funciona, sin misterios

Un config.org es un documento org normal: títulos con *, párrafos de texto, y bloques de código así:

#+begin_src emacs-lisp
(setq alguna-cosa t)
#+end_src

La magia está en una línea de cabecera al principio del documento que dice "todo el código emacs-lisp de aquí, vuélcalo a config.el":

#+PROPERTY: header-args:emacs-lisp :tangle config.el

A la acción de extraer el código se le llama tangle (enmarañar/destilar, en la jerga de Knuth). Cuando haces tangle del config.org, org recorre todos los bloques emacs-lisp y los escribe, en orden, a config.el. Ese config.el generado es el que Emacs carga: no cambia nada para Emacs, sigue viendo un fichero de código normal. El humano edita el .org; la máquina come del .el.

En Doom es un interruptor

Si usas Doom Emacs, no tienes que montar el tangle a mano. Hay un módulo que lo hace por ti: activas literate en la sección :config de tu init.el, y Doom se encarga de "destilar" tu config.org a config.el cada vez que lo cambias. Tú editas siempre el .org; el .el pasa a ser un derivado (de hecho conviene meterlo en el .gitignore: es producto, no fuente).

En otras distribuciones, o en vanilla, el patrón es el mismo con una llamada a org-babel-tangle (manual, o en un hook al guardar).

Por qué merece la pena

No es estética. Es un cambio en qué documentas:

• En un .el comentas el qué ("subo este número a 1MB"). En un .org documentas el porqué ("el valor por defecto ahoga al servidor de lenguaje; con 1MB las respuestas grandes fluyen sin tartamudeo"). Eso es lo que se te olvida en seis meses, no la línea de código.
• Se navega: títulos, índice, plegado. Tu config deja de ser una pared de 600 líneas y pasa a ser un libro con capítulos.
• Se vuelve enseñable. Cuando tu config es prosa + código, explicarla a otro (o a tu yo futuro) es gratis. De hecho, buena parte de esta serie de posts sale de leer la config y contarla: cuando ya está escrita en castellano, el post casi se escribe solo.

Una advertencia antes de presumir

La tentación es inmediata: "si mi config es un documento bonito, ¡lo publico!". Adelante, pero con una regla de oro: una config suele tener datos personales —rutas de tu disco, algún correo, identificadores de calendarios, y en el peor caso claves o tokens—. Antes de publicar el .org en ningún sitio, pásale un buen grep buscando secretos e información privada. Lo que es comodísimo de compartir es también comodísimo de filtrar sin querer. Un minuto de revisión te ahorra un disgusto.

El patrón de siempre

La mejor documentación de tu sistema es la que vive pegada al sistema. Si para entender tu config tienes que leer código y adivinar intenciones, te falta una capa. Esa capa es la prosa, y org-babel la pone justo donde toca.

Pasar de config.el a config.org no añade ni una funcionalidad a tu Emacs. Lo que añade es que, dentro de un año, vas a entender por qué hiciste cada cosa. Y eso, en un editor que configuras durante toda la vida, vale más que cualquier paquete.

— doomguru