[elpa] externals/eev ca3dd97 53/64: Added sections to `find-channels-intro'.

[Stefan Monnier]

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

    Added sections to `find-channels-intro'.
---
 ChangeLog       |   7 +++
 VERSION         |   4 +-
 eepitch.el      |  41 +++++++++++++----
 eev-channels.el |  40 ++++++++++++----
 eev-intro.el    | 138 ++++++++++++++++++++++++++++++++++++++++++++++++--------
 5 files changed, 194 insertions(+), 36 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 28e14fd..23fa5bf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2019-03-10  Eduardo Ochs  <address@hidden>
 
+       * eev-intro.el (find-channels-intro): added sections with setup
+       and tests.
+
+       * eev-channels.el (eexterm-args-ne): made some arguments optional.
+       (eexterm-create-ne): made some arguments optional.
+       (eexterm-ne): made some arguments optional.
+
        * eev-intro.el (find-eev-quick-intro): small changes.
 
 2019-03-08  Eduardo Ochs  <address@hidden>
diff --git a/VERSION b/VERSION
index 1b3f4f1..5fadd86 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sun Mar 10 16:10:26 GMT 2019
-Sun Mar 10 13:10:26 -03 2019
+Mon Mar 11 01:56:00 GMT 2019
+Sun Mar 10 22:56:00 -03 2019
diff --git a/eepitch.el b/eepitch.el
index 4bc5f83..839cab2 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb28
+;; Version:    2019mar10
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eepitch.el>
@@ -32,17 +32,42 @@
 
 ;;; Commentary:
 
-;; 2018may30: There's a tutorial on eepitch here:
+;; Eev's central idea is that you can keep "executable logs" of what
+;; you do, in a format that is reasonably readable and that is easy to
+;; "play back" later, step by step and in any order. These "steps" are
+;; mainly of two kinds:
+;;
+;;   1) elisp hyperlinks, and
+;;   2) lines sent to shell-like programs.
+;;
+;; Eepitch is the module that implements support for (2). For a
+;; tutorial, see:
+;;
 ;;   (find-eev-quick-intro "6. Controlling shell-like programs")
-;;    http://angg.twu.net/eev-intros/find-eev-quick-intro.html
+;;   http://angg.twu.net/eev-intros/find-eev-quick-intro.html#6
 ;;
-;; Eepitch implements a much simpler way to interact with external
-;; programs than the one shown in:
-;;   <http://angg.twu.net/eev-current/anim/channels.anim.html>
+;; For videos, see:
 ;;
-;; The comments below are VERY old and were partly superseded by this:
-;;   (find-eepitch-intro)
+;;   https://www.youtube.com/watch?v=Lj_zKC5BR64&t=16s
+;;   http://angg.twu.net/#eev
+;;
+;;
+;;
+;; NOTE: some Emacs modes have ways to send lines to an interpreter;
+;; eepitch reimplements that in a minimalistic way that is quite
+;; flexible. There is a package called isend-mode - here:
+;;
+;;   https://github.com/ffevotte/isend-mode.el
+;;   (find-epackage 'isend-mode)
+;;
+;; that also generalizes this "send lines to an interpreter" thing.
+;; TODO: integrate eepitch and isend-mode!
+
+
 
+;; The comments below are VERY old and were partly superseded by this:
+;;   (find-eev-quick-intro "6. Controlling shell-like programs")
+;;
 ;; The innards
 ;; ===========
 ;; In order to understand precisely how eepitch works (consider this a
diff --git a/eev-channels.el b/eev-channels.el
index 1a9e1cf..831e3dc 100644
--- a/eev-channels.el
+++ b/eev-channels.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar02
+;; Version:    2019mar10
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-channels.el>
@@ -45,6 +45,12 @@
 ;;   (find-eev "eechannel.el")
 
 
+;; �.eechannel�                (to "eechannel")
+;; �.eechannel-assert� (to "eechannel-assert")
+;; �.eexterm�          (to "eexterm")
+
+
+
 (defun ee-read-file (fname)
   (with-temp-buffer
     (insert-file-contents fname)
@@ -89,12 +95,16 @@
 ;;       /---> eechannel-pid ----------> eechannel-pidfile
 ;;       |
 ;;      eechannel-kill
+;;
+;; �eechannel� (to ".eechannel")
 
 (defvar eechannel-default nil)
 
+;; Test: (eechannel-strfile "A")
 (defun eechannel-strfile (channel)
   (ee-expand (format "$EEVTMPDIR/eeg.%s.str" channel)))
 
+;; Test: (eechannel-pidfile "A")
 (defun eechannel-pidfile (channel)
   (ee-expand (format "$EEVTMPDIR/eeg.%s.pid" channel)))
 
@@ -138,6 +148,7 @@ If the line starts with a `' then evaluate it as lisp 
instead of sending it."
 ;;; |  __/  __/ (__| | | |_____| (_| \__ \__ \  __/ |  | |_
 ;;;  \___|\___|\___|_| |_|      \__,_|___/___/\___|_|   \__|
 ;;;
+;; �eechannel-assert� (to ".eechannel-assert")
 
 (defun eechannel-pid-running-p (pid)
   "Return t if a process with pid PID is running. This is linux-specific."
@@ -190,8 +201,21 @@ If the line starts with a `' then evaluate it as lisp 
instead of sending it."
 ;;   eexterm-args ----> eexterm-args-ne      
 ;;
 ;;   eexterm-kill -----> eechannel-kill
-
-(defun eexterm-args-ne (channel prog-and-args xterm-args)
+;;
+;; �eexterm� (to ".eexterm")
+
+;; Tests:
+;;   (eexterm-args-ne "A")
+;;   (eexterm-args-ne "A" '("ssh" "address@hidden") "-geometry 80x20")
+;;   (eexterm-create-ne "A")
+;;   (eexterm-create "A")
+;;   (eexterm-create "A")
+;;   (eexterm "A")
+;;   (eechannel-send "A" "echo hello")
+;;   (eechannel-send "A" "echo hello\n")
+;;   (eexterm-kill "A")
+;;
+(defun eexterm-args-ne (channel &optional prog-and-args xterm-args)
 "Return a list of arguments for running a xterm listening on CHANNEL.
 Try these examples:
   (eexterm-args-ne \"A\" nil nil)
@@ -202,11 +226,11 @@ Try these examples:
     "-e" ,(ee-expand "$EEVDIR/eegchannel") ,channel
     ,@(ee-split (or prog-and-args (ee-expand "$SHELL")))))
 
-(defun eexterm-create-ne (channel prog-and-args xterm-args)
+(defun eexterm-create-ne (channel &optional prog-and-args xterm-args)
   "Start a xterm listening on CHANNEL. See `eexterm-args-ne'."
   (find-bgprocess-ne (eexterm-args-ne channel prog-and-args xterm-args)))
 
-(defun eexterm-ne (channel prog-and-args xterm-args)
+(defun eexterm-ne (channel &optional prog-and-args xterm-args)
 "Set the default channel to CHANNEL; create an xterm listening on CHANNEL if 
needed."
   (interactive "sDefault channel: ")
   (setq eechannel-default channel)
@@ -214,17 +238,17 @@ Try these examples:
       (message "Reusing xterm at channel %s" channel)
     (eexterm-create-ne channel prog-and-args xterm-args)))
 
-(defun eexterm-args   (channel &optional prog-and-args xterm-args)
+(defun eexterm-args (channel &optional prog-and-args xterm-args)
   (eexterm-args-ne   channel (ee-split-and-expand prog-and-args) xterm-args))
 
 (defun eexterm-create (channel &optional prog-and-args xterm-args)
   "Create an xterm listening on CHANNEL."
   (eexterm-create-ne channel (ee-split-and-expand prog-and-args) xterm-args))
 
-(defun eexterm        (channel &optional prog-and-args xterm-args)
+(defun eexterm (channel &optional prog-and-args xterm-args)
 "Set the default channel to CHANNEL; create an xterm listening on CHANNEL if 
needed."
   (interactive "sDefault channel: ")
-  (eexterm-ne        channel (ee-split-and-expand prog-and-args) xterm-args))
+  (eexterm-ne channel (ee-split-and-expand prog-and-args) xterm-args))
 
 (defalias 'eechannel-xterm 'eexterm)
 
diff --git a/eev-intro.el b/eev-intro.el
index 2c82099..a0193a7 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -2071,31 +2071,71 @@ These ones explain advanced features that require extra 
setup:
   22. (find-bounded-intro)
   23. (find-channels-intro)
 
-Items 0, 3, 4, 5, 6, 9, 10, 11 should give you a good grasp of the
-main ideas - namely, that _elisp hyperlinks and interactive scripts
-can be embedded anywhere_. The other tutorials mainly show how to make
-these ideas pervasive.
+These ones are obsolete:
 
-The last item above is an index of the video tutorials, with
-scripts for downloading local copies of them and links to
-important positions in the videos.
+  24. (find-emacs-intro)
+  25. (find-defun-intro)
 
-There are also these two, ahem, \"things\", that I use in
-workshops, but that are not very eev-specific:
-
-   A. (find-emacs-intro)
-   B. (find-defun-intro)
+Item 20 is an index of the (old) video tutorials, with scripts
+for downloading local copies of them and links to important
+positions in the videos.
 
 
 
 
 
+1. `eev-mode'
+=============
 To toggle eev-mode on and off, use `M-x eev-mode'.
 
+The text below is a copy of:
 
+  (find-eev-install-intro \"1. Installing eev by hand\")
 
-The keybindings
-===============
+Note that eev-mode.el has this commentary:
+
+  ;; Turning on eev-mode simply activates the eev-mode-map keymap, and
+  ;; adds an \"eev\" to the mode line to remind you this. Turning off
+  ;; eev-mode deactivates the keymap and the reminder. 
+
+If you prefer to start with eev-mode off, omit the
+line `(eev-mode 1)' above or change it to `(eev-mode 0)'. To
+toggle eev-mode on and off, use `M-x eev'. The keybindings in
+eev-mode are listed here:
+
+  (find-eev \"eev-mode.el\" \"eev-mode-map-set\")
+
+Years ago eev was a very invasive package that changed several
+global settings; now it's the opposite. If you load eev the only
+things that happen are:
+
+  1) Several functions and variables become defined. They ALL
+     have the prefixes \"find-\", \"ee\", \"code-\" or \"br\",
+     except for one: \"to\".
+
+  2) The standard-display-table is changed to make three
+     characters be displayed as colored glyphs: \"\" (char 15),
+     \"«\" (char 171), and \"»\" (char 187).
+     
+  3) The environment variables \"S\" and \"EEVDIR\" are set.
+
+  4) An innocuous wrapper is installed around an internal
+     function used by `man'. See:
+
+       (find-eev \"eev-blinks.el\" \"find-man\")
+
+This is all I remember now (2019mar05). I am trying to make eev
+as non-invasive as possible - to convince as many people as
+possible to install it and try it!
+
+  (find-eev-install-intro \"1. Installing eev by hand\")
+
+
+
+
+
+2. The keybindings
+==================
 `eev-mode' defines its own meanings for lots of meta-shift-letter
 key combinations - which are not normally used by Emacs - and,
 besides that, only for:
@@ -6619,7 +6659,69 @@ will present several tests that should help with 
troubleshooting.
 
 
 
-2. The innards
+
+
+2. Low-level tests
+==================
+Before we start please try this low-level test.
+(TODO: explain it!)
+
+2.1. Preparation
+----------------
+Make sure that the \"$EEVDIR/eegchannel\" script exists and is
+executable and check that the temporary directory \"$EEVTMPDIR/\"
+exists:
+
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+echo     $EEVDIR
+cd       $EEVDIR
+pwd
+wget -nc http://angg.twu.net/eev-current/eegchannel
+chmod 755 eegchannel
+ls -lAF  $EEVDIR/eegchannel
+echo     $EEVTMPDIR
+mkdir -p $EEVTMPDIR/
+
+
+
+2.2. Test eegchannel
+--------------------
+We create a window setting like this,
+
+   ______________________
+  |          |           |
+  |          |   shell   |
+  |  this    |___________|
+  |  intro   |           |
+  |          |  shell 2  |
+  |__________|___________|
+
+and we run an eegchannel at \"shell 2\" and we send some lines to
+it from \"shell\":
+
+
+ (find-3EE '(eepitch-shell) '(eepitch-shell2))
+ (eepitch-shell2)
+$EEVDIR/eegchannel A python
+
+ (eepitch-shell)
+# Check that eeg.A.pid exists and is very recent:
+date
+ls -lAF $EEVTMPDIR/eeg.A.*
+
+# Send lines to eegchannel:
+echo 'print(2+3)' > $EEVTMPDIR/eeg.A.str
+kill -USR1    $(cat $EEVTMPDIR/eeg.A.pid)
+echo 'exit()'     > $EEVTMPDIR/eeg.A.str
+kill -USR1    $(cat $EEVTMPDIR/eeg.A.pid)
+
+
+
+
+
+3. The innards
 ==============
 Let's start with a detailed low-level view of of what we have
 just summarized as to \"save a command into a temporary file,
@@ -6638,7 +6740,7 @@ you... =(
 
 
 
-3. The protocol, in diagrams
+4. The protocol, in diagrams
 ============================
 Here's a diagram that shows roughly what we have when X is
 running both an Emacs and an xterm, each in a separate window.
@@ -6784,7 +6886,7 @@ protocol are not shown.
 
 
 
-4. Downloading and testing eechannel
+5. Downloading and testing eechannel
 ====================================
 Here I'll suppose that the directory \"~/bin/\" exists and is in
 your PATH. Run this to download the \"eechannel\" script and make
@@ -6875,7 +6977,7 @@ If that worked, we're done. =)
 
 
 
-5. Several xterms
+6. Several xterms
 =================
 http://angg.twu.net/eev-current/anim/channels.anim.html