[elpa] externals/eev f6fd28a 62/64: Cleaned up the comments about `ee-code-c-d-filter-2'.

[Stefan Monnier]

branch: externals/eev
commit f6fd28a430692dd0382dfeef114792f4fe59732f
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Cleaned up the comments about `ee-code-c-d-filter-2'.
---
 ChangeLog     | 12 +++++++++
 README        | 38 +++++++++++++++++++++++++--
 VERSION       |  4 +--
 eev-code.el   |  6 ++---
 eev-elinks.el | 84 +++++++++++++++++++++++++++--------------------------------
 eev-intro.el  | 13 +--------
 6 files changed, 93 insertions(+), 64 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4c64ba7..2262867 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2019-04-01  Eduardo Ochs  <address@hidden>
+
+       * README: added a section "eev without eev-mode".
+
+       * eev-intro.el (find-eev-intro): small changes.
+       (find-eev-install-intro): small changes.
+
+       * eev-code.el (ee-code-c-d-pairs): fixed the comments.
+
+       * eev-elinks.el: Cleaned up the comments about
+       `ee-code-c-d-filter-2' and related functions.
+
 2019-03-29  Eduardo Ochs  <address@hidden>
 
        * eev-template0.el: new file.
diff --git a/README b/README
index 6597863..6703a17 100644
--- a/README
+++ b/README
@@ -14,14 +14,48 @@ eev-mode keybindings, and open this tutorial,
   (find-eev-quick-intro)
 
 in a sandboxed buffer. For a list of the other sandboxed tutorials,
-run:
+see:
 
+  http://angg.twu.net/eev-intros/find-eev-intro.html
   (find-eev-intro)
 
-For a non-technical description of what e-scripts are, see:
+Note that the URLs point to the HTMLized versions of the sandboxed
+tutorials, and the `(find-*-intro)' sexps open them in Emacs.
+
+For a _non-technical_ description of what e-scripts are, see:
 
   http://angg.twu.net/escripts.html
 
+For an analysis of an e-script that uses most of the main features of
+eev, see:
+
+  http://angg.twu.net/eev-intros/find-escripts-intro.html#4
+  (find-escripts-intro "4. How to read an e-script")
+
 The home page of eev is:
 
   http://angg.twu.net/#eev
+
+
+
+
+
+EEV WITHOUT EEV-MODE
+====================
+Eev mode only activates some keybindings and adds a reminder saying
+"eev" to the mode line, as explained here:
+
+  http://angg.twu.net/eev-intros/find-eev-intro.html#1
+  (find-eev-intro "1. `eev-mode'")
+
+It is possible to use eev's elisp hyperlink functions with eev-mode
+turned off: just put the point on a line with an elisp hyperlink and
+type `C-e C-x C-e'.
+
+If you want to load all the main modules of eev to make its functions
+available in this way, do:
+
+  (require 'eev-load)
+
+then you can use `M-x eev-mode' to toggle eev-mode on and off when
+desired.
diff --git a/VERSION b/VERSION
index 993ba0b..307e85d 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Fri Mar 29 23:08:28 GMT 2019
-Fri Mar 29 20:08:28 -03 2019
+Tue Apr  2 00:31:14 GMT 2019
+Mon Apr  1 21:31:14 -03 2019
diff --git a/eev-code.el b/eev-code.el
index 8639052..be2f727 100644
--- a/eev-code.el
+++ b/eev-code.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar29
+;; Version:    2019apr01
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-code.el>
@@ -125,8 +125,8 @@ Examples: (ee-areplace '((1 . one) (2 . two) (3 . three)) 2 
'foo)
 (defvar ee-code-c-d-pairs nil
   "Each (code-c-d C D) call generates an entry (C (ee-expand D)) here.
 A new entry with the same C as a previous one will replace the
-previous one. This list is maintained by `ee-code-c-d-add-pair' and
-is used by some functions in \"eev-insert.el\".")
+previous one. This list is maintained by `ee-code-c-d-add-pair'
+and is used by `ee-find-xxxfile-sexps' and `find-file-links'.")
 
 (defun ee-code-c-d-add-pair (c d)
   (setq ee-code-c-d-pairs (ee-areplace ee-code-c-d-pairs c (list d))))
diff --git a/eev-elinks.el b/eev-elinks.el
index 7372854..9ba2af3 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar05
+;; Version:    2019apr01
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -64,7 +64,6 @@
 ;; «.find-einfo-links»         (to "find-einfo-links")
 ;; «.find-eintro»              (to "find-eintro")
 
-;; «.ee-code-c-d-pairs-eval»   (to "ee-code-c-d-pairs-eval")
 ;; «.ee-code-c-d-filter»       (to "ee-code-c-d-filter")
 ;; «.ee-find-xxxfile-sexps»    (to "ee-find-xxxfile-sexps")
 ;; «.find-file-links»          (to "find-file-links")
@@ -591,34 +590,49 @@ a hack to let use use `M-h M-i' for both \"intro\" and 
\"info\"."
 
 
 
-
-;;;                _                          _                   _          
-;;;   ___ ___   __| | ___        ___       __| |      _ __   __ _(_)_ __ ___ 
-;;;  / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| '_ \ / _` | | '__/ __|
-;;; | (_| (_) | (_| |  __/_____| (_|_____| (_| |_____| |_) | (_| | | |  \__ \
-;;;  \___\___/ \__,_|\___|      \___|     \__,_|     | .__/ \__,_|_|_|  |___/
-;;;                                                  |_|                     
-;;
-;; «ee-code-c-d-pairs-eval» (to ".ee-code-c-d-pairs-eval")
+;;;                _                          _        __ _ _ _            
+;;;   ___ ___   __| | ___        ___       __| |      / _(_) | |_ ___ _ __ 
+;;;  / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| |_| | | __/ _ \ '__|
+;;; | (_| (_) | (_| |  __/_____| (_|_____| (_| |_____|  _| | | ||  __/ |   
+;;;  \___\___/ \__,_|\___|      \___|     \__,_|     |_| |_|_|\__\___|_|   
+;;;                                                                        
 ;; «ee-code-c-d-filter» (to ".ee-code-c-d-filter")
+;; This is a trick to make `find-file-links' generate short hyperlinks.
+;; See: (find-eev-quick-intro "10.1. Generating short hyperlinks to files")
+;;
 ;; Each call to `(code-c-d C D)' generates an entry `(C D)' in the
-;; alist `ee-code-c-d-pairs', and this is used to make
-;; `(find-file-links FNAME)' list short hyperlinks to FNAME. Let's
-;; look at an example:
+;; alist `ee-code-c-d-pairs'. Try:
 ;;
 ;;   (code-c-d "foo"  "/FOO")
 ;;   (code-c-d "bar"  "/FOO/BAR/")
 ;;   (code-c-d "plic" "/FOO/BAR/PLIC/")
+;;   (find-epp ee-code-c-d-pairs)
+;;
+;; You will see that the `ee-code-c-d-pairs' now begins with:
+;;
+;;   (("plic" "/FOO/BAR/PLIC/")
+;;    ("bar" "/FOO/BAR/")
+;;    ("foo" "/FOO")
+;;    ...
+;;    )
+;;
+;; And if you run
+;;
 ;;   (find-file-links "/FOO/BAR/PLIC/ploc")
 ;;
-;; The last links in the `find-file-links' buffer will be:
+;; Then the last links in the `find-file-links' buffer will be:
 ;;
-;;   (find-plicfile "ploc")
-;;   (find-barfile "PLIC/ploc")
+;;   (find-plicfile          "ploc")
+;;   (find-barfile      "PLIC/ploc")
 ;;   (find-foofile "/BAR/PLIC/ploc")
 ;;
-;; The implementation is tricky enough to deserve debug functions.
-;; Try:
+;; They are generated by `ee-find-xxxfile-sexps'. Try:
+;;
+;;   (find-epp (ee-find-xxxfile-sexps "/FOO/BAR/PLIC/ploc"))
+;;
+;; To understand the implementation, try the sexps below. Note that
+;; `find-code-c-d-filter-1' and `find-code-c-d-filter-2' are debugging
+;; functions.
 ;;
 ;;   (find-epp ee-code-c-d-pairs)
 ;;   (find-code-c-d-filter-1 'c-d)
@@ -627,7 +641,6 @@ a hack to let use use `M-h M-i' for both \"intro\" and 
\"info\"."
 ;;   (find-code-c-d-filter-1 'ed)
 ;;   (find-code-c-d-filter-2 "/FOO/BAR/PLIC/ploc" '(list c fname-))
 ;;   (find-code-c-d-filter-2 "/FOO/BAR/PLIC/ploc" '(ee-intern "find-%sfile" c))
-;;   (find-epp (ee-find-xxxfile-sexps "/FOO/BAR/PLIC/ploc"))
 ;;
 ;; See: (find-evariable 'ee-code-c-d-pairs)
 ;;      (find-elnode "Association Lists")
@@ -639,7 +652,7 @@ Actually return a list of `(F elt)'s."
 
 (defun ee-code-c-d-filter-1 (code)
   "Run CODE on each `c-d' of `ee-code-c-d-pairs' and return a list of results.
-This is a simpler version of `ee-code-c-d-filter-2', used for debugging."
+This is a simpler version of `ee-code-c-d-filter-2', used only for debugging."
   (ee-filter
    (lambda (c-d)
      (let* ((c (car c-d))
@@ -650,7 +663,9 @@ This is a simpler version of `ee-code-c-d-filter-2', used 
for debugging."
 
 (defun ee-code-c-d-filter-2 (fname code)
   "Run CODE on each `c-d' of `ee-code-c-d-pairs' and return a list of results.
-Only eval CODE when (ee-expand D) is a prefix of (ee-expand FNAME)."
+Only eval CODE when (ee-expand D) is a prefix of (ee-expand FNAME).
+CODE is evaluated inside a `let' that sets the variables `c',
+`d', `ed', `efname', and `fname-'. See the source for their meanings."
   (let ((efname (ee-expand fname)))
     (ee-filter
      (lambda (c-d)
@@ -689,36 +704,15 @@ Only eval CODE when (ee-expand D) is a prefix of 
(ee-expand FNAME)."
   (ee-replace-prefix0 (ee-expand prefix) newprefix (ee-expand fname)))
 
 (defun ee-intern (fmt &rest args)
+  "The result of (format FMT ARGS), converted to a symbol"
   (intern (apply 'format fmt args)))
 
-;; Renamed to `ee-code-c-d-filter-2'. See above.
-;;
-;; (defun ee-code-c-d-pairs-eval (fname code)
-;;   "For each entry (C D) in `ee-code-c-d-pairs' for which D is a prefix of 
FNAME,
-;; evaluate f in the context of a big `let', and return the result."
-;;   (let ((efname (ee-expand fname)))
-;;     (ee-filter (lambda (c-d)
-;;                  (let* ((c (car c-d))
-;;                         (d (cadr c-d))
-;;                         (ed (ee-expand d)))
-;;                    (if (ee-prefixp ed efname)
-;;                        (let ((fname- (ee-remove-prefix ed efname)))
-;;                          (eval code)))))
-;;                ee-code-c-d-pairs)))
-
 ;; «ee-find-xxxfile-sexps»  (to ".ee-find-xxxfile-sexps")
 (defun ee-find-xxxfile-sexps (fname)
   "For each (C D) in ee-code-c-d-pairs test if D is a prefix of FNAME;
 when this is true remove the prefix D from FNAME, and put the sexp
 (find-Cfile \"FNAME-\") in the list of results. Return that list."
-  (ee-code-c-d-pairs-eval
-   fname
-   '(list (ee-intern "find-%sfile" c) fname-)))
-
-;; Experimental:
-(defun ee-find-xxxfile-sexps (fname)
-  (;; ee-code-c-d-pairs-eval
-   ee-code-c-d-filter-2
+  (ee-code-c-d-filter-2
    fname
    '(list (ee-intern "find-%sfile" c) fname-)))
 
diff --git a/eev-intro.el b/eev-intro.el
index e589563..c0e886d 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar10
+;; Version:    2019apr01
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -1874,10 +1874,6 @@ things that happen are:
 
        (find-eev \"eev-blinks.el\" \"find-man\")
 
-This is all I remember now (2019mar05). I am trying to make eev
-as non-invasive as possible - to convince as many people as
-possible to install it and try it!
-
 
 
 
@@ -2134,13 +2130,6 @@ things that happen are:
 
        (find-eev \"eev-blinks.el\" \"find-man\")
 
-This is all I remember now (2019mar05). I am trying to make eev
-as non-invasive as possible - to convince as many people as
-possible to install it and try it!
-
-  (find-eev-install-intro \"1. Installing eev by hand\")
-
-