refactor:org-modules: Improve org-mode configuration

Remove redundant declarations and reorganize settings for clarity.
Centralize org-mode customizations and use `use-package` for
streamlined loading and configuration. Remove backward-compatible
safeguards and reduce inline comments for cleaner code. Optimize key
mappings and simplify the setup of org-related packages.

1 files changed, 124 insertions, 187 deletions

diff --git a/modules/org-config.el b/modules/org-config.el
index 178562f4..8fe8ed6d 100644
--- a/modules/org-config.el
+++ b/modules/org-config.el
@@ -2,60 +2,105 @@
 ;; author Craig Jennings <c@cjennings.net>
 ;;; Commentary:
 
-;; Setting org-modules to org-protocol, ol-eww, ol-w3m, and ol-info removes
-;; several modules that org would otherwise load automatically.
+;; note: org-archive-location is set in the :config section after org loads
 
 ;;; Code:
 
-;; Forward declarations
-(eval-when-compile (defvar org-dir))
-
-;; Forward declarations for org-mode variables
-(defvar org-mode-map)
-(defvar org-modules)
-(defvar org-startup-folded)
-(defvar org-cycle-open-archived-trees)
-(defvar org-outline-path-complete-in-steps)
-(defvar org-return-follows-link)
-(defvar org-list-allow-alphabetical)
-(defvar org-startup-indented)
-(defvar org-adapt-indentation)
-(defvar org-indent-indentation-per-level)
-(defvar org-startup-with-inline-images)
-(defvar org-image-actual-width)
-(defvar org-yank-image-save-method)
-(defvar org-bookmark-names-plist)
-(defvar org-file-apps)
-(defvar org-ellipsis)
-(defvar org-hide-emphasis-markers)
-(defvar org-hide-leading-stars)
-(defvar org-pretty-entities)
-(defvar org-pretty-entities-include-sub-superscripts)
-(defvar org-fontify-emphasized-text)
-(defvar org-fontify-whole-heading-line)
-(defvar org-todo-keywords)
-(defvar org-todo-keyword-faces)
-(defvar org-highest-priority)
-(defvar org-lowest-priority)
-(defvar org-default-priority)
-(defvar org-priority-faces)
-(defvar org-enforce-todo-dependencies)
-(defvar org-enforce-todo-checkbox-dependencies)
-(defvar org-deadline-warning-days)
-(defvar org-treat-insert-todo-heading-as-state-change)
-(defvar org-log-into-drawer)
-(defvar org-log-done)
-(defvar org-habit-graph-column)
-(defvar org-use-property-inheritance)
-
-;; Forward declarations for org-mode functions
-(declare-function org-eval-in-calendar "org" (form))
-(declare-function org-forward-heading-same-level "org" (arg))
-(declare-function org-backward-heading-same-level "org" (arg))
-
-;; ------------------------------- Org Constants -------------------------------
 
-;; note: org-archive-location is set in the :config section after org loads
+;; ---------------------------------- Org Mode ---------------------------------
+
+(use-package org
+  :defer t
+  :ensure nil ;; use the built-in package
+  :pin manual ;; never upgrade from the version built-into Emacs
+  :init
+  (defvar-keymap cj/org-table-map
+    :doc "org table operations.")
+  (keymap-global-set "C-c t" cj/org-table-map)
+  :bind
+  ("C-c c" . org-capture)
+  ("C-c a" . org-agenda)
+  (:map org-mode-map
+        ("C-c I"     . org-table-field-info) ;; was C-c ?
+        ("C-\\"      . org-match-sparse-tree)
+        ("C-c t"     . org-set-tags-command)
+        ("C-c l"     . org-store-link)
+        ("C-c C-l"   . org-insert-link)
+        ("s-<up>"    . org-priority-up)
+        ("s-<down>"  . org-priority-down)
+        ("C-c N"     . org-narrow-to-subtree)
+        ("C-c >"     . cj/org-narrow-forward)
+        ("C-c <"     . cj/org-narrow-backwards)
+        ("<f5>"      . org-reveal)
+        ("C-c <ESC>" . widen))
+  (:map cj/org-table-map
+        ("r i" . org-table-insert-row)
+        ("r d" . org-table-kill-row)
+        ("c i" . org-table-insert-column)
+        ("c d" . org-table-delete-column))
+
+  ;; backward and forward day are ','  and '.'
+  ;; shift & meta moves by week or year
+  ;; C-. jumps to today
+  ;; original keybindings blocked by windmove keys
+  ;; these are consistent with plain-old calendar mode
+  (:map org-read-date-minibuffer-local-map
+        (","   . (lambda () (interactive)
+                   (org-eval-in-calendar '(calendar-backward-day 1))))
+        ("."   . (lambda () (interactive)
+                   (org-eval-in-calendar '(calendar-forward-day 1))))
+        ("<"   . (lambda () (interactive)
+                   (org-eval-in-calendar '(calendar-backward-month 1))))
+        (">"   . (lambda () (interactive)
+                   (org-eval-in-calendar '(calendar-forward-month 1))))
+        ("M-," . (lambda () (interactive)
+                   (org-eval-in-calendar '(calendar-backward-year 1))))
+        ("M-." . (lambda () (interactive)
+                   (org-eval-in-calendar '(calendar-forward-year 1)))))
+
+  :init
+  ;; windmove's keybindings conflict with org-agenda-todo-nextset/previousset keybindings
+  ;; solution:  map the super key so that
+  ;; - super up/down increases and decreases the priority
+  ;; - super left/right changes the todo state
+  (setq org-replace-disputed-keys t)
+  (setq org-disputed-keys
+        '(([(shift left)]          . [(super left)])
+          ([(shift right)]         . [(super right)])
+          ([(shift up)]            . [(super up)])
+          ([(shift down)]          . [(super down)])
+          ([(control shift right)] . [(meta shift +)])
+          ([(control shift left)]  . [(meta shift -)])))
+
+  (defun cj/org-narrow-forward ()
+    "Narrow to the next subtree at the same level."
+    (interactive)
+    (widen)
+    (org-forward-heading-same-level 1)
+    (org-narrow-to-subtree))
+
+  (defun cj/org-narrow-backwards ()
+    "Narrow to the previous subtree at the same level."
+    (interactive)
+    (widen)
+    (org-backward-heading-same-level 1)
+    (org-narrow-to-subtree))
+
+  :hook
+  (org-mode . turn-on-visual-line-mode)
+  (org-mode . (lambda () (setq-local tab-width 8)))
+
+  :config
+  ;; Load org-protocol for org-protocol:// URL handling
+  (require 'org-protocol nil t)
+
+  ;; Set archive location (must be done after org loads)
+  (setq org-archive-location
+        (concat org-dir "/archives/archive.org::datetree/"))
+
+  (cj/org-general-settings)
+  (cj/org-appearance-settings)
+  (cj/org-todo-settings))
 
 ;; ---------------------------- Org General Settings ---------------------------
 
@@ -68,26 +113,26 @@
 
   ;; ORG-MODULES
   ;; enable recognition of org-protocol:// as a parameter
-  ;; add org-habits
-  (setq org-modules '(org-protocol ol-eww ol-w3m ol-info org-habit))
+  (setq org-modules '(org-protocol ol-eww ol-w3m ol-info))
 
   ;; GENERAL
   (setq org-startup-folded t)               ;; all org files should start in the folded state
   (setq org-cycle-open-archived-trees t)    ;; re-enable opening headings with archive tags with TAB
-  (setq org-outline-path-complete-in-steps nil)
+  (setopt org-outline-path-complete-in-steps nil)
   (setq org-return-follows-link t)          ;; hit return to follow an org-link
   (setq org-list-allow-alphabetical t)      ;; allow alpha ordered lists (i.e., a), A), a., etc.)
 
   ;; INDENTATION
   (setq org-startup-indented t)             ;; load org files indented
   (setq org-adapt-indentation t)            ;; adapt indentation to outline node level
-  (setq org-indent-indentation-per-level 2) ;; indent two character-widths per level
-  (setq tab-width 8)                  ;; org-mode complains when tabs aren't @ 8
+
+  ;; TASK: this variable doesn't exist. Remove
+  ;;  (setq org-indent-indentation-per-level 2) ;; indent two character-widths per level
 
   ;; IMAGES / MEDIA
   (setq org-startup-with-inline-images t)   ;; preview images by default
   (setq org-image-actual-width '(500))      ;; keep image sizes in check
-  (setq org-yank-image-save-method 'attach)  ;; attach images; save to data directory
+  (setq org-yank-image-save-method 'attach) ;; attach images; save to data directory
 
   (setq org-bookmark-names-plist nil)       ;; don't set org-capture bookmarks
 
@@ -134,29 +179,29 @@
 
   ;; logging task creation, task start, and task resolved states
   (setq org-todo-keywords '((sequence "TODO(t)" "PROJECT(p)" "DOING(i)"
-									  "WAITING(w)" "VERIFY(v)" "STALLED(s)"
-									  "DELEGATED(x)" "|"
-									  "FAILED(f!)" "DONE(d!)" "CANCELLED(c!)")))
+                                      "WAITING(w)" "VERIFY(v)" "STALLED(s)"
+                                      "DELEGATED(x)" "|"
+                                      "FAILED(f!)" "DONE(d!)" "CANCELLED(c!)")))
 
   (setq org-todo-keyword-faces
-		'(("TODO"      . "green")
-		  ("PROJECT"   . "blue")
-		  ("DOING"     . "yellow")
-		  ("WAITING"   . "white")
-		  ("VERIFY"    . "orange")
-		  ("STALLED"   . "light blue")
-		  ("DELEGATED" . "green")
-		  ("FAILED"    . "red")
-		  ("DONE"      . "dark grey")
-		  ("CANCELLED" . "dark grey")))
+        '(("TODO"      . "green")
+          ("PROJECT"   . "blue")
+          ("DOING"     . "yellow")
+          ("WAITING"   . "white")
+          ("VERIFY"    . "orange")
+          ("STALLED"   . "light blue")
+          ("DELEGATED" . "green")
+          ("FAILED"    . "red")
+          ("DONE"      . "dark grey")
+          ("CANCELLED" . "dark grey")))
 
   (setq org-highest-priority ?A)
   (setq org-lowest-priority ?D)
   (setq org-default-priority ?D)
   (setq org-priority-faces '((?A . (:foreground "Cyan" :weight bold))
-							 (?B . (:foreground "Yellow"))
-							 (?C . (:foreground "Green"))
-							 (?D . (:foreground "Grey"))))
+                             (?B . (:foreground "Yellow"))
+                             (?C . (:foreground "Green"))
+                             (?D . (:foreground "Grey"))))
 
   (setq org-enforce-todo-dependencies t)
   (setq org-enforce-todo-checkbox-dependencies t)
@@ -164,115 +209,12 @@
   (setq org-treat-insert-todo-heading-as-state-change nil) ;; log task creation
   (setq org-log-into-drawer nil) ;; don't log into drawer
   (setq org-log-done nil) ;; don't log completions
-  (setq org-habit-graph-column 75) ;; allow space for task name
 
   ;; inherit parents properties (sadly not schedules or deadlines)
   (setq org-use-property-inheritance t))
 
-;; ---------------------------------- Org Mode ---------------------------------
-
-;; Create org-table-map prefix command
-(defvar org-table-map (make-sparse-keymap)
-  "Keymap for org-table operations.")
-
-;;;###autoload (keymap-global-set "C-c T" org-table-map)
-
-(use-package org
-  :defer t
-  :ensure nil ;; use the built-in package
-  :pin manual ;; never upgrade from the version built-into Emacs
-  :bind
-  ("C-c c" . org-capture)
-  ("C-c a" . org-agenda)
-  (:map org-mode-map
-		("C-c I"     . org-table-field-info) ;; was C-c ?
-		("C-\\"      . org-match-sparse-tree)
-		("C-c t"     . org-set-tags-command)
-		("C-c l"     . org-store-link)
-		("C-c C-l"   . org-insert-link)
-		("s-<up>"    . org-priority-up)
-		("s-<down>"  . org-priority-down)
-		("C-c N"     . org-narrow-to-subtree)
-		("C-c >"     . cj/org-narrow-forward)
-		("C-c <"     . cj/org-narrow-backwards)
-		("<f5>"      . org-reveal)
-		("C-c <ESC>" . widen))
-  (:map org-table-map
-		("r i" . org-table-insert-row)
-		("r d" . org-table-kill-row)
-		("c i" . org-table-insert-column)
-		("c d" . org-table-delete-column))
-
-  ;; backward and forward day are ','  and '.'
-  ;; shift & meta moves by week or year
-  ;; C-. jumps to today
-  ;; original keybindings blocked by windmove keys
-  ;; these are consistent with plain-old calendar mode
-  (:map org-read-date-minibuffer-local-map
-        (","   . (lambda () (interactive)
-                   (org-eval-in-calendar '(calendar-backward-day 1))))
-        ("."   . (lambda () (interactive)
-                   (org-eval-in-calendar '(calendar-forward-day 1))))
-        ("<"   . (lambda () (interactive)
-                   (org-eval-in-calendar '(calendar-backward-month 1))))
-        (">"   . (lambda () (interactive)
-                   (org-eval-in-calendar '(calendar-forward-month 1))))
-        ("M-," . (lambda () (interactive)
-                   (org-eval-in-calendar '(calendar-backward-year 1))))
-        ("M-." . (lambda () (interactive)
-                   (org-eval-in-calendar '(calendar-forward-year 1)))))
-
-  :init
-  ;; windmove's keybindings conflict with org-agenda-todo-nextset/previousset keybindings
-  ;; solution:  map the super key so that
-  ;; - super up/down increases and decreases the priority
-  ;; - super left/right changes the todo state
-  (setq org-replace-disputed-keys t)
-  (setq org-disputed-keys
-        '(([(shift left)]          . [(super left)])
-          ([(shift right)]         . [(super right)])
-          ([(shift up)]            . [(super up)])
-          ([(shift down)]          . [(super down)])
-          ([(control shift right)] . [(meta shift +)])
-          ([(control shift left)]  . [(meta shift -)])))
-
-  (defun cj/org-narrow-forward ()
-	"Narrow to the next subtree at the same level."
-	(interactive)
-	(widen)
-	(org-forward-heading-same-level 1)
-	(org-narrow-to-subtree))
-
-  (defun cj/org-narrow-backwards ()
-	"Narrow to the previous subtree at the same level."
-	(interactive)
-	(widen)
-	(org-backward-heading-same-level 1)
-	(org-narrow-to-subtree))
-
-  :hook
-  (org-mode . turn-on-visual-line-mode)
-
-  :config
-  ;; Load org-protocol for org-protocol:// URL handling
-  (require 'org-protocol nil t)
-
-  ;; Set archive location (must be done after org loads)
-  (setq org-archive-location
-        (concat org-dir "/archives/archive.org::datetree/"))
-
-  (cj/org-general-settings)
-  (cj/org-appearance-settings)
-  (cj/org-todo-settings))
-
-
 ;; ------------------------------- Org Superstar -------------------------------
 
-;; Forward declarations
-(defvar org-superstar-leading-bullet)
-(declare-function org-superstar-configure-like-org-bullets "org-superstar")
-
-;; nicer bullets than simple asterisks.
 (use-package org-superstar
   :after org
   :hook (org-mode . org-superstar-mode)
@@ -281,27 +223,22 @@
   (setq org-superstar-leading-bullet ?\s))
 
 ;; ------------------------------- Org-Checklist -------------------------------
+
 ;; needed for org-habits to reset checklists once task is complete
 ;; this was a part of org-contrib which was deprecated
-
 (use-package org-checklist
   :ensure nil ;; in custom folder
-  :after org
-  :load-path "custom")
+  :load-path "custom"
+  :after org)
 
 ;; -------------------------- Org Link To Current File -------------------------
-;; get a link to the file the current buffer is associated with.
 
-;;;###autoload
 (defun cj/org-link-to-current-buffer-file ()
   "Create an Org mode link to the current file and copy it to the clipboard.
-
-The link is formatted as [[file:<file-path>][<file-name>]],
-where <file-path> is the full path to the current file and <file-name>
-is the name of the current file without any directory information.
-
-If the current buffer is not associated with a file, the function will throw an
-error."
+The link is formatted as [[file:<file-path>][<file-name>]], where <file-path>
+is the full path to the current file and <file-name> is the name of the current
+ file without any directory information. If the current buffer is not associated
+with a file, the function will throw an error."
   (interactive)
   (if (buffer-file-name)
       (let* ((filename (buffer-file-name))