[elpa] externals/eev 3c1f10718c: Added eev-helpful.el.

[ELPA Syncer]

branch: externals/eev
commit 3c1f10718c565155b83da08f8cae3bc5ef5d98ec
Author: Eduardo Ochs <eduardoochs@gmail.com>
Commit: Eduardo Ochs <eduardoochs@gmail.com>

    Added eev-helpful.el.
---
 ChangeLog      |  16 +++++
 VERSION        |   4 +-
 eev-blinks.el  |  22 ++++++-
 eev-elinks.el  |   2 +
 eev-helpful.el | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 eev-hlinks.el  |   2 +
 eev-load.el    |   9 +--
 eev-mode.el    |   3 +-
 eev-plinks.el  |   3 +-
 9 files changed, 246 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 37aa90e0e6..13c0518e27 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2022-03-18  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-helpful.el: new file.
+
+       * eev-elinks.el (find-evariable-links): added a link to helpful.
+       (ee-find-efunction-links): added a link to helpful.
+
+       * eev-hlinks.el (ee-helpful-bufferp): new function.
+       (ee-fhl-main-program): use `ee-helpful-bufferp'.
+
+       * eev-plinks.el (find-osm): use `find-dbsw-call'.
+
+2022-03-17  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-blinks.el (find-dbsw-call): new function.
+
 2022-03-16  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev-blinks.el (ee-find-eww-search-yes, ee-find-eww-search-for):
diff --git a/VERSION b/VERSION
index 601d71b6e8..a0bac3155d 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Wed Mar 16 07:30:13 GMT 2022
-Wed Mar 16 04:30:13 -03 2022
+Fri Mar 18 20:41:41 GMT 2022
+Fri Mar 18 17:41:41 -03 2022
diff --git a/eev-blinks.el b/eev-blinks.el
index 466457382a..a3a441f20d 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -21,7 +21,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20220316
+;; Version:    20220317
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -47,6 +47,7 @@
 ;;   «.curved-single-quotes»   (to "curved-single-quotes")
 ;; «.find-fline»               (to "find-fline")
 ;; «.find-wottb»               (to "find-wottb")
+;; «.find-dbsw»                        (to "find-dbsw")
 ;; «.find-efaces»              (to "find-efaces")
 ;; «.find-eregionpp»           (to "find-eregionpp")
 ;; «.find-ebuffercontents»     (to "find-ebuffercontents")
@@ -367,6 +368,25 @@ then go to the position specified by POS-SPEC-LIST.\n
 
 
 
+;;;   __ _           _           _ _                  
+;;;  / _(_)_ __   __| |       __| | |__  _____      __
+;;; | |_| | '_ \ / _` |_____ / _` | '_ \/ __\ \ /\ / /
+;;; |  _| | | | | (_| |_____| (_| | |_) \__ \\ V  V / 
+;;; |_| |_|_| |_|\__,_|      \__,_|_.__/|___/ \_/\_/  
+;;;                                                   
+;; «find-dbsw»  (to ".find-dbsw")
+;; See: https://lists.gnu.org/archive/html/help-gnu-emacs/2022-03/msg00354.html
+;; Thanks to Emanuel Berg for help with this!
+;;
+(defun find-dbsw-call (sexp &rest pos-spec-list)
+  "Run SEXP in \"display-buffer-same-window mode\" and go to POS-SPEC-LIST.
+This is similar to `find-wottb-call' but uses another method to
+force using the same window. This is an experimental hack and may
+change soon."
+  (let ((display-buffer-overriding-action '(display-buffer-same-window)))
+    (eval sexp))
+  (apply 'ee-goto-position pos-spec-list))
+
 
 
 
diff --git a/eev-elinks.el b/eev-elinks.el
index 22da9915ae..5ae84aa8bd 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -293,6 +293,7 @@ This is an internal function used by `find-efunction-links' 
and
     (find-efunctiond ',f)
     (find-ealias ',f)
     (find-eppp (symbol-plist ',f))
+    (find-hfunction ',f)
     ""
     ,@(if (commandp f)
          `((Info-goto-emacs-command-node ',f)
@@ -344,6 +345,7 @@ This is an internal function used by `find-efunction-links' 
and
      (find-evariable ',var)
      (find-epp ,var)
      (find-eppp (symbol-plist ',var))
+     (find-hvariable ',var)
      ""
      (find-enode "Variable Index" ,(format "* %S:" var))
      (find-elnode "Index" ,(format "* %S:" var))
diff --git a/eev-helpful.el b/eev-helpful.el
new file mode 100644
index 0000000000..8d6e9f1b05
--- /dev/null
+++ b/eev-helpful.el
@@ -0,0 +1,195 @@
+;;; eev-helpful.el -- eev support for helpful.  -*- lexical-binding: nil; -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+;;
+;; This file is part of GNU eev.
+;;
+;; GNU eev is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+;;
+;; GNU eev is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+;;
+;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
+;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
+;; Version:    20220318
+;; Keywords:   e-scripts
+;;
+;; Latest version: <http://angg.twu.net/eev-current/eev-helpful.el>
+;;       htmlized: <http://angg.twu.net/eev-current/eev-helpful.el.html>
+;;       See also: <http://angg.twu.net/eev-current/eev-readme.el.html>
+;;                 <http://angg.twu.net/eev-intros/find-eev-intro.html>
+;;                                                (find-eev-intro)
+
+
+;; «.find-helpful-links»       (to "find-helpful-links")
+;; «.find-hlinks»              (to "find-hlinks")
+
+
+
+;;; Commentary:
+
+;; For more info on helpful, see:
+;;
+;;   https://github.com/Wilfred/helpful
+;;   (find-epackage-links 'helpful)
+;;
+;; Status of this file: early alpha.
+;; This code is very recent. Everything here may change.
+;;
+;; Note that `find-here-links' calls functions from this file
+;; when the major mode is `helpful-mode' - see:
+;;
+;;   (find-eev "eev-hlinks.el" "ee-fhl-main-program")
+;;   (find-eev "eev-hlinks.el" "ee-fhl-main-program" "helpful")
+;;
+;; Also, `find-efunction-links' and `find-evariable-links' now include
+;; links with `find-hfunction' and `find-hvariable' in the temporary
+;; buffers that they generate. If you execute them without having
+;; helpful installed you will get errors that should be easy to
+;; interpret as "hm, I need to install helpful.el"...
+
+
+
+
+
+;;;  _                         _ _       _        
+;;; | |__   ___ _ __ ___      | (_)_ __ | | _____ 
+;;; | '_ \ / _ \ '__/ _ \_____| | | '_ \| |/ / __|
+;;; | | | |  __/ | |  __/_____| | | | | |   <\__ \
+;;; |_| |_|\___|_|  \___|     |_|_|_| |_|_|\_\___/
+;;;                                               
+;; «find-helpful-links»  (to ".find-helpful-links")
+;; Skel: (find-find-links-links-new "helpful" "action symbol" "")
+;; Test: (find-helpful-links "function" "find-file")
+;;  See: (find-eevfile "eev-hlinks.el" "ee-fhl-main-program" "helpful")
+;;
+(defun find-helpful-links (&optional action symbol &rest pos-spec-list)
+"Visit a temporary buffer containing hyperlinks to a helpful buffer."
+  (interactive)
+  (setq action (or action (ee-helpful-action) "{action}"))
+  (setq symbol (or symbol (ee-helpful-symbol) "{symbol}"))
+  (apply
+   'find-elinks
+   `((find-helpful-links ,action ,symbol ,@pos-spec-list)
+     ;; Convention: the first sexp always regenerates the buffer.
+     (find-efunction 'find-helpful-links)
+     ""
+     ,@(ee-find-helpful-links action symbol)
+     )
+   pos-spec-list))
+
+(defun ee-find-helpful-links (&optional action symbol)
+  (setq action (or action (ee-helpful-action) "{action}"))
+  (setq symbol (or symbol (ee-helpful-symbol) "{symbol}"))
+  (list (ee-template0 "\
+# (find-h{action} '{symbol})
+# (helpful-{action} '{symbol})
+# (find-efunction 'helpful-{action})
+
+# (find-efunction-links '{symbol})
+# (find-evariable-links '{symbol})
+")))
+
+
+;; Tests: 
+;; (ee-helpful-action "*helpful command: find-file*")
+;; (ee-helpful-symbol "*helpful command: find-file*")
+;;
+(defvar ee-helpful-regexp "^\\*helpful \\([a-z]+\\): \\(.*\\)\\*$"
+  "A regexp that extracts the \"action\" and the \"symbol\" from
+the name of a buffer in helpful-mode.")
+
+(defun ee-helpful-action (&optional buffername)
+"An internal function used by `ee-find-helpful-links' and 
`find-helpful-links'."
+  (setq buffername (or buffername (buffer-name)))
+  (if (string-match ee-helpful-regexp buffername)
+      (ee-no-properties (match-string 1 buffername))))
+
+(defun ee-helpful-symbol (&optional buffername)
+"An internal function used by `ee-find-helpful-links' and 
`find-helpful-links'."
+  (setq buffername (or buffername (buffer-name)))
+  (if (string-match ee-helpful-regexp buffername)
+      (intern (ee-no-properties (match-string 2 buffername)))))
+
+
+
+;; (load "eev-helpful.el")
+
+;; See:
+
+
+;;;  _     _       _        
+;;; | |   (_)_ __ | | _____ 
+;;; | |   | | '_ \| |/ / __|
+;;; | |___| | | | |   <\__ \
+;;; |_____|_|_| |_|_|\_\___/
+;;;                         
+;; «find-hlinks»  (to ".find-hlinks")
+;; The functions below - with names like `find-h<action>' -
+;; are hyperlinks to helpful buffers. They use this trick to
+;; make helpful use the current window:
+;;   (find-eev "eev-blinks.el" "find-dbsw")
+
+;; Test: (find-hcallable 'find-file)
+;;  See: (find-efunction 'helpful-callable)
+(defun find-hcallable (symbol &rest pos-spec-list)
+  "Run `(helpful-callable SYMBOL)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-callable ',symbol) pos-spec-list))
+
+;; Test: (find-hcommand  'find-file)
+;;  See: (find-efunction 'helpful-command)
+(defun find-hcommand (symbol &rest pos-spec-list)
+  "Run `(helpful-command SYMBOL)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-command ',symbol) pos-spec-list))
+
+;; Test: (find-hfunction 'find-file)
+;;  See: (find-efunction 'helpful-function)
+(defun find-hfunction (symbol &rest pos-spec-list)
+  "Run `(helpful-function SYMBOL)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-function ',symbol) pos-spec-list))
+
+;; Test: (find-hkey      (kbd "M-h M-h"))
+;;  See: (find-efunction 'helpful-key)
+(defun find-hkey (keyseq &rest pos-spec-list)
+  "Run `(helpful-key KEYSEQ)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-key ',keyseq) pos-spec-list))
+
+;; Test: (find-hmacro    'cl-loop)
+;;  See: (find-efunction 'helpful-macro)
+(defun find-hmacro (symbol &rest pos-spec-list)
+  "Run `(helpful-macro SYMBOL)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-macro ',symbol) pos-spec-list))
+
+;; Test: (find-hsymbol   'cl-loop)
+;;  See: (find-efunction 'helpful-symbol)
+(defun find-hsymbol (symbol &rest pos-spec-list)
+  "Run `(helpful-symbol SYMBOL)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-symbol ',symbol) pos-spec-list))
+
+;; Test: (find-hvariable 'line-move-visual)
+;;  See: (find-efunction 'helpful-variable)
+(defun find-hvariable (symbol &rest pos-spec-list)
+  "Run `(helpful-variable SYMBOL)' and search for POS-SPEC-LIST."
+  (apply 'find-dbsw-call `(helpful-variable ',symbol) pos-spec-list))
+
+
+
+
+
+
+
+(provide 'eev-helpful)
+
+
+;; Local Variables:
+;; coding:            utf-8-unix
+;; no-byte-compile:   t
+;; End:
diff --git a/eev-hlinks.el b/eev-hlinks.el
index e9072a8fc5..2dfd5a25f4 100644
--- a/eev-hlinks.el
+++ b/eev-hlinks.el
@@ -202,6 +202,7 @@ the \"*(find-here-links)*\" buffer."
    (:if (ee-custom-bufferp)    (ee-find-custom-links))
    (:if (ee-epackages-bufferp) (ee-find-epackages-links))
    (:if (ee-osm-bufferp)       (ee-find-osm-links))
+   (:if (ee-helpful-bufferp)   (ee-find-helpful-links))
    ;;
    ;; By buffer name:
    (:if (ee-intro-bufferp)     (ee-find-intro-links))
@@ -366,6 +367,7 @@ the \"*(find-here-links)*\" buffer."
 (defun ee-custom-bufferp    () (eq major-mode 'Custom-mode))
 (defun ee-epackages-bufferp () (eq major-mode 'package-menu-mode))
 (defun ee-osm-bufferp       () (eq major-mode 'osm-mode))
+(defun ee-helpful-bufferp   () (eq major-mode 'helpful-mode))
 
 ;; By buffer name
 (defun ee-intro-bufferp    () (ee-buffer-re "^\\*(find-\\(.*\\)-intro)\\*$"))
diff --git a/eev-load.el b/eev-load.el
index 55a4be7e48..bcd9f013be 100644
--- a/eev-load.el
+++ b/eev-load.el
@@ -1,7 +1,7 @@
 ;;; eev-load.el -- load all the main modules of eev.  -*- lexical-binding: 
nil; -*-
 ;;; This can also be used as an index to the main source files.
 
-;; Copyright (C) 2019-2021 Free Software Foundation, Inc.
+;; Copyright (C) 2019-2022 Free Software Foundation, Inc.
 ;;
 ;; This file is part of GNU eev.
 ;;
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20220224
+;; Version:    20220318
 ;; Keywords:   e-scripts
 ;;
 ;; Supersedes: (find-eev "eev-all.el")
@@ -142,6 +142,7 @@
 (require 'eev-edit)            ; (find-eev "eev-edit.el")
 (require 'eev-testblocks)      ; (find-eev "eev-testblocks.el")
 (require 'eev-kla)             ; (find-eev "eev-kla.el")
+(require 'eev-helpful)         ; (find-eev "eev-helpful.el")
 ;;
 ;; Hyperlinks to audio, video, and IRC:
 ;;   (find-video-links-intro)
@@ -160,8 +161,8 @@
 ' (require 'eev-prepared)      ; (find-eev "eev-prepared.el")
 ' (require 'eev-bounded)       ; (find-eev "eev-bounded.el")
 ' (require 'eev-channels)      ; (find-eev "eev-channels.el")
-;; IMPORTANT: Since 2019mar05 they are no longer loaded by default!
-;; Note the "'" at the beginning of each line!
+;; IMPORTANT: Since 2019mar05 these files are no longer loaded by
+;; default! Note the "'" at the beginning of each line!
 
 
 ;; Make `M-x eev-beginner' work in the "expert setups" too.
diff --git a/eev-mode.el b/eev-mode.el
index 0b78a72f1b..8d07e968b8 100644
--- a/eev-mode.el
+++ b/eev-mode.el
@@ -278,7 +278,8 @@ Commands to edit hyperlinks:
      ,eev-mode-help
      :init-value nil
      :global t
-     :lighter ,eev-mode-lighter)
+     :lighter ,eev-mode-lighter
+     :group 'eev)
    ;; 
    ))
 
diff --git a/eev-plinks.el b/eev-plinks.el
index 2e7bafa409..3778ea055c 100644
--- a/eev-plinks.el
+++ b/eev-plinks.el
@@ -456,8 +456,7 @@ If wget can't download URL then this function runs `error'."
 The COMMENTS are ignored. You need to have osm.el - OpenStreetMap
 viewer - installed for this to work, and Emacs 28 or later."
   (require 'osm)
-  (same-window-prefix)
-  (osm-goto lat lon zoom))
+  (find-dbsw-call `(osm-goto ,lat ,lon ,zoom)))