branch: externals/eev
commit 43c5f82ad9b4fe47de3ea363fd1a0d28e18a8ddf
Author: Eduardo Ochs <eduardoo...@gmail.com>
Commit: Eduardo Ochs <eduardoo...@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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@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)
