[elpa] externals/eev 43c5f82ad9: Rewrote many comments in eev-kla.el.

[ELPA Syncer]

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

    Rewrote many comments in eev-kla.el.
---
 VERSION      |   4 +-
 eev-code.el  |  18 ++--
 eev-intro.el |   9 +-
 eev-kla.el   | 295 ++++++++++++++++-------------------------------------------
 4 files changed, 93 insertions(+), 233 deletions(-)

diff --git a/VERSION b/VERSION
index 1b7c490d23..d76cc3aa88 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sat Nov 26 00:37:16 GMT 2022
-Fri Nov 25 21:37:16 -03 2022
+Mon Nov 28 03:03:10 GMT 2022
+Mon Nov 28 00:03:11 -03 2022
diff --git a/eev-code.el b/eev-code.el
index ea2ac05e0e..ca188a6a75 100644
--- a/eev-code.el
+++ b/eev-code.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20221122
+;; Version:    20221127
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-code.el>
@@ -230,8 +230,17 @@ Try this: (find-code-c-d \"CODE\" \"/DIR/\" :info 
\"INFO\")"
      (apply 'ee-find-grep ee-{c}dir grep-command-args pos-spec-list))
    "))
 
+(defun ee-code-c-d-:anchor (c d &rest rest)
+  (concat (ee-template0 "
+   ;; See: (find-eev-quick-intro \"9.2. Extra arguments to `code-c-d'\")
+   ;; {(ee-S `(ee-code-c-d-:anchor ,c ,d ,@rest))}
+   (defun find-{c} (str &rest pos-spec-list)
+     (apply 'find-anchor (ee-{c}file str) pos-spec-list))
+   ") (ee-code-c-d-rest c d rest)))
+
 (defun ee-code-c-d-:info (c d info &rest rest)
   (concat (ee-template0 "
+   ;; See: (find-eev-quick-intro \"9.2. Extra arguments to `code-c-d'\")
    ;; {(ee-S `(ee-code-c-d-:info ,c ,d ,info ,@rest))}
    (defun find-{c}node (page &rest pos-spec-list)
      (interactive (list \"\"))
@@ -257,13 +266,6 @@ Try this: (find-code-c-d \"CODE\" \"/DIR/\" :info 
\"INFO\")"
      (apply 'find-fline-gz (ee-{c}file str) pos-spec-list))
    ") (ee-code-c-d-rest c d rest)))
 
-(defun ee-code-c-d-:anchor (c d &rest rest)
-  (concat (ee-template0 "
-   ;; {(ee-S `(ee-code-c-d-:anchor ,c ,d ,@rest))}
-   (defun find-{c} (str &rest pos-spec-list)
-     (apply 'find-anchor (ee-{c}file str) pos-spec-list))
-   ") (ee-code-c-d-rest c d rest)))
-
 (defun ee-code-c-d-:tags (c d &rest rest)
   (concat (ee-template0 "
    ;; {(ee-S `(ee-code-c-d-:anchor ,c ,d ,@rest))}
diff --git a/eev-intro.el b/eev-intro.el
index 12ac04c5e7..d1a05cc4ad 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20221120
+;; Version:    20221126
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -14481,11 +14481,9 @@ This buffer is _temporary_ and _editable_.
 It is meant as both a tutorial and a sandbox.
 
 
-
-WARNING:
-  This is being rewritten!
   See: http://angg.twu.net/emacsconf2022-kla.html
-       (find-eev \"eev-kla.el\")
+    (find-eev \"eev-kla.el\")
+    `kla' means \"kill link to anchor\".
   The prerequisites for this tutorial are:
     (find-eev-quick-intro \"8. Anchors\")
     (find-eev-quick-intro \"9.1. `code-c-d'\")
@@ -14896,6 +14894,7 @@ See: (find-eev \"eev-kla.el\" \"ee-kl-expand\")
 (defalias 'klf  'eeklf)
 (defalias 'klfs 'eeklfs)
 (defalias 'klt  'eeklt)
+(defalias 'klts 'eeklts)
 (defalias 'kli  'ee-kl-insert)
 (defalias 'kla2 'eekla2)
 
diff --git a/eev-kla.el b/eev-kla.el
index 85582b295e..4e7a83ab4f 100644
--- a/eev-kla.el
+++ b/eev-kla.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20221122
+;; Version:    20221128
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-kla.el>
@@ -28,14 +28,11 @@
 ;;                 <http://angg.twu.net/eev-intros/find-eev-intro.html>
 ;;                                                (find-eev-intro)
 
-;; «.tests»                    (to "tests")
-;; «.intro»                    (to "intro")
-;;  «.test»                    (to "test")
+;; «.a-test»                   (to "a-test")
+;; «.more-tests»               (to "more-tests")
 ;;
-;; «.variables»                        (to "variables")
 ;; «.ee-kl-expand»             (to "ee-kl-expand")
 ;; «.default-args»             (to "default-args")
-;;
 ;; «.best-lrcd»                        (to "best-lrcd")
 ;; «.ee-kl-r-c-d»              (to "ee-kl-r-c-d")
 ;; «.shorter-fnames»           (to "shorter-fnames")
@@ -51,238 +48,78 @@
 
 ;;; Commentary:
 
-;; «tests»  (to ".tests")
-;; Most of the docs about eev-kla.el are in this intro:
-;;
-;;   http://angg.twu.net/eev-intros/find-kla-intro.html
-;;                                 (find-kla-intro)
-;;
-;; Here are some tests that need to be run from a file. Try:
-;;
-;;   (ee-kl-anchor)
-;;   (ee-kl-c)
-;;   (ee-kl-sexp-kla)
-;;   (ee-kl-sexp-klf)
-;;   (ee-kl-sexp-klt)
-;;
-;; And then:
+;; «a-test»  (to ".a-test")
+;; Try this:
 ;;
 ;;   M-x eekla
-;;   M-x eeklf
-;;   M-x eeklt
-
-
-;; WARNING (2022nov15): This is being rewritten!
-;; One of my presentations at the EmacsConf2022 will be about
-;; eev-kla.el. Its page is:
-;;
-;;   http://angg.twu.net/emacsconf2022-kla.html
-;;
-;; Right now - 2022nov15 - I am in the middle of rewriting both and
-;; the code and the docs of eev-kla.el almost completely. The docs are
-;; being moved to:
-
-
-;;
-;;   «intro»  (to ".intro")
-;; 1. Very short introduction
-;; ==========================
-;; This:
-;;
-;;   (find-eev "eev-kla.el" "intro")
-;;
-;; is a short hyperlink to the anchor "intro" above. The standard way
-;; to create a link like that is using `find-here-links', refining,
-;; and shrinking, and that way needs many keys. It is explained here:
-;;
-;;   (find-saving-links-intro "2.3. The base case 3")
-;;
-;; This file implements another way to generate links like the one
-;; in the beginning of this section. Try this:
-;;
-;;   M-x eekla
-;;
-;; You will see a message like this one
-;;
-;;   Copied to the kill ring: (find-eev "eev-kla.el" "intro")
-;;
-;; in the echo area. Then go to the your notes, paste that link with
-;; `C-y', and follow it - it will take you back here.
-;;
-;;
-;;
-;; 8. `eekla' and friends
-;; ======================
-;; At the moment this file implements these commands:
-;;
-;;   1) `M-x eekla', that <K>ills a <L>ink to an <A>nchor.
-;;      See: (find-anchors-intro "3. The preceding tag" "M-1 M-h M-w")
-;;           (find-refining-intro "5. Pointing to anchors")
-;;
-;;         «test»  (to ".test")
-;;
-;;      To test this, run `M-x eekla' here. It will highlight the
-;;      anchor above ("test") for a fraction of a second and will show
-;;      this message in the echo area:
-;;
-;;        Copied to the kill ring: (find-eev "eev-kla.el" "test")
-;;
-;;   2) `M-x eeklf', that <K>ills a <L>ink to a <F>ile.
-;;       To test this, just run `M-x eeklf'. You will see this message
-;;       in the echo area:
-;;
-;;         Copied to the kill ring: (find-eevfile "eev-kla.el")
-;;
-;;   3) `M-x eeklas': <K>ill a <L>ink to an <A>nchor and <S>tring.
-;;      This is similar to `M-x eekla', but if "refines" the link
-;;      generated by `M-x eekla' by adding the region between the
-;;      point and the mark. For example, is the region is this "blah"
-;;      then `M-x eeklas' with show this message:
-;;
-;;        Copied to the kill ring: (find-eev "eev-kla.el" "test" "blah")
-;;
-;;   4) `M-x eeklfs': <K>ill a <L>ink to a <F>ile and <S>string.
-;;      If the region is this "bleh" then `M-x eeklfs' will show
-;;      this message:
-;;
-;;        Copied to the kill ring: (find-eevfile "eev-kla.el" "bleh")
-;;
-;;   5) `M-x eeklt': <K>ills a <L>ink made with (<T>o ...).
-;;      To test this, run `M-x eeklt' here. You will see this message
-;;      in the echo area:
-;;
-;;         Copied to the kill ring: (to "test")
-;;
-;;   6) `M-x ee-kl-insert' and `M-x eekla2', that are explained in the
-;;      next section.
 ;;
+;; You will see this message in the echo area:
 ;;
+;;   Copied to the kill ring: (find-eev "eev-kla.el" "a-test")
 ;;
-;; 9. Aliases
-;; ==========
-;; The last section of this file - i.e.:
+;; Congratulations! You have just "killed a link to an anchor"! =)
+;; What happened in this test was that `eekla' has generated a link to
+;; the anchor above and "killed it", in the sense of "copied it to the
+;; kill ring"...
 ;;
-;;   (find-eev "eev-kla.el" "aliases")
-;;
-;; suggests some aliases - for example, `M-x kla' for `M-x eekla'.
-;; From here onwards I will suppose that these aliases are active.
-;;
-;;
-;;
-;; 10. Bidirectional links
-;; =======================
-;; This page
-;;
-;;    http://angg.twu.net/emacsconf2022-kla.html
-;;
-;; has one of my submissions to the EmacsConf2022; its title is
-;; "Bidirectional links with eev", and that title refers to something
-;; that I will show in the last part - probably the last minute - of
-;; my video. The idea is that sometimes we have two windows displaying
-;; different files, like this:
-;;
-;;    _____________________
-;;   |          |          |
-;;   | ;; «a»   | # «b»    |
-;;   | _        | _        |
-;;   |          |          |
-;;   |__________|__________|
-;;   |__foo.el__|__bar.py__|
-;;
-;; In the drawing above the first window is visiting a file called
-;; "foo.el" (in Elisp) and the second one is visiting a file called
-;; "bar.py" (in Python). In the first one the point is just after an
-;; anchor whose tag is "a", and in the second one the point is after
-;; an anchor whose tag is "b".
-;;
-;; We want to create a link from the "a" to the "b", and a link from
-;; the "b" to the "a", with few keystrokes. Or, more precisely...
-;;
-;; An `M-x kla' in the first window generates a link like this,
-;;
-;;   (find-foo "foo.el" "a")
+;; Most of the docs about eev-kla.el are in this intro:
 ;;
-;; and an `M-x kla' in the second window generates one like this:
+;;   http://angg.twu.net/eev-intros/find-kla-intro.html
+;;                                 (find-kla-intro)
 ;;
-;;   (find-bar "bar.py" "b")
+;; but some tests can't be run from the intro because they need to
+;; "invert the action of a `code-c-d'". For example,
 ;;
-;; We want a VERY VERY FAST WAY to put the first link on the second
-;; window, and the second link in the first window, to get something
-;; like this:
-;;    ____________________________________________________________
-;;   |                              |                             |
-;;   | ;; «a»                       | # «b»                       |
-;;   | ;; (find-bar "bar.py" "b")   | # (find-foo "foo.el" "a")   |
-;;   | _                            | _                           |
-;;   |                              |                             |
-;;   |______________________________|_____________________________|
-;;   |__foo.el______________________|__bar.py_____________________|
+;;   (find-eev "eev-kla.el" "tests")
 ;;
-;; we also want these links to be inserted in comments. In Elisp
-;; comments start with ";;", and in Python they start with "#".
+;; is a hyperlink to this file, and to the anchor above. The function
+;; `find-eev' was defined by a call to `code-c-d' like the one below,
 ;;
-;; In pseudocode, what we want is roughly this:
+;;   ;; (find-code-c-d "eev" ee-eev-source-directory :anchor)
+;;           (code-c-d "eev" ee-eev-source-directory :anchor)
 ;;
-;;   1. start at the first window
-;;   2. generate a link to the "a" with `M-x kla'
-;;   3. switch to the next window
-;;   4. insert that link with a comment prefix and a newline
-;;   5. generate a link to the "b" with `M-x kla'
-;;   6. switch back to the first window
-;;   7. insert that link with a comment prefix and a newline
+;; that was run from this module of eev:
 ;;
-;; The command `M-x kla2' (or `M-x eekla2') does that.
+;;   (find-eev "eev-code.el" "code-c-d-s")
 ;;
-;; 11. Overridable functions
-;; =========================
-;; On my machine I have some "living fossils" - the ones mentioned
-;; in `find-angg-es-links',
+;; That `code-c-d' defined the function `find-eev' in the "right" way,
+;; and added an entry for "eev" in `ee-code-c-d-pairs'. You can see
+;; that entry by running this,
 ;;
-;;   (find-angg-es-links)
-;;   (find-angg-es-links 2 "living fossil")
-;;   (find-eev "eev-tlinks.el" "find-angg-es-links")
-;;   (find-eev "eev-tlinks.el" "find-angg-es-links" "living fossil")
+;;   (find-eppp ee-code-c-d-pairs "\"eev\"")
 ;;
-;; ...and a few other ones. My trick for making `kla' and `klas'
-;; support them is to override `ee-kl-shorterfname', and redefine it
-;; in my ~/.emacs by a function that deletes the suffixes.
+;; or by running
 ;;
-;; Also, a friend of mine uses Doom Emacs, that uses straight.el, and
-;; he told me that in Doom Emacs this
+;;   (find-kla-links)
 ;;
-;;   (find-eev "eev-code.el" "code-c-d-s")
-;;   (find-eev "eev-code.el" "code-c-d-s" "ee-eev-source-directory")
+;; and exploring the sexps in the temporary buffer that
+;; `find-kla-links' generates.
+
+
+
+;; «more-tests»  (to ".more-tests")
+;; Now try:
 ;;
-;; points to a directory that only has .el files, and all these ".el"s
-;; are symlinks. This breaks `ee-kl-shortfname', and I'm experimenting
-;; with variants of `ee-kl-shortfname' - that are hacks, and that have
-;; to be put in his ~/.emacs to override the original function - that
-;; contain code to handle these symlinks correctly.
+;;   M-x eeklf
+;;   M-x eeklt
 ;;
+;; You should get these messages in the echo area:
 ;;
-;; 12. Please test!
-;; ================
-;; ..and get in touch, either through the mailing list,
+;;   Copied to the kill ring: (find-eevfile "eev-kla.el")
+;;   Copied to the kill ring: (to "more-tests")
 ;;
-;;   https://lists.gnu.org/archive/html/eev/
-;;   https://lists.nongnu.org/mailman/listinfo/eev
+;; The results of the next tests will depend on what is in the region.
+;; If you mark this "foo" - without the quotes - and try
 ;;
-;; or by one of the ways listed here:
+;;   M-x eeklas
+;;   M-x eeklfs
+;;   M-x eeklts
 ;;
-;;   http://angg.twu.net/contact.html
+;; you will get these messages in the echo area:
 ;;
-;; Thanks! =)
-
-
-
-
-;; «variables»  (to ".variables")
-
-(defvar ee-kl-transforms nil
-  "Set this if you need to support symlinks in eev-kla.el.
-The value of this variable should be a list of pairs of this form:
-(regexp replacement).")
-
+;;   Copied to the kill ring: (find-eev "eev-kla.el" "more-tests" "foo")
+;;   Copied to the kill ring: (find-eevfile "eev-kla.el" "foo")
+;;   Copied to the kill ring: (to "more-tests" "foo")
 
 
 
@@ -296,17 +133,27 @@ The value of this variable should be a list of pairs of 
this form:
 ;; «ee-kl-expand»  (to ".ee-kl-expand")
 ;; See: (find-kla-intro "9. Symlinks")
 ;;
-(defun ee-kl-expand (fname)
-  "Expand FNAME using `ee-expand'. Use other hacks if needed."
-  (ee-kl-transform (ee-expand fname)))
+(defvar ee-kl-transforms nil
+  "Set this if you need to support symlinks in eev-kla.el.
+The value of this variable should be a list of pairs of this form:
+(regexp replacement).")
 
 (defun ee-kl-transform (fname)
-  "Transform FNAME into a canonical form.
-This is a hack to support symlinks in eev-kla.el. See the source."
+  "Transform FNAME into a canonical form using regexps.
+For each pair (regexp replacement) in `ee-kl-transforms' this
+function replaces all occurrences of the regexp in FNAME by the
+corresponding replacement."
   (cl-loop for (regexp repl) in ee-kl-transforms
            do (setq fname (replace-regexp-in-string regexp repl fname)))
   fname)
 
+(defun ee-kl-expand (fname)
+  "Expand FNAME using `ee-expand'.
+This function also runs `ee-kl-transform' on the result, but
+`ee-kl-transform' is usually a no-op."
+  (ee-kl-transform (ee-expand fname)))
+
+
 
 ;;;  ____        __             _ _                         
 ;;; |  _ \  ___ / _| __ _ _   _| | |_    __ _ _ __ __ _ ___ 
@@ -490,6 +337,12 @@ If (ee-kl-lrcds FNAME) doesn't return any matching 
`lrcd's, return nil."
   (setq anchor (or anchor (ee-kl-anchor)))
   (list 'to anchor))
 
+(cl-defun ee-kl-sexp-klts (&key anchor region)
+  "<K>ill <l>ink to a (<t>o ... ...) - make sexp."
+  (setq anchor (or anchor (ee-kl-anchor))
+       region (or region (ee-kl-region)))
+  (list 'to anchor region))
+
 
 
 ;;;                  _    _       _    _ _ _ 
@@ -557,6 +410,11 @@ Put in the kill ring a link to the preceding anchor."
   (interactive)
   (ee-kl-kill (ee-kl-sexp-klt)))
 
+(defun eeklts ()
+  "<K>ill <L>ink to a (<T>o ... ...)."
+  (interactive)
+  (ee-kl-kill (ee-kl-sexp-klts)))
+
 
 
 ;;;                  _    _       _                     _   
@@ -653,6 +511,7 @@ When not at BOL, move to the beginning of the next line."
 ;; (defalias 'klf  'eeklf)
 ;; (defalias 'klfs 'eeklfs)
 ;; (defalias 'klt  'eeklt)
+;; (defalias 'klts 'eeklts)
 ;; (defalias 'kli  'ee-kl-insert)
 ;; (defalias 'kla2 'eekla2)