[elpa] externals/eev 7b787f0 1/4: New: (find-eepitch-intro "3.2. Test blocks as documentation")

[Stefan Monnier]

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

    New: (find-eepitch-intro "3.2. Test blocks as documentation")
---
 ChangeLog         |  14 ++++++
 VERSION           |   4 +-
 eepitch.el        |   2 +-
 eev-intro.el      | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 eev-on-windows.el |   7 +++
 eev-testblocks.el |  12 +++++
 eev-tlinks.el     |   9 ++--
 7 files changed, 173 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8513222..a831470 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2021-01-23  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-intro.el (find-eepitch-intro): new section: "3.2. Test
+       blocks as documentation".
+
+2021-01-13  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-intro.el (find-audiovideo-intro): rewrote the section "4.
+       Short hyperlinks to audio and video files".
+
+2021-01-11  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-testblocks.el (ee-insert-test-scheme-mode): new function.
+
 2021-01-02  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev.el: bumped the version. Changed the "Package-Requires" to
diff --git a/VERSION b/VERSION
index 46ff82b..3529abb 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sun Jan  3 12:42:47 GMT 2021
-Sun Jan  3 09:42:47 -03 2021
+Sun Jan 24 04:56:17 GMT 2021
+Sun Jan 24 01:56:17 -03 2021
diff --git a/eepitch.el b/eepitch.el
index 7dd1648..ef6006a 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -794,7 +794,7 @@ This is useful for for running processes that use pagers 
like
   "Send LINE to the vterm buffer and run the key binding for RET there."
   (eepitch-eval-at-target-window
     '(progn (vterm-send-string line)   ; "type" the line
-           (vterm-send-return))))  ; then do a RET
+           (vterm-send-return))))      ; then do a RET
 
 
 
diff --git a/eev-intro.el b/eev-intro.el
index ca30c71..fda81aa 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:    2021jan02
+;; Version:    2021jan23
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -5088,6 +5088,87 @@ the current major mode, or to implement it yourself.
 
 
 
+3.2. Test blocks as documentation
+---------------------------------
+I found that test blocks are a really good way to document my
+programs. Most people think that they look very alien at first,
+but they understand them immediately when they see a demo - so
+here are some demos. You need to have lua5.1 in your path to run
+them; they use eepitch-lua51, that calls lua5.1. So try this
+first:
+
+ (eepitch-lua51)
+ (eepitch-kill)
+ (eepitch-lua51)
+  print(\"Hello!\")
+  for k,v in pairs(os) do print(k, v) end
+  os.exit()
+
+If it works then try the demo below. Note that eepitch treats the
+lines with two red stars as comments; the sexps in \"\"-lines
+are hyperlinks, and the ones in \"\"-lines are not.
+
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+  rm -Rv /tmp/dednat6/
+  mkdir  /tmp/dednat6/
+  cd     /tmp/dednat6/
+  wget http://angg.twu.net/dednat6-minimal.zip
+  unzip dednat6-minimal.zip
+
+ (code-c-d \"dn6lua\" \"/tmp/dednat6/dednat6/\" :anchor)
+ (setenv \"LUA_INIT\" \"@/tmp/dednat6/dednat6/edrxlib.lua\")
+ (find-dn6lua \"edrxlib.lua\")
+ (find-dn6lua \"treetex.lua\" \"TreeNode-tests\" 3)
+ (find-dn6lua \"rect.lua\" \"dedtorect-tests\" 3)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 -=-=-=-=-
@@ -7401,23 +7482,45 @@ For more realistic examples, see:
 
 
 
+
 4. Short hyperlinks to audio and video files
 ============================================
 This sexp
 
-  (code-video \"eevtk2video\" \"~/eev-videos/three-keys-2.mp4\")
+  (code-video \"eev2020video\" \"~/eev-videos/emacsconf2020.mp4\")
+
+defines a function `find-eev2020video'. The function `code-video'
+is similar to the functions `code-c-d' and `code-pdf-page', that
+we saw in:
+
+  (find-eev-quick-intro \"9. Shorter hyperlinks\")
+  (find-pdf-like-intro \"7. Shorter hyperlinks to PDF files\")
+
+After running the `(code-video ...)' above, this sexp
+
+  (find-eev2020video \"8:20\" \"defines several functions\")
+
+becomes a shorthand for:
 
-defines a function `find-eevtk2video'. Note that the function
-definition in
+  (find-video \"~/eev-videos/emacsconf2020.mp4\" \"8:20\")
 
-  (find-code-video \"eevtk2video\" \"~/eev-videos/three-keys-2.mp4\")
+Note that the string \"defines several functions\" is treated as a
+comment, and is ignored - as in `find-pdf-page'.
 
-has this line:
+If we run the second sexp below instead of the first one,
 
-  (setq ee-audiovideo-last 'find-eevtk2video)
+       (code-video \"eev2020video\" \"~/eev-videos/emacsconf2020.mp4\")
+  (find-code-video \"eev2020video\" \"~/eev-videos/emacsconf2020.mp4\")
+
+we get a temporary buffer with the code that the
+sexp `(code-video ...)' would execute. Try it - and note that the
+definition of `find-eev2020video' in the temporary buffer
+contains a line like this:
+
+  (setq ee-audiovideo-last 'find-eev2020video)
+
+This line will be explained in the section 4.4.
 
-Every call to a function with a name like `find-*audio' or
-`find-*video' sets the variable `ee-audiovideo-last'.
 
 
 
@@ -8536,6 +8639,10 @@ functions that connect to Freenode (the IRC server where 
most
 discussion of free software projects happen), called
 `find-freenode', `find-freenode-2a' and `find-freenode-3a'.
 
+For a good explanation of what IRC is, see:
+
+  http://www.irchelp.org/faq/new2irc.html
+
 
 
 
@@ -9873,6 +9980,11 @@ deliberately ignoring the ones that I consider 
obsolete!):
     http://angg.twu.net/eev-videos/2020-find-here-links.mp4
     http://www.youtube.com/watch?v=8jtiBlaDor4
 
+  \"Short videos about workflows - and how to upload them\":
+    http://angg.twu.net/2021-ssr.html
+    http://angg.twu.net/eev-videos/2020-short-find-ssr-links-2.mp4
+    http://www.youtube.com/watch?v=_0_NLXTVhBk
+
 The ones that I prepared for the two EmacsConfs are very
 well-rehearsed, the other ones are not.
 
@@ -12593,6 +12705,16 @@ receive any number of arguments. See:
   (find-eval-intro \"10.1. Byte-compiled functions\")
   (find-elnode \"Defining Functions\" \"defun bar (a &optional b &rest c)\")
 
+Try:
+
+  (defun bar (a b &optional c d &rest e) (list a b c d e))
+        (bar 1 2 3 4 5 6)
+        (bar 1 2 3 4 5)
+        (bar 1 2 3 4)
+        (bar 1 2 3)
+        (bar 1 2)
+        (bar 1)
+
 
 
 
diff --git a/eev-on-windows.el b/eev-on-windows.el
index 913fe59..e3035fe 100644
--- a/eev-on-windows.el
+++ b/eev-on-windows.el
@@ -113,6 +113,13 @@
 
 
 
+;; TODO: Rewrite some of this using:
+;; (find-efunctiondescr 'parse-colon-path)
+;; (find-efunction      'parse-colon-path)
+;; (find-elnode "System Environment" "Variable: path-separator")
+;; (find-elnode "System Environment" "Function: parse-colon-path path")
+
+
 
 
 (provide 'eev-on-windows)
diff --git a/eev-testblocks.el b/eev-testblocks.el
index 8354d89..2dd6cb1 100644
--- a/eev-testblocks.el
+++ b/eev-testblocks.el
@@ -149,6 +149,18 @@ load \"%s\"
 =end
 " (buffer-name))))
 
+(defun ee-insert-test-scheme-mode ()
+  (interactive)
+  (insert (format "
+#!
+ (eepitch-guile)
+ (eepitch-kill)
+ (eepitch-guile)
+(load \"%s\")
+
+!#
+" (buffer-name))))
+
 (defun ee-insert-test-sh-mode ()
   (interactive)
   (insert (format "
diff --git a/eev-tlinks.el b/eev-tlinks.el
index 7f289b0..81608f8 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -1080,15 +1080,18 @@ cd {dir}
 ;;; |_|                   
 ;;
 ;; «find-psne-links» (to ".find-psne-links")
-;; (find-find-links-links "<none>" "psne" "url wget-options")
-;; A test: (find-psne-links "http://foo/bar";)
+;; Skel: (find-find-links-links-new "psne" "url wget-options" "")
+;; Test: (find-psne-links "http://foo/bar";)
+;;  See: (find-psne-intro "3. The new way: `M-x brep'")
+;;       (find-psne-intro "3. The new way: `M-x brep'" "find-psne-links")
 
 (defun find-psne-links (&optional url wget-options &rest pos-spec-list)
 "See: (find-psne-intro)"
   (interactive)
   (setq url (or url "{url}"))
   (setq wget-options (or wget-options "-nc"))
-  (apply 'find-elinks
+  (apply
+   'find-elinks
    `((find-psne-links ,url ,wget-options ,@pos-spec-list)
      (find-psne-links ,url "-c" ,@pos-spec-list)
      (find-psne-links ,url "" ,@pos-spec-list)