[elpa] scratch/mheerdegen-preview 4f3d9bf 11/32: WIP [el-search] Add quick help command

[Michael Heerdegen]

branch: scratch/mheerdegen-preview
commit 4f3d9bf0a1e25128a3c2338c0bdd061ccd2f5d14
Author: Michael Heerdegen <address@hidden>
Commit: Michael Heerdegen <address@hidden>

    WIP [el-search] Add quick help command
---
 packages/el-search/el-search.el | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/packages/el-search/el-search.el b/packages/el-search/el-search.el
index 9728039..4faba21 100644
--- a/packages/el-search/el-search.el
+++ b/packages/el-search/el-search.el
@@ -43,6 +43,11 @@
 ;; later.  Finally, it allows you to define your own kinds of search
 ;; patterns and your own multi-search commands.
 ;;
+;; The following text is an exhaustive introduction to this package.
+;; After having learned the basics, hitting C-? or ?
+;; (el-search-toggle-quick-help) should suffice to refresh your
+;; memory.
+;;
 ;;
 ;; Key bindings
 ;; ============
@@ -83,6 +88,11 @@
 ;;     hit RET to exit, or hit C-g to abort and jump back to where you
 ;;     started.
 ;;
+;;   C-?, M-s e ? (el-search-toggle-quick-help)
+;;
+;;     While an el-search is active, popup (or close) quick help
+;;     window.
+;;
 ;;   C-R, M-s e r (el-search-pattern-backward)
 ;;     Search backward.
 ;;
@@ -415,8 +425,6 @@
 ;;
 ;; TODO:
 ;;
-;; - Add a help command that can be called while searching.
-;;
 ;; - Make searching work in comments, too? (->
 ;;   `parse-sexp-ignore-comments').  Related: should the pattern
 ;;   `symbol' also match strings that contain matches for a symbol so
@@ -579,6 +587,7 @@ from the prompt."
   ;; explicitly install the transient map themselves.
   '(el-search-pattern
     el-search-pattern-backward
+    el-search-toggle-quick-help
     el-search-from-beginning
     el-search-last-buffer-match
     el-search-continue-in-next-buffer
@@ -1181,6 +1190,27 @@ be specified as fourth argument, and COUNT becomes the 
fifth argument."
               (funcall fail)
             match-beg)))))))
 
+(defvar el-search-quick-help-buffer-name "*El-search help*" )
+(defvar el-search-quick-help "...
+...
+...")
+
+(defun el-search-close-quick-help-maybe ()
+  (when-let ((help-buffer (get-buffer el-search-quick-help-buffer-name))
+             (help-wins (get-buffer-window-list help-buffer)))
+    (mapc #'delete-window help-wins)
+    t))
+
+(defun el-search-toggle-quick-help ()
+  "Doc..."
+  (interactive)
+  (setq this-command 'el-search-pattern)
+  (unless (el-search-close-quick-help-maybe)
+    (with-current-buffer (get-buffer-create el-search-quick-help-buffer-name)
+      (erase-buffer)
+      (insert el-search-quick-help)
+      (display-buffer (current-buffer)))))
+
 (defun el-search-forward (pattern &optional bound noerror count)
   "Search for el-search PATTERN in current buffer from point.
 Set point to the beginning of the occurrence found and return point.
@@ -1734,6 +1764,7 @@ in, in order, when called with no arguments."
 
 ;;;###autoload
 (defun el-search-loop-over-bindings (function)
+  (defvar el-search-basic-transient-map) ;defined later
   (cl-flet ((keybind (apply-partially #'funcall function)))
 
     (keybind emacs-lisp-mode-map           ?s #'el-search-pattern)
@@ -1763,6 +1794,8 @@ in, in order, when called with no arguments."
     (keybind global-map                    ?l #'el-search-load-path)
     (keybind global-map                    ?b #'el-search-buffers)
 
+    (keybind el-search-basic-transient-map ?? #'el-search-toggle-quick-help)
+
     (defvar dired-mode-map)
     (defvar ibuffer-mode-map)
 
@@ -1798,6 +1831,7 @@ any case."
     (define-key transient-map [return]       #'el-search-pause-search)
     (define-key transient-map (kbd "RET")    #'el-search-pause-search)
     (define-key transient-map [(control ?g)] #'el-search-keyboard-quit)
+    (define-key transient-map [??]           #'el-search-toggle-quick-help)
     transient-map))
 
 (defvar el-search-prefix-key-transient-map
@@ -2440,7 +2474,8 @@ local binding of `window-scroll-functions'."
          (el-search-hl-remove)
          (remove-hook 'post-command-hook 'el-search-hl-post-command-fun t)
          (setq el-search--temp-buffer-flag nil)
-         (el-search-kill-left-over-search-buffers)))))
+         (el-search-kill-left-over-search-buffers)
+         (el-search-close-quick-help-maybe)))))
 
 (defun el-search--pending-search-p ()
   (memq #'el-search-hl-post-command-fun post-command-hook))