From 1ea379f9072cff0845c758c6302d1dd56e1bb109 Mon Sep 17 00:00:00 2001
From: Lucien Cartier-Tilet <lucien@phundrak.com>
Date: Sun, 3 May 2026 01:11:40 +0200
Subject: [PATCH] docs(emacs): user user-lisp/ dir instead of plain lisp/ dir

Also precompile user-lisp content if the ELC files are older than
their original source file.
---
 docs/emacs/basic-config.org            |  2 +-
 docs/emacs/custom-elisp.org            |  2 +-
 docs/emacs/index.org                   | 71 +++++++++++++++++++-------
 docs/emacs/keybinding-managers.org     |  2 +-
 docs/emacs/keybindings.org             |  4 +-
 docs/emacs/package-manager.org         |  2 +-
 docs/emacs/packages/applications.org   |  2 +-
 docs/emacs/packages/autocompletion.org |  2 +-
 docs/emacs/packages/editing.org        |  2 +-
 docs/emacs/packages/emacs-builtin.org  |  2 +-
 docs/emacs/packages/exwm.org           |  2 +-
 docs/emacs/packages/helpful.org        |  2 +-
 docs/emacs/packages/latex.org          |  2 +-
 docs/emacs/packages/misc.org           |  2 +-
 docs/emacs/packages/org.org            |  2 +-
 docs/emacs/packages/programming.org    |  2 +-
 docs/emacs/packages/visual-config.org  |  2 +-
 17 files changed, 69 insertions(+), 36 deletions(-)

diff --git a/docs/emacs/basic-config.org b/docs/emacs/basic-config.org
index d21b2db..e589386 100644
--- a/docs/emacs/basic-config.org
+++ b/docs/emacs/basic-config.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Basic Configuration
 #+setupfile: ../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/basic-config.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/basic-config.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Basic Configuration
diff --git a/docs/emacs/custom-elisp.org b/docs/emacs/custom-elisp.org
index a67dbef..766f562 100644
--- a/docs/emacs/custom-elisp.org
+++ b/docs/emacs/custom-elisp.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Custom Elisp
 #+setupfile: ../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/custom-elisp.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/custom-elisp.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Custom Elisp
diff --git a/docs/emacs/index.org b/docs/emacs/index.org
index eb97f06..7ffcf46 100644
--- a/docs/emacs/index.org
+++ b/docs/emacs/index.org
@@ -78,6 +78,8 @@ block.
 #+end_src
 
 ** Loading All Configuration Modules
+Here are all my Emacs configuration modules, each dedicated to a
+specific aspect of my Emacs configuration.
 
 #+name: emacs-modules
 | Module Name            | Config Page                      |
@@ -98,27 +100,58 @@ block.
 | =visual-config.el=       | [[file:./packages/visual-config.org][Packages — Visual Configuration]]  |
 | =keybindings.el=         | [[file:./keybindings.org][Keybindings]]                      |
 
-#+name: generate-modules
-#+begin_src emacs-lisp :tangle no :cache yes :var modules=emacs-modules :exports none
-(mapconcat (lambda (line)
-             (concat "\"" (string-trim (car line) "=" "=") "\""))
-           modules
-           " ")
+#+name: modules
+#+begin_src emacs-lisp :tangle no :cache yes :var modules=emacs-modules :exports none :results list
+(mapcar (lambda (module) (string-trim (car module) "=" "="))
+        modules)
 #+end_src
 
-#+RESULTS[05f9bb535bec2ba84390cc118600323683f51e7c]: generate-modules
-: "basic-config.el" "custom-elisp.el" "package-manager.el" "keybinding-managers.el" "applications.el" "autocompletion.el" "editing.el" "emacs-builtin.el" "helpful.el" "latex.el" "misc.el" "org.el" "programming.el" "visual-config.el" "keybindings.el"
+#+RESULTS[1c6034eb268577137e95a6f828c249fc306943b1]: modules
+- basic-config.el
+- custom-elisp.el
+- package-manager.el
+- keybinding-managers.el
+- applications.el
+- autocompletion.el
+- editing.el
+- emacs-builtin.el
+- helpful.el
+- latex.el
+- misc.el
+- org.el
+- programming.el
+- visual-config.el
+- keybindings.el
 
-#+begin_src emacs-lisp :noweb yes
-(dolist (module '(<<generate-modules()>>))
+The first thing Emacs does is verify if any of these modules need to
+be byte-compiled again, i.e. if the =.el= file is younger than its
+corresponding =.elc= file. If so, the =.el= file is byte-compiled.
+
+#+begin_src emacs-lisp :var modules=modules :results none
+(defun my/mtime (file)
+  "Get the modification time of FILE as a timestamp."
+  (let* ((current-time-list nil)
+         (attr (file-attributes file))
+         (time-attr (file-attribute-modification-time attr)))
+    (/ (car time-attr) (cdr time-attr))))
+
+;; `modules' is a variable created by org-mode from the table of modules
+(let* ((config-dir (expand-file-name "user-lisp" user-emacs-directory))
+       (modules (mapcar (lambda (module)
+                         (file-name-sans-extension (expand-file-name module config-dir)))
+                        modules)))
+  (dolist (module modules)
+    (let* ((el-file (concat module ".el"))
+           (elc-file (concat module ".elc"))
+           (el-last-change (my/mtime el-file))
+           (elc-last-change (if (file-exists-p elc-file) (my/mtime elc-file) 0)))
+      (when (> el-last-change elc-last-change)
+        (byte-compile-file el-file)))))
+#+end_src
+
+Now we can load them.
+#+begin_src emacs-lisp :var modules=modules :results none
+(dolist (module (mapcar #'file-name-sans-extension modules))
   (load (expand-file-name module
-                          (expand-file-name "lisp" user-emacs-directory))))
+                          (expand-file-name "user-lisp" user-emacs-directory))))
 #+end_src
-
-* TODOs                                                            :noexport:
-** TODO advise ~evil-insert~ in eshell
-Advise ~evil-insert~ to go to the end of the buffer while in
-~eshell-mode~.
-
-** DONE Get started with org-roam
-CLOSED: [2023-06-17 Sat 13:38]
diff --git a/docs/emacs/keybinding-managers.org b/docs/emacs/keybinding-managers.org
index eb05ee9..0e1319a 100644
--- a/docs/emacs/keybinding-managers.org
+++ b/docs/emacs/keybinding-managers.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Keybinding Managers
 #+setupfile: ../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/keybinding-managers.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/keybinding-managers.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Keybinding Managers
diff --git a/docs/emacs/keybindings.org b/docs/emacs/keybindings.org
index 8211a3e..23eafb2 100644
--- a/docs/emacs/keybindings.org
+++ b/docs/emacs/keybindings.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Keybindings
 #+setupfile: ../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/keybindings.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/keybindings.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Keybindings
@@ -263,7 +263,7 @@ I also have some keybindings dedicated to opening specific files.
 "fI"  '((lambda ()
           (interactive)
           (quick-find-files nil
-                            (expand-file-name "lisp" user-emacs-directory)
+                            (expand-file-name "user-lisp" user-emacs-directory)
                             "el"))
         :which-key "elisp config"
         :package quick-find-files)
diff --git a/docs/emacs/package-manager.org b/docs/emacs/package-manager.org
index 0b780f9..4240a58 100644
--- a/docs/emacs/package-manager.org
+++ b/docs/emacs/package-manager.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Package Manager
 #+setupfile: ../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/package-manager.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/package-manager.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Package Manager
diff --git a/docs/emacs/packages/applications.org b/docs/emacs/packages/applications.org
index 0fb1107..ab13ee8 100644
--- a/docs/emacs/packages/applications.org
+++ b/docs/emacs/packages/applications.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Applications
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/applications.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/applications.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Applications
diff --git a/docs/emacs/packages/autocompletion.org b/docs/emacs/packages/autocompletion.org
index a903e3f..5f92a98 100644
--- a/docs/emacs/packages/autocompletion.org
+++ b/docs/emacs/packages/autocompletion.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Autocompletion
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/autocompletion.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/autocompletion.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Autocompletion
diff --git a/docs/emacs/packages/editing.org b/docs/emacs/packages/editing.org
index ed19d27..3d1839f 100644
--- a/docs/emacs/packages/editing.org
+++ b/docs/emacs/packages/editing.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Editing
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/editing.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/editing.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 
diff --git a/docs/emacs/packages/emacs-builtin.org b/docs/emacs/packages/emacs-builtin.org
index bb9e8eb..7d34418 100644
--- a/docs/emacs/packages/emacs-builtin.org
+++ b/docs/emacs/packages/emacs-builtin.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Emacs Built-ins
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/emacs-builtin.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/emacs-builtin.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 
diff --git a/docs/emacs/packages/exwm.org b/docs/emacs/packages/exwm.org
index d597902..1a12ce6 100644
--- a/docs/emacs/packages/exwm.org
+++ b/docs/emacs/packages/exwm.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — EXWM (Deprecated)
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/exwm.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/exwm.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * EXWM (Deprecated)
diff --git a/docs/emacs/packages/helpful.org b/docs/emacs/packages/helpful.org
index aeb0ac0..4823ce1 100644
--- a/docs/emacs/packages/helpful.org
+++ b/docs/emacs/packages/helpful.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Making My Life Easier
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/helpful.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/helpful.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Making my life easier
diff --git a/docs/emacs/packages/latex.org b/docs/emacs/packages/latex.org
index 7226782..eb157b9 100644
--- a/docs/emacs/packages/latex.org
+++ b/docs/emacs/packages/latex.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — LaTeX
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/latex.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/latex.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * LaTeX
diff --git a/docs/emacs/packages/misc.org b/docs/emacs/packages/misc.org
index 8a7894d..b6fd29a 100644
--- a/docs/emacs/packages/misc.org
+++ b/docs/emacs/packages/misc.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Misc
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/misc.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/misc.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Misc
diff --git a/docs/emacs/packages/org.org b/docs/emacs/packages/org.org
index 08e202a..6e2acd3 100644
--- a/docs/emacs/packages/org.org
+++ b/docs/emacs/packages/org.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Org Mode
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/org.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/org.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Org-mode
diff --git a/docs/emacs/packages/programming.org b/docs/emacs/packages/programming.org
index f382fee..0dd7ef4 100644
--- a/docs/emacs/packages/programming.org
+++ b/docs/emacs/packages/programming.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Programming
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/programming.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/programming.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Programming
diff --git a/docs/emacs/packages/visual-config.org b/docs/emacs/packages/visual-config.org
index 2fd9652..c1bd5e3 100644
--- a/docs/emacs/packages/visual-config.org
+++ b/docs/emacs/packages/visual-config.org
@@ -1,7 +1,7 @@
 #+title: Emacs — Packages — Visual Configuration
 #+setupfile: ../../headers
 #+property: header-args:emacs-lisp  :mkdirp yes :lexical t :exports code
-#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/lisp/visual-config.el
+#+property: header-args:emacs-lisp+ :tangle ~/.config/emacs/user-lisp/visual-config.el
 #+property: header-args:emacs-lisp+ :mkdirp yes :noweb no-export
 
 * Visual Configuration