blob: cfe67bf0df8f9270b05ee9eb27888e94cf683154 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
;;; help-config --- Help Functionality Configuration -*- lexical-binding: t; coding: utf-8; -*-
;; author Craig Jennings <c@cjennings.net>
;;; Commentary:
;;
;; This module enhances Emacs' built-in help system and documentation features.
;; It configures:
;;
;; 1. Helpful - A better help buffer that provides context, examples, and source code
;; 2. Man - Man page viewing integration
;; 3. Info - Enhanced Info mode with custom keybindings and directory configuration
;;
;; The configuration prioritizes discoverability and improves the experience of
;; reading documentation within Emacs. Custom keybindings maintain the C-h prefix
;; convention for help-related commands.
;;; Code:
(setq help-window-select t) ;; Always select the help buffer in a separate window
(keymap-global-set "C-h P" #'list-packages) ;; bring up the package menu
;; ---------------------------------- Helpful ----------------------------------
(use-package helpful
:bind
("C-h f" . helpful-callable)
("C-h v" . helpful-variable)
("C-h k" . helpful-key)
("C-h F" . helpful-function)
("C-h C" . helpful-command)
("C-h ." . helpful-at-point)
("C-h o" . helpful-symbol)) ;; overrides 'describe-symbol' keybinding
;; ------------------------------------ Man ------------------------------------
(use-package man
:ensure nil ;; built-in
:bind ("C-h M" . man))
;; ------------------------------------ Info -----------------------------------
(defun cj/open-with-info-mode ()
"Open the current buffer's file in Info mode if it's a valid info file.
Preserves any unsaved changes and checks if the file exists."
(interactive)
(let ((file-name (buffer-file-name)))
(when file-name
(if (and (file-exists-p file-name)
(string-match-p "\\.info\\'" file-name))
(progn
(when (buffer-modified-p)
(if (y-or-n-p "Buffer has unsaved changes. Save before opening in Info? ")
(save-buffer)
(message "Operation canceled")
(cl-return-from cj/open-with-info-mode)))
(kill-buffer (current-buffer))
(info file-name))
(message "Not a valid info file: %s" file-name)))))
(defun cj/browse-info-files ()
"Browse and open .info or .info.gz files from user-emacs-directory."
(interactive)
(let* ((info-files (directory-files-recursively
user-emacs-directory
"\\.info\\(\\.gz\\)?$"))
(files-alist (mapcar (lambda (f)
(cons (file-name-nondirectory f) f))
info-files))
(chosen-name (completing-read
"Select Info file: "
(mapcar #'car files-alist)
nil t))
(chosen-file (cdr (assoc chosen-name files-alist))))
(when chosen-file
(info chosen-file))))
(global-unset-key (kbd "C-h i"))
(keymap-global-set "C-h i" #'cj/browse-info-files)
(use-package info
:ensure nil ;; built-in
:bind
(:map Info-mode-map
("m" . bookmark-set) ;; Rebind 'm' from Info-menu to bookmark-set
("M" . Info-menu)) ;; Move Info-menu to 'M' instead
:preface
:init
;; Add personal info files BEFORE Info mode initializes
;; (let ((personal-info-dir (expand-file-name "assets/info" user-emacs-directory)))
;; (when (file-directory-p personal-info-dir)
;; (setq Info-directory-list (list personal-info-dir))))
;; the above makes the directory the info list. the below adds it to the default list
;; (add-to-list 'Info-default-directory-list personal-info-dir)))
:hook
(info-mode . info-persist-history-mode)
:config
;; Make .info files open with our custom function
(add-to-list 'auto-mode-alist '("\\.info\\'" . cj/open-with-info-mode)))
(provide 'help-config)
;;; help-config.el ends here.
|
