[elpa] externals/eev b56266f 54/64: Added `eev-beginner' (our first autoload).

[Stefan Monnier]

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

    Added `eev-beginner' (our first autoload).
---
 ChangeLog          | 11 ++++++++
 VERSION            |  4 +--
 eepitch.el         |  8 +++++-
 eev-beginner.el    | 70 +++++++++++++++++++++++++++++++++++------------
 eev-channels.el    | 22 ++++++++-------
 eev-flash.el       |  2 +-
 eev-intro.el       | 80 +++++++++++++++++++++++++++++++++++++++++++++++-------
 eev-load.el        |  2 +-
 eev-multiwindow.el |  3 +-
 eev-pdflike.el     |  2 +-
 eev-rcirc.el       | 27 ++++++++++++++++--
 eev2-all.el        |  2 +-
 12 files changed, 184 insertions(+), 49 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 23fa5bf..f2e1656 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2019-03-13  Eduardo Ochs  <address@hidden>
+
+       * eev-rcirc.el: updated the comments.
+
+       * eev-beginner.el: don't change the load-path. Added comments.
+       (eev-beginner): new function.
+
+       * eev-intro.el (find-channels-intro): added some sections.
+
+       * eev-channels.el: converted to UTF-8 and added comments.
+
 2019-03-10  Eduardo Ochs  <address@hidden>
 
        * eev-intro.el (find-channels-intro): added sections with setup
diff --git a/VERSION b/VERSION
index 5fadd86..645d70a 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Mon Mar 11 01:56:00 GMT 2019
-Sun Mar 10 22:56:00 -03 2019
+Wed Mar 13 23:29:39 GMT 2019
+Wed Mar 13 20:29:39 -03 2019
diff --git a/eepitch.el b/eepitch.el
index 839cab2..13350d4 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -54,7 +54,13 @@
 ;;
 ;;
 ;; NOTE: some Emacs modes have ways to send lines to an interpreter;
-;; eepitch reimplements that in a minimalistic way that is quite
+;; for example, `python-mode' has `python-shell-send-string':
+;;
+;;   (find-efile "progmodes/python.el" "(defvar python-mode-map")
+;;   (find-efile "progmodes/python.el"       "'python-shell-send-string")
+;;   (find-efile "progmodes/python.el" "(defun python-shell-send-string")
+;;
+;; 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
diff --git a/eev-beginner.el b/eev-beginner.el
index b31670b..dfebeff 100644
--- a/eev-beginner.el
+++ b/eev-beginner.el
@@ -1,4 +1,4 @@
-;;; eev-beginner.el -- load eev and turn eev-mode on.
+;;; eev-beginner.el -- load eev, turn eev-mode on, open a tutorial.
 
 ;; Copyright (C) 2019 Free Software Foundation, Inc.
 ;;
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar05
+;; Version:    2019mar13
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-beginner.el>
@@ -29,33 +29,67 @@
 
 ;;; Commentary:
 
-;; Most beginners start playing with Emacs+eev by following the
-;; instructions here,
+;; This file serves two purposes.
 ;;
-;;   (find-eev-quick-intro "1. Installing eev")
+;; 1) Most beginners start playing with Emacs+eev by following the
+;;    instructions here,
 ;;
-;; i.e., by copying and pasting a certain script to a terminal. That
-;; script creates an executable file called "~/eev" that switches to
-;; the directory where eev was unpacked and invokes Emacs like this:
+;;      (find-eev-quick-intro "1. Installing eev")
 ;;
-;;   emacs -l eev-beginner.el --eval="(find-eev-quick-intro)" $*
+;;    i.e., by copying and pasting a certain script to a terminal.
+;;    That script creates an executable file called "~/eev" whose
+;;    contents are something like this:
 ;;
-;; which makes Emacs load "eev-beginner.el" (this file!) and run
-;; `(find-eev-quick-intro)' to open the "eev quick intro" tutorial.
-;; This file simply loads all the default modules of eev and turns
-;; eev-mode on.
+;;      #!/bin/sh
+;;      cd ~/eev2/ && emacs -l eev-beginner.el --eval="(find-eev-quick-intro)" 
$*
 ;;
-;; Older versions of eev loaded "eev-readme.el" instead of
+;;    Running "~/eev" on a shell starts Emacs and makes it load this
+;;    file and load the main tutorial - i.e., (find-eev-quick-intro).
+;;
+;; 2) If you install eev as an emacs package via `M-x list-packages'
+;;    then no eev modules will be loaded UNTIL you run `M-x
+;;    eev-beginner', which loads everything, starts eev-mode, and
+;;    opens the main tutorial.
+;;
+;; When, or if, you are no longer a beginner, you may want to load eev
+;; by just adding a "(require 'eev-load)" to your ".emacs". This loads
+;; all the main modules but not turn on eev-mode on by default, and
+;; does not open the tutorial. See:
+;;
+;;    (find-eev-intro "1. `eev-mode'")
+
+
+
+;; NOTE: older versions of eev loaded "eev-readme.el" instead of
 ;; "eev-beginner.el". See:
 ;;
 ;;   (find-eev "eev-readme.el")
 
-(add-to-list 'load-path default-directory)
-(require 'eev-load)           ; (find-eev "eev-load.el")
+
+
+;; 2019mar13: Commented this out.
+;; (add-to-list 'load-path default-directory)
+
+
+;; Load all the main modules of eev.
+;; Do not load some advanced modules that require extra setup.
+;; See the comments here: (find-eev "eev-load.el")
+(require 'eev-load)
 (eev-mode 1)
+(find-eev-quick-intro)
+
+
+;; This is the only autoload of eev at this moment.
+;; (find-elnode "Autoload" "magic autoload comment")
+
+;;;###autoload
+(defun eev-beginner ()
+  "Load all basic modules of eev, turn eev-mode on, and open a tutorial."
+  (interactive)
+  (require 'eev-load)
+  (eev-mode 1)
+  (find-eev-quick-intro))
 
-;; (find-eev-install-intro "1. Installing eev by hand")
-;; (find-eev-install-intro "1. Installing eev by hand" "require 'eev-load")
 
 (provide 'eev-beginner)
 
diff --git a/eev-channels.el b/eev-channels.el
index 831e3dc..7d842ad 100644
--- a/eev-channels.el
+++ b/eev-channels.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar10
+;; Version:    2019mar13
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-channels.el>
@@ -32,11 +32,13 @@
 ;;; Commentary:
 
 ;; `eechannel' is very difficult to set up and has been mostly
-;; superseded by `eepitch'. There is some documentation here,
+;; superseded by `eepitch'. There is some documentation here -
+;; including e-scripts for tests - but it is incomplete and some parts
+;; need to be rewritten:
 ;;
 ;;  (find-channels-intro)
+;;  (find-channels-intro "2. Low-level tests")
 ;;
-;; but it needs to be rewritten.
 
 
 ;; TODO: import code from:
@@ -45,9 +47,9 @@
 ;;   (find-eev "eechannel.el")
 
 
-;; �.eechannel�                (to "eechannel")
-;; �.eechannel-assert� (to "eechannel-assert")
-;; �.eexterm�          (to "eexterm")
+;; «.eechannel»                (to "eechannel")
+;; «.eechannel-assert» (to "eechannel-assert")
+;; «.eexterm»          (to "eexterm")
 
 
 
@@ -96,7 +98,7 @@
 ;;       |
 ;;      eechannel-kill
 ;;
-;; �eechannel� (to ".eechannel")
+;; «eechannel» (to ".eechannel")
 
 (defvar eechannel-default nil)
 
@@ -148,7 +150,7 @@ If the line starts with a `' then evaluate it as lisp 
instead of sending it."
 ;;; |  __/  __/ (__| | | |_____| (_| \__ \__ \  __/ |  | |_
 ;;;  \___|\___|\___|_| |_|      \__,_|___/___/\___|_|   \__|
 ;;;
-;; �eechannel-assert� (to ".eechannel-assert")
+;; «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."
@@ -202,7 +204,7 @@ If the line starts with a `' then evaluate it as lisp 
instead of sending it."
 ;;
 ;;   eexterm-kill -----> eechannel-kill
 ;;
-;; �eexterm� (to ".eexterm")
+;; «eexterm» (to ".eexterm")
 
 ;; Tests:
 ;;   (eexterm-args-ne "A")
@@ -263,6 +265,6 @@ Try these examples:
 
 
 ;; Local Variables:
-;; coding:          raw-text-unix
+;; coding:          utf-8-unix
 ;; no-byte-compile: t
 ;; End:
diff --git a/eev-flash.el b/eev-flash.el
index f374854..eb8d568 100644
--- a/eev-flash.el
+++ b/eev-flash.el
@@ -92,6 +92,6 @@ we set ADD-TO-E to 1."
 
 
 ;; Local Variables:
-;; coding:            raw-text-unix
+;; coding:            utf-8-unix
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev-intro.el b/eev-intro.el
index a0193a7..4ab5656 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -1991,6 +1991,16 @@ installing a package with `M-x list-packages' is too 
hard.
 If you want to change these statistics, send me a \"hi\"!
 
 
+
+5.1. The experimental package for eev
+-------------------------------------
+There is now an EXPERIMENTAL package for eev in ELPA with a
+single autoload. It is called \"eev\" and you can install it via
+`M-x list-packages'. To use it, install it and run `M-x
+eev-beginner'. See:
+
+  (find-eev \"eev-beginner.el\")
+
 " pos-spec-list)))
 
 ;; (find-eev-install-intro)
@@ -6630,7 +6640,7 @@ Is is meant as both a tutorial and a sandbox.
 
 1. Introduction
 ===============
-Before eepitch had been invented, eev had two other ways to send
+Before eepitch had been invented eev had two other ways to send
 commands to external shell-like programs. The first way,
 described here,
 
@@ -6652,7 +6662,7 @@ listens to signals and handles them pretending that the 
saved
 commands came from the keyboard... and, as some people have said,
 this is \"a nightmare to set up\".
 
-Here we explain the protocol - which can be adapted to other
+Here we explain the protocol - that can be adapted to other
 cases too, like, for example, to make Emacs talk to SmallTalk
 environments and to computer algebra systems with GUIs - and we
 will present several tests that should help with troubleshooting.
@@ -6663,32 +6673,46 @@ will present several tests that should help with 
troubleshooting.
 
 2. Low-level tests
 ==================
-Before we start please try this low-level test.
-(TODO: explain it!)
+Before we start the theory please try these low-level tests.
+
 
 2.1. Preparation
 ----------------
-Make sure that the \"$EEVDIR/eegchannel\" script exists and is
-executable and check that the temporary directory \"$EEVTMPDIR/\"
-exists:
+Have have to make sure that:
+
+  1) \"eev-channel.el\" has been loaded,
+  2) the \"$EEVDIR/eegchannel\" script exists and is executable,
+  3) we have expect installed - eegchannel depends on it,
+  4) the temporary directory \"$EEVTMPDIR/\" exists.
+
+Here is an e-script for that:
+
+  (add-to-list 'load-path (ee-expand \"$EEVDIR\"))
+  (require 'eev-channel)
 
  (eepitch-shell)
  (eepitch-kill)
  (eepitch-shell)
+sudo apt-get install expect
 echo     $EEVDIR
 cd       $EEVDIR
 pwd
 wget -nc http://angg.twu.net/eev-current/eegchannel
 chmod 755 eegchannel
 ls -lAF  $EEVDIR/eegchannel
+expect -v
+$EEVDIR/eegchannel A echo ok
 echo     $EEVTMPDIR
 mkdir -p $EEVTMPDIR/
 
+# (find-eev \"eegchannel\")
+
+
 
 
 2.2. Test eegchannel
 --------------------
-We create a window setting like this,
+In this test we create a window setting like this,
 
    ______________________
   |          |           |
@@ -6698,8 +6722,27 @@ We create a window setting like this,
   |          |  shell 2  |
   |__________|___________|
 
-and we run an eegchannel at \"shell 2\" and we send some lines to
-it from \"shell\":
+and then:
+
+  1) we run \"eegchannel A python\" at the lower shell. This runs
+     a python interpreter \"listening on channel A\";
+
+  2) we use the top shell to send the lines \"print(2+3)\" and
+     \"exit()\" \"thorugh the channel A\". In low-level terms
+     this means that for each line
+
+       a) we save it into the file \"$EEVTMPDIR/eeg.A.str\",
+
+       b) we send a signal SIGUSR1 to the process -
+          \"eegchannel\" - whose PID is stored in the file
+          \"$EEVTMPDIR/eeg.A.pid\".
+
+       c) When the eegchannel listening on the channel A receives
+          a SIGUSR1 it sends the line in \"$EEVTMPDIR/eeg.A.str\"
+          to the process that it controls (that is \"python\") \"as
+          if the user had typed it\".
+
+Here is the demo. Run it with <F8>s:
 
 
  (find-3EE '(eepitch-shell) '(eepitch-shell2))
@@ -6719,6 +6762,23 @@ kill -USR1    $(cat $EEVTMPDIR/eeg.A.pid)
 
 
 
+2.3. Test `eechannel'
+---------------------
+TODO: write this.
+See:
+
+  (find-eev \"eev-channels.el\" \"eechannel\")
+
+
+2.4. Test `eexterm'
+-------------------
+TODO: write this.
+See:
+
+  (find-eev \"eev-channels.el\" \"eexterm\")
+
+
+
 
 
 3. The innards
diff --git a/eev-load.el b/eev-load.el
index 111ade5..410e725 100644
--- a/eev-load.el
+++ b/eev-load.el
@@ -139,6 +139,6 @@
 
 
 ;; Local Variables:
-;; coding:            raw-text-unix
+;; coding:            utf-8-unix
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev-multiwindow.el b/eev-multiwindow.el
index b7f105f..3f283de 100644
--- a/eev-multiwindow.el
+++ b/eev-multiwindow.el
@@ -152,7 +152,6 @@ that. This is mainly for `find-wset'."
 
 
 ;; Local Variables:
-;; coding:            raw-text-unix
-;; ee-anchor-format:  "defun %s "
+;; coding:            utf-8-unix
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev-pdflike.el b/eev-pdflike.el
index 5834c9d..380bf49 100644
--- a/eev-pdflike.el
+++ b/eev-pdflike.el
@@ -388,7 +388,7 @@ newline are spurious - and replaces them by \"(ff)\"."
 (defun find-pdftools-page (fname &optional page &rest rest)
   (pdf-tools-install)
   (find-fline fname)
-  (pdf-view-goto-page (or page 1)))
+  (if page (pdf-view-goto-page (or page 1))))
 
 
 
diff --git a/eev-rcirc.el b/eev-rcirc.el
index d445d6a..cc376cf 100644
--- a/eev-rcirc.el
+++ b/eev-rcirc.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar02
+;; Version:    2019mar13
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-rcirc.el>
@@ -30,6 +30,29 @@
 
 ;;; Commentary:
 
+;; Most of the _comments_ below are obsolete. The recommended way to
+;; use this is now by running, for example,
+;;
+;;   (find-freenode-links "e" "#emacs")
+;;
+;; and then copying and pasting these lines to your .emacs:
+;;
+;;   (setq ee-freenode-ichannels "#eev #emacs")
+;;   (setq ee-freenode-achannels "#eev #emacs")
+;;   (defun e2 () (interactive) (find-freenode-2a "#emacs"))
+;;   (defun e3 () (interactive) (find-freenode-3a "#emacs"))
+;;
+;; Then `M-x e3' creates the three-window setup described here,
+;;
+;;   (find-rcirc-intro "1. The server buffer and the channel buffers")
+;;
+;; that lets you follow all the steps of the connection. Once you're
+;; sure that you're connected to the server you can use `M-x e2' to
+;; create a two-window setup with just the current buffer and the
+;; #emacs buffer.
+
+;; OBSOLETE COMMENTS:
+;;
 ;; Here we implement a very thin eev-ish layer on top of rcirc. The
 ;; main goal is:
 ;;
@@ -243,7 +266,7 @@ the right - \"#foo\" means channel \"#foo\", \"nick\" means 
query
 
 
 ;; Local Variables:
-;; coding:            raw-text-unix
+;; coding:            utf-8-unix
 ;; ee-anchor-format:  "defun %s "
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev2-all.el b/eev2-all.el
index 14f0a54..13ccb34 100644
--- a/eev2-all.el
+++ b/eev2-all.el
@@ -120,6 +120,6 @@
 
 
 ;; Local Variables:
-;; coding:            raw-text-unix
+;; coding:            utf-8-unix
 ;; no-byte-compile:   t
 ;; End: