branch: externals/eev
commit 1133d7ab731e7b466f28e7d8c4264c814f962bad
Author: Eduardo Ochs <eduardoo...@gmail.com>
Commit: Eduardo Ochs <eduardoo...@gmail.com>
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 <eduardoo...@gmail.com>
+
+ * 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 <eduardoo...@gmail.com>
+
+ * eev-tlinks.el (find-git-links): use "export PAGER=cat".
+
+2019-11-13 Eduardo Ochs <eduardoo...@gmail.com>
+
+ * 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 <eduardoo...@gmail.com>
* 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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@gmail.com>
-;; 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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@gmail.com>
-;; 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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@gmail.com>
-;; 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")
