refactor:keymaps: Replace define-prefix-command with defvar-keymap

Refactor the keymap definitions across multiple modules by replacing
`define-prefix-command` with `defvar-keymap`. This simplifies the
keymap setup and integrates better with the `which-key` package for
enhanced documentation and usability. Updated modules include
custom-ordering, custom-text-enclose, custom-whitespace,
mail-config, music-config, org-drill-config, test-runner, and
vc-config.

8 files changed, 93 insertions, 72 deletions

diff --git a/modules/custom-ordering.el b/modules/custom-ordering.el
index 8e8a4da6..5d308604 100644
--- a/modules/custom-ordering.el
+++ b/modules/custom-ordering.el
@@ -84,13 +84,16 @@ Produce a comma-separated list as the result."
 
 
 ;; Ordering & sorting prefix and keymap
-(define-prefix-command 'cj/ordering-map nil
-                       "text ordering and sorting operations.")
-(keymap-set cj/custom-keymap "o" #'cj/ordering-map)
-(keymap-set cj/ordering-map "a" #'cj/arrayify)
-(keymap-set cj/ordering-map "u" #'cj/unarrayify)
-(keymap-set cj/ordering-map "A" #'cj/alphabetize-region)
-(keymap-set cj/ordering-map "l" #'cj/comma-separated-text-to-lines)
+(defvar-keymap cj/ordering-map
+  :doc "Keymap for text ordering and sorting operations"
+  "a" #'cj/arrayify
+  "u" #'cj/unarrayify
+  "A" #'cj/alphabetize-region
+  "l" #'cj/comma-separated-text-to-lines)
+
+(keymap-set cj/custom-keymap "o" cj/ordering-map)
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; o" "ordering/sorting menu"))
 
 (provide 'custom-ordering)
 ;;; custom-ordering.el ends here.
diff --git a/modules/custom-text-enclose.el b/modules/custom-text-enclose.el
index fa41d39f..514419cd 100644
--- a/modules/custom-text-enclose.el
+++ b/modules/custom-text-enclose.el
@@ -69,12 +69,15 @@
         (forward-line 1)))))
 
 ;; Surround, append, prepend prefix keymap
-(define-prefix-command 'cj/enclose-map nil
-					   "Keymap for enclosing text: surrounding, appending, and prepending.")
-(keymap-set cj/custom-keymap "s" #'cj/enclose-map)
-(keymap-set cj/enclose-map "s" #'cj/surround-word-or-region)
-(keymap-set cj/enclose-map "a" #'cj/append-to-lines-in-region-or-buffer)
-(keymap-set cj/enclose-map "p" #'cj/prepend-to-lines-in-region-or-buffer)
+(defvar-keymap cj/enclose-map
+  :doc "Keymap for enclosing text: surrounding, appending, and prepending"
+  "s" #'cj/surround-word-or-region
+  "a" #'cj/append-to-lines-in-region-or-buffer
+  "p" #'cj/prepend-to-lines-in-region-or-buffer)
+
+(keymap-set cj/custom-keymap "s" cj/enclose-map)
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; s" "text enclose menu"))
 
 (provide 'custom-text-enclose)
 ;;; custom-text-enclose.el ends here.
diff --git a/modules/custom-whitespace.el b/modules/custom-whitespace.el
index 2f6b7435..a69d6138 100644
--- a/modules/custom-whitespace.el
+++ b/modules/custom-whitespace.el
@@ -102,13 +102,16 @@ Operate on the active region designated by START and END."
 
 
 ;; Whitespace operations prefix and keymap
-(define-prefix-command 'cj/whitespace-map nil
-					   "Keymap for whitespace operations.")
-(keymap-set cj/custom-keymap "w" #'cj/whitespace-map)
-(keymap-set cj/whitespace-map "r" #'cj/remove-leading-trailing-whitespace)
-(keymap-set cj/whitespace-map "c" #'cj/collapse-whitespace-line-or-region)
-(keymap-set cj/whitespace-map "l" #'cj/delete-blank-lines-region-or-buffer)
-(keymap-set cj/whitespace-map "-" #'cj/hyphenate-whitespace-in-region)
+(defvar-keymap cj/whitespace-map
+  :doc "Keymap for whitespace operations"
+  "r" #'cj/remove-leading-trailing-whitespace
+  "c" #'cj/collapse-whitespace-line-or-region
+  "l" #'cj/delete-blank-lines-region-or-buffer
+  "-" #'cj/hyphenate-whitespace-in-region)
+
+(keymap-set cj/custom-keymap "w" cj/whitespace-map)
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; w" "whitespace menu"))
 
 (provide 'custom-whitespace)
 ;;; custom-whitespace.el ends here.
diff --git a/modules/mail-config.el b/modules/mail-config.el
index e51cefd4..c65e5342 100644
--- a/modules/mail-config.el
+++ b/modules/mail-config.el
@@ -288,17 +288,18 @@ Prompts user for the action when executing."
   :load-path "~/code/org-msg/"
   :after (org mu4e)
   :preface
-	(define-prefix-command 'cj/email-map nil
-						 "keymap for email operations.")
-	(keymap-set cj/custom-keymap "e" #'cj/email-map)
+	(defvar-keymap cj/email-map
+	  :doc "Keymap for email operations"
+	  "a" #'org-msg-attach-attach
+	  "d" #'org-msg-attach-delete)
+	(keymap-set cj/custom-keymap "e" cj/email-map)
+	(with-eval-after-load 'which-key
+	  (which-key-add-key-based-replacements "C-; e" "email menu"))
   :bind
   ;; more intuitive keybinding for attachments
   (:map org-msg-edit-mode-map
 		("C-c C-a" . org-msg-attach-attach)
 		("C-c C-d" . org-msg-attach-delete))
-  (:map cj/email-map
-		("a" . org-msg-attach-attach)
-		("d" . org-msg-attach-delete))
   :config
   ;; inline CSS, no postamble, no TOC, no stars or footers
   (setq org-msg-options "html-postamble:nil H:5 num:nil ^:{} toc:nil author:nil email:nil")
diff --git a/modules/music-config.el b/modules/music-config.el
index 394c9fa3..90feb7eb 100644
--- a/modules/music-config.el
+++ b/modules/music-config.el
@@ -352,10 +352,25 @@ Dirs added recursively."
 
 ;;; EMMS setup and keybindings
 
+;; Music/EMMS keymap
+(defvar-keymap cj/music-map
+  :doc "Keymap for music commands"
+  "m" #'cj/music-playlist-toggle
+  "M" #'cj/music-playlist-show
+  "a" #'cj/music-fuzzy-select-and-add
+  "r" #'cj/music-create-radio-station
+  "SPC" #'emms-pause
+  "s" #'emms-stop
+  "p" #'emms-playlist-mode-go
+  "x" #'emms-shuffle)
+
+(keymap-set cj/custom-keymap "m" cj/music-map)
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; m" "music menu"))
+
 (use-package emms
   :defer t
   :init
-  (defvar cj/music-map (make-sparse-keymap) "Keymap for music commands.")
   ;; Set buffer name BEFORE emms loads to prevent default buffer creation
   (setq emms-playlist-buffer-name "*EMMS-Playlist*")
   :commands (emms-mode-line-mode)
@@ -407,9 +422,6 @@ Dirs added recursively."
   (advice-remove 'emms-playlist-clear #'cj/music--after-playlist-clear)
   (advice-add 'emms-playlist-clear :after #'cj/music--after-playlist-clear)
 
-  :bind-keymap
-  ("C-; m" . cj/music-map)
-
   :bind
   (:map emms-playlist-mode-map
         ;; Playback
@@ -432,16 +444,7 @@ Dirs added recursively."
         ("r" . cj/music-create-radio-station)
         ;; Volume (MPD)
         ("-" . emms-volume-lower)
-        ("=" . emms-volume-raise))
-  (:map cj/music-map
-        ("m" . cj/music-playlist-toggle)
-        ("M" . cj/music-playlist-show)
-        ("a" . cj/music-fuzzy-select-and-add)
-        ("r" . cj/music-create-radio-station)
-        ("SPC" . emms-pause)
-        ("s" . emms-stop)
-        ("p" . emms-playlist-mode-go)
-        ("x" . emms-shuffle)))
+        ("=" . emms-volume-raise)))
 
 ;; Quick toggle key - use autoload to avoid loading emms at startup
 (autoload 'cj/music-playlist-toggle "music-config" "Toggle EMMS playlist window." t)
diff --git a/modules/org-drill-config.el b/modules/org-drill-config.el
index bfdeb26a..f18760c7 100644
--- a/modules/org-drill-config.el
+++ b/modules/org-drill-config.el
@@ -59,15 +59,18 @@
 
   ;; ------------------------------ Org Drill Keymap -----------------------------
 
-  ;; Buffer & file operations prefix and keymap
-  (define-prefix-command 'cj/drill-map nil
-						 "Keymap for org-drill.")
-  (keymap-set cj/custom-keymap "D" #'cj/drill-map)
-  (keymap-set cj/drill-map "s" #'cj/drill-start)
-  (keymap-set cj/drill-map "e" #'cj/drill-edit)
-  (keymap-set cj/drill-map "c" #'cj/drill-capture)
-  (keymap-set cj/drill-map "r" #'cj/drill-refile)
-  (keymap-set cj/drill-map "R" #'org-drill-resume))
+  ;; Org drill operations keymap
+  (defvar-keymap cj/drill-map
+	:doc "Keymap for org-drill"
+	"s" #'cj/drill-start
+	"e" #'cj/drill-edit
+	"c" #'cj/drill-capture
+	"r" #'cj/drill-refile
+	"R" #'org-drill-resume)
+
+  (keymap-set cj/custom-keymap "D" cj/drill-map)
+  (with-eval-after-load 'which-key
+	(which-key-add-key-based-replacements "C-; D" "org-drill menu")))
 
 (provide 'org-drill-config)
 ;;; org-drill-config.el ends here.
diff --git a/modules/test-runner.el b/modules/test-runner.el
index e05a4e0b..b4c40820 100644
--- a/modules/test-runner.el
+++ b/modules/test-runner.el
@@ -252,19 +252,21 @@ Otherwise, message that no test is found."
 	(cj/test-run-focused)))
 
 ;; Test runner operations prefix and keymap
-(define-prefix-command 'cj/test-map nil
-					   "Keymap for test-runner operations.")
-(keymap-set cj/custom-keymap "t" #'cj/test-map)
+(defvar-keymap cj/testrunner-map
+  :doc "Keymap for test-runner operations"
+  "L" #'cj/test-load-all
+  "R" #'cj/test-run-all
+  "." #'cj/run-test-at-point
+  "r" #'cj/test-run-smart
+  "a" #'cj/test-focus-add
+  "b" #'cj/test-focus-add-this-buffer-file
+  "c" #'cj/test-focus-clear
+  "v" #'cj/test-view-focused
+  "t" #'cj/test-toggle-mode)
 
-(keymap-set cj/test-map "L" #'cj/test-load-all)
-(keymap-set cj/test-map "R" #'cj/test-run-all)
-(keymap-set cj/test-map "." #'cj/run-test-at-point)
-(keymap-set cj/test-map "r" #'cj/test-run-smart)
-(keymap-set cj/test-map "a" #'cj/test-focus-add)
-(keymap-set cj/test-map "b" #'cj/test-focus-add-this-buffer-file)
-(keymap-set cj/test-map "c" #'cj/test-focus-clear)
-(keymap-set cj/test-map "v" #'cj/test-view-focused)
-(keymap-set cj/test-map "t" #'cj/test-toggle-mode)
+(keymap-set cj/custom-keymap "t" cj/testrunner-map)
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; t" "test runner menu"))
 
 (provide 'test-runner)
 ;;; test-runner.el ends here
diff --git a/modules/vc-config.el b/modules/vc-config.el
index 56ba1944..3b116cc1 100644
--- a/modules/vc-config.el
+++ b/modules/vc-config.el
@@ -118,17 +118,20 @@
 ;; --------------------------------- VC Keymap ---------------------------------
 
 ;; Ordering & sorting prefix and keymap
-(define-prefix-command 'cj/vc-map nil
-					   "Keymap for version control operations.")
-(keymap-set cj/custom-keymap "v" #'cj/vc-map)
-(keymap-set cj/vc-map "d" #'cj/goto-git-gutter-diff-hunks)
-(keymap-set cj/vc-map "c" #'cj/forge-create-issue)
-(keymap-set cj/vc-map "f" #'forge-pull)
-(keymap-set cj/vc-map "i" #'forge-list-issues)
-(keymap-set cj/vc-map "n" #'git-gutter:next-hunk)
-(keymap-set cj/vc-map "p" #'git-gutter:previous-hunk)
-(keymap-set cj/vc-map "r" #'forge-list-pullreqs)
-(keymap-set cj/vc-map "t" #'cj/git-timemachine)
+(defvar-keymap cj/vc-map
+  :doc "Keymap for version control operations"
+  "d" #'cj/goto-git-gutter-diff-hunks
+  "c" #'cj/forge-create-issue
+  "f" #'forge-pull
+  "i" #'forge-list-issues
+  "n" #'git-gutter:next-hunk
+  "p" #'git-gutter:previous-hunk
+  "r" #'forge-list-pullreqs
+  "t" #'cj/git-timemachine)
+
+(keymap-set cj/custom-keymap "v" cj/vc-map)
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; v" "version control menu"))
 
 (provide 'vc-config)
 ;;; vc-config.el ends here.