[elpa] externals/eev 121acfc 05/20: Added comments to `find-grep-links'.

[Stefan Monnier]

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

    Added comments to `find-grep-links'.
---
 ChangeLog     |   5 +++
 VERSION       |   4 +--
 eev-elinks.el | 101 +++++++++++++++++++++++++++++++++++++---------------------
 eev-intro.el  |  28 +++++++++-------
 4 files changed, 87 insertions(+), 51 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ab89b0b..706bee5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2020-11-01  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-elinks.el (find-grep-links): rewrote using
+       `find-find-links-links-new' and added documentation.
+
 2020-10-30  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev-tlinks.el (find-youtubedl-links): rewrote using
diff --git a/VERSION b/VERSION
index afeeaa4..bb1436d 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Fri Oct 30 06:26:39 GMT 2020
-Fri Oct 30 03:26:39 -03 2020
+Mon Nov  2 07:19:36 GMT 2020
+Mon Nov  2 04:19:36 -03 2020
diff --git a/eev-elinks.el b/eev-elinks.el
index 5199a19..8362018 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -1,6 +1,6 @@
 ;;; eev-elinks.el --- `find-efunction-links' and other `find-e*-links'
 
-;; Copyright (C) 2012-2019 Free Software Foundation, Inc.
+;; Copyright (C) 2012-2020 Free Software Foundation, Inc.
 ;;
 ;; This file is part of GNU eev.
 ;;
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    2020oct30
+;; Version:    2020nov01
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -805,16 +805,71 @@ when this is true remove the prefix D from FNAME, and put 
the sexp
 ;;;                          |___/         |_|                             
 ;;
 ;; «find-grep-links» (to ".find-grep-links")
-;; Skel: (find-find-links-links-old "\\M-g" "grep" "")
+;; Skel: (find-find-links-links-new "grep" "" "")
+;;
+;; The functions `find-grep-links' and `ee-find-grep-links' are
+;; similar to `find-file-links', described here,
+;;
+;;   (find-eev-quick-intro "10.1. Generating short hyperlinks to files")
+;;
+;; in the sense that they generate short hyperlinks to the default
+;; directory and to its parent directories, but 1) they generate
+;; `find-xxxgrep' links instead of `find-xxxfile' links, and 2) they
+;; combine them with most recent elements in `grep-history'.
+;;
+;; Here's a micro-tutorial. Run `M-x grep', and complete the grep
+;; command with a string to search for and a list of files, like this,
+;;
+;;   grep --color -nH --null -e
+;;   -->
+;;   grep --color -nH --null -e Punch *.el
+;;
+;; and hit RET. You should get a buffer named "*grep*" with the
+;; results. If you type `M-h M-h' there the function `find-here-links'
+;; will run `ee-find-grep-links' to generate hyperlinks to the result
+;; of running that grep command, and one of those hyperlinks will be:
+;;
+;;   (find-eevgrep "grep --color -nH --null -e Punch *.el")
+;;
+(defun find-grep-links (&rest pos-spec-list)
+"Visit a temporary buffer containing `find-xxxgrep' sexps."
+  (interactive)
+  (apply
+   'find-elinks
+   `((find-grep-links ,@pos-spec-list)
+     ;; Convention: the first sexp always regenerates the buffer.
+     (find-efunction 'find-grep-links)
+     ""
+     ,@(ee-find-grep-links)
+     )
+   pos-spec-list))
+
+(defun ee-find-grep-links ()
+  "An internal function used by `find-grep-links'."
+  (ee-find-grep-links0
+   (ee-find-grep-functions default-directory)
+   (ee-find-grep-commands)))
+
+;; Low-level functions used by `ee-find-grep-links'.
 ;; Tests:
-;;   (ee-find-grep-commands)
-;;   (ee-find-grep-functions "~/eev-current/")
-;;   (ee-find-grep-links '(find-agrep find-bgrep) '("grep a *" "grep b *"))
-;;   (find-grep-links)
+;;   (find-elinks (ee-find-grep-links))
+;;   (ee-find-grep-links)
+;;   (ee-find-grep-links0 '(find-Agrep find-Bgrep) '("grep AA *" "grep BB *"))
+;;     (ee-find-grep-functions ee-emacs-lisp-directory)
+;;     (ee-find-grep-functions ee-eev-source-directory)
+;;     (ee-find-grep-commands)
 ;;
+(defun ee-find-grep-links0 (find-xxxgreps grep-commands)
+  "An internal function used by `find-grep-links'."
+  (let (result)
+    (dolist (head find-xxxgreps)
+      (dolist (command grep-commands)
+       (setq result (cons `(,head ,command) result))))
+    (nreverse result)))
 
-;; Moved to eev-mode.el:
-;; (define-key eev-mode-map "\M-h\M-g" 'find-grep-links)
+(defun ee-find-grep-commands ()
+  "An internal function used by `find-grep-links'."
+  (cons "grep -nH -e _ *" (ee-first-n-elements 4 grep-history)))
 
 (defun ee-first-n-elements (n list)
   "Example: (ee-first-n-elements 2 '(a b c d e f))   ==> (a b)"
@@ -826,34 +881,6 @@ when this is true remove the prefix D from FNAME, and put 
the sexp
   "An internal function used by `find-grep-links'."
   (ee-code-c-d-filter-2 dir '(ee-intern "find-%sgrep" c)))
 
-(defun ee-find-grep-commands ()
-  "An internal function used by `find-grep-links'."
-  (cons "grep -nH -e _ *" (ee-first-n-elements 4 grep-history)))
-
-(defun ee-find-grep-links0 (find-xxxgreps grep-commands)
-  "An internal function used by `find-grep-links'."
-  (let (result)
-    (dolist (head find-xxxgreps)
-      (dolist (command grep-commands)
-       (setq result (cons `(,head ,command) result))))
-    (nreverse result)))
-
-(defun ee-find-grep-links ()
-  (ee-find-grep-links0
-   (ee-find-grep-functions default-directory)
-   (ee-find-grep-commands)))
-
-(defun find-grep-links (&rest pos-spec-list)
-"Visit a temporary buffer containing `find-xxxgrep' sexps."
-  (interactive)
-  (apply 'find-elinks
-   `((find-grep-links ,@pos-spec-list)
-     ;; Convention: the first sexp always regenerates the buffer.
-     (find-efunction 'find-grep-links)
-     ""
-     ,@(ee-find-grep-links)
-     )
-   pos-spec-list))
 
 
 
diff --git a/eev-intro.el b/eev-intro.el
index 5a074af..d62b009 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -1795,7 +1795,8 @@ This section was moved to:
 Source code:  (find-efunction 'find-emacs-keys-intro)
 More intros:  (find-eev-quick-intro)
               (find-eev-intro)
-              (find-eval-intro)
+              (find-here-links-intro)
+              (find-refining-intro)
               (find-eepitch-intro)
 This buffer is _temporary_ and _editable_.
 It is meant as both a tutorial and a sandbox.
@@ -2440,10 +2441,9 @@ See:
 Source code:  (find-eev \"eev-intro.el\" \"find-eev-intro\")
 Main intros:  (find-eev-quick-intro)
               (find-emacs-keys-intro)
-              (find-eval-intro)
               (find-eepitch-intro)
-              (find-wrap-intro)
-              (find-eev-intro)
+              (find-here-links-intro)
+              (find-refining-intro)
 Index to the source files: (find-eev \"eev-load.el\")
 This buffer is _temporary_ and _editable_.
 It is meant as both a tutorial and a sandbox.
@@ -2814,14 +2814,14 @@ and the \"1\" is a reference to this:
 Note that `M-h M-1' undoes what `M-h M-3' did. In a figure:
 
    _______________           _____________________           ________________ 
-  |               |        |          |          |         |                |
-  |               |        |          |  elinks  |         |                |
-  |               |        |          |  buffer  |         |                |
+  |               |         |          |          |         |                |
+  |               |         |          |  elinks  |         |                |
+  |               |         |          |  buffer  |         |                |
   |    target     | M-h M-3 |  target  |__________| M-h M-1 |     target     |
   |    buffer     | ------> |  buffer  |          | ------> |     buffer     |
-  |               |        |          |  notes   |         |                |
-  |               |        |          |  buffer  |         |                |
-  |_______________|        |__________|__________|         |________________|
+  |               |         |          |  notes   |         |                |
+  |               |         |          |  buffer  |         |                |
+  |_______________|         |__________|__________|         |________________|
 
 
 
@@ -2904,7 +2904,9 @@ The next steps are to learn how:
 \(Re)generate: (find-refining-intro)
 Source code:  (find-efunction 'find-refining-intro)
 More intros:  (find-eev-quick-intro)
-              (find-eval-intro)
+              (find-eev-intro)
+              (find-emacs-keys-intro)
+              (find-here-links-intro)
 This buffer is _temporary_ and _editable_.
 It is meant as both a tutorial and a sandbox.
 
@@ -6101,7 +6103,9 @@ Try: (find-code-pdf      \"CODE\" \"FILE.pdf\")
 \(Re)generate: (find-pdf-like-intro)
 Source code:  (find-eev \"eev-intro.el\" \"find-pdf-like-intro\")
 More intros:  (find-eev-quick-intro)
-              (find-eval-intro)
+              (find-eev-intro)
+              (find-here-links-intro)
+              (find-refining-intro)
               (find-eepitch-intro)
 This buffer is _temporary_ and _editable_.
 It is meant as both a tutorial and a sandbox.