Merge pull request #237 from pkryger/help-improvements

.ci/batch-flycheck.el

@@ -19,7 +19,8 @@ SOURCE is the source file used to compile with
     (let (matches
           (not-errors
            (list
-            (rx "the function ‘exordium--require-load’ might not be defined at runtime."))))
+            (rx "the function ‘exordium--require-load’ might not be defined at runtime.")
+            (rx "the function `exordium--require-load' might not be defined at runtime."))))
       (when-let* (((re-search-forward (rx-to-string `(seq " -- " ,source line-end))
                                       nil t))
                   (pattern (rx-to-string

README.md

@@ -48,8 +48,10 @@ might want to check these links:
   [Avy](https://github.com/abo-abo/avy) (jump to visible text in 2 or 3 key-strokes);
   [ace-window](https://github.com/abo-abo/ace-window) (quick jump between windows);
   [helpful](https://github.com/Wilfred/helpful) (a better Emacs *help* buffer);
-  [which-key](https://github.com/justbur/emacs-which-key) (display available keybindings).
-  [Treesitter]()(Parser-based font lock.)
+  [casual](https://github.com/kickingvegas/casual) (A collection of opinionated
+  keyboard-driven user interfaces for various built-in Emacs modes);
+  [which-key](https://github.com/justbur/emacs-which-key) (display available keybindings);
+  [Treesitter]()(Parser-based font lock).
 * Projects: [Projectile](http://batsov.com/projectile) (project-based file
   management tool).
 * Git: [Magit](http://magit.vc) (git UI);
@@ -175,7 +177,7 @@ Keybinding              | Description
 ------------------------|----------------------------------------------------------
 <kbd>C-c ARROW</kbd>    | Move cursor between windows.
 <kbd>C-c S-ARROW</kbd>  | Move the windows themselves.
-<kbd>M-p NUMBER</kbd>   | Jump to the specified window number using [ace-window](https://github.com/abo-abo/ace-window). If you only have 2 windows, cycle between them.
+<kbd>M-o NUMBER</kbd>   | Jump to the specified window number using [ace-window](https://github.com/abo-abo/ace-window). If you only have 2 windows, cycle between them.
 
 Auto-complete/Company:
 
@@ -198,14 +200,37 @@ of the symbol.
 
 A few example bindings:
 
-Keybinding     | Description
--------------- |----------------------------------------------------------
-<kbd>M-n</kbd> | Jump to next location of highlighted symbol at point.
-<kbd>M-p</kbd> | Jump to previous location of highlighted symbol at point.
-<kbd>M-h</kbd> | Display bindings for highlighted symbol at point.
+Keybinding                       | Description
+-------------------------------- |----------------------------------------------------------
+<kbd>M-n</kbd>                   | Jump to next location of highlighted symbol at point.
+<kbd>M-p</kbd>                   | Jump to previous location of highlighted symbol at point.
+<kbd>M-h</kbd> or <kbd>C-o</kbd> | Display bindings for highlighted symbol at point.
 
 You can change the modifier key (default: <kbd>M</kbd>) by customizing `exordium-highlight-symbol-map-modifier`.
 
+## Help extensions
+Exordium provides a few help extensions that enhance default Emacs
+configuration presenting user with more information. All of them are enabled by
+setting `exordium-help-extensions` to t. Noteably, the following are turned on:
+
+- [which-key](https://github.com/justbur/emacs-which-key) - display available
+  keybindings after a short while (for example type <kbd>C-x</kbd> and wait a
+  second,
+- [casual](https://github.com/kickingvegas/casual) - a collection of
+  opinionated keyboard-driven user interfaces for various built-in Emacs modes,
+- [helpful](https://github.com/Wilfred/helpful) - an alternative to the
+  built-in Emacs help that provides much more contextual information.
+
+Keybinding          | Description
+------------------- |----------------------------------------------------------
+<kbd>C-o</kbd>      | Display a transient with bindings for a `casual` user of `org-agenda`, `bookmark`, `calc`, `calendar`, `dired`, `ibuffer`, `info`, `isearch`, `rebuilder`, `symbol-overlay` or a Casual EditKit menu.
+<kbd>C-h f</kbd>    | Show `helpful` buffer for function, macro, or a special form (`helpful-callable`).
+<kbd>C-h F</kbd>    | Show `helpful` buffer for function (`helpful-function`).
+<kbd>C-h v</kbd>    | Show `helpful` buffer for variable (`helpful-variable`).
+<kbd>C-h C</kbd>    | Show `helpful` buffer for interactive command (`helpful-command`).
+<kbd>C-c C-d</kbd>  | Show `helpful` buffer for thing at point, when in `emacs-lisp-mode` (`helpful-thing-at-point`).
+<kbd>C-j</kbd>      | Show `helpful` buffer for currently selected candidate, when completing read for `helpful` commands.
+
 ## Projectile
 
 [Projectile](https://github.com/bbatsov/projectile) adds the notion of
@@ -416,6 +441,12 @@ Keybinding            | Description
 <kbd>D</kbd>          | Run Difftastic diff (guessing what to diff from context) (`difftastic-magit-diff`).
 <kbd>S</kbd>          | Run Difftastic show (`difftastic-magit-show`).
 
+or when you are in `dired-mode`:
+
+Keybinding            | Description
+----------------------|-----------------------------------------------------------
+<kbd>C-c =</kbd>      | Run Difftastic (`difftastic-dired-diff`).
+
 Forge keys:
 
 Keybinding            | Description

modules/init-git.el

@@ -20,7 +20,9 @@
 ;; C-c g d           Diff current hunk
 ;; C-c g r           Revert current hunk (asks for confirmation)
 ;;
-;; C-c ^ d           Show SMerge Dispatch
+;; C-c ^ d           Show SMerge Dispatch (when in `smerge-mode')
+;; C-o               Show SMerge Dispatch (when in `smerge-mode' and
+;;                   `exordium-help-extensions' is non-nil)
 ;;
 ;; When in `magit-diff' or `magit-blame' transient,
 ;; or in `magit-blame-read-only-mode':
@@ -218,10 +220,23 @@ with `exordium-magit-quit-session'."
   (:map smerge-mode-map
   ("C-c ^ d" . #'exordium-smerge-dispatch)))
 
+(use-package smerge-mode
+  :ensure nil
+  :defer t
+  :if exordium-help-extensions
+  :bind
+  (:map smerge-mode-map
+  ("C-o" . #'exordium-smerge-dispatch)))
+
 (defun exordium-smerge-dispatch-maybe ()
   "Display `exordium-smerge-dispatch' when buffer is in `smerge-mode'."
-  (when (and smerge-mode exordium-smerge-show-dispatch)
-    (funcall-interactively #'exordium-smerge-dispatch)))
+  (when (and smerge-mode
+             exordium-smerge-show-dispatch
+             (fboundp 'smerge-next))
+    (funcall-interactively #'exordium-smerge-dispatch)
+    (goto-char (point-min))
+    (smerge-next)
+    (recenter-top-bottom)))
 
 (use-package magit
   :hook

modules/init-help.el

@@ -11,8 +11,11 @@
 ;; C-h v             Show help for variable
 ;; C-h k             Show help for interactive command bound to key sequence
 ;; C-h C             Show help for interactive command
+;; C-j               Show help for currentlyselected candidate, when completing
+;;                   read for `helpful' commands
 ;; C-c C-d           Show help for thing at point (in `emacs-lisp-mode')
-
+;; C-o               Show a `casual' transient, which one depends on mode.
+;; C-c =             Run `difftastic-dired-diff' in `dired-mode'.
 
 
 ;;; Code:
@@ -21,6 +24,7 @@
     (load (file-name-concat (locate-user-emacs-file "modules") "init-require"))))
 (exordium-require 'init-lib)
 (exordium-require 'init-helm)
+(exordium-require 'init-git)
 
 ;;; Which Key - display available keybindings in popup.
 (when exordium-enable-which-key
@@ -42,16 +46,84 @@
 
 
 (use-package helpful
+  :functions (exordium--helpful-persistent-action
+              exordium--helm-helpful-completing-read)
   :init
   (use-package helm
     :defer t
     :custom
     (helm-describe-variable-function #'helpful-variable)
     (helm-describe-function-function #'helpful-function))
+  (use-package helm-mode
+    :ensure helm
+    :defer t
+    :autoload (helm-completing-read-default-handler))
 
-  (use-package paren
-    :ensure nil
-    :commands (show-paren-local-mode))
+  (defun exordium--helpful-pop-to-buffer (buffer)
+    "Pop to BUFFER in the same window if it is a Helpful window.
+Otherwise pop to buffer (presumably in a new window)."
+    (if (derived-mode-p 'helpful-mode)
+        (pop-to-buffer-same-window buffer)
+      (pop-to-buffer buffer)))
+
+  (defun exordium--helpful-persistent-action (type)
+    "Generate a function that adds `:persistent-action' TYPE to args."
+    (lambda (&rest args)
+      (plist-put (plist-put (car args)
+                            :persistent-help
+                            (format "Describe %s" type))
+                 :persistent-action
+                 (lambda (candidate)
+                   (pcase (intern-soft candidate)
+                     ((and (pred fboundp) (pred boundp) sym)
+                      (if (eq type 'variable)
+                          (helm-describe-variable sym)
+                        (helm-describe-function sym)))
+                     ((and (pred boundp) sym)
+                      (helm-describe-variable sym))
+                     ((and (pred fboundp) sym)
+                      (helm-describe-function sym))
+                     ((and (pred facep) sym)
+                      (helm-describe-face sym)))))))
+
+  (defun exordium--helm-helpful-completing-read (&rest args)
+                                        ; checkdoc-params: (args)
+    "Ensure affixation and persistent actions are used."
+    (let* ((current-command (or (helm-this-command) this-command))
+           (str-command (if current-command
+                            (helm-symbol-name current-command)
+                          "completing-read"))
+           (buf-name (format "*%s*" str-command))
+           (type (cond
+                  ((eq current-command 'helpful-variable) 'variable)
+                  ((eq current-command 'helpful-symbol) 'symbol)
+                  (t 'function)))
+           (persistent-action (exordium--helpful-persistent-action type)))
+      (unwind-protect
+          (let ((completion-extra-properties
+                 '(:affixation-function
+                   helm-symbol-completion-table-affixation)))
+            (advice-add 'helm-comp-read
+                        :filter-args persistent-action)
+            (apply #'helm-completing-read-default-handler
+                   (append args
+                           (list str-command buf-name))))
+        (advice-remove 'helm-comp-read persistent-action))))
+
+  :custom
+  ;; By default `show-paren-mode' is disabled in modes deriving from
+  ;; `special-mode'.  Enable it for `helpful' if it doesn't match
+  ;; the `show-paren-predicate'
+  (show-paren-predicate (if (with-temp-buffer
+                              (require 'helpful nil t)
+                              (helpful-mode)
+                              (buffer-match-p show-paren-predicate
+                                              (current-buffer)))
+                            show-paren-predicate
+                          (list 'or '(derived-mode . helpful-mode)
+                                show-paren-predicate)))
+  (helpful-switch-buffer-function #'exordium--helpful-pop-to-buffer)
+  (completions-detailed t)
 
   :bind
   (;; Note that the built-in `describe-function' includes both functions
@@ -72,12 +144,113 @@
    ("C-c C-d" . #'helpful-at-point)
    ("C-c C-o" . #'exordium-browse-url-at-point))
   :config
-  ;; By default `show-paren-mode' is disabled in modes deriving from
-  ;; `special-mode'.  Force it for `helpful'.
-  (add-hook 'helpful-mode-hook #'show-paren-local-mode))
+  (require 'helm-mode)
+  (dolist (fun '(helpful-callable
+                 helpful-command
+                 helpful-function
+                 helpful-macro
+                 helpful-variable
+                 helpful-symbol))
+    (add-to-list 'helm-completing-read-handlers-alist
+                 (cons fun #'exordium--helm-helpful-completing-read))))
 
 
+(when (version< "29" emacs-version) ;; Since Emacs-29
+
+(use-package casual
+  :defer t
+  :bind ("C-o" . #'casual-editkit-main-tmenu)
+  :init
+  (use-package org-agenda
+    :ensure nil
+    :defer t
+    :commands (org-agenda-clock-goto)
+    :bind (:map org-agenda-mode-map
+           ("C-o" . #'casual-agenda-tmenu)
+           ("M-j" . #'org-agenda-clock-goto)
+           ("J" . #'bookmark-jump)))
+  (use-package bookmark
+    :ensure nil
+    :defer t
+    :bind (:map bookmark-bmenu-mode-map
+           ("C-o" .  #'casual-bookmarks-tmenu)
+           ("J" . #'bookmark-jump)))
+  (use-package calc
+    :ensure nil
+    :defer t
+    :bind (:map calc-mode-map
+           ("C-o" . #'casual-calc-tmenu)))
+  (use-package calc-ext
+    :ensure nil
+    :defer t
+    :bind (:map calc-alg-map
+           ("C-o" . #'casual-calc-tmenu)))
+  (use-package calendar
+    :ensure nil
+    :defer t
+    :bind (:map calendar-mode-map
+           ("C-o" . #'casual-calendar)))
+  (use-package dired
+    :ensure nil
+    :defer t
+    :bind (:map dired-mode-map
+           ("C-o" . #'casual-dired-tmenu)
+           ("s" . #'casual-dired-sort-by-tmenu)
+           ("/" . #'casual-dired-search-replace-tmenu)
+           ("C-c =" . #'difftastic-dired-diff)))
+  (use-package ibuffer
+    :init
+    (use-package ibuf-ext
+      :ensure nil
+      :commands (ibuffer-backwards-next-marked
+                 ibuffer-forward-next-marked
+                 ibuffer-backward-filter-group
+                 ibuffer-forward-filter-group
+                 ibuffer-toggle-filter-group))
+    :ensure nil
+    :defer t
+    :bind (:map ibuffer-mode-map
+           ("C-o" . #'casual-ibuffer-tmenu)
+           ("F" . #'casual-ibuffer-filter-tmenu)
+           ("s".  #'casual-ibuffer-sortby-tmenu)
+           ("{" . #'ibuffer-backwards-next-marked)
+           ("}" . #'ibuffer-forward-next-marked)
+           ("[" . #'ibuffer-backward-filter-group)
+           ("]" . #'ibuffer-forward-filter-group)
+           ("$" . #'ibuffer-toggle-filter-group)))
+  (use-package info
+    :ensure nil
+    :defer t
+    :bind (:map Info-mode-map
+           ("C-o" . #'casual-info-tmenu)
+           ("M-[" . #'Info-history-back)
+           ("M-]" . #'Info-history-forward)
+           ("/" . #'Info-search)
+           ("B" . #'bookmark-set)))
+  (use-package isearch
+    :ensure nil
+    :defer t
+    :bind (:map isearch-mode-map
+           ("C-o" . #'casual-isearch-tmenu)))
+  (use-package re-builder
+    :ensure nil
+    :defer t
+    :bind (:map reb-mode-map
+           ("C-o". #'casual-re-builder-tmenu)
+           :map reb-lisp-mode-map
+           ("C-o" . #'casual-re-builder-tmenu)))
+  :config
+  (with-eval-after-load 'casual-dired
+    (let ((loc '(1 -1))
+          (suffix ["Compare"
+                   ("=" "Diff" dired-diff)
+                   ("C-c =" "Difftastic" difftastic-dired-diff)]))
+      (unless (equal (transient-parse-suffix 'casual-transient-tmenu suffix)
+                     (transient-get-suffix 'casual-dired-tmenu loc))
+        (transient-append-suffix 'casual-dired-tmenu loc suffix)))))
+) ;; (when (version< "29" emacs-version) ;; Since Emacs-29
 
+
 (provide 'init-help)
 
 ;;; init-help.el ends here

modules/init-look-and-feel.el

@@ -158,6 +158,14 @@ Set FONT and SIZE if they are passed as arguments."
 ;; Show only 1 window on startup (useful if you open multiple files)
 (add-hook 'emacs-startup-hook #'delete-other-windows t)
 
+;; Remove surrounding quotes for link buttons and stick to the same window
+(use-package help
+  :ensure nil
+  :defer t
+  :custom
+  (help-clean-buttons t)
+  (help-window-keep-selected t))
+
 
 ;;; Keyboard preferences
 

modules/init-window-manager.el

@@ -7,9 +7,10 @@
 ;; ----------------- ---------------------------------------------------------
 ;; C-c <arrow>       Move cursor between windows (similar to C-x o).
 ;; C-c shift-<arrow> Move the windows themselves, e.g. swap them.
-;; M-p <number>      Ace-window: M-p displays a number in each window, and you
-;;                   just have to type the number you want.  If there are only
-;;                   2 windows, it cycles between them.
+;; M-o <letter>      Ace-window: M-o displays a letter in each window, and you
+;;                   just have to type the letter you want.  If there are only
+;;                   2 windows, it cycles between them.  When called with
+;;                   prefix arg, swap windows.
 ;;
 ;; Simple test:
 ;; - C-x 2           split the screen between 2 windows one on top of the other