[elpa] externals/eev 5496a57 09/20: Added the file `README.org'.

[Stefan Monnier]

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

    Added the file `README.org'.
---
 ChangeLog         |   6 ++
 README.org        | 100 ++++++++++++++++++++++++++
 VERSION           |   4 +-
 eev-audiovideo.el | 211 ++++++++++++++++++++++++++++--------------------------
 eev-intro.el      |  39 +++++++++-
 5 files changed, 255 insertions(+), 105 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9b45e65..30be12b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2020-12-17  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * README.org: new file.
+
+       * eev-intro.el (find-little-languages-intro): new function.
+
 2020-12-16  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev-elinks.el (find-esetkey-links): new function.
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..1be952b
--- /dev/null
+++ b/README.org
@@ -0,0 +1,100 @@
+# (find-eev "README.org")
+# (defun c () (interactive) (eek "C-c C-e h h"))
+# (defun v () (interactive) (brg "~/eev-current/README.html"))
+# (defun e () (interactive) (find-eev "README.org"))
+# (defun m () (interactive) (find-eev "README.md"))
+# (defun cv () (interactive) (c) (v))
+# (find-angg "edrxrepl/README.org")
+# (find-orgsrcfile "README")
+# (find-es "org" "git")
+
+# (find-orgnode "Table of Contents")
+#+OPTIONS: toc:nil
+
+* Introduction
+
+I used to call eev a "tool for automating almost everything" and "my
+project to save the world with Free Software". In more concrete terms,
+eev is a library for Emacs that lets us create 
[[http://angg.twu.net/eev-intros/find-here-links-intro.html#1][executable 
logs]] of
+what we do in a format that is reasonably easy to read and to modify,
+and that lets us "play back" those logs step by step in any order.
+
+The best introductions to eev are:
+
+- "[[http://angg.twu.net/emacsconf2019.html][How to record executable notes 
with eev - and how to play them
+  back]]": my talk at the EmacsConf 2019. Executable notes are mostly
+  made of [[http://angg.twu.net/eev-intros/find-eev-quick-intro.html#3][sexp 
hyperlinks]] and 
[[http://angg.twu.net/eev-intros/find-eev-quick-intro.html#6][eepitch blocks]]. 
This talk has a quick
+  explanation of sexp hyperlinks at 
[[http://angg.twu.net/LATEX/2019emacsconf.pdf#page=5][slides 5 and 6]], a 
mention in [[http://angg.twu.net/LATEX/2019emacsconf.pdf#page=8][slide
+  8]] of my 20+ years of executable notes in [[http://angg.twu.net/e/]], and
+  a very nice demo of playing back non-trivial executable notes in the
+  video starting at 
[[http://www.youtube.com/watch?v=86yiRG8YJD0#t=13m10s][13:10]]; the demo of 
eepitch starts at 
[[http://www.youtube.com/watch?v=86yiRG8YJD0#t=15m11s][15:11]],
+
+- "[[http://angg.twu.net/emacsconf2020.html][On why most of the best features 
in eev look like 5-minute hacks]]":
+  my talk at the EmacsConf 2020. It is mostly about design decisions,
+  but at [[http://www.youtube.com/watch?v=hOAqBc42Gg8#t=21m02s][21:02]] it 
shows how I use M-j to teach Emacs and eev to total
+  beginners, and at 
[[https://www.youtube.com/watch?v=hOAqBc42Gg8#t=18m47s][18:47]] it explains the 
design decisions behind M-j.
+
+- its [[http://angg.twu.net/eev-intros/find-eev-intro.html][sandboxed 
tutorials]],
+
+- its homepage: [[http://angg.twu.net/#eev]] .
+
+# (find-eev-quick-intro "3. Elisp hyperlinks")
+# (find-eev-quick-intro "6. Controlling shell-like programs")
+# (find-eev2019video "13:10" "Demo: patching xpdf")
+# (find-eev2019video "15:11" "Demo: the eepitch block (in red star lines)")
+# (find-eev2020video "18:47" "M-j - design decisions")
+# (find-eev2020video "21:02" "M-j itself")
+# (ecop 8 "prehistory-7" "several megabytes")
+# (eco    "prehistory-7" "several megabytes")
+
+# (ecop 10 "prehistory-9" "users should not be forced to see Lisp")
+# (eco     "prehistory-9" "users should not be forced to see Lisp")
+
+I've been using eev quite successfully to teach Emacs to total
+beginners - with an approach that is the exact opposite of 
"[[http://angg.twu.net/LATEX/2019emacsconf.pdf#page=10][users
+should not be forced to see Lisp]]".
+
+* Trying it
+
+The recommended way to try eev it to install it with M-x list-packages
+and then run M-x eev-beginner; this will load all the modules of eev,
+turn eev-mode on, and open the 
[[http://angg.twu.net/eev-intros/find-eev-quick-intro.html][main tutorial]]. I 
tried to make eev as
+friendly as possible both to:
+
+- beginners, who at first know only the most obvious keybindings, like
+  the arrow keys, and no Lisp at all -- there is even a 
[[https://www.youtube.com/watch?v=kxBjiUo88_U][video]] for
+  them! -- and:
+
+- experts, who want a very 
[[http://angg.twu.net/eev-intros/find-eev-intro.html#1][non-invasive]] package, 
with a mode that they
+  can turn on and off easily (hint: M-x eev-mode), and that they can
+  learn by playing with it just 5 minutes per week. The "expert setup"
+  is explained 
[[http://angg.twu.net/eev-intros/find-eev-install-intro.html#1][here]]. The 
source code for M-x eev-beginner is 
[[http://angg.twu.net/eev-current/eev-beginner.el.html][here]].
+
+# (find-eev-install-intro "1. Beginners and experts")
+# http://angg.twu.net/eev-intros/find-eev-install-intro.html#1
+
+# (find-eev-quick-intro)
+# http://angg.twu.net/eev-intros/find-eev-quick-intro.html
+
+# (find-eev "eev-beginner.el")
+# http://angg.twu.net/eev-current/eev-beginner.el.html
+
+# (find-eev-quick-intro "1. Installing eev")
+# http://angg.twu.net/eev-intros/find-eev-quick-intro.html#1
+
+# (find-eev-intro "1. `eev-mode'")
+# http://angg.twu.net/eev-intros/find-eev-intro.html#1
+
+# https://orgmode.org/ prose
+
+# (ecop 5 "prehistory-4")
+# (eco    "prehistory-4")
+
+# (find-here-links-intro "1. Alternating between \"task\" and \"notes\"")
+# http://angg.twu.net/eev-intros/find-here-links-intro.html#1
+
+# http://angg.twu.net/LATEX/2019emacsconf.pdf
+# http://angg.twu.net/LATEX/2019emacsconf.pdf#page=8
+# http://angg.twu.net/LATEX/2019emacsconf.pdf#page=13
+
+
diff --git a/VERSION b/VERSION
index 84e90b8..2d84c40 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Thu Dec 17 09:31:29 GMT 2020
-Thu Dec 17 06:31:29 -03 2020
+Thu Dec 17 15:36:48 GMT 2020
+Thu Dec 17 12:36:48 -03 2020
diff --git a/eev-audiovideo.el b/eev-audiovideo.el
index 2f78287..ccd229f 100644
--- a/eev-audiovideo.el
+++ b/eev-audiovideo.el
@@ -1,6 +1,6 @@
 ;;; eev-audiovideo.el -- elisp hyperlinks to audio and video files.
 
-;; Copyright (C) 2013-2019 Free Software Foundation, Inc.
+;; Copyright (C) 2013-2020 Free Software Foundation, Inc.
 ;;
 ;; This file is part of GNU eev.
 ;;
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    2020oct27
+;; Version:    2020dec17
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-audiovideo.el>
@@ -87,13 +87,17 @@
 
 
 
-;; «.ee-time-from-bol» (to "ee-time-from-bol")
-;; «.eev-avadj-mode»   (to "eev-avadj-mode")
-;; «.find-mplayer»     (to "find-mplayer")
-;; «.find-termplayer»  (to "find-termplayer")
-;; «.find-mpv-video»   (to "find-mpv-video")
-;; «.find-mpv-audio»   (to "find-mpv-audio")
-;; «.aliases»          (to "aliases")
+;; «.ee-time-from-bol»         (to "ee-time-from-bol")
+;; «.ee-time-to-seconds»       (to "ee-time-to-seconds")
+;;   «.mm:ss»                  (to "mm:ss")
+;;   «.youtube-time»           (to "youtube-time")
+;; «.ee-time-shift»            (to "ee-time-shift")
+;; «.eev-avadj-mode»           (to "eev-avadj-mode")
+;; «.find-mplayer»             (to "find-mplayer")
+;; «.find-termplayer»          (to "find-termplayer")
+;; «.find-mpv-video»           (to "find-mpv-video")
+;; «.find-mpv-audio»           (to "find-mpv-audio")
+;; «.aliases»                  (to "aliases")
 
 
 
@@ -121,6 +125,8 @@
 ;;;                                                                         
 ;; «ee-time-from-bol»  (to ".ee-time-from-bol")
 
+;; Old version:
+;; (defvar ee-time-regexp "[0-9]?[0-9]:[0-9][0-9]\\(:[0-9][0-9]\\)?")
 (defvar ee-time-regexp
        "\\(?:\\([0-9]?[0-9]\\):\\)?\\([0-9]?[0-9]\\):\\([0-9][0-9]\\)")
 
@@ -147,19 +153,32 @@
 
 
 
-
-;;;  _   _                          _     _  __ _   
-;;; | |_(_)_ __ ___   ___       ___| |__ (_)/ _| |_ 
-;;; | __| | '_ ` _ \ / _ \_____/ __| '_ \| | |_| __|
-;;; | |_| | | | | | |  __/_____\__ \ | | | |  _| |_ 
-;;;  \__|_|_| |_| |_|\___|     |___/_| |_|_|_|  \__|
-;;;                                                 
+;;;  _   _                      _                                           _  
   
+;;; | |_(_)_ __ ___   ___      | |_ ___        ___  ___  ___ ___  _ __   __| 
|___ 
+;;; | __| | '_ ` _ \ / _ \_____| __/ _ \ _____/ __|/ _ \/ __/ _ \| '_ \ / _` / 
__|
+;;; | |_| | | | | | |  __/_____| || (_) |_____\__ \  __/ (_| (_) | | | | (_| 
\__ \
+;;;  \__|_|_| |_| |_|\___|      \__\___/      |___/\___|\___\___/|_| 
|_|\__,_|___/
+;;;                                                                            
   
+;; «ee-time-to-seconds»  (to ".ee-time-to-seconds")
 ;; Tests:
-;; (ee-time-to-seconds "1:00:00")
 ;; (ee-seconds-to-time   5)
 ;; (ee-seconds-to-time 300)
 ;; (ee-time+ -20 "0:05")
 
+;; Old notes:
+;; (find-elnode "Time Parsing")
+;; (find-elnode "Time Parsing" "Function: format-seconds")
+;; (seconds-to-time 4000)
+;; (date-to-time "2:30")
+;; (float-time '(0 4000 0))
+;; (format-seconds     "%h:%m:%s" 4000)
+;; (format-seconds "%h:%02m:%02s" 4000)
+;; (ee-seconds-to-time  260)
+;; (ee-seconds-to-time 4000)
+;; (ee-time-to-seconds    "4:20")
+;; (ee-time-to-seconds "1:00:00")
+;; (string-to-number "")
+
 (defun ee-time-to-seconds (time)
   (save-match-data
     (if (string-match ee-time-regexp time)
@@ -172,6 +191,75 @@
       (format-seconds "%m:%02s" seconds)
     (format-seconds "%h:%02m:%02s" seconds)))
 
+
+
+
+;;;                                
+;;;  _ __ ___  _ __ ___  _ ___ ___ 
+;;; | '_ ` _ \| '_ ` _ \(_) __/ __|
+;;; | | | | | | | | | | |_\__ \__ \
+;;; |_| |_| |_|_| |_| |_(_)___/___/
+;;;                                
+;; «mm:ss»  (to ".mm:ss")
+;; Convert between a number of seconds (a number)
+;; and a "minutes:seconds" thing (a string).
+;; TODO: convert all calls to `ee-secs-to-mm:ss' to `ee-seconds-to-time' and
+;;               all calls to `ee-mm:ss-to-secs' to `ee-time-to-seconds',
+;;           and declare this obsolete.
+;;
+(defun ee-secs-to-mm:ss (n)
+  "Force N - a number of seconds or an \"mm:ss\" string - to the mm:ss format"
+  (if (stringp n) n
+    (let* ((s (mod n 60))
+          (m (/ (- n s) 60)))
+      (format "%d:%02d" m s))))
+
+(defun ee-mm:ss-to-secs (mm:ss)
+  "Force MM:SS - a string or a number of seconds - to a number of seconds"
+  (if (numberp mm:ss) mm:ss
+    (let* ((ms (mapcar 'string-to-number (split-string mm:ss ":"))))
+      (+ (* 60 (car ms)) (cadr ms)))))
+
+
+
+
+;; «youtube-time»  (to ".youtube-time")
+;; Tests: (ee-time-to-youtube-time "2")
+;;        (ee-time-to-youtube-time "23")
+;;        (ee-time-to-youtube-time "1:23")
+;;        (ee-time-to-youtube-time "1:23:43")
+;;
+(defun ee-time-to-youtube-time (str)
+  "Convert strings like \"1:23\" to strings like \"#t=1m23s\".
+Supports the input formats \"ss\", \"mm:ss\", and \"hh:mm:ss\".
+If the input does not match any of these formats, return nil."
+  (save-match-data
+    (cond ((string-match "^\\([0-9]+\\)$" str)
+          (format "#t=%ss" (match-string 1 str)))
+          ((string-match "^\\([0-9]+\\):\\([0-9][0-9]\\)$" str)
+          (format "#t=%sm%ss" (match-string 1 str) (match-string 2 str)))
+          ((string-match "^\\([0-9]+\\):\\([0-9][0-9]\\):\\([0-9][0-9]\\)$" 
str)
+          (format "#t=%sh%sm%ss" (match-string 1 str) (match-string 2 str)
+                  (match-string 2 str))))))
+         
+
+
+
+
+
+
+
+;;;  _   _                          _     _  __ _   
+;;; | |_(_)_ __ ___   ___       ___| |__ (_)/ _| |_ 
+;;; | __| | '_ ` _ \ / _ \_____/ __| '_ \| | |_| __|
+;;; | |_| | | | | | |  __/_____\__ \ | | | |  _| |_ 
+;;;  \__|_|_| |_| |_|\___|     |___/_| |_|_|_|  \__|
+;;;                                                 
+;; «ee-time-shift»  (to ".ee-time-shift")
+;; See: (find-audiovideo-intro "2. `eev-avadj-mode'")
+;; Tests: (ee-time+ 40 "4:20")
+;;        (ee-time+ -1000 "4:20")
+
 (defun ee-time+ (seconds time)
   (save-match-data
     (ee-seconds-to-time
@@ -191,6 +279,7 @@
 
 
 
+
 ;;;  _           _                     _ _         __      _     _            
 ;;; | | __ _ ___| |_    __ _ _   _  __| (_) ___   / /_   _(_) __| | ___  ___  
 ;;; | |/ _` / __| __|  / _` | | | |/ _` | |/ _ \ / /\ \ / / |/ _` |/ _ \/ _ \ 
@@ -198,6 +287,7 @@
 ;;; |_|\__,_|___/\__|  \__,_|\__,_|\__,_|_|\___/_/    \_/ |_|\__,_|\___|\___/ 
 ;;;                                                                           
 ;; See: (find-audiovideo-intro "4.4. The default audio/video file")
+;; (find-audiovideo-intro "2. `eev-avadj-mode'" "play the default")
 
 (defvar ee-audiovideo-last nil
   "See: (find-audiovideo-intro \"The current audio or video\")")
@@ -219,6 +309,7 @@ With a prefix of 0 just display what would be done. See:
 
 
 
+
 ;;;                       _  _                           _      
 ;;;   __ ___   ____ _  __| |(_)      _ __ ___   ___   __| | ___ 
 ;;;  / _` \ \ / / _` |/ _` || |_____| '_ ` _ \ / _ \ / _` |/ _ \
@@ -249,6 +340,7 @@ See: (find-audiovideo-intro \"`eev-avadj-mode'\")"
 
 
 
+
 ;;;                  _                       
 ;;;  _ __ ___  _ __ | | __ _ _   _  ___ _ __ 
 ;;; | '_ ` _ \| '_ \| |/ _` | | | |/ _ \ '__|
@@ -353,8 +445,6 @@ See: (find-audiovideo-intro \"`eev-avadj-mode'\")"
 ;;;           |_|                                      
 ;;
 ;; «find-mpv-video»  (to ".find-mpv-video")
-;; Experimental! To use it run:
-;; (defun find-video (&rest rest) (apply 'find-mpv-video rest))
 ;;
 (defun    find-mpv-video (fname &optional pos &rest rest)
   "Open FNAME with mpv, with a GUI (in fullscreen mode, for video files)."
@@ -457,92 +547,9 @@ See: (find-audiovideo-intro \"`eev-avadj-mode'\")"
 
 
 
-;;;                _                            _ _       
-;;;   ___ ___   __| | ___        __ _ _   _  __| (_) ___  
-;;;  / __/ _ \ / _` |/ _ \_____ / _` | | | |/ _` | |/ _ \ 
-;;; | (_| (_) | (_| |  __/_____| (_| | |_| | (_| | | (_) |
-;;;  \___\___/ \__,_|\___|      \__,_|\__,_|\__,_|_|\___/ 
-
-
-
-
-
-
 (provide 'eev-audiovideo)
 
 
-
-
-;; Garbage?
-
-
-;; Tests: (ee-time-to-youtube-time "2")
-;;        (ee-time-to-youtube-time "23")
-;;        (ee-time-to-youtube-time "1:23")
-;;        (ee-time-to-youtube-time "1:23:43")
-;;
-(defun ee-time-to-youtube-time (str)
-  "Convert strings like \"1:23\" to strings like \"#t=1m23s\".
-Supports the input formats \"ss\", \"mm:ss\", and \"hh:mm:ss\".
-If the input does not match any of these formats, return nil."
-  (save-match-data
-    (cond ((string-match "^\\([0-9]+\\)$" str)
-          (format "#t=%ss" (match-string 1 str)))
-          ((string-match "^\\([0-9]+\\):\\([0-9][0-9]\\)$" str)
-          (format "#t=%sm%ss" (match-string 1 str) (match-string 2 str)))
-          ((string-match "^\\([0-9]+\\):\\([0-9][0-9]\\):\\([0-9][0-9]\\)$" 
str)
-          (format "#t=%sh%sm%ss" (match-string 1 str) (match-string 2 str)
-                  (match-string 2 str))))))
-         
-
-
-
-;;;                                
-;;;  _ __ ___  _ __ ___  _ ___ ___ 
-;;; | '_ ` _ \| '_ ` _ \(_) __/ __|
-;;; | | | | | | | | | | |_\__ \__ \
-;;; |_| |_| |_|_| |_| |_(_)___/___/
-;;;                                
-
-;; Convert between a number of seconds (a number)
-;; and a "minutes:seconds" thing (a string).
-;; OBSOLETE.
-;; TODO: convert all calls to `ee-secs-to-mm:ss' to `ee-seconds-to-time' and
-;;               all calls to `ee-mm:ss-to-secs' to `ee-time-to-seconds'.
-;;
-(defun ee-secs-to-mm:ss (n)
-  "Force N - a number of seconds or an \"mm:ss\" string - to the mm:ss format"
-  (if (stringp n) n
-    (let* ((s (mod n 60))
-          (m (/ (- n s) 60)))
-      (format "%d:%02d" m s))))
-(defun ee-mm:ss-to-secs (mm:ss)
-  "Force MM:SS - a string or a number of seconds - to a number of seconds"
-  (if (numberp mm:ss) mm:ss
-    (let* ((ms (mapcar 'string-to-number (split-string mm:ss ":"))))
-      (+ (* 60 (car ms)) (cadr ms)))))
-
-
-;; Old notes on time regexps:
-;; (find-elnode "Time Parsing")
-;; (seconds-to-time 4000)
-;; (float-time '(0 4000 0))
-;; (format-seconds "%h:%m:%s" 4000)
-;; (format-seconds "%h:%02m:%02s" 4000)
-;; (ee-seconds-to-time 260)
-;; (ee-seconds-to-time 4000)
-;; (ee-time-to-seconds "4:20")
-;; (date-to-time "2:30")
-;; (string-to-number "")
-;; (ee-time+ 40 "4:20")
-;; (ee-time+ -1000 "4:20")
-;;
-;; (defvar ee-time-regexp "[0-9]?[0-9]:[0-9][0-9]\\(:[0-9][0-9]\\)?")
-
-
-
-
-
 ;; Local Variables:
 ;; coding:            utf-8-unix
 ;; ee-anchor-format:  "«%s»"
diff --git a/eev-intro.el b/eev-intro.el
index f478b45..43283f4 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -92,7 +92,7 @@
 ;; «.find-org-intro»           (to "find-org-intro")
 ;; «.find-escripts-intro»      (to "find-escripts-intro")
 ;; «.find-git-intro»           (to "find-git-intro")
-
+;; «.find-little-languages-intro»      (to "find-little-languages-intro")
 ;; «.find-windows-beginner-intro»      (to "find-windows-beginner-intro")
 
 ;; Videos:
@@ -12675,6 +12675,43 @@ will give you information about the current definition.
 
 
 
+;; «find-little-languages-intro»  (to ".find-little-languages-intro")
+;; Skel: (find-intro-links "little-languages")
+
+(defun find-little-languages-intro (&rest pos-spec-list) (interactive)
+  (let ((ee-buffer-name "*(find-little-languages-intro)*"))
+    (apply 'find-eintro "\
+\(Re)generate: (find-little-languages-intro)
+Source code:  (find-efunction 'find-little-languages-intro)
+More intros:  (find-eev-quick-intro)
+              (find-eev-intro)
+              (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+It is meant as both a tutorial and a sandbox.
+
+
+
+http://angg.twu.net/emacsconf2020.html
+http://angg.twu.net/emacsconf2020.html#forth
+
+  (find-eev \"eev-blinks.el\" \"ee-goto-position\")
+  (find-eev \"eev-blinks.el\" \"ee-goto-rest\")
+  (find-multiwindow-intro)
+  (find-eev-quick-intro \"7.4. Commands with very short names\")
+
+control structures in eepitch
+
+M-7 M-e
+
+
+
+Hello
+=====
+" pos-spec-list)))
+
+;; (find-little-languages-intro)
+
+