[elpa] externals/eev 0361b42 06/12: New file: eev-explain.el.

[Stefan Monnier]

branch: externals/eev
commit 0361b422bd7c27ab57602f1ad6e31171a7ac8342
Author: Eduardo Ochs <edrx@circe.birdland>
Commit: Eduardo Ochs <edrx@circe.birdland>

    New file: eev-explain.el.
---
 ChangeLog      |  30 ++++
 VERSION        |   4 +-
 eev-blinks.el  |   4 +-
 eev-elinks.el  |  19 ++-
 eev-eval.el    |  10 +-
 eev-explain.el | 250 ++++++++++++++++++++++++++++++
 eev-intro.el   | 468 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 eev-tlinks.el  |  14 +-
 8 files changed, 737 insertions(+), 62 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cc0e445..74f2c7b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,33 @@
+2019-08-10  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-three-main-keys-intro): new function.
+       (find-creating-links-intro): new function.
+
+2019-08-09  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-here-links-intro): new section: "1.1. Reading
+       and writing".
+
+2019-08-08  Eduardo Ochs  <address@hidden>
+
+       * eev-tlinks.el (find-git-links): small changes.
+
+2019-08-06  Eduardo Ochs  <address@hidden>
+
+       * eev-elinks.el (ee-efunctiondescr-re): added support for special
+       forms (e.g., condition-case).
+       (ee-shorten-file-name): new function.
+       (find-code-pdf-links): use `ee-shorten-file-name'.
+
+2019-08-05  Eduardo Ochs  <address@hidden>
+
+       * eev-eval.el (ee-backward-sexp, ee-forward-sexp): changed the
+       docstrings.
+
+2019-07-15  Eduardo Ochs  <address@hidden>
+
+       * eev-blinks.el (ee-goto-position): added support for `:end'.
+
 2019-07-14  Eduardo Ochs  <address@hidden>
 
        * eev-intro.el (find-eev-quick-intro): many changes.
diff --git a/VERSION b/VERSION
index 619ffb2..7e54d15 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Mon Jul 15 01:21:53 GMT 2019
-Sun Jul 14 22:21:53 -03 2019
+Sat Aug 10 03:21:49 GMT 2019
+Sat Aug 10 04:21:49 BST 2019
diff --git a/eev-blinks.el b/eev-blinks.el
index 506af2b..e45ad95 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -21,7 +21,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jun17
+;; Version:    2019aug10
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -145,6 +145,8 @@ they skip the first \"absolute\" pos-spec."
                        (goto-char (point-min))   ; (goto-char (point-min))
                        (search-forward pos-spec) ; (search-forward pos-spec)
                        (point))))                ;
+         ((eq pos-spec :end)
+          (goto-char (point-max)))
          (t (error "This is not a valid pos-spec: %S" pos-spec)))
     (if rest (ee-goto-rest rest))))
 
diff --git a/eev-elinks.el b/eev-elinks.el
index 1001cd5..16506f7 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jul12
+;; Version:    2019aug06
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -1112,6 +1112,9 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 ;;   (find-eevfile "eev-mode.el" "\\M-h\\M-h")
 ;; (define-key eev-mode-map "\M-h\M-h" 'find-here-links)
 
+;; TODO: support cases like these:
+;;   (find-efunctiondescr 'condition-case)
+
 ;; Some tools for detecting which kind of buffer we're in.
 (defun ee-buffer-re (re)
   (if (string-match re (buffer-name))
@@ -1146,7 +1149,8 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 (defun ee-pdftext-bufferp  () (ee-buffer-re "^pdftotext"))
 
 ;; By buffer name (when it is "*Help*")
-(defvar ee-efunctiondescr-re "^\\([^ \t\n]+\\) is a[^\t\n]*\\(function\\|Lisp 
macro\\)")
+(defvar ee-efunctiondescr-re
+  "^\\([^ \t\n]+\\) is a[^\t\n]*\\(function\\|Lisp macro\\|special form\\)")
 (defun  ee-efunctiondescr-bufferp () (ee-buffer-help ee-efunctiondescr-re 1))
 (defun  ee-find-efunctiondescr-links ()
   (let ((f (ee-efunctiondescr-bufferp)))
@@ -1321,18 +1325,23 @@ See: (find-here-links-intro \"5. `find-here-links-1'\")"
 ;; (find-code-pdf-links 
"/usr/local/texlive/2018/texmf-dist/doc/latex/base/source2e.pdf")
 ;; (find-code-pdf-links 
"/usr/local/texlive/2018/texmf-dist/doc/latex/base/source2e.pdf" "foo")
 
+;; See: (find-efunction 'ee-if-prefixp)
+(defun ee-shorten-file-name (fname)
+  "Shorten FNAME if possible to make it start with \"$S/\" or \"~/\"."
+  (or (ee-if-prefixp "$S/" "$S/" fname 'fname+)
+      (ee-if-prefixp "~/"  "~/"  fname 'fname+)
+      fname))
+
 (defun find-code-pdf-links (&optional fname c &rest pos-spec-list)
 "Visit a temporary buffer containing hyperlinks and `code-pdf-*'s to a PDF 
file."
   (interactive (list (and (eq major-mode 'dired-mode) (ee-dired-to-fname))))
+  (if fname (setq fname (ee-shorten-file-name fname)))
   (setq fname (or fname "{fname}"))
   (setq c (or c "{c}"))
   (let ((dir (file-name-directory fname)))
     (apply 'find-elinks-elisp
      `((find-code-pdf-links ,fname ,c ,@pos-spec-list)
        ;; Convention: the first sexp always regenerates the buffer.
-       ;; Shortened versions of the first sexp:
-       ,(ee-if-prefixp "~/"  "~/"  fname '`(find-code-pdf-links ,fname+ ,c))
-       ,(ee-if-prefixp "$S/" "$S/" fname '`(find-code-pdf-links ,fname+ ,c))
        ;;
        ;; (find-efunction 'find-code-pdf-links)
        ,(ee-template0 "\
diff --git a/eev-eval.el b/eev-eval.el
index ccadbcf..d26a1a6 100644
--- a/eev-eval.el
+++ b/eev-eval.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jun16
+;; Version:    2019aug05
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-eval.el>
@@ -40,7 +40,7 @@
 ;;   (find-eev-quick-intro "2. Evaluating Lisp" "When you type `M-e'")
 ;;   (find-eev-quick-intro "2. Evaluating Lisp" "numeric prefixes")
 ;;   (find-eev-quick-intro "2. Evaluating Lisp" "`M-0 M-e'")
-;; Note that `M-2 M-e' and `M-2 M-e' only make sense when the sexp is
+;; Note that `M-2 M-e' and `M-3 M-e' only make sense when the sexp is
 ;; a hyperlink.
 
 
@@ -61,7 +61,8 @@
 
 ;; See (find-efunction 'eval-last-sexp-1)
 (defun ee-backward-sexp ()
-  "An internal function used by `ee-eval-last-sexp'."
+  "Like `(forward-sexp -1)' but always uses elisp syntax.
+This is an internal function used by `ee-eval-last-sexp'."
   (interactive)
   (with-syntax-table emacs-lisp-mode-syntax-table
     (forward-sexp -1)
@@ -72,7 +73,8 @@
   (point))
 
 (defun ee-forward-sexp ()
-  "An internal function used by `ee-eval-last-sexp'."
+  "Like `(forward-sexp 1)' but always uses elisp syntax.
+This is an internal function used by `ee-eval-last-sexp'."
   (interactive)
   (with-syntax-table emacs-lisp-mode-syntax-table
     (forward-sexp 1))
diff --git a/eev-explain.el b/eev-explain.el
new file mode 100644
index 0000000..fac2854
--- /dev/null
+++ b/eev-explain.el
@@ -0,0 +1,250 @@
+;;; eev-explain.el -- explain an eev sexp.
+;; Explain some difficult sexps, like eejump-nnn and code-xxx.
+;; This is an experimental feature - I am using it in tutorials and
+;; videos.
+
+;; Copyright (C) 2019 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 <address@hidden>
+;; Maintainer: Eduardo Ochs <address@hidden>
+;; Version:    2019aug06
+;; Keywords:   e-scripts
+;;
+;; Latest version: <http://angg.twu.net/eev-current/eev-explain.el>
+;;       htmlized: <http://angg.twu.net/eev-current/eev-explain.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)
+
+;;; Commentary:
+
+;; (load "eev-explain.el")
+
+;; This is very new. Everything is going to change.
+;;
+;; Terminology: a "bet" is a triple of the form (begin end text); the
+;; global variable `ee-bets' holds a list of bets.
+;;
+;; The tests below show some of the things we do with ee-bets:
+;;
+;;   (defun eejump-100 () (set-frame-font "nil2"))
+;;   (progn (eek "  <up> C-e")      (ee-bets-set))
+;;   (progn (eek "2*<up> C-e") (cdr (ee-bets-set)))
+;;   ee-bets
+;;   (ee-bets-text 0)
+;;   (ee-bets-text 1)
+;;   (ee-bets-text 2)
+;;   (ee-bets-flash 0)
+;;   (ee-bets-flash 2)
+;;   (ee-bets-flash 2 7 0)
+;;   (ee-bets-flash 2 7 0 nil 'eepitch-star-face)
+;;   (ee-bets-flash 3)
+;;   (ee-bets-flash 4)
+;;
+;; (ee-explain-eejump)
+;; (eev-explain)
+
+
+
+;;;  _          _       
+;;; | |__   ___| |_ ___ 
+;;; | '_ \ / _ \ __/ __|
+;;; | |_) |  __/ |_\__ \
+;;; |_.__/ \___|\__|___/
+;;;                     
+
+(defun ee-forward-sexp1 ()
+  "Like `ee-forward-sexp' but returns point on success and nil on error."
+  (interactive)
+  (condition-case nil
+      (progn (ee-forward-sexp) (point))
+    (error nil)))
+
+(defun ee-forward-sexp3 ()
+  "Like `ee-forward-sexp1' but returns (pos1 pos2 text), or nil on error."
+  (interactive)
+  (looking-at "[ \t\n]*\\(;[^\n]*\n[ \t\n]*\\)*")
+  (goto-char (match-end 0))            ; skip whitespace and comments
+  (let ((pos1 (point)))
+    (if (ee-forward-sexp1)
+       (let* ((pos2 (point))
+              (text (buffer-substring-no-properties pos1 pos2)))
+           (list pos1 pos2 text)))))
+
+(defun ee-forward-sexp3s ()
+  "Like `ee-forward-sexp3' but returns a list of triples like (begin end 
text)."
+  (interactive)
+  (let ((bets ()))
+    (catch 'no-more-sexps
+      (while t
+       (let ((bet (ee-forward-sexp3)))
+         (if bet
+             (setq bets (cons bet bets))
+           (throw 'no-more-sexps nil)))))
+    (reverse bets)))
+
+(defun ee-subsexps-before-point ()
+  (save-excursion
+    (ee-backward-sexp)
+    (let ((whole-sexp (save-excursion (ee-forward-sexp3))))
+      (when (eq (following-char) (aref "(" 0))
+       (forward-char 1)
+       (cons whole-sexp (ee-forward-sexp3s))))))
+
+(defvar ee-bets ()
+  "A list of triples of the form (begin end text) corresponding
+to the subsexps of the sexp before point.")
+
+(defun ee-bets-set ()
+  (interactive)
+  (setq ee-bets (ee-subsexps-before-point)))
+
+(defun ee-bets-begin (n) (nth 0 (nth n ee-bets)))
+(defun ee-bets-end   (n) (nth 1 (nth n ee-bets)))
+(defun ee-bets-text  (n) (nth 2 (nth n ee-bets)))
+
+
+;;;   __ _           _     
+;;;  / _| | __ _ ___| |__  
+;;; | |_| |/ _` / __| '_ \ 
+;;; |  _| | (_| \__ \ | | |
+;;; |_| |_|\__,_|___/_| |_|
+;;;                        
+;; (find-es "emacs" "set-string-face")
+;; (find-angg ".emacs" "find-epalette")
+;; (find-efaces)
+;; (find-ecolors)
+
+(defun ee-set-string-property (str property-name value)
+  (put-text-property 0 (length str) property-name value str)
+  str)
+
+(defun ee-set-string-face (str &optional face)
+  (ee-set-string-property str 'face face))
+
+(defun ee-set-string-fg (str &optional fg)
+  (ee-set-string-face str (cons 'foreground-color fg)))
+
+(defun ee-bets-flash (n &optional b-adj e-adj spec face)
+  (let* ((b (+ (or b-adj 0) (nth 0 (nth n ee-bets))))
+         (e (+ (or e-adj 0) (nth 1 (nth n ee-bets))))
+        (text (buffer-substring-no-properties b e))
+        )
+    (eeflash+ b e (or spec ee-highlight-spec))
+    (if face (ee-set-string-face text face))
+    text))
+
+;; The `ee-explain' functions.
+;; They work on the current value of the variable `ee-bets'.
+;; Tests:
+;;
+;;   (defun eejump-100 () (set-frame-font "nil2"))
+;;   (progn (eek "<up> C-e") (cdr (ee-bets-set)))
+;;
+;;   (find-2a nil '(find-estring (ee-explain-eejump)))
+;;
+;;   (code-c-d "ud" "/usr/share/doc/")
+;;   (progn (eek "<up> C-e") (cdr (ee-bets-set)))
+;;
+;;   (find-2a nil '(find-estring (ee-explain-code-c-d)))
+;; (buffer-substring 1 10)
+
+
+(defun ee-explain-eejump ()
+  (when (and (equal "defun" (ee-bets-text 1))
+          (string-match "^eejump-" (ee-bets-text 2)))
+    (ee-bets-flash 2 7 0)
+    (ee-bets-flash 4)
+    (format "The sexp %s
+Makes `M-%sj' execute this one-liner:  %s
+See: (find-eev-quick-intro \"7.1. `eejump'\")"
+           (ee-bets-text 0)
+           (substring (ee-bets-text 2) 7)
+           (ee-bets-text 4))))
+
+(defun ee-explain-code-c-d ()
+  (when (equal "code-c-d" (ee-bets-text 1))
+    (ee-bets-flash 2 1 -1)
+    (ee-bets-flash 3 1 -1)
+    (let* ((c (substring (ee-bets-text 2) 1 -1))
+          (d (substring (ee-bets-text 3) 1 -1))
+          (cpos (- (ee-bets-begin 2) (ee-bets-begin 0)))
+          (dpos (- (ee-bets-begin 3) (ee-bets-begin 0)))
+          )
+      (format "The sexp %s
+  makes:      (find-%sfile             \"FNAME\")
+ act as:    (find-fline \"%sFNAME\")
+
+See: (find-eev-quick-intro \"9.1. `code-c-d'\")"
+             (ee-bets-text 0)
+             c
+             d))))
+
+(defun ee-explain-code-c-d ()
+  (when (equal "code-c-d" (ee-bets-text 1))
+    (let* ((c (ee-bets-flash 2 1 -1 nil 'eepitch-star-face))
+          (d (ee-bets-flash 3 1 -1))
+          )
+      (format "The sexp %s
+  makes:      (find-%sfile             \"FNAME\")
+ act as:    (find-fline \"%sFNAME\")
+
+See: (find-eev-quick-intro \"9.1. `code-c-d'\")"
+             (ee-bets-text 0)
+             c
+             d))))
+
+;; (substring "abcdef" 1 -1)
+;; (substring "abcdef" 1 nil)
+;; (substring "abcdef" nil nil)
+;; (substring "abcdef" 0 -1)
+
+
+(defun eev-explain ()
+  (interactive)
+  (let ((ee-buffer-name "*eev-explain*")
+       (str (or (ee-explain-eejump)
+                (ee-explain-code-c-d)
+                (ee-explain-code-pdf-page)
+                )
+            ))
+    (if str
+       (find-2a nil '(find-estring str)))))
+
+;; (defun eejump-100 () (set-frame-font "nil2"))
+;; (progn (eek "<up> C-e") (ee-bets-set))
+;; ee-bets
+;;
+;; (ee-explain-eejump)
+;; (eev-explain)
+
+
+
+
+
+(provide 'eev-explain)
+
+
+
+
+
+
+;; Local Variables:
+;; coding:            utf-8-unix
+;; no-byte-compile:   t
+;; End:
diff --git a/eev-intro.el b/eev-intro.el
index be9f171..65f300b 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jul14
+;; Version:    2019aug10
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -91,6 +91,11 @@
 ;; «.find-org-intro»           (to "find-org-intro")
 ;; «.find-escripts-intro»      (to "find-escripts-intro")
 
+;; Videos:
+;; «.find-three-main-keys-intro»       (to "find-three-main-keys-intro")
+;; «.find-creating-links-intro»                (to "find-creating-links-intro")
+
+
 ;; See: (find-anchors-intro)
 
 
@@ -875,6 +880,29 @@ echo ...and bye >> /tmp/o
 print(open(\"/tmp/o\").read())
 
 
+  It is possible to display all the targets at the same time,
+  using advanced features that are explained here:
+
+    (find-multiwindow-intro \"find-3EE\")
+
+  Here is a demo:
+
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (eepitch-shell)
+echo Hello... > /tmp/o
+
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+
+ (eepitch-shell)
+echo ...and bye >> /tmp/o
+
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+
+
+
+
 
 
 6.3. Creating eepitch blocks: `M-T'
@@ -1658,48 +1686,10 @@ We will only discuss here the other way.
 
 11.1. `find-pdf-links'
 ----------------------
-Let's call a pair of lines like this,
-
-  (code-pdf-page \"asy\" 
\"/usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf\")
-  (code-pdf-text \"asy\" 
\"/usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf\")
-
-in which we have a call to `code-pdf-page' and a call to
-`code-pdf-text', both pointing to the same PDF file, a \"code-pdf
-pair\". One quick way to generate a code-pdf pair is to visit the
-directory where your PDF file is, put the point on the line of
-the PDF, and type `M-h M-p' (`find-pdf-links'). Try it here:
-
-  (find-fline \"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
-
-The exact action of `M-h M-p' depends on the major mode. If
-you're in dired mode then it supposes that you want links to the
-current directory and to the PDF on the current line - including
-a `code-c-d' and a code-pdf pair - and it runs
-`find-code-pdf-links'. The first line of the buffer will be
-something like:
-
-  ;; (find-code-pdf-links 
\"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf\" \"{c}\")
-
-where the \"{c}\" is something that you have to adjust by hand
-and then execute the first line again to regenerate the buffer -
-like in `find-latex-links', that was described in section 7.5.
-
-If you're not it dired mode then `find-pdf-links' supposes that
-you're in a buffer generated by a short hyperlink to the text of
-a PDF file, and it runs the function `find-pdflike-page-links'.
-Try `M-h M-p' in the buffer generated by the sexp below:
-
-  (find-livesofanimalstext (+ -110 134))
-
-`find-pdflike-page-links' is not very smart. It has to guess the
-stem (\"livesofanimals\"), the offset (-110), the current page,
-and the string that you want to use in the pos-spec. It takes the
-stem and the offset from the global variables `ee-page-c' and
-`ee-page-offset', that probably were set by the last call to a
-function of the form `find-___text', and it guesses the current
-page by counting formfeeds, and guesses that the pos-spec string
-is in the top of the kill ring.
+This section was moved to:
 
+  (find-pdf-like-intro \"8. `find-pdf'-pairs\")
+  (find-pdf-like-intro \"9. Generating three pairs\")
 
 
 
@@ -2411,6 +2401,7 @@ For the full lists of keybindings, see:
 \(Re)generate: (find-here-links-intro)
 Source code:  (find-efunction 'find-here-links-intro)
 More intros:  (find-eev-quick-intro)
+              (find-eev-intro)
               (find-refining-intro)
 This buffer is _temporary_ and _editable_.
 It is meant as both a tutorial and a sandbox.
@@ -2423,6 +2414,14 @@ at some point...
 
 
 
+Eev's central idea is that you can keep \"executable logs\" of
+what you do, in a format that is reasonably readable and that is
+easy to \"play back\" later, step by step and in any order. We
+call these executable logs, or executable notes, \"e-scripts\".
+
+
+
+
 1. Alternating between \"task\" and \"notes\"
 =========================================
 In the old days log books were always made of paper, and there
@@ -2446,6 +2445,59 @@ and having some practice.
 
 
 
+1.1. Reading and writing
+------------------------
+Learning eev is like learning to read and write. We first learn
+_how to read_, and we learn _how to write_ in a second stage,
+when we have read a lot and we are able to read what we write.
+
+Learning eev is also like learning to use paper notebooks. It is
+much easier to understand the notes and ideas what we wrote
+ourselves in our notebooks than to understand what other people
+wrote in their notebooks... when we go back to what _we_ wrote we
+are able to reconnect with what we were thinking, even when our
+notes are quite terse because we did not write down all details -
+and we can't do that with other people's notes.
+
+So: we have to first learn how to _read_ executable notes in
+order to be able to _write_ our own executable notes, but after
+learning the basics we will usually find it much easier to read
+our own executable notes than to read other people's notes...
+
+This is very similar to what happens in programming. Programmers
+usually takes years, and a lot of effort, to learn to write code
+and comments that other people find readable, and what they do
+after that is not that they write super-readable code all the
+time - instead they _adjust_ the level of readability of their
+code depending on the situation: they write the code that will be
+used and read by other people in a cleaner, more readable style
+with lots of comments, and they write \"throwaway code\" that
+they will only run once in a very terse, and often messy, style.
+
+Most of my executable notes are written - or rather, \"appear\" -
+when I am learning something and I am switching rather mindlessly
+between \"task\" and \"notes\" as I explained in the previous
+section. What I write looks like throwaway code, only worse -
+because I usually leave lots of unfinished parts intermixed with
+the parts that run, without marking clearly which are which...
+but when I go through my notes about a task again I usually clean
+my notes a bit. For me going through my executable notes about a
+task again always involves a bit of _rewriting_ - which is
+something that programmers often do with their own code, but that
+we don't do much with paper notebooks.
+
+Anyway: be prepared to create executable notes that are almost
+unreadable, even by you when you go back to them a few hours
+later - that's normal, that's how things are, and you can, and
+WILL, rewrite the most useful parts...
+
+Note that this \"intro\" is about writing elisp hyperlinks. The
+tricks for writing eepitch blocks and index-anchor pairs are
+discussed elsewhere.
+
+
+
+
 
 2. \"Here\"
 =========
@@ -5677,6 +5729,8 @@ they will define the functions `find-livesofanimalspage' 
and
   (find-livesofanimalstext (+ -110 127) \"wrong thoughts\")
   (find-livesofanimalspage (+ -110 132) \"into the place of their victims\")
   (find-livesofanimalstext (+ -110 132) \"into the place of their victims\")
+  (find-livesofanimalspage (+ -110 133) \"To write that book I had to think\")
+  (find-livesofanimalstext (+ -110 133) \"To write that book I had to think\")
   (find-livesofanimalspage (+ -110 134) \"woke up haggard in the mornings\")
   (find-livesofanimalstext (+ -110 134) \"woke up haggard in the mornings\")
   (find-livesofanimalspage (+ -110 143) \"Babies have no self-consciousness\")
@@ -5849,7 +5903,10 @@ that page of the book!
 
 12. Another way to generate `code-pdf'-pairs
 ============================================
-\[Explain M-P]
+\[Explain M-P. Example:]
+
+  (eek \"<down> M-P  ;; eewrap-pdflike\")
+  livesofanimals ~/Coetzee99.pdf
 
 " rest)))
 
@@ -9026,6 +9083,12 @@ The quickest way to open or recreate this is with `M-6 
M-j'.
 
 
 
+This intro will be merged with
+  (find-here-links-intro)
+at some point...
+
+
+
 Eev's central idea is that you can keep \"executable logs\" of
 what you do, in a format that is reasonably readable and that is
 easy to \"play back\" later, step by step and in any order. We
@@ -9701,6 +9764,325 @@ This can also be used to generate links to info nodes.
 
 
 
+
+
+;; «find-three-main-keys-intro»  (to ".find-three-main-keys-intro")
+;; (find-intro-links "three-main-keys")
+;; (find-three-main-keys-intro)
+
+;; Used in this video:
+;; http://angg.twu.net/index.html#eev-three-main-keys
+;; A version in English in coming soon!
+
+(defun find-three-main-keys-intro (&rest pos-spec-list) (interactive)
+  (let ((ee-buffer-name "*(find-three-main-keys-intro)*"))
+    (apply 'find-eintro "\
+
+
+
+  The three basic keys of eev:
+  A mini tutorial
+    Eduardo Ochs
+    http://angg.twu.net/#eev
+    (Version: 2019aug09)
+
+  Eev's central idea is that you can keep \"executable logs\" of
+  what you do, in a format that is reasonably readable and that is
+  easy to \"play back\" later, step by step and in any order.
+
+  The is the second of the mini-tutorials.
+  The first one was on a way to install eev \"for total beginners\"
+  that creates a script called ~/eev that starts Emacs with eev-mode on
+  and opens the main sandboxed tutorial of eev:
+
+    (find-eev-quick-intro)
+
+  The `(find-*-intro)'s are interactive tutorials.
+  The mini-tutorials are videos.
+  This mini-tutorial is about the basic ideas that you need to understand
+  to run the interactive tutorials.
+                                       ^
+                                       |
+                                  three keys!
+
+
+
+  In Emacs terminology `C-e' is `control-e',
+                   and `M-e' is `alt-e'.
+          We pronounce `M-e' as `meta-e'.
+  Some old keyboards had a \"meta key\".
+  See: https://en.wikipedia.org/wiki/Meta_key
+
+  Some keys in Emacs recognize numeric prefixes.
+  For example, `M-4 M-2 a' inserts 42 `a's.
+
+  Lisp is a programming language that uses:
+    1. lots of lists
+    2. lots of parentheses - they delimit the lists
+    3. no \",\"s between the elements of these lists
+    4. the name of a function at the beginning of the list,
+       the arguments for the function after that.
+
+  These lists without commas are called \"sexps\".
+  See: https://en.wikipedia.org/wiki/Sexp
+
+  These sexp are Lisp expressions (programs!):
+
+       (* 2 3)
+               (* 4 5)
+    (+ (* 2 3) (* 4 5))
+
+  they return these results:
+
+       (* 2 3)            --> 6
+               (* 4 5)    --> 20
+    (+ (* 2 3) (* 4 5))   --> 26
+
+  This is a sexp with \"side effects\":
+
+    (insert \"HELLO\")
+
+
+  SPOILER: The basic keys of eev are:
+
+  M-e   - to follow an elisp hyperlink. (Elisp = Emacs Lisp)
+          Mnemonic: \"(e)valuate\"/\"(e)xecute\".
+  M-k   - to go back.  Mnemonic: \"(k)ill buffer\".
+  M-j   - to (j)ump to certain predefined places. For example:
+
+       M-2 M-j  runs:  (find-emacs-keys-intro)
+       M-5 M-j  runs:  (find-eev-quick-intro)
+           M-j  takes you to the list of jump targets.
+
+  You just need to learn `M-e', `M-k' and `M-j' keys to navigate:
+    1. the sandboxed tutorials for eev,
+    2. the list of all most important keys,
+    3. and the Emacs manuals!
+
+  This mini-tutorial is BASED on these parts of the main tutorial:
+    (find-eev-quick-intro)
+    (find-eev-quick-intro \"2. Evaluating Lisp\")
+    (find-eev-quick-intro \"3. Elisp hyperlinks\")
+    (find-eev-quick-intro \"7.1. `eejump'\")
+    (find-eev-quick-intro \"7.1. `eejump'\" \"numeric arguments\")
+
+
+
+
+
+2. Evaluating Lisp
+==================
+When you type `M-e' emacs moves the point to the end of the
+current line, then runs a variant of `C-x C-e'. Try this on each
+line of the block below:
+
+  (+ (* 2 3)
+     (* 4 5)
+     )
+
+`M-e' accepts several different numeric prefixes that alter its
+behavior. We are only interested in one of them now - `M-0 M-e'
+highlights the sexp for a fraction of a second insted of executing it.
+Try it above.
+
+Also:
+
+  (insert \"HELLO\")
+
+\[In this video we will also use `M-3 M-e' to open a hyperlink in
+the right window.]
+
+
+
+
+3. Elisp hyperlinks
+===================
+Each one of the sexps below makes Emacs \"go somewhere\" if you execute
+it with `M-e'. Executing sexps like those - we will call them \"elisp
+hyperlinks\" - is like following a hyperlink in a browser.
+
+In a browser you can \"go back\" after following a hyperlink because the
+previous page is kept in the memory somehow. In Emacs+eev the easiest
+way to \"go back\" is with `M-k', which runs a function called
+`ee-kill-this-buffer'. If you follow one of the links below with
+`M-e', it creates a new buffer and displays it. If you then type `M-k'
+this new buffer is killed, and Emacs displays the buffer that was just
+below it, which is this tutorial... try it! Here are some nice elisp
+hyperlinks:
+
+  (find-file  \"~/eev-current/eev-flash.el\")
+  (find-fline \"~/eev-current/eev-flash.el\")
+  (find-fline \"~/eev-current/\")
+  (find-fline \"/tmp/\")
+  (find-efunctiondescr 'find-file)
+  (find-man \"date\")
+  (find-man \"sleep\")
+  (find-sh  \"date; sleep 1; date\")
+  (find-node \"(emacs)Lisp Eval\")
+  (find-enode       \"Lisp Eval\")
+  (find-efunction 'find-file)
+
+Not all elisp hyperlinks \"go somewhere\"; some are like buttons that
+perform an action, like the one below, that acts as if the user had
+pressed a series of keys,
+
+  (eek \"<down> C-a H E L L O ! <up> C-e\")
+
+and some display their output in the echo area:
+
+  (find-sh0 \"date\")
+
+
+Note: `find-fline' is a contraction of `find-file-line'...
+`find-fline' is better for hyperlinks than `find-file' for
+reasons explained in other tutorials:
+
+  (find-links-conv-intro \"4. Elisp hyperlinks: some conventions\")
+  (find-links-conv-intro \"messy\")
+  (find-refining-intro \"2. Refining hyperlinks\")
+
+
+
+
+7.1. `eejump'
+-------------
+Some key sequences in Emacs accept numeric arguments. For
+example, try typing `M-9 a' (not `M-9 M-a'!) - this will insert 9
+copies of the letter `a'. See:
+
+  (find-enode \"Arguments\")
+
+Eev binds the key `M-j' (`eejump') to a function that jumps to a
+place that depends on the numeric argument. For example, `M-5
+M-j' runs (find-eev-quick-intro), that reloads this intro and
+goes to the top of it, and
+
+  `M-2 M-j' runs: (find-emacs-keys-intro)
+  `M-6 M-j' runs: (find-escripts-intro)
+  `M-1 M-j' runs: (find-fline \"~/TODO\")
+
+
+
+7.2. The list of eejump targets
+-------------------------------
+If you type `M-j' without a prefix argument then it runs
+`(find-eejumps)', that displays a help text followed by all the
+current eejump targets as defuns, one in each line. Try it:
+
+  (eek \"M-j\")
+  (find-eejumps)
+
+You will see that two of those entries are:
+
+  (defun eejump-1 () (find-fline \"~/TODO\"))
+  (defun eejump-5 () (find-eev-quick-intro))
+
+The help text starts with:
+
+  ;; (find-eejumps)
+  ;; See: (find-eev-quick-intro \"7.1. `eejump'\")
+  ;;      (find-emacs-keys-intro \"1. Basic keys (eev)\")
+  ;; For example,
+  ;;     M-1 M-j  runs:  (find-fline \"~/TODO\")
+  ;;     M-2 M-j  runs:  (find-emacs-keys-intro)
+  ;;     M-5 M-j  runs:  (find-eev-quick-intro)
+  ;; Current eejump targets:
+
+So if your mind goes blank and you forget everything except for
+`M-j' and `M-e' you can just type `M-j' and follow one of the
+elisp hyperlinks in the help text.
+
+
+
+
+What are the next steps?
+========================
+Next steps:
+
+  1) Learn e-script blocks:
+
+      (find-eev-quick-intro \"6.1. The main key: <F8>\")
+      (find-eev-quick-intro \"6.2. Other targets\" \"display all\")
+
+  2) Learn how to use index-anchor pairs:
+
+      (find-eev-quick-intro \"8.1. Introduction: `to'\")
+
+  3) Learn how to write your executable notes and put them here:
+
+      `M-1 M-j' runs: (find-fline \"~/TODO\")
+
+Etc, etc, etc...
+Note that learning to read comes after learning to write!...
+See: 
+
+  (find-here-links-intro \"1.1. Reading and writing\")
+
+
+
+
+" pos-spec-list)))
+
+;; (find-three-main-keys-intro)
+
+
+
+
+
+
+;; «find-creating-links-intro»  (to ".find-creating-links-intro")
+;; (find-intro-links "creating-links")
+
+(defun find-creating-links-intro (&rest pos-spec-list) (interactive)
+  (let ((ee-buffer-name "*(find-creating-links-intro)*"))
+    (apply 'find-eintro "\
+
+
+  Some quick ways to generate
+  elisp hyperlinks in eev -
+  A mini tutorial
+    Eduardo Ochs
+    http://angg.twu.net/#eev
+    (Version: 2019jun17)
+
+
+
+  From other tutorials:
+    (find-escripts-intro \"5. Tools for writing e-scripts\")
+    (find-emacs-keys-intro \"beginner's way\")
+    (find-here-links-intro)
+    (find-here-links-intro \"4. `find-here-links-3'\")
+    (find-here-links-intro \"5. `find-here-links-1'\")
+    (find-here-links-intro \"6. Copying the hyperlink\" \"M-h M-w\")
+
+
+
+1. Basic keys (eev)
+===================
+(...)
+
+The beginner's way of creating \"hyperlinks to here\" is with:
+  M-h M-3   - (find-here-links-intro \"4. `find-here-links-3'\")
+  M-h M-1   - (find-here-links-intro \"5. `find-here-links-1'\")
+  M-h M-w   - (find-here-links-intro \"6. Copying the hyperlink\" \"M-h M-w\")
+
+
+
+
+" pos-spec-list)))
+
+;; (find-creating-links-intro)
+
+
+
+
+
+
+;; (find-intro-links "creating-links")
+
+
+
+
 (provide 'eev-intro)
 
 
diff --git a/eev-tlinks.el b/eev-tlinks.el
index b900c72..1fbff23 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jun21
+;; Version:    2019aug08
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-tlinks.el>
@@ -1068,18 +1068,18 @@ cd      {ee-git-dir}
 git clone {url}
 cd      {dir}
 
-# git pull --depth 1
-# git pull
-# git reset
-# git clean -dfx
-# git reset --hard
-
 # (find-fline \"{ee-git-dir}\")
 # (find-fline \"{dir}\")
 # (find-gitk  \"{dir}\")
 
 # (code-c-d \"{c}\" \"{dir}\")
 # (find-{c}file \"\")
+
+# git pull --depth 1
+# git pull
+# git reset
+# git clean -dfx
+# git reset --hard
 ")
      )
    pos-spec-list)))