[elpa] externals/eev 1133d7a 02/14: Added a new section to `(find-audiovideo-intro)'.

[Stefan Monnier]

branch: externals/eev
commit 1133d7ab731e7b466f28e7d8c4264c814f962bad
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Added a new section to `(find-audiovideo-intro)'.
---
 ChangeLog         |  19 ++++++
 VERSION           |   4 +-
 eev-audiovideo.el |  87 ++++++++++++++++++++----
 eev-blinks.el     |   5 +-
 eev-elinks.el     |   4 +-
 eev-intro.el      | 193 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 eev-testblocks.el |  10 +++
 eev-tlinks.el     |  11 +++-
 8 files changed, 297 insertions(+), 36 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c1d52fe..5436577 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2020-01-03  Eduardo Ochs  <address@hidden>
+
+       * eev-audiovideo.el: rewrote many comments.
+
+       * eev-intro.el (find-audiovideo-intro): new section: "4.4. The
+       default audio/video file".
+
+       * eev-blinks.el (ee-find-man-pos-spec-list): `defvar'ed. Was
+       undeclared before.
+
+2020-01-02  Eduardo Ochs  <address@hidden>
+
+       * eev-tlinks.el (find-git-links): use "export PAGER=cat".
+
+2019-11-13  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-eev-quick-intro): rewrote the section 7.2 to
+       explain how beginners should use `M-j' without a prefix argument.
+
 2019-11-11  Eduardo Ochs  <address@hidden>
 
        * eev-intro.el (find-org-intro): use \":results output\" (thx Ken
diff --git a/VERSION b/VERSION
index d37bfea..4aec24a 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Mon Nov 11 14:19:25 GMT 2019
-Mon Nov 11 11:19:25 -03 2019
+Fri Jan  3 19:02:41 GMT 2020
+Fri Jan  3 16:02:41 -03 2020
diff --git a/eev-audiovideo.el b/eev-audiovideo.el
index f252ba5..19399d7 100644
--- a/eev-audiovideo.el
+++ b/eev-audiovideo.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019sep29
+;; Version:    2020jan03
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-audiovideo.el>
@@ -31,12 +31,63 @@
 
 ;;; Commentary:
 
-;; There is an introduction to these features here,
+;; This file implements links to audio or video files _at certain time
+;; offsets_. Here are two examples, in a long syntax:
+;;
+;;   (find-video "~/eev-videos/Punch_and_Judy_Mark_Poulton-K6LmZ0A1s9U.mp4")
+;;   (find-video "~/eev-videos/Punch_and_Judy_Mark_Poulton-K6LmZ0A1s9U.mp4" 
"1:17")
+;;
+;; There are also the usual shorter hyperlinks, like this,
+;;
+;;   (find-punchandjudyvideo "1:04" "right position")
+;;
+;; and a very compact syntax, used by `eev-avadj-mode', in which `M-p'
+;; plays the default audio or video file at the first time offset that
+;; can the parsed in the current line (the "time from BOL"). See:
 ;;
 ;;   (find-audiovideo-intro)
+;;   (find-audiovideo-intro "1. Time offsets")
+;;   (find-audiovideo-intro "4. Short hyperlinks to audio and video files")
+;;   (find-audiovideo-intro "4.3. A demo")
+;;   (find-audiovideo-intro "4.4. The default audio/video file")
+;;   (find-audiovideo-intro "4.4. The default audio/video file" "`M-p'")
 ;;
-;; but that needs to be rewritten...
+;; NOTE: I am not aware of other packages - for emacs or not - that
+;; implement links that play audio or video files at given time
+;; offsets... but in 2020jan03 a guy called stardiviner sent this
+;; proposal to the Org mailing list:
+;;
+;;   https://lists.gnu.org/archive/html/emacs-orgmode/2020-01/msg00007.html
+
+
 
+;; Historical note:
+;;
+;; I wrote a first version of this in 2011 or 2012, and some time
+;; later a friend - Rafael Duarte Pinheiro - helped me to create a way
+;; to play my indexed audios in a browser. Here is an example:
+;;
+;;   http://angg.twu.net/audios/2011dec13-ict.html
+;;
+;; I used these indexed audios to show what was happening in the
+;; banana meetings of the Banana Institute of Science and Technology
+;; of the banana campus in which I work, that is part of a banana
+;; university in a banana republic.
+;;
+;; My tools for indexed audios later became one third of my "tools for
+;; activists", that are documented here:
+;;
+;;   http://angg.twu.net/ferramentas-para-ativistas.html#audios-introducao
+;;
+;; but everything there is in Portuguese.
+;;
+;; In 2014 I had a burn-out and stopped working on these tools for
+;; activists.
+
+
+
+
+;; «.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")
@@ -68,6 +119,8 @@
 ;;; | |_| | | | | | |  __/_____|  _| | | (_) | | | | | |_____| |_) | (_) | |
 ;;;  \__|_|_| |_| |_|\___|     |_| |_|  \___/|_| |_| |_|     |_.__/ \___/|_|
 ;;;                                                                         
+;; «ee-time-from-bol»  (to ".ee-time-from-bol")
+
 (defvar ee-time-regexp
        "\\(?:\\([0-9]?[0-9]\\):\\)?\\([0-9]?[0-9]\\):\\([0-9][0-9]\\)")
 
@@ -77,10 +130,14 @@
     (if (re-search-forward regexp limit t repeat)
        (match-string-no-properties 0))))
 
+;; Test: 98:76:54 3:21 (ee-time-from-bol)
+;;
 (defun ee-time-from-bol ()
   "Try this: 98:76:54 3:21 (ee-time-from-bol)"
   (ee-re-search-from (ee-bol) ee-time-regexp (ee-eol)))
 
+;; Test: 98:76:54 3:21 (ee-time-from-bol-flash)
+;;
 (defun ee-time-from-bol-flash () (interactive)
   "Try this: 98:76:54 3:21 (ee-time-from-bol-flash)"
   (if (ee-time-from-bol)
@@ -97,6 +154,12 @@
 ;;; | |_| | | | | | |  __/_____\__ \ | | | |  _| |_ 
 ;;;  \__|_|_| |_| |_|\___|     |___/_| |_|_|_|  \__|
 ;;;                                                 
+;; Tests:
+;; (ee-time-to-seconds "1:00:00")
+;; (ee-seconds-to-time   5)
+;; (ee-seconds-to-time 300)
+;; (ee-time+ -20 "0:05")
+
 (defun ee-time-to-seconds (time)
   (save-match-data
     (if (string-match ee-time-regexp time)
@@ -127,20 +190,21 @@
   (ee-time-from-bol-shift (- (or seconds 1))))
 
 
+
 ;;;  _           _                     _ _         __      _     _            
 ;;; | | __ _ ___| |_    __ _ _   _  __| (_) ___   / /_   _(_) __| | ___  ___  
 ;;; | |/ _` / __| __|  / _` | | | |/ _` | |/ _ \ / /\ \ / / |/ _` |/ _ \/ _ \ 
 ;;; | | (_| \__ \ |_  | (_| | |_| | (_| | | (_) / /  \ V /| | (_| |  __/ (_) |
 ;;; |_|\__,_|___/\__|  \__,_|\__,_|\__,_|_|\___/_/    \_/ |_|\__,_|\___|\___/ 
 ;;;                                                                           
-;;
+;; See: (find-audiovideo-intro "4.4. The default audio/video file")
+
 (defvar ee-audiovideo-last nil
   "See: (find-audiovideo-intro \"The current audio or video\")")
 
 (defun ee-audiovideo-sexp (time)
   (list ee-audiovideo-last time))
 
-
 (defun ee-time-from-bol-rerun (&optional arg)
   "Play the current audio or video starting at '(ee-time-from-bol)'.
 With a prefix of 0 just display what would be done. See:
@@ -418,7 +482,10 @@ See: (find-audiovideo-intro \"`eev-avadj-mode'\")"
 ;;;                                
 
 ;; Convert between a number of seconds (a number)
-;; and a "minutes:seconds" thing (a string)
+;; 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"
@@ -433,13 +500,7 @@ See: (find-audiovideo-intro \"`eev-avadj-mode'\")"
       (+ (* 60 (car ms)) (cadr ms)))))
 
 
-;;;  _   _                                                     
-;;; | |_(_)_ __ ___   ___       _ __ ___  __ _  _____  ___ __  
-;;; | __| | '_ ` _ \ / _ \_____| '__/ _ \/ _` |/ _ \ \/ / '_ \ 
-;;; | |_| | | | | | |  __/_____| | |  __/ (_| |  __/>  <| |_) |
-;;;  \__|_|_| |_| |_|\___|     |_|  \___|\__, |\___/_/\_\ .__/ 
-;;;                                      |___/          |_|    
-;;
+;; Old notes on time regexps:
 ;; (find-elnode "Time Parsing")
 ;; (seconds-to-time 4000)
 ;; (float-time '(0 4000 0))
diff --git a/eev-blinks.el b/eev-blinks.el
index ad1e66b..73199e6 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -637,10 +637,11 @@ This is like `find-sh' but sets the buffer's 
default-directory to DIR."
 ;; Tests:
 ;;   (find-man "1 cat")
 
-(defvar ee-find-man-flag nil "See `find-man'.")
+(defvar ee-find-man-flag          nil "See `find-man'.")
+(defvar ee-find-man-pos-spec-list nil "See `find-man'.")
 
 ;; See: (find-elnode "Advising Functions")
-;;      (find-elnode "Porting old advices")
+;;      (find-elnode "Porting old advice")
 ;;      (find-efunctiondescr 'defadvice)
 (defadvice Man-notify-when-ready (around find-man (man-buffer) activate)
   "After rendering a manpage jump to `ee-find-man-pos-spec-list'."
diff --git a/eev-elinks.el b/eev-elinks.el
index 5852631..edd1f7b 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -35,7 +35,9 @@
 ;; See this for a (rough) classification of eev's hyperlink functions
 ;; into several classes:
 ;;
-;;   (find-links-intro "6. Basic and non-basic hyperlinks")
+;;   (find-links-conv-intro "3. Classification")
+;;   (find-links-conv-intro "3. Classification" "`find-elinks'")
+;;   (find-links-conv-intro "3. Classification" "`find-elinks'+")
 ;;
 ;; In this file we define `find-elinks' and several functions based on
 ;; it that generate relatively simple elisp hyperlinks buffers -
diff --git a/eev-intro.el b/eev-intro.el
index c17e79b..c6b1005 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -1,6 +1,6 @@
 ;;; eev-intro.el --- sandboxed tutorials for eev, like (find-eev-quick-intro)
 
-;; 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 <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019nov11
+;; Version:    2020jan01
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -982,7 +982,9 @@ active. So:
 
       `M-j' runs: (find-eejumps)
 
-Let's try to understand this from both a user's point of view and
+`find-eejumps' is explained in the next section.
+
+Let's try to understand `M-j' from both a user's point of view and
 from a technical point of view.
 
 We may have elisp one-liners that we want to be able to execute very
@@ -1037,20 +1039,49 @@ as the \"target associated to nnn\".
 
 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:
+If you type `M-j' without a prefix argument it runs
+`(find-eejumps)', that displays a temporary buffer with a header
+with help and links and then a list of all the current eejump targets.
+Try it:
 
   (eek \"M-j\")
   (find-eejumps)
 
-You will see that two of those entries are:
+The header is this:
+
+  ;; Generated by: (find-eejumps)
+  ;; See: (find-eev-quick-intro \"7.1. `eejump'\" \"`M-j'\")
+  ;;      (find-emacs-keys-intro \"1. Basic keys (eev)\")
+  ;;      (find-emacs-keys-intro \"2. Key sequences\")
+  ;; 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:
+
+Note that after the \"See:\" we have three elisp hyperlinks to
+sections of tutorials, and after the \"For example:\" we have
+three examples of how to run `M-j' with numeric prefixes; each
+one of these examples is followed by the elisp hyperlink whose
+action corresponds to running `M-j' with that prefix.
+
+That header is very beginner-friendly, and if you are a beginner
+who only knows how to use `M-e' and `M-j' you can, and should,
+use that header as your main starting point: every time that you
+feel lost you can type `M-j' to go back to that header, and you
+can use its links to navigate to the documentation for Emacs and
+eev.
+
+That header is followed by a section that is very beginner
+UN-friendly, that contains a series of defuns like these ones:
 
   (defun eejump-1 () (find-fline \"~/TODO\"))
   (defun eejump-5 () (find-eev-quick-intro))
 
 
 
+
+
 7.3. Defining eejump targets
 ----------------------------
 We can define new eejump targets, or overwrite the current ones, by
@@ -1091,7 +1122,7 @@ Let's start with an example. If we are editing a LaTeX 
file, say
 If our \"/tmp/foo.tex\" starts with these lines
 
   % (defun c () (interactive) (find-sh \"cd /tmp/; pdflatex foo.tex\"))
-  % (defun d () (interactive) (find-xpdfpage \"/tmp/foo.pdf\"))
+  % (defun d () (interactive) (find-pdf-page \"/tmp/foo.pdf\"))
   % (defun e () (interactive) (find-fline \"/tmp/foo.tex\"))
 
 and we execute these defuns, then from that point on `M-x c', `M-x d'
@@ -4377,11 +4408,10 @@ Most of the \"M-h commands\" generate buffers with elisp
 hyperlinks in which the the first line \"regenerates the
 buffers\". This means two things:
 
-  1. You can copy the first to your notes, and it will work as a
-     link to that buffer. For example:
+  1. You can copy the first line to your notes, and it will work
+     as a link to that buffer. Here are some examples of these
+     first lines:
 
-     (find-efunction 'next-line)
-     (find-evariable 'line-move-visual)
      (find-latex-links \"/tmp/mytest\")
      (find-latex-links \"~/latextest\")
      (find-code-pdf-links 
\"/usr/local/texlive/2019/texmf-dist/doc/asymptote/\" \"{c}\")
@@ -7151,8 +7181,8 @@ execute these sexps occasionally to check if they are 
really
 pointing to the right places, and then make further adjustments;
 we are not doing that yet.
 
-The idea of a \"default audio/video file\" will be explained
-later.
+The idea of a \"default audio/video file\" will be explained in
+section 4.4.
 
 
 
@@ -7325,6 +7355,77 @@ Then try:
 
 
 
+4.4. The default audio/video file
+---------------------------------
+One of the things that the function `find-punchandjudyvideo' does
+when executed is this:
+
+  (setq ee-audiovideo-last 'find-punchandjudyvideo)
+
+It sets the \"default audio/video file\" - more precisely, it
+sets the global variable `ee-audiovideo-last' that indicate that
+the way to play again the \"default audio/video file\" is by
+running the function `find-punchandjudyvideo'.
+
+This is similar to what the `find-xxxtext' functions do - they
+store some informations about the last PDF opened with a
+`find-xxxtext' function into global variables. See:
+
+  (find-pdf-like-intro \"11. How `M-h M-p' guesses everything\")
+  (find-pdf-like-intro \"11. How `M-h M-p' guesses everything\" 
\"find-xxxtext\")
+
+and, for more technical details:
+
+  (find-eev-quick-intro \"9.1. `code-c-d'\")
+  (find-eev-quick-intro \"9.1. `code-c-d'\" \"find-code-c-d\")
+  (find-code-video \"punchandjudyvideo\"
+                   
\"~/eev-videos/Punch_and_Judy_Mark_Poulton-K6LmZ0A1s9U.mp4\")
+
+In section 2 we mentioned that the key `M-p' in `eev-avadj-mode'
+does this:
+
+  M-p    play the default audio/video file at a time offset
+
+Let's see in practice what this means. If we run these three
+sexps here,
+
+  (code-video \"punchandjudyvideo\" 
\"~/eev-videos/Punch_and_Judy_Mark_Poulton-K6LmZ0A1s9U.mp4\")
+  (find-punchandjudyvideo \"1:17\" \"he will sing the baby to sleep\")
+  (eev-avadj-mode 1)
+
+we will a) define `find-punchandjudyvideo', b) set the global
+variable `ee-audiovideo-last' to `find-punchandjudyvideo', c)
+turn `eev-avadj-mode' on. Now `M-p' should work! If you type
+`M-p' on any of the lines with timestamps below it will open the
+default audio/video file at that timestamp.
+
+  0:00 
+  0:10 calls the baby
+  0:40 where's the baby
+  1:04 right position
+  1:17 he will sing the baby to sleep
+  1:33 1-2-3
+  1:48 baby downstairs
+  3:12 slaps
+  3:50 1-2-3
+  4:34 you keep an eye on mr Punch
+  4:46 hat
+  5:03 hat
+  5:25 did you see him?
+  5:55 clown
+  6:14 slaps
+  6:52 sausages
+  7:24 crocodile
+  8:07 crocodile + sausages
+  8:32 another scene
+  8:39 fight
+  9:03 clown
+  9:45 mr punch
+
+
+
+
+
 
 5. Passing options to mplayer
 =============================
@@ -8218,8 +8319,68 @@ It is meant as both a tutorial and a sandbox.
 
 
 
-This into is currently GARBAGE.
-It should be rewritten to become a tutorial on:
+This intro is being rewritten!
+
+
+
+
+1. Introduction
+===============
+In dec/2019 I sent this e-mail to the eev mailing list:
+
+  https://lists.gnu.org/archive/html/eev/2019-12/msg00001.html
+
+It was a kind of a call for help. It contained a very brief
+explanation of how the \"templated\" functions of eev, like
+`find-ekey-links' and `find-latex-links', are implemented, and
+showed how people can write their own templated functions as
+quick hacks.
+
+If you want to learn how to _use_ templated functions, start by:
+
+  (find-eev-quick-intro \"4.2. `find-ekey-links' and friends\")
+  (find-eev-quick-intro \"7.5. `find-latex-links'\")
+
+If you want to look at the source code of the existing templated
+functions, take a look at:
+
+  (find-eev \"eev-elinks.el\")
+  (find-eev \"eev-tlinks.el\")
+
+  (find-links-intro \"3. Elisp hyperlinks buffers conventions\")
+
+This tutorial is for people who want to learn how to _write_
+their own templated functions.
+
+
+
+
+2. `ee-template0'
+=================
+See:
+
+  (find-efunction 'ee-template0)
+  (find-eev \"eev-template0.el\")
+
+
+
+
+3. `find-elinks'
+================
+See:
+
+  (find-efunction 'find-elinks)
+  (find-eev \"eev-elinks.el\" \"find-elinks\")
+
+
+
+4. `find-find-links-links'
+==========================
+
+  (find-eev \"eev-tlinks.el\" \"find-find-links-links\")
+
+
+
 
   1) How to use `ee-template0' and `find-elinks':
 
diff --git a/eev-testblocks.el b/eev-testblocks.el
index 538b921..33e1a04 100644
--- a/eev-testblocks.el
+++ b/eev-testblocks.el
@@ -60,6 +60,7 @@
         ((eq major-mode 'ruby-mode)   (ee-insert-test-ruby))
         ((eq major-mode 'sh-mode)     (ee-insert-test-sh))
         ((eq major-mode 'tcl-mode)    (ee-insert-test-tcl))
+        ((eq major-mode 'idris-mode)  (ee-insert-test-idris))
        (t (error "ee-insert-test: Unsupported major mode"))))
 
 (defun ee-insert-test-lua ()
@@ -122,6 +123,15 @@ source %s
 }
 " (buffer-name))))
 
+(defun ee-insert-test-idris ()
+  (interactive)
+  (insert (format "
+{-
+ (eepitch-to-buffer \"*idris-repl*\")
+
+-}
+" (buffer-name))))
+
 
 
 
diff --git a/eev-tlinks.el b/eev-tlinks.el
index 56b84e1..a277c0d 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019oct14
+;; Version:    2020jan02
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-tlinks.el>
@@ -41,6 +41,10 @@
 ;; The functions here are one complexity step above the functions in:
 ;;   (find-eev "eev-elinks.el")
 ;;
+;; See:
+;;   (find-links-conv-intro "3. Classification")
+;;   (find-links-conv-intro "3. Classification" "find-elinks")
+
 ;; NOTE (written in 2019mar05): some of the functions here are very
 ;; old and ugly and I haven't used them in ages. They will be deleted
 ;; in the next few months.
@@ -1088,9 +1092,10 @@ cd      {ee-git-dir}
 git clone {url}
 cd      {dir}
 
+export PAGER=cat
 git branch --list -a
 git for-each-ref
-PAGER=cat git log --oneline --graph --all -20
+git log --oneline --graph --all -20
 
 # (find-fline \"{ee-git-dir}\")
 # (find-fline \"{dir}\")
@@ -1332,6 +1337,8 @@ echo     'http://angg.twu.net/eev-videos/{anggstem}.mp4' 
>> ~/.psne.log
 
 ;; Tests: (find-latex-links)
 ;;        (find-latex-links "/tmp/foo")
+;;        (find-latex-links "/tmp/foo" 2)
+;;        (find-latex-links "/tmp/foo" 2 "copy-rest")