[elpa] externals/eev 39f1868e1f: Smalls changes in tutorials and comments.

[ELPA Syncer]

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

    Smalls changes in tutorials and comments.
---
 ChangeLog     |   5 +++
 VERSION       |   4 +--
 eepitch.el    |   3 +-
 eev-intro.el  | 106 ++++++++++++++++++++++++++++++++++------------------------
 eev-rstdoc.el |  79 ++++++++++++++++++++++++++++++++++++++++---
 5 files changed, 146 insertions(+), 51 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fba8c40b95..5e18d93a9b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2022-08-20  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-intro.el (find-video-links-intro): rewrote the section "5.1.
+       Subtitles".
+
 2022-08-14  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev-rstdoc.el: new file.
diff --git a/VERSION b/VERSION
index 03df9a4dd6..3b6c983bd7 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sun Aug 14 03:27:14 GMT 2022
-Sun Aug 14 00:27:14 -03 2022
+Sat Aug 20 05:37:56 GMT 2022
+Sat Aug 20 02:37:56 -03 2022
diff --git a/eepitch.el b/eepitch.el
index 58de9d651f..288b794a28 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -930,7 +930,8 @@ The arguments are explained here:
 ;;;                   |___/             |___/           
 ;;
 ;; «eepitch-langs»  (to ".eepitch-langs")
-;; See: (find-eepitch-intro "2.5. `find-comintprocess'")
+;; See: (find-eev-quick-intro "6.2. Other targets")
+;;      (find-eepitch-intro "2.5. `find-comintprocess'")
 
 ;; Shells:
 ;; These three are commented out because they are defined above.
diff --git a/eev-intro.el b/eev-intro.el
index 141af3b1a8..3f2252211a 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20220525
+;; Version:    20220820
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -11535,15 +11535,14 @@ The local copy will be played with Mpv, with:
 [NOTE: The support for subtitles was added
 in may/2022, and it's a work in progress]
 
-Some video have subtitles. The low-level way to download a video
-and its subtitles is with sexps like these ones - try them:
+Some of the videos in
 
-  (find-psne-eevvideo-links \"NAMEOFTHEVIDEO\" \"\")
-  (find-psne-eevvideo-links \"NAMEOFTHEVIDEO\" \".srt\")
-  (find-psne-eevvideo-links \"NAMEOFTHEVIDEO\" \".srt .vtt\")
+  http://angg.twu.net/eev-videos/
 
-The third sexp generates a temporary buffer whose core is this
-eepitch block:
+have subtitles in separate files. If a video called
+NAMEOFTHEVIDEO(.mp4) has subtitles in two formats, .srt and .srt,
+then the _low-level way_ to download it from the eev home page
+would be with this eepitch block:
 
  (eepitch-shell2)
  (eepitch-kill)
@@ -11554,58 +11553,79 @@ eepitch block:
   wget -N   http://angg.twu.net/eev-videos/NAMEOFTHEVIDEO.srt
   wget -N   http://angg.twu.net/eev-videos/NAMEOFTHEVIDEO.vtt
 
-The \"-nc\" says to wget that if the .mp4 (the video) is already
-downloaded then it (the wget) shouldn't try to download it again;
-the \"-N\" says to wget that if the version of the file at
-angg.twu.net is newer than the local copy then wget should
-download the newer version, and replace the local copy with the
-newer version. The argument \".srt .vtt\" is a list of the
-extensions of the subtitles.
+The eepitch block above follows all the conventions that are
+explained here,
 
-The high-level way to play a first-class video (see section 9)
-is with sexps like this one:
+  (find-psne-intro \"1. Local copies of files from the internet\")
 
-  (find-eev2021video)
+except for the arguments to wget. The help message for wget
+explains \"-nc\" and \"-N\" as:
 
-The sexp above calls:
+  (find-sh \"wget --help\" \"-nc, --no-clobber\")
+  (find-sh \"wget --help\" \"-N,  --timestamping\")
 
-  (find-1stclassvideo-video \"eev2021\")
+  -nc, --no-clobber        skip downloads that would download to
+                             existing files (overwriting them)
+  -N,  --timestamping      don't re-retrieve files unless newer than
+                             local
 
-and that sexp uses the information in `ee-1stclassvideos-info' -
-i.e., from here:
+The \".mp4\"s at angg.twu.net are never updated, so if we already
+have a local copy of the .mp4 then wget shouldn't try to download
+it again. In contrast, subtitle files are revised occasionally,
+so if the subtitle files on angg.twu.net are newer than the local
+copy then wget should download the newer version, and overwrite
+the local subtitle files with their newer versions.
 
-  (find-eev \"eev-videolinks.el\" \"ee-1stclassvideos-info\")
-  (find-1stclassvideodef \"eev2021\")
+The _medium-level way_ to download videos from angg.twu.net, with
+or without subtitles, is by running sexps like these ones:
 
-to convert the \"eev2021\" to the name of an .mp4 file. When the
-local copy of the video is not found the
-sexp `(find-1stclassvideo-video ...)' above calls this,
+  (find-psne-eevvideo-links \"NAMEOFTHEVIDEO\" \"\")
+  (find-psne-eevvideo-links \"NAMEOFTHEVIDEO\" \".srt\")
+  (find-psne-eevvideo-links \"NAMEOFTHEVIDEO\" \".srt .vtt\")
+
+Try them - they create temporary buffers with scripts like the
+one in the beginning of this section, but with different commands
+for downloading subtitles: the sexp with \".srt .vtt\" creates a
+script that downloads two subtitle files, the one with \".srt\"
+creates a script that downloads just one, and the sexp with \"\"
+creates a script that doesn't try to download any subtitle files.
 
-  (find-psne-1stclassvideo-links \"eev2021\")
+The _high-level way_ to play a first-class video is with sexps
+like this one - see section 9 for details:
 
-that is similar to `find-psne-eevvideo-links'. Compare:
+  (find-eev2021video)
 
-  (find-psne-1stclassvideo-links \"eev2021\")
-  (find-psne-eevvideo-links \"emacsconf2021\" \".vtt\")
+The sexp above calls this one,
+
+  (find-1stclassvideo-video \"eev2021\")
 
-The conversion from \"eev2021\" to \"emacsconf2021\" and \".vtt\"
-is done by:
+that will play the local copy of the video if it exists, or
+download a local copy if we don't have a local copy of it yet.
+The entry about the video \"eev2021\" in the list of first-class
+videos is here:
 
-  (ee-1stclassvideos-mp4stem \"eev2021\")
-  (ee-1stclassvideos-field   \"eev2021\" :subs)
+  (find-eev \"eev-videolinks.el\" \"eev2021\")
 
-The support for subtitles is recent, and is still a bit
-primitive. The temporary buffer generated by
+Try these sexps:
+
+  (ee-1stclassvideos-mp4stem  \"eev2021\")
+  (ee-1stclassvideos-localmp4 \"eev2021\")
+  (ee-1stclassvideos-mp4found \"eev2021\")
+  (ee-1stclassvideos-field    \"eev2021\"       :subs)
+  (ee-1stclassvideos-field    \"2021workshop5\" :subs)
+
+You will see that the video \"eev2021\" has subtitles, and the
+video \"2021workshop5\" doesn't.
+
+NOTE: the support for subtitles is recent, and is still a bit
+rough. The temporary buffer generated by
 `find-1stclassvideo-links' contains a few extra lines when a
 video has subtitles - compare:
 
-  (find-1stclassvideo-links \"2022pict2elua\")
-  (find-1stclassvideo-links \"2021workshop6\")
-
-The video \"2022pict2elua\" has subtitles, and \"2021workshop6\"
-doesn't.
+  (find-1stclassvideo-links \"eev2021\")
+  (find-1stclassvideo-links \"2021workshop5\")
 
-The process of downloading or updating subtitles is not well
+but the process of downloading or updating subtitles is not well
 integrated in the rest of eev yet, and at this moment the
 \"right\" way to download or update subtitles is with
 `find-1stclassvideo-links' and with the link in its \"Download
diff --git a/eev-rstdoc.el b/eev-rstdoc.el
index 83be8f0b11..3d3f3740a2 100644
--- a/eev-rstdoc.el
+++ b/eev-rstdoc.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20220813
+;; Version:    20220818
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-rstdoc.el>
@@ -39,8 +39,44 @@
 ;;   https://lists.nongnu.org/mailman/listinfo/eev
 ;;
 ;;
-;; 1. Introduction 
-;; ===============
+;; 1. Very short introduction
+;; ==========================
+;; We can load this file and make it define some new functions with:
+;;
+;;   (load (buffer-file-name))
+;;   (ee-rstdoc-defun-all)
+;;
+;; After that these three sexps - try them! -
+;;
+;;   (find-pydoc  "tutorial/classes")
+;;   (find-pydocw "tutorial/classes")
+;;   (find-pydocr "tutorial/classes")
+;;   
+;; will work as sexp hyperlinks to these two URLs and this file:
+;;
+;;                https://docs.python.org/3/tutorial/classes.html
+;;            /usr/share/doc/python3.9/html/tutorial/classes.html
+;;   /usr/share/doc/python3.9/html/_sources/tutorial/classes.rst.txt
+;;
+;; If we look at the comments of `ee-rstdoc-defun-all', at
+;;
+;;   (find-eev "eev-rstdoc.el" "ee-rstdoc-defun-all")
+;;
+;; we will see that they are:
+;;
+;;   See: (find-code-rstdoc ee-rstdoc-python)
+;;        (find-code-rstdoc ee-rstdoc-sympy)
+;;        (find-code-rstdoc ee-rstdoc-matplotlib)
+;;
+;; The first `find-code-rstdoc' shows that the corresponding
+;; `code-rstdoc' defines four functions: `find-pydoc', `find-pydocw',
+;; `find-pydocr', and `pdk'. The first three are very easy to
+;; understand; the fourth, `pdk', is much stranger, and it is it that
+;; makes this module practical to use.
+;;
+;;
+;; 2. Long introduction 
+;; ====================
 ;; On my Debian box I have two local files that are related to this
 ;; page of the Python docs:
 ;;
@@ -190,8 +226,11 @@
 ;;           (code-rstdoc ee-rstdoc-python)
 ;;   ;; (find-code-rstdoc ee-rstdoc-sympy)
 ;;           (code-rstdoc ee-rstdoc-sympy)
+;;   ;; (find-code-rstdoc ee-rstdoc-matplotlib)
+;;           (code-rstdoc ee-rstdoc-matplotlib)
 
 
+;; «.ee-rstdoc-defun-all»      (to "ee-rstdoc-defun-all")
 
 ;; Should I use cl-defstruct instead?
 ;; See: (find-node "(cl)Structures" "cl-defstruct")
@@ -268,6 +307,9 @@
          (kill      (slot-value rd 'kill))
         )
     (ee-template0 "\
+;; (find-code-rstdoc {name})
+;; See: (find-eev-quick-intro \"9.1. `code-c-d'\")
+;;
 (defun {find-html} (str &rest rest)
   \"Open the local html page associated to the rstdoc STR.
 This function uses {name} to transform STR in the right way.\"
@@ -296,8 +338,9 @@ and to convert it into a sexp.\"
 (setq ee-rstdoc-python
       (ee-rstdoc
        :name      'ee-rstdoc-python
-       :res       '("#.*$" ".html$" ".rst.txt$" "^file://"
+       :res       '("#.*$" "\\?.*$" ".html$" ".rst.txt$" "^file://"
                     "^https://docs.python.org/3/";
+                   "^/usr/share/doc/python[0-9.]*-doc/html/"
                    "^/usr/share/doc/python3-doc/html/"
                    "^/usr/share/doc/python3.9-doc/html/")
        :base-html "file:///usr/share/doc/python3.9-doc/html/"
@@ -312,7 +355,7 @@ and to convert it into a sexp.\"
 (setq ee-rstdoc-sympy
       (ee-rstdoc
        :name      'ee-rstdoc-sympy
-       :res       '("#.*$" ".html$" ".rst.txt$" "^file://"
+       :res       '("#.*$" "\\?.*$" ".html$" ".rst.txt$" "^file://"
                    "^/usr/share/doc/python-sympy-doc/html/"
                    "^/docs.sympy.org/latest/")
        :base-html "file:///usr/share/doc/python-sympy-doc/html/"
@@ -324,6 +367,32 @@ and to convert it into a sexp.\"
        :kill      'sdk
        ))
 
+(setq ee-rstdoc-matplotlib
+      (ee-rstdoc
+       :name      'ee-rstdoc-matplotlib
+       :res       '("#.*$" "\\?.*$" ".html$" ".rst.txt$" "^file://"
+                   "^/usr/share/doc/python-matplotlib-doc/html/"
+                   "^/docs.matplotlib.org/latest/")
+       :base-html "file:///usr/share/doc/python-matplotlib-doc/html/"
+       :base-rst  "/usr/share/doc/python-matplotlib-doc/html/_sources/"
+       :base-web  "https://matplotlib.org/stable/";
+       :find-html 'find-mpldoc
+       :find-rst  'find-mpldocr
+       :find-web  'find-mpldocw
+       :kill      'mdk
+       ))
+
+;; «ee-rstdoc-defun-all»  (to ".ee-rstdoc-defun-all")
+;; See: (find-code-rstdoc ee-rstdoc-python)
+;;      (find-code-rstdoc ee-rstdoc-sympy)
+;;      (find-code-rstdoc ee-rstdoc-matplotlib)
+;;
+(defun ee-rstdoc-defun-all ()
+  (interactive)
+  (code-rstdoc ee-rstdoc-python)
+  (code-rstdoc ee-rstdoc-sympy)
+  (code-rstdoc ee-rstdoc-matplotlib))
+
 
 
 (provide 'eev-rstdoc)