[elpa] externals/eev 3baac40 43/64: Added some sections to `find-escripts-intro'.

[Stefan Monnier]

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

    Added some sections to `find-escripts-intro'.
---
 ChangeLog     |   8 ++
 VERSION       |   4 +-
 eev-blinks.el |   7 +-
 eev-code.el   |  48 +++++++---
 eev-elinks.el |   2 +-
 eev-intro.el  | 296 +++++++++++++++++++++++++++++++++++++++-------------------
 6 files changed, 254 insertions(+), 111 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 040079d..da135a4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2019-02-27  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-escripts-intro): added several new sections.
+
+       * eev-code.el: better comments.
+
+       * eev-elinks.el: better comments.
+
 2019-02-26  Eduardo Ochs  <address@hidden>
 
        * eev-intro.el (find-eev-quick-intro, find-eev-intro)
diff --git a/VERSION b/VERSION
index d360ec3..0bc821b 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Tue Feb 26 16:50:11 GMT 2019
-Tue Feb 26 13:50:11 -03 2019
+Thu Feb 28 01:45:03 GMT 2019
+Wed Feb 27 22:45:03 -03 2019
diff --git a/eev-blinks.el b/eev-blinks.el
index 9111b29..d62a5df 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -23,7 +23,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb23
+;; Version:    2019feb27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -695,6 +695,11 @@ it doesn't convert relative filenames into urls. See
 ;;   (find-available      "bash")
 ;;   (find-grep-status    "bash")
 ;;   (find-grep-available "bash")
+;;
+;; Note that these links are all equivalent:
+;;   (find-status                                    "bash")
+;;   (find-Package "/var/lib/dpkg/status"            "bash")
+;;   (find-fline   "/var/lib/dpkg/status" "\nPackage: bash\n")
 
 (defun find-Package (fname &optional packagename &rest pos-spec-list)
   "Hyperlink to \"Package: \" achors in Debian package control files.
diff --git a/eev-code.el b/eev-code.el
index 1325d61..0fdf2a7 100644
--- a/eev-code.el
+++ b/eev-code.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb24
+;; Version:    2019feb27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-code.el>
@@ -45,13 +45,15 @@
 
 
 
+;; �.alists�           (to "alists")
+;; �.code-c-d-pairs�   (to "code-c-d-pairs")
+;; �.code-c-d�         (to "code-c-d")
+;; �.code-c-d-s�       (to "code-c-d-s")
+
+
+
 
 
-;; A simple and flexible implementation of argument lists.
-;; Inspired by: (find-node "(cl)Argument Lists")
-;;              (find-node "(cl)Argument Lists" "&body")
-;;    See also: (find-elnode "Symbol Type" "`:'")
-;;              (find-elnode "Constant Variables")
 ;; The name "tail call" is misleading - this is recursive,
 ;; but not a tail call in the usual sense.
 
@@ -71,25 +73,44 @@
 ;;; | (_| | | \__ \ |_\__ \
 ;;;  \__,_|_|_|___/\__|___/
 ;;;                        
+;; �alists� (to ".alists")
+;; A simple and flexible implementation of argument lists.
+;; Inspired by: (find-node "(cl)Argument Lists")
+;;              (find-node "(cl)Argument Lists" "&body")
+;;    See also: (find-elnode "Symbol Type" ":" "keyword")
+;;              (find-elnode "Constant Variables")
 
+;; Test: (ee-aref '((1 . one) (2 . two) (3 . three)) 2)
+;;                              -> two
 (defun ee-aref (alist idx)
   "Like `aref', but for alists.
 Example: (ee-aref '((1 . one) (2 . two) (3 . three)) 2)
                                 -> two"
   (cdr (assoc idx alist)))
 
+;; Test: (ee-adel '((1 . one) (2 . two) (3 . three)) 2)
+;;              -> ((1 . one)           (3 . three))
+;;
 (defun ee-adel (alist idx)
   "Like `remq', but for alists. This is non-destructive, so wrap it in a setq.
 Example: (ee-adel '((1 . one) (2 . two) (3 . three)) 2)
                 -> ((1 . one)           (3 . three))"
   (remq (assoc idx alist) alist))
 
+;; Test: (ee-aset '((1 . one) (2 . two) (3 . three)) 2 'foo)
+;;    -> ((2 . foo) (1 . one)           (3 . three))
+;;
 (defun ee-aset (alist idx newelt)
   "Like `aset', but for alists. This is non-destructive, so wrap it in a setq.
 Example: (ee-aset '((1 . one) (2 . two) (3 . three)) 2 'foo)
       -> ((2 . foo) (1 . one)           (3 . three))"
   (cons (cons idx newelt) (ee-adel alist idx)))
 
+;; Tests: (ee-areplace '((1 . one) (2 . two) (3 . three)) 2 'foo)
+;;                   -> ((1 . one) (2 . foo) (3 . three))
+;;        (ee-areplace '((1 . one) (2 . two) (3 . three)) 0 'zero)
+;;        -> ((0 . zero) (1 . one) (2 . two) (3 . three))
+;;
 (defun ee-areplace (alist idx newelt)
   "Like `ee-aset', but keeping the order.
 Examples: (ee-areplace '((1 . one) (2 . two) (3 . three)) 2 'foo)
@@ -101,14 +122,17 @@ Examples: (ee-areplace '((1 . one) (2 . two) (3 . three)) 
2 'foo)
             alist)
     (cons (cons idx newelt) alist)))
 
+
+
 ;;;                _                          _                   _          
 ;;;   ___ ___   __| | ___        ___       __| |      _ __   __ _(_)_ __ ___ 
 ;;;  / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| '_ \ / _` | | '__/ __|
 ;;; | (_| (_) | (_| |  __/_____| (_|_____| (_| |_____| |_) | (_| | | |  \__ \
 ;;;  \___\___/ \__,_|\___|      \___|     \__,_|     | .__/ \__,_|_|_|  |___/
 ;;;                                                  |_|                     
-;; Old: (find-evardescr 'code-c-d-keywords)
-;;      (find-evariable 'code-c-d-keywords)
+;;
+;; �code-c-d-pairs� (to ".code-c-d-pairs")
+;; Used by: (find-eev "eev-elinks.el" "ee-code-c-d-filter")
 
 (defvar ee-code-c-d-pairs nil
   "Each (code-c-d C D) call generates an entry (C (ee-expand D)) here.
@@ -129,7 +153,8 @@ is used by some functions in \"eev-insert.el\".")
 ;;; | (_| (_) | (_| |  __/_____| (_|_____| (_| |
 ;;;  \___\___/ \__,_|\___|      \___|     \__,_|
 ;;;                                             
-;; See: (find-code-c-d-intro)
+;; �code-c-d� (to ".code-c-d")
+;; See: (find-eev-quick-intro "9.1. `code-c-d'")
 ;; Try: (find-code-c-d "lua51" "~/usrc/lua-5.1.4/")
 ;;      (find-code-c-d "lua51" "~/usrc/lua-5.1.4/" :anchor)
 
@@ -273,7 +298,8 @@ Note: the POS-SPEC-LIST arguments are currently not used."
 ;;; | (_| (_) | (_| |  __/_____| (_|_____| (_| \__ \
 ;;;  \___\___/ \__,_|\___|      \___|     \__,_|___/
 ;;;                                                 
-;; Some default `code-c-d's (debian-centric)
+;; �code-c-d-s� (to ".code-c-d-s")
+;; Some default `code-c-d's (debian-centric).
 
 (defun ee-locate-library (fname)
   (if (locate-library fname)
@@ -314,7 +340,7 @@ Note: the POS-SPEC-LIST arguments are currently not used."
 
 ;; Local Variables:
 ;; coding:            raw-text-unix
-;; ee-anchor-format:  "�%s�"
 ;; ee-anchor-format:  "defun %s "
+;; ee-anchor-format:  "�%s�"
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev-elinks.el b/eev-elinks.el
index d43ddb9..ba83314 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb25
+;; Version:    2019feb27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
diff --git a/eev-intro.el b/eev-intro.el
index 9a3ae02..42db115 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb26
+;; Version:    2019feb27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -2950,7 +2950,7 @@ and step (3) sometimes gives several sexps for us to 
choose from]
 
 
 4. ee-hyperlink-prefix
-=======================
+======================
 `ee-hyperlink-prefix' is both a variable and a function that
 helps us set that variable; it started to an experiment on how to
 create an alternative to `M-x customize' and ended up becoming
@@ -2989,7 +2989,7 @@ Try this, with `M-2 M-e' on each line:
 
 
 5. The first line regenerates the buffer
-=========================================
+========================================
 \[To do: explain this convention with examples; explain the
 conventions for the \"variants of the first line\"\]
 
@@ -3003,7 +3003,7 @@ conventions for the \"variants of the first line\"\]
 
 
 6. Pointing to where we are now
-================================
+===============================
 Several of the `M-h' commands are mainly meant to help us
 generate hyperlinks to \"where we are now\": to the current file,
 to the current Info page, to the current `find-*-intro', to an
@@ -3046,7 +3046,7 @@ buffer, and so on. They don't try to be very smart -
 
 
 7. The rest of the buffer
-==========================
+=========================
 Several elisp hyperlinks buffers are composed of two parts: a
 series of links at the top, and then a template-generated text
 that is mean to be copied to somewhere else. The canonical
@@ -7643,7 +7643,7 @@ 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:
 
-  1) a file with elisp hyperlinks,
+  1) a file with elisp hyperlinks and eepitch blocks,
   2) a file with e-script blocks and an index,
   3) several files with elisp hyperlinks and e-script blocks,
   4) source files with eepitch blocks in multi-line comments,
@@ -7817,152 +7817,256 @@ they only very rarely showed me their code or notes, 
and I can
 remember only a handful of cases in which we sat side-by-side on
 a terminal.
 
-These people should be stripped of their hacker status.
+These people - who shared very little - were the most respected
+hackers of that place.
 
+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 -
+we will call it \"Example 1\" - exemplifies most of the basic
+techniques available for e-scripts. These techniques will be
+reviewed in the subsections below.
 
 
-# �.lua5.1-debian�     (to \"lua5.1-debian\")
-# �.lua-tutorial�      (to \"lua-tutorial\")
+  --snip, snip--
 
+  # Index:
+  # �.lua5.1-debian�   (to \"lua5.1-debian\")
+  # �.lua-tutorial�    (to \"lua-tutorial\")
 
 
-#####
-#
-# The main Debian packages for Lua 5.1
-# 2018jun02
-#
-#####
 
-# �lua5.1-debian� (to \".lua5.1-debian\")
-# (find-status   \"lua5.1\")
-# (find-vldifile \"lua5.1.list\")
-# (find-udfile   \"lua5.1/\")
-# (find-status   \"lua5.1-doc\")
-# (find-vldifile \"lua5.1-doc.list\")
-# (find-udfile   \"lua5.1-doc/\")
-# (find-udfile   \"lua5.1-doc/doc/\")
-# (find-udfile   \"lua5.1-doc/test/\")
-# http://www.lua.org/docs.html
-# http://www.lua.org/manual/5.1/manual.html
-# file:///usr/share/doc/lua5.1-doc/doc/manual.html
+  #####
+  #
+  # The main Debian packages for Lua 5.1
+  # 2018jun02
+  #
+  #####
 
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-sudo apt-get install lua5.1 lua5.1-doc
+  # �lua5.1-debian� (to \".lua5.1-debian\")
+  # (find-status   \"lua5.1\")
+  # (find-vldifile \"lua5.1.list\")
+  # (find-udfile   \"lua5.1/\")
+  # (find-status   \"lua5.1-doc\")
+  # (find-vldifile \"lua5.1-doc.list\")
+  # (find-udfile   \"lua5.1-doc/\")
+  # (find-udfile   \"lua5.1-doc/doc/\")
+  # (find-udfile   \"lua5.1-doc/test/\")
+  # http://www.lua.org/docs.html
+  # http://www.lua.org/manual/5.1/manual.html
+  # file:///usr/share/doc/lua5.1-doc/doc/manual.html
 
+   (eepitch-shell)
+   (eepitch-kill)
+   (eepitch-shell)
+  sudo apt-get install lua5.1 lua5.1-doc
 
 
 
-#####
-#
-# Downloading and opening the eev-based Lua tutorial
-# 2018jun02
-#
-#####
 
-# �lua-tutorial� (to \".lua-tutorial\")
-# http://angg.twu.net/e/lua-intro.e.html
-# http://angg.twu.net/e/lua-intro.e
-# (find-es \"lua-intro\")
+  #####
+  #
+  # Downloading and opening an eev-based Lua tutorial
+  # 2018jun02
+  #
+  #####
 
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-cd /tmp/
-rm -v lua-intro.e
-wget http://angg.twu.net/e/lua-intro.e
+  # �lua-tutorial� (to \".lua-tutorial\")
+  # http://angg.twu.net/e/lua-intro.e.html
+  # http://angg.twu.net/e/lua-intro.e
 
-# (find-fline \"/tmp/lua-intro.e\")
-# (defun eejump-11 () (find-fline \"/tmp/lua-intro.e\"))
+   (eepitch-shell)
+   (eepitch-kill)
+   (eepitch-shell)
+  cd /tmp/
+  rm -v lua-intro.e
+  wget http://angg.twu.net/e/lua-intro.e
 
+  # (find-fline \"/tmp/lua-intro.e\")
+  # (defun eejump-11 () (find-fline \"/tmp/lua-intro.e\"))
 
+  --snip, snip--
 
 
 
-Let's name its parts - they will be explained in the sections below.
 
-1. The lines with �.lua5.1-debian� and �lua5.1-debian� use
-   the `(to ...)' sexps to \"point to one another\". They are
-   explained at:
+4.1. Anchors and `to'
+---------------------
+The two lines below
 
-     (find-eev-quick-intro \"8. Anchors\")
+  # �.foo�      (to \"foo\")
+  # �foo�      (to \".foo\")
 
-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:
+\"point to one another\". This is explained here:
 
-     (find-eev-quick-intro \"8.4. Creating e-script blocks\")
+  (find-eev-quick-intro \"8. Anchors\")
 
-3. The sexps starting with `find-status' and other `find-xxx's
-   are elisp hyperlinks.
+We used this in Example 1 to create an index. Compare with:
 
-4. The lines with \"http://...\"; and \"file:///...\" contain URLs
-   that can be visited using `browse-url' or with `brg' and other
-   `brxxx' functions.
+  # Index:
+  # �.one�     (to \"one\")
+  # �.two�     (to \"two\")
 
-5. The lines with a red star, like \" (eepitch-shell)\", start
-   \"eepitch blocks\", that are explained here:
+  ###
+  ## Stuff in block \"one\"
+  ###
 
-     (find-eev-quick-intro \"6. Controlling shell-like programs\")
+  # �one� (to \".one\")
+  (...)
 
-6. The lines just below the lines with \"\"s are shell commands
-   that can be executed with eepitch.
+  ###
+  ## Stuff in block \"two\"
+  ###
 
+  # �two� (to \".two\")
 
 
 
+4.2. Debian hyperlinks
+----------------------
+The hyperlinks using `find-status', `find-vldifile', and
+`find-udfile' are hyperlinks to information about a Debian
+package. These hyperlinks
 
-1. Reading e-scripts
-====================
+  (find-status   \"bash\")
+  (find-vldifile \"bash.list\")
+  (find-udfile   \"bash/\")
 
-1.1. A miniature example
-------------------------
+are equivalent to:
 
-1.1. Elisp hyperlinks
----------------------
+  (find-fline \"/var/lib/dpkg/status\" \"\\nPackage: bash\\n\")
+  (find-fline \"/var/lib/dpkg/info/bash.list\")
+  (find-fline \"/usr/share/doc/bash/\")
 
-\(Mention code-c-d)
+See:
+
+  (find-eev \"eev-blinks.el\" \"find-Package\")
+  (find-eev \"eev-blinks.el\" \"find-Package\" \"find-status\")
+  (find-eev-quick-intro \"9.1. `code-c-d'\")
+  (find-eev-quick-intro \"9.1. `code-c-d'\" \"(code-c-d \\\"ud\\\"\")
+  (find-eev \"eev-code.el\" \"code-c-d-s\")
+  (find-eev \"eev-code.el\" \"code-c-d-s\" \"(code-c-d \\\"ud\\\"\")
+  (find-eev \"eev-code.el\" \"code-c-d-s\" \"(code-c-d \\\"vldi\\\"\")
 
-1.2. Shorter elisp hyperlinks
------------------------------
 
-1.3. URLs
----------
 
-1.4. Eepitch blocks
+4.3. URL hyperlinks
 -------------------
+The lines
 
-1.5. Anchors, indexes and e-script blocks
------------------------------------------
+  # http://www.lua.org/docs.html
+  # http://www.lua.org/manual/5.1/manual.html
+  # file:///usr/share/doc/lua5.1-doc/doc/manual.html
 
-1.6. E-scripts embedded in other files
---------------------------------------
+are URL hyperlinks. Here's how to follow them:
 
+  (find-eev-quick-intro \"3.1. Non-elisp hyperlinks\")
 
+Note that the \"file:///\" URL above points to a local copy of
+the Lua manual at \"http://www.lua.org/manual/5.1/manual.html\"; -
+but the local copy will only exist if the Debian package
+\"lua5.1-doc\" is installed.
 
-2. Writing e-scripts
-====================
 
-2.1. Creating hyperlinks with `M-h M-h'
----------------------------------------
 
-2.3. Refining hyperlinks
-------------------------
+4.4. Eepitch blocks
+-------------------
+This
 
-2.4. Creating eepitch blocks
-----------------------------
+   (eepitch-shell)
+   (eepitch-kill)
+   (eepitch-shell)
+  sudo apt-get install lua5.1 lua5.1-doc
 
+is an \"eepitch block\", as explained here:
+
+  (find-eev-quick-intro \"6. Controlling shell-like programs\")
+  (find-eev-quick-intro \"6.1. The main key: <F8>\")
+
+Note that it will only work if you delete the whitespace before
+the \"\"s!
+
+
+
+4.5. Htmlized e-scripts
+-----------------------
+The \"Eev Manifesto\" in section 3 above has this:
+
+  I have placed essentially all my \"scripts\" written in this
+  way (I call them \"e-scripts\") in a public place. They contain
+  almost everything I know about Unix.
+
+The \"public place\" is here:
+
+  http://angg.twu.net/e/
+
+The links
+
+  # http://angg.twu.net/e/lua-intro.e.html
+  # http://angg.twu.net/e/lua-intro.e
+
+point to one of these e-scripts - one that I use to teach (or
+introduce) Lua to people that already know other programming
+languages. The
+
+  # http://angg.twu.net/e/lua-intro.e.html
+
+point to an \"htmlized version\" of it, in which many of the
+hyperlinks are converted to something that works in a browser.
+The header of the .html explains briefly how the htmlized version
+is produced.
+
+
+
+
+4.6. The `rm' in the eepitch block
+----------------------------------
+When we execute this eepitch block a first time,
+
+   (eepitch-shell)
+   (eepitch-kill)
+   (eepitch-shell)
+  cd /tmp/
+  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
+
+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.
+
+  (...)
+
+  (find-anchor \"/tmp/lua-intro.e\" \"intro:types\")
+
+
+
+
+
+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'\")
 
 
-3. Social consequences
-======================
-\(of sharing e-scripts)
 
 
 " pos-spec-list)))