[elpa] externals/eev 8dd8866 18/20: Added a section about `find-eevvideo-links' to `(find-audiovideo-intro)'.

[Stefan Monnier]

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

    Added a section about `find-eevvideo-links' to `(find-audiovideo-intro)'.
---
 ChangeLog       |  14 ++++++
 VERSION         |   4 +-
 eev-beginner.el |  48 +++++++++++--------
 eev-blinks.el   |   2 +-
 eev-elinks.el   |   5 +-
 eev-intro.el    | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++-----
 eev-pkg.el      |   4 +-
 eev-tlinks.el   |  24 ++++++++--
 eev.el          |   8 ++--
 9 files changed, 205 insertions(+), 49 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8bdb019..8513222 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,19 @@
 2021-01-02  Eduardo Ochs  <eduardoochs@gmail.com>
 
+       * eev.el: bumped the version. Changed the "Package-Requires" to
+       Emacs 24.4 because of the new `advice-add' used by `find-man'.
+
+       * eev-pkg.el: same.
+
+       * eev-intro.el (find-audiovideo-intro): new section: "7.2.
+       `find-eevvideo-links'".
+
+       * eev-elinks.el (ee-find-efunction-links): added a line like this:
+       `(find-epp (assoc FILENAME load-history))'.
+
+       * eev-tlinks.el (ee-code-psnevideo): added an `interactive'.
+       (ee-code-eevvideo): added an `interactive'.
+
        * eev-intro.el (find-videos-intro): rewrote the beginning.
 
 2021-01-01  Eduardo Ochs  <eduardoochs@gmail.com>
diff --git a/VERSION b/VERSION
index 9a95afe..b65c1f5 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sat Jan  2 03:24:08 GMT 2021
-Sat Jan  2 00:24:08 -03 2021
+Sat Jan  2 07:49:17 GMT 2021
+Sat Jan  2 04:49:17 -03 2021
diff --git a/eev-beginner.el b/eev-beginner.el
index 61d5c2e..277d9c7 100644
--- a/eev-beginner.el
+++ b/eev-beginner.el
@@ -1,6 +1,6 @@
 ;;; eev-beginner.el -- load eev, turn eev-mode on, open a tutorial.
 
-;; Copyright (C) 2019 Free Software Foundation, Inc.
+;; Copyright (C) 2019-2021 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:    2019jun23
+;; Version:    2021jan02
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-beginner.el>
@@ -29,41 +29,45 @@
 
 ;;; Commentary:
 
-;; This file serves two purposes.
+;; This file serves two purposes:
 ;;
-;; 1) Most beginners start playing with Emacs+eev by following the
-;;    instructions here,
+;; 1) If you install eev as an emacs package via `M-x list-packages'
+;;    then no eev modules will be loaded UNTIL you run `M-x
+;;    eev-beginner', which loads everything, starts eev-mode, and
+;;    opens the main tutorial. Note that `eev-beginner' is the ONLY
+;;    autoloaded function in eev!
+;;
+;; 2) Some people start playing with Emacs+eev by copying and pasting
+;;    a certain script to a terminal and executing it, following the
+;;    instructions here:
 ;;
 ;;      (find-eev-quick-intro "1. Installing eev")
 ;;
-;;    i.e., by copying and pasting a certain script to a terminal.
-;;    That script creates an executable file called "~/eev" whose
-;;    contents are something like this:
+;;    That script creates an executable file called "~/eev" whose contents
+;;    are something like this:
 ;;
 ;;      #!/bin/sh
 ;;      cd ~/eev2/ && emacs -l eev-beginner.el --eval="(find-eev-quick-intro)" 
$*
 ;;
 ;;    Running "~/eev" on a shell starts Emacs and makes it load this
-;;    file and load the main tutorial - i.e., (find-eev-quick-intro).
-;;
-;; 2) If you install eev as an emacs package via `M-x list-packages'
-;;    then no eev modules will be loaded UNTIL you run `M-x
-;;    eev-beginner', which loads everything, starts eev-mode, and
-;;    opens the main tutorial.
-;;
+;;    file - that loads all the other modules of eev - and then makes
+;;    Emacs evaluate the sexp `(find-eev-quick-intro)', that opens the
+;;    main tutorial.
+
 ;; When, or if, you are no longer a beginner, you may want to load eev
 ;; by just adding a "(require 'eev-load)" to your ".emacs". This loads
 ;; all the main modules but does not turn on eev-mode on by default,
 ;; and does not open the tutorial. See:
 ;;
 ;;    (find-eev-intro "1. `eev-mode'")
+;;    (find-eev-install-intro "2. The expert setup")
 ;;    (find-eev "eev-load.el")
 
-
 ;; NOTE: older versions of eev loaded "eev-readme.el" instead of
-;; "eev-beginner.el". See:
+;; "eev-beginner.el". Compare:
 ;;
 ;;   (find-eev "eev-readme.el")
+;;   (find-eev "eev-load.el")
 
 
 
@@ -71,17 +75,19 @@
 ;; 2019mar29: Uncommented - it seems that emacs25 needs this.
 (add-to-list 'load-path default-directory)
 
-
-
 ;; Load all the main modules of eev.
 ;; Do not load some advanced modules that require extra setup.
 ;; See the comments here: (find-eev "eev-load.el")
 (require 'eev-load)
+
+;; Turn eev-mode on.
+;; See: (find-eev-intro "1. `eev-mode'")
 (eev-mode 1)
-(find-eev-quick-intro)
 
+;; Open the main tutorial.
+(find-eev-quick-intro)
 
-;; This is the only autoload of eev at this moment.
+;; `eev-beginner' is the only autoload of eev at this moment.
 ;; See: (find-elnode "Autoload" "magic autoload comment")
 ;;      (find-eev "eev-load.el" "autoloads")
 
diff --git a/eev-blinks.el b/eev-blinks.el
index ea9f6a6..44af9e6 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -2,7 +2,7 @@
 ;; The basic hyperlinks are the ones that do not depend on templates,
 ;; and that are not created by `code-c-d' and friends.
 
-;; Copyright (C) 1999-2019 Free Software Foundation, Inc.
+;; Copyright (C) 1999-2020 Free Software Foundation, Inc.
 ;;
 ;; This file is part of GNU eev.
 ;;
diff --git a/eev-elinks.el b/eev-elinks.el
index 725ced8..78a1a77 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -1,6 +1,6 @@
 ;;; eev-elinks.el --- `find-efunction-links' and other `find-e*-links'
 
-;; Copyright (C) 2012-2020 Free Software Foundation, Inc.
+;; Copyright (C) 2012-2021 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:    2020dec16
+;; Version:    2021jan02
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -275,6 +275,7 @@ This is an internal function used by `find-efunction-links' 
and
     (symbol-file ',f 'defun)
     (find-fline (symbol-file ',f 'defun))
     (find-epp (assoc (symbol-file ',f 'defun) load-history))
+    (find-epp (assoc ,(symbol-file f 'defun) load-history))
     (find-eppp (mapcar 'car load-history))
     (find-estring (mapconcat 'identity (mapcar 'car load-history) "\n"))
     (find-estring (documentation ',f))
diff --git a/eev-intro.el b/eev-intro.el
index 9b90dff..7bcceaa 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-2020 Free Software Foundation, Inc.
+;; Copyright (C) 2013-2021 Free Software Foundation, Inc.
 ;;
 ;; This file is part of GNU eev.
 ;;
@@ -7953,6 +7953,107 @@ the person a pair of sexps like these:
 
 
 
+
+7.2. `find-eevvideo-links'
+--------------------------
+It may be simpler to explain `code-eevvideo' in another order,
+starting from the function `find-eevvideo-links' - that, as its
+name suggests, is a hyperlink to a temporary buffer containing
+elisp hyperlinks (plus some parts generated by templates). A sexp
+like
+
+  (find-eevvideo-links \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\")
+
+generates a temporary buffer whose first line follows the
+convention that \"the first line regenerates the buffer\", and
+its second line is a link like
+
+  (find-video \"$S/http/angg.twu.net/eev-videos/emacsconf2020.mp4\")
+
+that plays the local copy of the video (if it exists). That
+temporary buffer also contains several \"help sexps\" that point
+to parts of this intro, and also a part like
+
+  # URL, local file, and a link to the directory of the local file:
+  #               http://angg.twu.net/eev-videos/emacsconf2020.mp4
+  #              $S/http/angg.twu.net/eev-videos/emacsconf2020.mp4
+  # (find-fline \"$S/http/angg.twu.net/eev-videos/\")
+
+  # Youtube:
+  # (kill-new \"http://www.youtube.com/watch?v=hOAqBc42Gg8\";)
+  #            http://www.youtube.com/watch?v=hOAqBc42Gg8
+
+that tries (!) to explain clearly how the URL and the file name
+of the local copy were generated from the argument
+\"emacsconf2020\" to `find-eevvideo-links', and how the youtube
+URL was generated by the argument \"hOAqBc42Gg8\"; and the
+temporary buffer also contains a last part with a script to
+download the .mp4 file, and a help sexp that explains that.
+
+That temporary buffer also contains a pair of sexps like
+
+  (code-video \"eev2020video\" 
\"$S/http/angg.twu.net/eev-videos/emacsconf2020.mp4\")
+  (find-eev2020video)
+
+that are easy to understand - the first one defines
+`find-eev2020video' as a short line to play the local copy of the
+.mp4 file.
+
+If you compare the temporary buffers generated by these two
+sexps,
+
+  (find-eevvideo-links \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\")
+  (find-eevvideo-links \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\" \"17:20\")
+
+you will see that the second sexp adds a time offset \"17:20\"s
+at several places, and adds a \"#t=17m20s\"s at the end of each
+youtube URL. These sexps and URLs can be used for _communication_
+- for example, if I am chatting with someone on an IRC channel I
+can say \"watch this:\", and then send these two lines:
+
+  (find-eev2020video \"17:20\")
+  http://www.youtube.com/watch?v=hOAqBc42Gg8#t=17m20s
+
+If I take the
+
+  (find-eevvideo-links \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\")
+
+and change it to
+
+        (code-eevvideo \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\")
+
+this `code-eevvideo' sexps defines, or redefines,
+`find-eev2020video', to a \"version for communication\", such
+that
+
+  (find-eev2020video \"17:20\")
+
+runs 
+
+  (find-eevvideo-links \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\" \"17:20\")
+
+that generates a temporary buffer with all the stuff described
+above, instead of playing the video file right away - to play the
+video file you have to execute the sexp
+
+  (find-video \"$S/http/angg.twu.net/eev-videos/emacsconf2020.mp4\" \"17:20\")
+
+in the second line of the temporary buffer.
+
+There are some examples of `find-eevvideo-links' sexps here:
+
+  (find-videos-intro \"2. Some `find-eevvideo-links'\")
+
+At this moment I don't have variants of `find-eevvideo-links' and
+`code-eevvideo' that point to other sides - see the comments
+here:
+
+  (find-eev \"eev-tlinks.el\" \"hardcoded-paths\")
+
+
+
+
+
 " pos-spec-list)))
 
 ;; (find-audiovideo-intro)
@@ -9737,8 +9838,10 @@ Prerequisites:
 
 
 
-At this moment I have these five videos about eev (not counting
-the ones that I consider obsolete):
+1. Some videos
+==============
+At this moment I have these five videos about eev (I am
+deliberately ignoring the ones that I consider obsolete!):
 
   \"How to record executable notes with eev - and how to play them back\":
     http://angg.twu.net/emacsconf2019.html
@@ -9773,12 +9876,26 @@ the ones that I consider obsolete):
 The ones that I prepared for the two EmacsConfs are very
 well-rehearsed, the other ones are not.
 
-The best way to watch them is by downloading local copies of
-their .mp4s and then using the short hyperlinks of
+The links with #code-video, like
+
+  http://angg.twu.net/emacsconf2019.html#code-video
+
+point to indexes of the videos made with sexp hyperlinks.
+
+The best way to watch them is to download local copies of their
+.mp4s and then use the short hyperlinks described in
 
   (find-audiovideo-intro \"4. Short hyperlinks to audio and video files\")
 
-to jump to positions in them. You can do this with these sexps:
+to jump to positions in them.
+
+
+
+
+2. Some `find-eevvideo-links'
+=============================
+Another way to download these videos, and to get links that play
+them from the beginning, is by using these sexps:
 
   (find-eevvideo-links \"eev2019\" \"emacsconf2019\" \"86yiRG8YJD0\")
   (find-eevvideo-links \"eev2020\" \"emacsconf2020\" \"hOAqBc42Gg8\")
@@ -9786,22 +9903,24 @@ to jump to positions in them. You can do this with 
these sexps:
   (find-eevvideo-links \"2020sometbf\" \"2020-some-template-based\" 
\"91-9YfRPsuk\")
   (find-eevvideo-links \"2020findherelinks\" \"2020-find-here-links\" 
\"8jtiBlaDor4\")
 
-The links with #code-video, like
+The function `find-eevvideo-links' is explained here:
 
-  http://angg.twu.net/emacsconf2019.html#code-video
+  (find-audiovideo-intro \"7.2. `find-eevvideo-links'\")
 
-point to indexes of the videos made with sexp hyperlinks.
+
+
+TO DO (urgent): make a video about `find-eevvideo-links' and friends,
+TO DO (not urgent): rewrite most of this intro!
+
+Everything below this point is VERY old!!!
 
 
 
-TO DO: 1) make a video about `find-eevvideo-links' and friends,
-2) rewrite most of this intro!
-Everything below this point is very old.
 
 
 
 
-1. What we have now
+3. What we have now
 ===================
 I am producing a series of videos about eev - but at this moment
 only two very broad introductions are ready 8-(. I have plans for
diff --git a/eev-pkg.el b/eev-pkg.el
index 5f0950a..af9e388 100644
--- a/eev-pkg.el
+++ b/eev-pkg.el
@@ -1,5 +1,5 @@
-(define-package "eev" "20201030" "Support for e-scripts (eepitch blocks, elisp 
hyperlinks, etc)"
-  '((emacs "24.1"))
+(define-package "eev" "20210102" "Support for e-scripts (eepitch blocks, elisp 
hyperlinks, etc)"
+  '((emacs "24.4"))
   :keywords
   '("lisp" "e-scripts")
   :authors
diff --git a/eev-tlinks.el b/eev-tlinks.el
index 49c517c..7f289b0 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -1,6 +1,6 @@
 ;;; eev-tlinks.el --- hyperlinks to temporary buffers generated by templates
 
-;; Copyright (C) 2013-2020 Free Software Foundation, Inc.
+;; Copyright (C) 2013-2021 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:    2020dec27
+;; Version:    2021jan02
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-tlinks.el>
@@ -77,6 +77,7 @@
 ;; «.code-psnevideo»                   (to "code-psnevideo")
 ;; «.code-eevvideo»                    (to "code-eevvideo")
 ;; «.find-eevvideo-links»              (to "find-eevvideo-links")
+;; «.hardcoded-paths»                  (to "hardcoded-paths")
 ;;
 ;; «.find-latex-links»                 (to "find-latex-links")
 ;; «.find-lua-links»                   (to "find-lua-links")
@@ -1545,6 +1546,7 @@ echo     '{url}' >> ~/.psne.log
 ;;                 (find-{c}video \"0:00\")
 
 (defun find-{c}video (&optional time &rest rest)
+  (interactive)
   (find-psnevideo-links \"{c}\" \"{url}\" \"{youtubeid}\" time))
 "))
 
@@ -1558,6 +1560,7 @@ echo     '{url}' >> ~/.psne.log
 ;; «find-eevvideo-links»  (to ".find-eevvideo-links")
 ;; Test: (find-eevvideo-links "eevnav" "M-x-list-packages-eev-nav" "0:00")
 ;; Skel: (find-find-links-links-new "eevvideo" "c stem youtubeid time" "url")
+;;  See: (find-audiovideo-intro "7.2. `find-eevvideo-links'")
 ;;
 (defun find-eevvideo-links (&optional c stem youtubeid time &rest 
pos-spec-list)
 "Visit a temporary buffer containing hyperlinks for eevvideo."
@@ -1578,8 +1581,9 @@ echo     '{url}' >> ~/.psne.log
 
 ;; «code-eevvideo»  (to ".code-eevvideo")
 ;; See: (find-audiovideo-intro "7.1. `code-eevvideo'")
-;; Test: (code-eevvideo "eevnav" "M-x-list-packages-eev-nav")
-;;       (find-eevnavvideo "0:00")
+;; Test: (find-code-eevvideo "eevnav" "M-x-list-packages-eev-nav")
+;;            (code-eevvideo "eevnav" "M-x-list-packages-eev-nav")
+;;                      (find-eevnavvideo "0:00")
 ;;
 (defun      code-eevvideo (c stem &optional youtubeid)
   (eval (ee-read (ee-code-eevvideo c stem youtubeid))))
@@ -1597,10 +1601,22 @@ echo     '{url}' >> ~/.psne.log
 ;; See: (find-audiovideo-intro \"7.1. `code-eevvideo'\")
 
 (defun find-{c}video (&optional time &rest rest)
+  (interactive)
   (find-eevvideo-links \"{c}\" \"{stem}\" \"{youtubeid}\" time))
 "))
 
 
+;; «hardcoded-paths»  (to ".hardcoded-paths")
+;;
+;; The definitions of `find-eevvideo-links' and `code-eevvideo' above
+;; have strings like "eev" and "http://angg.twu.net/eev-videos/";
+;; hardcoded in several places... it is easy, but not entirely
+;; trivial, to create variants of them that point to other sites that
+;; stores video tutorials and presentations in ways that are easy to
+;; download. If you are aware of sites like that, please get in touch
+;; and I'll create functions pointing to them!
+
+
 
 
 
diff --git a/eev.el b/eev.el
index eff0fd3..e39a2d1 100644
--- a/eev.el
+++ b/eev.el
@@ -1,12 +1,12 @@
 ;;; eev.el --- Support for e-scripts (eepitch blocks, elisp hyperlinks, etc)  
-*- lexical-binding: t; -*-
 
-;; Copyright (C) 2019,2020 Free Software Foundation, Inc.
+;; Copyright (C) 2019-2021 Free Software Foundation, Inc.
 
 ;; Author: Eduardo Ochs <eduardoochs@gmail.com>
-;; Package-Requires: ((emacs "24.1"))
+;; Package-Requires: ((emacs "24.4"))
 ;; Keywords: lisp e-scripts
 ;; URL: http://angg.twu.net/#eev
-;; Version: 20201030
+;; Version: 20210102
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -23,7 +23,7 @@
 
 ;;; Commentary:
 
-;;
+;; See eev-beginner.el for how to load eev.
 
 ;;; Code: