[elpa] externals/eev e0d1bf1 44/64: Added some sections to `find-escripts-intro'.

[Stefan Monnier]

branch: externals/eev
commit e0d1bf14fdfc6757bf4ee91199a2a19627d7d99d
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Added some sections to `find-escripts-intro'.
---
 ChangeLog    |   6 ++
 VERSION      |   4 +-
 eepitch.el   |  18 ++---
 eev-intro.el | 210 ++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 4 files changed, 203 insertions(+), 35 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index da135a4..e77ed61 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2019-02-28  Eduardo Ochs  <address@hidden>
+
+       * eepitch.el (at-nth-window): commented out.
+       (ee-with-pager-cat): renamed `with-pager-cat' to
+       `ee-with-pager-cat'.
+
 2019-02-27  Eduardo Ochs  <address@hidden>
 
        * eev-intro.el (find-escripts-intro): added several new sections.
diff --git a/VERSION b/VERSION
index 0bc821b..f5cb945 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Thu Feb 28 01:45:03 GMT 2019
-Wed Feb 27 22:45:03 -03 2019
+Thu Feb 28 20:07:42 GMT 2019
+Thu Feb 28 17:07:42 -03 2019
diff --git a/eepitch.el b/eepitch.el
index 5eca200..654dbf3 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb16
+;; Version:    2019feb28
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eepitch.el>
@@ -632,18 +632,18 @@ Note the DIR is `ee-expand'-ed."
   (interactive "beepitch to buffer: ")
   (eepitch `(switch-to-buffer ,name)))
 
-(defun with-pager-cat (code)
+(defun ee-with-pager-cat (code)
   "Run CODE with the environment variable PAGER set to \"cat\".
 This is useful for for running processes that use pagers like
 \"more\" by default."
   (let ((process-environment (cons "PAGER=cat" process-environment)))
     (eval code)))
 
-(defun at-nth-window (n code)
-  "Run `other-window' N times, run CODE there, and go back."
-  (save-selected-window
-    (other-window n)
-    (eval code)))
+;; (defun at-nth-window (n code)
+;;   "Run `other-window' N times, run CODE there, and go back."
+;;   (save-selected-window
+;;     (other-window n)
+;;     (eval code)))
 
 
 
@@ -711,7 +711,7 @@ This is useful for for running processes that use pagers 
like
 (defun eepitch-maxima () (interactive) (eepitch-comint "maxima" "maxima"))
 (defun eepitch-octave () (interactive) (eepitch-comint "octave" "octave"))
 (defun eepitch-R () (interactive)
-  (eepitch '(with-pager-cat (find-comintprocess "R" "R"))))
+  (eepitch '(ee-with-pager-cat (find-comintprocess "R" "R"))))
 
 ;; Plotters.
 ;; We force GhostScript's resolution to make its window fit on the screen.
@@ -729,7 +729,7 @@ This is useful for for running processes that use pagers 
like
 
 ;; SQL. To do: add postgres and sqlite
 (defun eepitch-mysql () (interactive)
-  (eepitch '(with-pager-cat '(find-comintprocess "mysql" "mysql -u root"))))
+  (eepitch '(ee-with-pager-cat '(find-comintprocess "mysql" "mysql -u root"))))
 
 ;; SmallTalk
 (defun eepitch-gst () (interactive)
diff --git a/eev-intro.el b/eev-intro.el
index 42db115..55d85a3 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -1127,7 +1127,7 @@ beginning of the file, as explained here:
 8.4. Creating e-script blocks
 -----------------------------
 The key `M-B' (`eewrap-escript-block') is a variant of `M-A' that
-converts the current line into seven (!) lines instead of two. If
+converts the current line into nine (!) lines instead of two. If
 we type `M-B' on the line below
 
   second-test Long description
@@ -5912,7 +5912,7 @@ in #eev than when in #emacs. See:
 
 
 3. Other channels
-==============
+=================
 
 where `find-freenode-3a' is based on `find-3a', described here:
 
@@ -7640,19 +7640,17 @@ easy to \"play back\" later, step by step and in any 
order. We
 call these executable logs \"e-scripts\".
 
 We will start this intro by explaining how eev and e-scripts
-appeared. Then we will discuss some of the most usual formats of
-e-scripts, that are, in order or complexity:
+appeared. Then we will see how to read and play back a sample
+e-script, and understand its conventions; then we will see some
+tools to help writing e-scripts in several usual formats:
 
-  1) a file with elisp hyperlinks and eepitch blocks,
+  1) a file with hyperlinks and eepitch blocks,
   2) a file with e-script blocks and an index,
-  3) several files with elisp hyperlinks and e-script blocks,
+  3) several files with e-script blocks and indexes,
   4) source files with eepitch blocks in multi-line comments,
-  5) temporary buffers like the ones generated by
+  5) temporary buffers, like the ones generated by
      `find-latex-links' and `find-lua-links'.
 
-We will see first how to \"read\" (and \"play back\"!) them, then
-how to create e-scripts in those formats.
-
 
 
 
@@ -7825,6 +7823,7 @@ They had to be stripped of their status.
 
 
 
+
 4. How to read an e-script
 ==========================
 The indented block below between the two \"snip, snip\" lines -
@@ -7888,6 +7887,7 @@ reviewed in the subsections below.
   wget http://angg.twu.net/e/lua-intro.e
 
   # (find-fline \"/tmp/lua-intro.e\")
+  # (find-anchor \"/tmp/lua-intro.e\" \"intro:types\")
   # (defun eejump-11 () (find-fline \"/tmp/lua-intro.e\"))
 
   --snip, snip--
@@ -8035,11 +8035,6 @@ When we execute this eepitch block a first time,
   rm -v lua-intro.e
   wget http://angg.twu.net/e/lua-intro.e
 
-  rm -v lua-intro.e lua50init.lua
-  wget http://angg.twu.net/e/lua-intro.e
-  wget http://angg.twu.net/LUA/lua50init.lua
-
-
 the \"rm\" gives an error:
 
   rm: cannot remove 'lua-intro.e': No such file or directory
@@ -8048,26 +8043,193 @@ When we execute it a second, third, fourth time, the 
\"rm\"
 deletes the file \"/tmp/lua-intro.e\" that the wget downloaded in
 the previous run.
 
-  (...)
+I usually write my eepitch blocks a few lines at a time, and I
+test the new lines by running the whole block again from the
+beginning. This means that for me most of the time a line like
 
-  (find-anchor \"/tmp/lua-intro.e\" \"intro:types\")
+  rm -v lua-intro.e
 
+does not give an error - and I got used to ignoring the error
+when it's run for the first time.
 
+Most e-scripts in
 
+  http://angg.twu.net/e/
+
+follow these conventions:
+
+  1) they can be re-run,
+  2) they start with clean-up code,
+  3) I prefer to write the clean-up code to be short, even when
+     this means that I will have to ignore errors and warnings.
+
+
+
+
+5. Tools for writing e-scripts
+==============================
+
+5.1. Anchors-to pairs and e-script blocks
+-----------------------------------------
+Anchor-to pairs can be generated easily using `M-A':
+
+  (find-eev-quick-intro \"8.3. Creating index/section anchor pairs\")
+  (find-eev-quick-intro \"8.3. Creating index/section anchor pairs\" \"M-A\")
+
+Typing `M-A' on this line:
+
+  # <bletch>
+
+yields this pair of anchor-to lines:
+
+  # �.bletch�  (to \"bletch\")
+  # �bletch�   (to \".bletch\")
+
+let's call the first one a \"to-forward\" and the second one a
+\"to-back\". In my e-scripts files I follow the convention that
+the to-forwards are all together at the beginning of the file,
+forming an index of sections of the file, and each to-back is at
+the beginning of a section. Most of the source files of eev
+follow this convention; see, for example:
+
+  (find-eev \"eev-blinks.el\" \".eek\")
+  (find-eev \"eev-blinks.el\" \"eek\")
+
+Note that there, and in most source files of eev, above each
+to-back line there a title in big letters in ASCII art in Lisp
+comments.
+
+After creating a to-forward-to-back pair with `M-A' we have to
+move the to-forward line to the index by hand, using cut and
+paste.
+
+In the e-script files in
+
+  http://angg.twu.net/e/
+
+I follow another convention - \"e-script blocks\". The title
+above each to-backward line is written like this:
+
+  #####
+  #
+  # Long description for the section Bletch
+  # 2016feb29
+  #
+  #####
+
+Note that you can generate a title in \"#\"s like that, followed
+by a to-forward-to-back pair, by typing `M-B' on a line like:
+
+  bletch Long description for the section Bletch
+
+See:
+
+  (find-eev-quick-intro \"8.4. Creating e-script blocks\")
+  (find-eev-quick-intro \"8.4. Creating e-script blocks\" \"`M-B'\")
+
+The to-forward line still has to be moved to the index by cut and
+paste by hand.
 
 
-5. Creating e-scripts
-=====================
 
-2. The comment block that says \"The main Debian packages for Lua
-   5.1\" is simply a way to distinguish visually one e-script
-   block from its neighboring ones. It was produced by `M-B', as
-   explained here:
 
-     (find-eev-quick-intro \"8.4. Creating e-script blocks\" \"`M-B'\")
+5.2. Debian hyperlinks
+----------------------
+The key `M-D' converts a line with the name of a Debian package,
+like this,
+
+lua5.1-doc
+
+to these three hyperlinks,
+
+# (find-status   \"lua5.1-doc\")
+# (find-vldifile \"lua5.1-doc.list\")
+# (find-udfile   \"lua5.1-doc/\")
+
+and moves the point to the next line. Try it! Put the point on
+the \"bash\" line below and type `M-D M-D M-D':
+
+bash
+lua5.1
+lua5.1-doc
+
+
+
+
+5.3. URL hyperlinks
+-------------------
+I usually \"write\" URLs in Emacs by copying them from a browser
+to Emacs.
 
 
 
+5.4. Eepitch blocks
+-------------------
+We saw in 
+
+  (find-eev-quick-intro \"6.3. Creating eepitch blocks: `M-T'\")
+
+how to create eepitch blocks with `M-T'. Try that on the line
+that says \"lua51\" below:
+
+lua51
+
+
+
+5.5. `rm/mkdir/cd' triples
+--------------------------
+Try typing `M-R' on the line with the \"/tmp/foo/\" below:
+
+/tmp/foo/
+
+
+
+
+5.6. Hyperlinks to files, directories, and info nodes
+-----------------------------------------------------
+One practical way to create a `find-fline' hyperlink is with
+`M-F' (`eewrap-find-fline'). Try it here:
+
+/usr/share/doc/lua5.1-doc/test/
+/usr/share/doc/lua5.1-doc/test/README
+/usr/share/doc/lua5.1-doc/test/fibfor.lua
+
+Note that the three lines above were copied from:
+
+  (find-vldifile \"lua5.1-doc.list\")
+  (find-vldifile \"lua5.1-doc.list\" \"/usr/share/doc/lua5.1-doc/test\")
+
+Another way is by visiting a file and typing `M-h M-h'. See:
+
+  (find-eev-quick-intro \"4.1. `find-here-links'\")
+
+This can also be used to generate links to info nodes.
+
+(...)
+
+
+
+5.7. Refining hyperlinks
+------------------------
+(...)
+
+5.8. Pointing to anchors
+------------------------
+(...)
+
+5.9. Using a TODO file
+----------------------
+(...)
+
+5.10. Using several e-script files
+----------------------------------
+(...)
+
+5.11. Eepitch blocks in multi-line comments
+-------------------------------------------
+(...)
+
+
 
 " pos-spec-list)))