General refactor for readability

+ Removes redundant/unhelpful comments
+ Renames functions, hooks and variables to be self-documenting
+ Use add-to-list to ensure idempotency (and is more performant)

modules/lang/org/+attach.el

@@ -31,11 +31,9 @@
 (def-package! org-download
   :commands (org-download-dnd org-download-dnd-base64)
   :init
-  ;; Add these myself, so that org-download is lazy-loaded...
-  (setq dnd-protocol-alist
-        `(("^\\(https?\\|ftp\\|file\\|nfs\\):" . +org-attach-download-dnd)
-          ("^data:" . org-download-dnd-base64)
-          ,@dnd-protocol-alist))
+  ;; Add these manually so that org-download is lazy-loaded...
+  (add-to-list 'dnd-protocol-alist '("^\\(https?\\|ftp\\|file\\|nfs\\):" . +org-attach-download-dnd))
+  (add-to-list 'dnd-protocol-alist '("^data:" . org-download-dnd-base64))
 
   (advice-add #'org-download-enable :override #'ignore)
   :config
@@ -78,8 +76,7 @@
   (setq org-attach-directory (expand-file-name +org-attach-dir org-directory))
 
   ;; A shorter link to attachments
-  (push (cons "attach" (abbreviate-file-name org-attach-directory))
-        org-link-abbrev-alist)
+  (add-to-list 'org-link-abbrev-alist (cons "attach" (abbreviate-file-name org-attach-directory)))
 
   (org-link-set-parameters
    "attach"
@@ -93,10 +90,9 @@
                  'error)))
 
   (after! projectile
-    (push (car (last (split-string +org-attach-dir "/" t)))
-          projectile-globally-ignored-directories))
+    (add-to-list 'projectile-globally-ignored-directories
+                 (car (last (split-string +org-attach-dir "/" t)))))
 
   (after! recentf
-    (push (format "%s.+$" (regexp-quote org-attach-directory))
-          recentf-exclude)))
+    (add-to-list 'recentf-exclude (format "%s.+$" (regexp-quote org-attach-directory)))))
 

modules/lang/org/+babel.el

@@ -40,12 +40,11 @@ string). Stops at the first function to return non-nil.")
         t)))
   (advice-add #'org-babel-confirm-evaluate :around #'+org*babel-lazy-load-library)
 
-  ;; I prefer C-c C-c for confirming over the default C-c '
+  ;; I prefer C-c C-c over C-c '
   (define-key org-src-mode-map (kbd "C-c C-c") #'org-edit-src-exit)
 
-  ;; In a recent update, `org-babel-get-header' was removed from org-mode, which
-  ;; is something a fair number of babel plugins use. So until those plugins
-  ;; update, this polyfill will do:
+  ;; `org-babel-get-header' was removed from org in 9.0. Quite a few babel
+  ;; plugins use it, so until those plugins update, this polyfill will do:
   (defun org-babel-get-header (params key &optional others)
     (cl-loop with fn = (if others #'not #'identity)
              for p in params

modules/lang/org/autoload/org.el

@@ -268,7 +268,7 @@ wrong places)."
   (org-toggle-checkbox '(4)))
 
 ;;;###autoload
-(defalias #'+org/toggle-fold #'+org|toggle-only-current-fold)
+(defalias #'+org/toggle-fold #'+org|cycle-only-current-subtree)
 
 ;;;###autoload
 (defun +org/open-fold ()
@@ -319,7 +319,7 @@ another level of headings on each invocation."
 ;;
 
 ;;;###autoload
-(defun +org|delete-backward-char ()
+(defun +org|delete-backward-char-and-realign-table-maybe ()
   "TODO"
   (when (eq major-mode 'org-mode)
     (org-check-before-invisible-edit 'delete-backward)
@@ -388,7 +388,7 @@ another level of headings on each invocation."
     t))
 
 ;;;###autoload
-(defun +org|toggle-only-current-fold (&optional arg)
+(defun +org|cycle-only-current-subtree (&optional arg)
   "Toggle the local fold at the point (as opposed to cycling through all levels
 with `org-cycle')."
   (interactive "P")
@@ -416,7 +416,7 @@ with `org-cycle')."
 ;;
 
 ;;;###autoload
-(defun +org*return-indent-in-src-blocks ()
+(defun +org*fix-newline-and-indent-in-src-blocks ()
   "Try to mimic `newline-and-indent' with correct indentation in src blocks."
   (when (org-in-src-block-p t)
     (org-babel-do-in-edit-buffer

modules/lang/org/config.el

@@ -30,7 +30,7 @@
   (add-hook 'org-load-hook #'+org|setup-evil)
   (add-hook 'evil-org-mode-hook #'evil-normalize-keymaps)
   :config
-  ;; only support the `evil-org-key-theme' workflow
+  ;; change `evil-org-key-theme' instead
   (advice-add #'evil-org-set-key-theme :override #'ignore)
   (def-package! evil-org-agenda
     :after org-agenda
@@ -44,7 +44,7 @@
 (add-hook! 'org-load-hook
   #'(org-crypt-use-before-save-magic
      +org|setup-ui
-     +org|setup-popups-rules
+     +org|setup-popup-rules
      +org|setup-agenda
      +org|setup-keybinds
      +org|setup-hacks
@@ -132,7 +132,7 @@ unfold to point on startup."
    org-agenda-start-on-weekday nil
    org-agenda-start-day "-3d"))
 
-(defun +org|setup-popups-rules ()
+(defun +org|setup-popup-rules ()
   "Defines popup rules for org-mode (does nothing if :ui popup is disabled)."
   (set-popup-rules!
     '(("^\\*Org Links" :slot -1 :vslot -1 :size 2 :ttl 0)
@@ -193,7 +193,7 @@ unfold to point on startup."
 
   ;; Previews are usually rendered with light backgrounds, so ensure their
   ;; background (and foreground) match the current theme.
-  (defun +org|update-latex-faces ()
+  (defun +org|update-latex-preview-background-color ()
     (setq-default
      org-format-latex-options
      (plist-put org-format-latex-options
@@ -201,7 +201,7 @@ unfold to point on startup."
                 (face-attribute (or (cadr (assq 'default face-remapping-alist))
                                     'default)
                                 :background nil t))))
-  (add-hook 'doom-load-theme-hook #'+org|update-latex-faces)
+  (add-hook 'doom-load-theme-hook #'+org|update-latex-preview-background-color)
 
   ;; Custom links
   (setq org-link-abbrev-alist
@@ -246,18 +246,18 @@ unfold to point on startup."
   "Sets up org-mode and evil keybindings. Tries to fix the idiosyncrasies
 between the two."
   (add-hook 'doom-escape-hook #'+org|remove-occur-highlights)
+
   ;; C-a & C-e act like `doom/backward-to-bol-or-indent' and
   ;; `doom/forward-to-last-non-comment-or-eol', but with more org awareness.
   (setq org-special-ctrl-a/e t)
-  ;; Try indenting normally or expanding snippets on TAB
-  (add-hook! 'org-tab-first-hook #'(+org|indent-maybe +org|yas-expand-maybe))
-  ;; Tell `doom/delete-backward-char' to respect org tables
-  (add-hook 'doom-delete-backward-functions #'+org|delete-backward-char)
-  ;; Don't split current tree on M-RET
+
   (setq org-M-RET-may-split-line nil
         ;; insert new headings after current subtree rather than inside it
         org-insert-heading-respect-content t)
-  ;; Custom keybinds
+
+  (add-hook! 'org-tab-first-hook #'(+org|indent-maybe +org|yas-expand-maybe))
+  (add-hook 'doom-delete-backward-functions #'+org|delete-backward-char-and-realign-table-maybe)
+
   (define-key! org-mode-map
     (kbd "C-c C-S-l") #'+org/remove-link
     (kbd "C-c C-i")   #'org-toggle-inline-images
@@ -268,20 +268,20 @@ between the two."
   ;; In case this hook is used in an advice on `evil-org-set-key-theme', this
   ;; prevents recursive requires.
   (unless args (require 'evil-org))
-  ;; By default, TAB cycles the visibility of all children under the current
-  ;; tree between three states. I want to toggle the tree between two states,
-  ;; without affecting its children.
-  (add-hook 'org-tab-first-hook #'+org|toggle-only-current-fold t)
-  ;; Fix newline-and-indent behavior in src blocks
-  (advice-add #'org-return-indent :after #'+org*return-indent-in-src-blocks)
+
+  (add-hook 'org-tab-first-hook #'+org|cycle-only-current-subtree t)
+  (advice-add #'org-return-indent :after #'+org*fix-newline-and-indent-in-src-blocks)
+
   ;; Fix o/O creating new list items in the middle of nested plain lists. Only
   ;; has an effect when `evil-org-special-o/O' has `item' in it (not the
   ;; default).
   (advice-add #'evil-org-open-below :around #'+org*evil-org-open-below)
-  ;; Undo `evil-collection-outline'
+
+  ;; Undo keybinds in `evil-collection-outline'
   (evil-define-key* 'normal outline-mode-map
     "^" nil
     [backtab] nil
+    "\M-j" nil "\M-k" nil
     "\C-j" nil "\C-k" nil
     "]" nil "[" nil)
   (evil-define-key* 'insert evil-org-mode-map
@@ -346,6 +346,7 @@ between the two."
   "Getting org to behave."
   ;; Don't open separate windows
   (setf (alist-get 'file org-link-frame-setup) #'find-file)
+
   ;; Fix variable height org-level-N faces in the eldoc string
   (defun +org*fix-font-size-variation-in-eldoc (orig-fn)
     (cl-letf (((symbol-function 'org-format-outline-path)
@@ -360,7 +361,7 @@ between the two."
                   separator))))
       (funcall orig-fn)))
   (advice-add #'org-eldoc-get-breadcrumb :around #'+org*fix-font-size-variation-in-eldoc)
-  ;; Let OS decide what to do with files when opened
+
   (setq org-file-apps
         `(("pdf" . default)
           ("\\.x?html?\\'" . default)
@@ -368,7 +369,7 @@ between the two."
           (directory . emacs)
           (t . ,(cond (IS-MAC "open -R \"%s\"")
                       (IS-LINUX "xdg-open \"%s\"")))))
-  ;; Don't clobber recentf or current workspace with agenda files
+
   (defun +org|exclude-agenda-buffers-from-workspace ()
     (when org-agenda-new-buffers
       (let (persp-autokill-buffer-on-remove)