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")