[elpa] externals/eev 7589a9d394: Added more sections to (find-rstdoc-intro).

[ELPA Syncer]

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

    Added more sections to (find-rstdoc-intro).
---
 ChangeLog     |   5 ++
 VERSION       |   4 +-
 eev-intro.el  | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++-------
 eev-kla.el    |   9 +++
 eev-rstdoc.el |   3 +-
 eev-tlinks.el |   8 ++-
 6 files changed, 197 insertions(+), 27 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3e3bb83ca8..ea8813b0e8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2022-12-03  Eduardo Ochs  <eduardoochs@gmail.com>
 
+       * eev-intro.el (find-rstdoc-intro): added some sections.
+
+       * eev-tlinks.el (find-rstdoc-links): use another name for the
+       temporary buffer.
+
        * eev-videolinks.el (find-eev2022klavideo): new function.
        (ee-1stclassvideos-info): added an entry for "eev2022kla".
 
diff --git a/VERSION b/VERSION
index bc251a4e7d..ebb2742367 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sat Dec  3 09:59:52 GMT 2022
-Sat Dec  3 06:59:52 -03 2022
+Sat Dec  3 19:12:41 GMT 2022
+Sat Dec  3 16:12:41 -03 2022
diff --git a/eev-intro.el b/eev-intro.el
index 227d7f5ef9..fb68364b93 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -14586,6 +14586,7 @@ It is meant as both a tutorial and a sandbox.
     (find-eev-quick-intro \"4. Creating Elisp Hyperlinks\")
     (find-eev-quick-intro \"4.1. `find-here-links'\")
 
+  Video: (find-eev2022klavideo \"0:00\")
 
 
 
@@ -15510,7 +15511,12 @@ and in the last link,
   (find-pydocr \"reference/datamodel\" \"_numeric-types:\")
 
 the suffix `r' means \"open the source in .rst instead of the
- HTML version\".
+ HTML version\"; it opens this file
+
+  /usr/share/doc/python3.9/html/_sources/reference/datamodel.rst.txt
+
+and searches for the first occurrence of the string
+\"_numeric-types:\" in it.
 
 
 
@@ -15533,6 +15539,7 @@ string.
 
 
 
+
 3. `code-rstdoc'
 ================
 The six functions of the previous section are all part of the
@@ -15601,44 +15608,190 @@ functions: `:py', for Python itself, `:sympy', for 
SymPy, and
   (find-eppp       ee-rstdoc-:mpl)
   (find-code-rstdoc          :mpl)
 
+These `ee-rstdoc-:*'s contain plists. We can access some of their
+fields - the ones that are easier to understand - with:
 
+  (plist-get ee-rstdoc-:py :base-html)
+  (plist-get ee-rstdoc-:py :base-web)
+  (plist-get ee-rstdoc-:py :base-rst)
 
+and with the functions in:
 
+  (find-eev \"eev-rstdoc.el\" \"basic-ops\")
 
+The fields `:base-html', `:base-web', and `:base-html' are used
+in expansions. What are the other fields?
 
 
-If you are on Debian Stable then all the `find-pydoc*'s above should
-work out of the box.
 
+5. Shortening and killing
+=========================
+The documentation of Python in intended to be read in a browser.
+Suppose that we start here,
 
+  (find-pydocw \"tutorial/classes\")
+  https://docs.python.org/3/tutorial/classes.html
 
+and we navigate the docs a bit, and we find this other section
+that we want to keep a link to:
 
+  https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions
 
+Try this: put the point on the URL above and type `M-x pdk' - for
+\"Python doc kill\". The `pdk' will interpret the URL above as
+something that points to the Python docs, in the sense that it is
+related to the family defined by `ee-rstdoc-:py', not the ones
+for SymPy or MatPlotLib - and it will show this message in the
+echo area:
 
-See: (find-eev \"eev-rstdoc.el\" \"introduction\")
-     (find-eev \"eev-rstdoc.el\" \"default-defuns\")
-     (find-eev \"eev-rstdoc.el\" \"ee-rstdoc-:py\")
-     (find-code-rstdoc :py)
-Try:
+  Copied to the kill ring: # (find-pydoc 
\"tutorial/controlflow#lambda-expressions\")
+
+What happened here was that `pdk' \"shortened\" the URL above by
+deleting all the parts in it that are not the \"stem\" or the
+\"hashanchor\",
+
+  https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions
+                            \\------------------/     \\-----------------/
+                                   stem                  hashanchor
+
+then it produced this sexp,
+
+  (find-pydoc \"tutorial/controlflow#lambda-expressions\")
+        \\/     \\------------------/\\-----------------/
+        kw             stem             hashanchor
+
+using the \"py\" from the keyword `:py', the stem, and the
+hashanchor, and then it \"killed it\" - i.e., it copied it to the
+kill rings. The definition of `ee-rstdoc-:py' in eev-rstdoc.el is
+this one:
+
+  ;; From: (find-eev \"eev-rstdoc.el\" \"ee-rstdoc-:py\")
+  ;;       (find-evariable 'ee-rstdoc-:py)
+  (defvar ee-rstdoc-:py
+        '(:base      \"index\"
+          :base-web  \"https://docs.python.org/3/\";
+          :base-html \"file:///usr/share/doc/python3.9-doc/html/\"
+          :base-rst  \"/usr/share/doc/python3.9/html/_sources/\"
+          :rst       \".rst.txt\"
+          :res       (\"#.*$\" \"\\\\?.*$\" \".html$\" \".txt$\" \".rst$\" 
\"^file://\"
+                      \"^https://docs.python.org/3/\";
+                      \"^/usr/share/doc/python[0-9.]*-doc/html/\")
+          :kill      pdk
+       )
+        \"See: (find-code-rstdoc :py)\")
+
+and the field `:res' controls how the shortening should work -
+the value of the `:res' field is a list of regexps, and during
+the shortening each occurrence of each one of these regexps is
+replaced by the empty string.
+
+The field `:kill' in `ee-rstdoc-:py' determines the name of the
+killing function for the `:py' family. Take a look at the
+temporary buffer generated by the `find-code-rstdoc' below:
 
-  (ee-rstdoc-default-defuns)
-  (find-pydoc  \"tutorial/classes\")
-  (find-pydocw \"tutorial/classes\")
-  (find-pydocr \"tutorial/classes\")
+  ;; (find-code-rstdoc :py)
+          (code-rstdoc :py)
 
-2. Expansion
-============
+The last thing in that temporary buffer is a `(defun pdk ...)'
+that defines `pdk' \"in the right way\".
 
-3. Shrinking
-============
 
-4. `code-rstdoc'
-================
-See: (find-eev \"eev-rstdoc.el\" \"code-rstdoc\")
 
-5. `find-rstdoc-links'
+
+6. A workflow
+=============
+Let's suppose that you have just copied this URL from your
+browser to your notes:
+
+  https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions
+
+Run `M-x pdk' on it, go to the next line, and insert the sexp.
+You should get something like this:
+
+  https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions
+  # (find-pydoc \"tutorial/controlflow#lambda-expressions\")
+
+Usually what I do then is that I test the sexp to see if it works
+as expected, and if it does I delete the URL. So my workflow is:
+
+  1. copy an URL from the browser,
+  2. run `M-x pdk' (or `M-x sdk', or `M-x mdk') on it,
+  3. go to the next line,
+  4. insert the sexp,
+  5. test the sexp,
+  6. delete the URL.
+
+I tried to keep the code as simple as possible, so there isn't a
+\"smarter\" way with fewer steps - yet.
+
+Sometimes I also do this:
+
+  7. duplicate the sexp with `M-h M-2',
+  8. add a `w' or a `r' to the new sexp,
+  9. adjust the `find-pydocr' sexp.
+
+The \"adjust\" step is because the \"#lambda-expressions\" part
+in the second sexp below doesn't work, and I don't know a way to
+convert it - the \"hashanchor\" part - into a string to search
+for; so I convert the second sexp below into the third by hand,
+by trial and error. Try:
+
+  # (find-pydoc  \"tutorial/controlflow#lambda-expressions\")
+  # (find-pydocr \"tutorial/controlflow#lambda-expressions\")
+  # (find-pydocr \"tutorial/controlflow\" \"_tut-lambda:\")
+
+The documentation for Python has lots of code snippets. The most
+obvious way to convert them into executable notes - like this:
+
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+def make_incrementor(n):
+    return lambda x: x + n
+
+f = make_incrementor(42)
+f(0)
+f(1)
+
+is by using cut-and-paste from the browser to Emacs, but I find
+it much easier to open the .rst file and do cut-and-paste from it
+to my notes.
+
+
+
+
+7. `find-rstdoc-links'
 ======================
-Try: (find-rstdoc-links :py)
+The easiest way to define new families is by using
+`find-rstdoc-links'. Compare the temporary buffers generated by
+the two sexps below:
+
+  (find-2a
+    ' (find-rstdoc-links :py)
+    ' (find-rstdoc-links :foo)
+    )
+
+The `(find-rstdoc-links :foo)' shows lots of strings like
+\"BASE-WEB\", \"BASE-HTML\", \"BASE-RST\", and \"{kil}\", that
+indicate that `find-rstdoc-links' couldn't find good guesses for
+those parts of the template. In `(find-rstdoc-links :foo)' those
+\"holes\" don't exist, but compare:
+
+  (find-2a
+    ' (find-eev \"eev-rstdoc.el\" \"ee-rstdoc-:py\")
+    ' (find-rstdoc-links :py)
+    )
+
+The `defvar' in
+
+  (find-eev \"eev-rstdoc.el\" \"ee-rstdoc-:py\")
+
+uses some regexps that are smarter than the ones that were
+generated by the `find-rstdoc-links'...
+
+TODO: explain how to use `find-rstdoc-links'!
+
+
 
 
 " pos-spec-list)))
diff --git a/eev-kla.el b/eev-kla.el
index 7b8e0c7d13..45d2b1a6b7 100644
--- a/eev-kla.el
+++ b/eev-kla.el
@@ -31,6 +31,7 @@
 ;; «.a-test»                   (to "a-test")
 ;; «.more-tests»               (to "more-tests")
 ;; «.test-elsewhere»           (to "test-elsewhere")
+;; «.the-video»                        (to "the-video")
 ;;
 ;; «.ee-kl-expand»             (to "ee-kl-expand")
 ;; «.default-args»             (to "default-args")
@@ -148,6 +149,14 @@
 
 
 
+;; «the-video»  (to ".the-video")
+;; I recorded a video about this for the EmacsConf2022.
+;; The video is here:
+;;   (find-eev2022klavideo "0:00")
+;; and the page about it is here:
+;;   http://angg.twu.net/emacsconf2022-kla.html
+
+
 
 ;;;                  _    _                                       _ 
 ;;;   ___  ___      | | _| |       _____  ___ __   __ _ _ __   __| |
diff --git a/eev-rstdoc.el b/eev-rstdoc.el
index 98ef648b04..51004bcfa6 100644
--- a/eev-rstdoc.el
+++ b/eev-rstdoc.el
@@ -262,7 +262,8 @@
         :rst       ".rst.txt"
         :res       ("#.*$" "\\?.*$" ".html$" ".txt$" ".rst$" "^file://"
                     "^https://docs.python.org/3/";
-                    "^/usr/share/doc/python[0-9.]*-doc/html/")
+                    "^/usr/share/doc/python[0-9.]*-doc/html/"
+                    "^/usr/share/doc/python[0-9.]*/html/_sources/")
         :kill      pdk
        )
       "See: (find-code-rstdoc :py)")
diff --git a/eev-tlinks.el b/eev-tlinks.el
index e5cbd117ac..a9ad0576f2 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20221202
+;; Version:    20221203
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-tlinks.el>
@@ -3802,7 +3802,9 @@ N should be either a number or a symbol; SEXP should be a 
sexp."
         (bhtml0 (replace-regexp-in-string "^file://" "" bhtml))
          (kil    (or (ee-rstdoc-getfield0 kw :kill)
                     "{kil}")))
-    (let ((ee-buffer-name (or ee-buffer-name "*find-rstdoc-links*")))
+    (let ((ee-buffer-name
+          (or ee-buffer-name
+              (format "*(find-rstdoc-links %S)*" kw))))
       (apply
        'find-elinks-elisp
        `((find-rstdoc-links ,kw ,@pos-spec-list)
@@ -3810,7 +3812,7 @@ N should be either a number or a symbol; SEXP should be a 
sexp."
         (find-efunction 'find-rstdoc-links)
         ""
         ,(ee-template0 "\
-;; See: (find-rstdoc-intro \"5. `find-rstdoc-links'\")
+;; See: (find-rstdoc-intro \"7. `find-rstdoc-links'\")
 
 ;; <ee-rstdoc-{kw}>
 ;; Skel: (find-rstdoc-links {kw})