Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
(defun c () (interactive)
  (find-sh "cd ~/blogme4/doc/ &&
            blogme4.lua -o eev.texi -i eev.b4texi &&
            makeinfo eev.texi"))
(defun i () (interactive) (find-node "(eev)Top"))
(defun ii () (interactive) (find-angg "blogme4/doc/eev.b4texi"))
(defun ii () (interactive) (find-angg "blogme4/doc/eev.texi"))
;; (find-sh0 "cd ~/info/ && rm -v eev.info")
;; (find-sh0 "cd ~/info/ && ln -s ../blogme4/doc/eev.info .")
;; (find-angg "info/")
;; (find-node "(eev)Top")
;; (find-blogme4 "texinfo.lua")
;; (find-angg ".emacs" "nd")
  def [[ P 1 body body ]]
  def [[ R 1 body body ]]
  def [[ QQ      1Q body tquote(body) ]]
  def [[ QQQ     1Q body IE(body) ]]
  def [[ QQQSHOT 1Q body IE(body) ]]
  def [[ SEE:    1Q body IE(body) ]]
  def [[ `` 1 body "``"..body.."''" ]]
  def [[ REF 1 body "(ref "..body..")" ]]
  def [[ _   1 body "_"..body.."_" ]]
  def [[ <   0 _  "[" ]]
  def [[ >   0 _  "]" ]]
 # «.abstract»			(to "abstract")
 # «.three-kinds-of-interfaces»	(to "three-kinds-of-interfaces")
 # «.one-thing-well»		(to "one-thing-well")
 # «.making-progs-receive-cmds»	(to "making-progs-receive-cmds")
 # «.sending-commands»		(to "sending-commands")
 # «.hyperlinks»		(to "hyperlinks")
 # «.shorter-hyperlinks»	(to "shorter-hyperlinks")
 # «.forward-and-back»		(to "forward-and-back")
 # «.dangerous-hyperlinks»	(to "dangerous-hyperlinks")
 # «.generating-hyperlinks»	(to "generating-hyperlinks")
 # «.returning»			(to "returning")
 # «.local-copies»		(to "local-copies")
 # «.glyphs»			(to "glyphs")
 # «.compose-pairs»		(to "compose-pairs")
 # «.delimited-regions»		(to "delimited-regions")
 # «.channels»			(to "channels")
 # «.channels-implementation»	(to "channels-implementation")
 # «.anchors»			(to "anchors")
 # «.e-scripts»			(to "e-scripts")
 # «.splitting-eev.el»		(to "splitting-eev.el")
 # «.eesteps»			(to "eesteps")
 # «.eepitch»			(to "eepitch")
 # «.eepitch-unprepared»	(to "eepitch-unprepared")
 # «.eepitch-gud»		(to "eepitch-gud")
 # «.eepitch-gdb»		(to "eepitch-gdb")
 # «.little-dbg-langs»		(to "little-dbg-langs")
 # «.inspecting-data»		(to "inspecting-data")
 # «.iskidip»			(to "iskidip")
 # «.what-is-automating»	(to "what-is-automating")
 # «.availability»		(to "availability")
 # «.acknowledgments»		(to "acknowledgments")
 # «.references»		(to "references")

 # «.install-debian»		(to "install-debian")

[TOP eev [J The eev manual]
  tt.srclink_fmt  = '(find-angg "blogme4/doc/eev.b4texi" "%s")'
  tt.infolink_fmt = '(find-node "(eev)%s")'

[ANODE «abstract»  (to ".abstract")
  (find-blogme4node "Abstract")
  [J Abstract]

  [P Interacting with programs with command-line interfaces always
    involves a bit of line editing, and each CLI program tends to
    implement independently its own minimalistic editing features. We
    show a way of centralizing these editing tasks by making these
    programs receive commands that are prepared, and sent from, Emacs.
    The resulting system is a kind of Emacs- and Emacs Lisp-based
    [`` universal scripting language] in which commands can be sent to
    both external programs and to Emacs itself either in blocks or
    step-by-step under very fine control from the user.

  [P Note: this is a working draft that has many pieces missing and
     needs urgent revision on the pieces it has. Current version: (see
     top). Newer versions are being uploaded to
     [R http://angg.twu.net/eev-current/article/], and two animations
     (in Flash) showing eev at work can be found at:
     [R http://angg.twu.net/eev-current/anim/channels.anim.html] and
     [R http://angg.twu.net/eev-current/anim/gdb.anim.html].


[ANODE «three-kinds-of-interfaces»  (to ".three-kinds-of-interfaces")
  (find-blogme4node "Three kinds of interfaces")
  [J Three kinds of interfaces]

[P Interactive programs in a Un*x system(1) can have basically three
kinds of interfaces: they can be mouse-oriented, like most programs
with graphical interfaces nowadays, in which commands are given by
clicking with the mouse; they can be character-oriented, like most
editors and mail readers, in which most commands are single keys or
short sequences of keys; and they can be line-oriented, as, for
example, shells are: in a shell commands are given by editing a full
line and then typing [`` enter] to process that line.]

[P It is commonplace to classify computer users in a spectrum where
the [`` users] are in one extreme and the [`` programmers] are in the
other; the [`` users] tend to use only mouse-oriented and
character-oriented programs, and the [`` programmers] only
character-oriented and line-oriented programs.]

[P In this paper we will show a way to [`` automate] interactions with
line-oriented programs, and, but not so well, to character-oriented
programs; more precisely, it is a way to edit commands for these
programs in a single central place --- Emacs --- and then send them to
the programs; re-sending the same commands afterwards, with or without
modifications, then becomes very easy.]

[P This way ([`` e-scripts]) can not be used to send commands to
mouse-oriented programs --- at least not without introducing several
new tricks. But [`` programmers] using Un*x systems usually see most
mouse-oriented programs --- except for a few that are [IT
intrinsically] mouse-oriented, like drawing programs --- as being just
wrappers around line-oriented programs than perform the same tasks
with different interfaces; and so, most mouse-oriented programs [`` do
not matter], and our method of automating interactions using
e-scripts can be used to automate [`` almost everything]; hence the
title of the paper.]

[P (1): Actually we are more interested in GNU systems than in
[`` real] Unix systems; the reasons will become clear in the section
nnn. By the way: the term [`` Unix] is Copyright (C) Bell Labs).]


[ANODE «one-thing-well»  (to ".one-thing-well")
  (find-blogme4node "Make each program do one thing well")
  [J Make each program do one thing well]

[P One of the tenets of the Unix philosophy is that each program
should do one thing, and do it well; this is a good design rule for
Unix programs because the system makes it easy to invoke external
programs to perform tasks, and to connect programs.]

[P Some of parts of a Unix system are more like [`` meta-programs] or
[`` sub-programs] than like self-contained programs that do some
clearly useful task by themselves. Shells, for example, are
meta-programs: their main function is to allow users to invoke [`` real
programs] and to connect these programs using pipes, redirections,
control structures (if, for, etc) and Unix [`` signals]. On the other
hand, libraries are sub-programs: for example, on GNU systems there's
a library called GNU readline that line-oriented programs can use to
get input; if a program, say, bc (a calculator) gets its input by
calling [QQ readline(...)] instead of using the more basic function
[QQ fgets(...)] then its line-oriented interface will have a little
more functionality: it will allow the user to do some minimal editing
in the current line, and also to recall, edit and issue again some of
the latest commands given.]


[ANODE «making-progs-receive-cmds»  (to ".making-progs-receive-cmds")
  (find-blogme4node "Making programs receive commands")
  [J Making programs receive commands]

[SEE: [code eev.el], [minicode eev-mini.el#find-fline],
      [AL eev-current/INSTALL INSTALL], 
      [AL eev-current/eev-rctool eev-rctool]

[P Many line-oriented programs allow [`` scripting], which means
executing commands from a file. For example, in most shells we can say
[`` [QQ source ~/ee.sh]], and the shell will then execute the commands
in the file [QQ ~/ee.sh]. There are other ways of executing commands
from a file --- like [`` [QQ sh ~/ee.sh]] --- but the one with [`` [QQ
source]] is the one that we'll be more interested in, because it is
closer to running the commands in [QQ ~/ee.sh] one by one by hand: for
example, with [`` [QQ source ~/ee.sh]] the commands that change
parameters of the shell --- like the current directory and the
environment variables --- will work in the obvious way, while with
[`` [QQ sh ~/ee.sh]] they would only change the parameters of a
temporary sub-shell; the current directory and the environment
variables of the present shell would be [`` protected].]

[P So, it is possible to prepare commands for a shell (or for
scriptable line-oriented programs; for arbitrary line-oriented
programs see the section nnn) in several ways: by typing them at the
shell's interface --- and if the shell uses readline its interface can
be reasonably friendly --- or, alternatively, by using a text editor
to edit a file, say, [QQ ~/ee.sh], and by then [`` executing] that file
with [`` [QQ source ~/ee.sh]]. [`` [QQ source ~/ee.sh]] is a lot of
keystrokes, but that can be shortened if we can define a shell
function: by putting

function ee () { source ~/ee.sh; }

in the shell's initialization file ([QQ ~/.bashrc], [QQ ~/.zshrc],
...) we can reduce [`` [QQ source ~/ee.sh]] to just [`` [QQ ee]]: [QQ
e], [QQ e], enter --- three keystrokes.]

[P We just saw how a shell --- or, by the way, any line-oriented
program in which we can define an `ee' function like we did for the
shell --- can receive commands prepared in an external editor and
stored in a certain file; let's refer to that file, [QQ ~/ee.sh], as a
[`` temporary script file]. Now it remains to see how an external text
editor can [`` send commands to the shell], i.e., how to make the
editor save some commands in a temporary script file in a convenient
way, that is, without using too many keystrokes...]


[ANODE «sending-commands»  (to ".sending-commands")
  (find-blogme4node "Sending commands")
  [J Sending commands]

[P GNU Emacs, [`` the extensible, self-documenting text-editor] ([REF
S79]), does at least two things very well: one is to edit text, and so
it can be used to edit temporary scripts, and thus to send commands to
shells and to line-oriented programs with `ee' functions; and the
other one is to run Lisp. Lisp is a powerful programming language, and
(at least in principle!) any action or series of actions can be
expressed as a program in Lisp; the first thing that we want to do is
a way to mark a region of a text and [`` send it as commands to a
shell], by saving it in a temporary script file. We implement that in
two ways:

 1: (defun ee (s e)
 2:   "Save the region in a temporary script"
 3:   (interactive "r")
 4:   (write-region s e "~/ee.sh"))
 6: (defun eev (s e)
 7:   "Like `ee', but the script executes in verbose mode"
 8:   (interactive "r")
 9:   (write-region
10:    (concat "set -v\n" (buffer-substring s e)
11:            "\nset+v")
12:    nil "~/ee.sh"))

`[QQ ee]' (the name stands for something like `emacs-execute') just
saves the currently-marked region of text to [QQ ~/ee.sh]; `[QQ eev]'
(for something like `emacs-execute-verbose') does the same but adding
to the beginning of the temporary script a command to put the shell in
[`` verbose mode], where each command is displayed before being
executed, and also adding at the end an command to leave verbose mode.]

[P We can now use `[QQ ee]' and `[QQ eev]' to send a block of commands
to a shell: just select a region and then run `[QQ ee]' or `[QQ eev]'.
More precisely: mark a region, that is, put the cursor at one of the
extremities of the region, then type [QQ C-SPC] to set Emacs's
[`` mark] to that position, then go to other extremity of the region
and type [QQ M-x eev] ([QQ C-SPC] and [QQ M-x] are Emacs's notations
for Control-Space and Alt-x, a.k.a. [`` Meta-x]). After doing that, go
to a shell and make it [`` receive these commands], by typing `[QQ


[ANODE «hyperlinks»  (to ".hyperlinks")
  (find-blogme4node "Hyperlinks")
  [J Hyperlinks]

[SEE: [code eev.el#find-fline],
      [minicode eev-mini.el#find-fline]]

[P When we are using a system like *NIX, in a part of the time we are
using programs with which we are perfectly familiar, and in the rest
of the time we are using things that we don't understand completely
and that make us have to access the documentation from time to time.
In a GNU system the documentation is all on-line, and the steps needed
to access any piece of documentation can be automated. We can use
Emacs Lisp [`` one-liners] to create [`` hyperlinks] to files:]

A: (info "(emacs)Lisp Eval")
B: (find-file "~/usrc/busybox-1.00/shell/ash.c")
C: (find-file "/usr/share/emacs/21.4/lisp/info.el")

[P These expressions, when executed --- which is done by placing the
cursor after them and then typing [QQ C-x C-e], or, equivalently, [QQ
M-x eval-last-sexp] --- will (A) open a page of Emacs manual (the
manual is a set of files in [`` Info] format), (B) open the source file
`[QQ shell/ash.c]' of a program called busybox, and (C) open the file
`[QQ info.el]' from the Emacs sources, respectively. As some of these
files and pages can be very big, these hyperlinks are not yet very
satisfactory: we want ways to not only open these files and pages but
also to [`` point to specific positions], i.e., to make the cursor go
to these positions automatically. We can do that by defining some new
hyperlink functions, that are invoked like this:]

A': (find-node "(emacs)Lisp Eval" "C-x C-e")
B': (find-fline "~/usrc/busybox-1.00/shell/ash.c"
C': (find-fline "/usr/share/emacs/21.4/lisp/info.el"
                "defun info")

[P The convention is that these [`` extended hyperlink functions] have
names like `[QQ find-xxxnode]', `[QQ find-xxxfile]', or `[QQ
find-xxxyyy]'; as the name `[QQ find-file]' was already taken by a
standard Emacs function we had to use `[QQ find-fline]' for ours.]

[P Here are the definitions of `find-node' and `find-fline':]

14: (defun ee-goto-position (&optional pos-spec)
15:   "If POS-SPEC is a string search for its first
16:    occurrence in the file; if it is a number go to the
17:    POS-SPECth line; if it is nil, don't move."
18:   (cond ((null pos-spec))
19:         ((numberp pos-spec)
20:          (goto-char (point-min))
21:          (forward-line (1- pos-spec)))
22:         ((stringp pos-spec)
23:          (goto-char (point-min))
24:          (search-forward pos-spec))
25:         (t (error "Invalid pos-spec: %S" pos-spec))))
27: (defun find-fline (fname &optional pos-spec)
28:   "Like (find-file FNAME), but accepts a POS-SPEC"
29:   (find-file fname)
20:   (ee-goto-position pos-spec))
32: (defun find-node (node &optional pos-spec)
33:   "Like (info NODE), but accepts a POS-SPEC"
34:   (info node)
35:   (ee-goto-position pos-spec)))

[P Now consider what happens when we send to a shell a sequence of
commands like this one:]

# (find-node "(gawk)Fields")
seq 4 9 | gawk '{print $1, $1*$1}'

[# BE'
# (find-node "(gawk)Fields")
seq 4 9 | gawk '{print $1, $1*$1}'

[P the shell ignores the first line because of the `[QQ #]', that
makes the shell treat that line as a comment; but when we are editing
that in Emacs we can execute the `[QQ (find-node ...)]' with [QQ C-x
C-e]. Hyperlinks can be mixed with shell code --- they just need to be
marked as comments.]

[P Note: the actual definitions of `[QQ eev]', `[QQ
ee-goto-position]', `[QQ find-fline]' and `[QQ find-node]' in eev's
source code are a bit more complex than the code in the listings above
(lines 6--12 in the previous section and 14--35 in the current
section). In all the (few) occasions in this paper where we will
present the source code of eev's functions what will be shown are
versions that implement only the [`` essence] of those functions,
stripped down of all extra functionality. The point that we wanted to
stress with those listings is how natural it is to use Emacs in a
certain way, as an editor for commands for external programs, and with
these plain-text hyperlinks that can be put almost anywhere: the
essence of that idea can be implemented in 30 lines of Lisp and one or
two lines of shell code.]

[P (See also: the section about [_ e-scripts]).]


[ANODE «shorter-hyperlinks»  (to ".shorter-hyperlinks")
  (find-blogme4node "Shorter Hyperlinks")
  [J Shorter Hyperlinks]

[IE' SEE: [code eev.el#code-c-d], [minicode eev-mini.el#code-c-d]]

[P The hyperlinks in lines [QQ A''], [QQ B''] and [QQ C''], below,]

A'': (find-enode "Lisp Eval" "C-x C-e")
B'': (find-busyboxfile "shell/ash.c" "void\nevalpipe")
C'': (find-efile "info.el" "defun info")

[P are equivalent to the ones labeled [QQ A'], [QQ B'], [QQ C'] in
Section 5, but are a bit shorter, and they hide details like Emacs's
path and the version of BusyBox; if we switch to newer versions of
Emacs and BusyBox we only need to change the definitions of `[QQ
find-busyboxfile]' and `[QQ find-efile]' to update the hyperlinks.
Usually not many things change from one version of a package to
another, so most hyperlinks continue to work after the update.]

[P Eev defines a function called `[QQ code-c-d]' that makes defining
functions like `[QQ find-enode]', `[QQ find-busyboxfile]' and `[QQ
find-efile]' much easier:]

(code-c-d "busybox" "~/usrc/busybox-1.00/")
(code-c-d "e" "/usr/share/emacs/21.4/lisp/" "emacs")

[P The arguments for `[QQ code-c-d]' are (1) a [`` code] (the [`` [QQ
xxx]] in a [`` [QQ find-xxxfile]]), (2) a directory, and optionally
(3) the name of a manual in Info format. The definition of [QQ
code-c-d] is not very interesting, so we won't show it here.]


[ANODE «forward-and-back»  (to ".forward-and-back")
  (find-blogme4node "Forward and back")
  [J Keys for following hyperlinks and for going back]

[P (Rewrite this; mention M-k, M-K, `to' and the (disabled) stubs to
  implement a `back' command)]

[P It is so common to have Lisp hyperlinks that extend from some
position in a line --- usually after a comment sign --- to the end of
the line that eev implements a special key for executing these
hyperlinks: the effect of typing M-e (when eev is installed and [`` eev
mode] is on) is roughly the same of first going to the end of the
line and then typing C-x C-e; that is, M-e does the same as the key
sequence C-e C-x C-e(1).]

[P (There are many other kinds of hyperlinks. Examples?)]

[P (1) The main difference between [QQ M-e] and [QQ C-e C-x C-e] is
how they behave when called with numeric [`` prefix arguments]: for
example, [QQ M-0 M-e] highlights temporarily the Lisp expression
instead of executing it and [QQ M-4 M-e] executes it with some
debugging flags turned on, while [QQ C-x C-e] when called with any
prefix argument inserts the result of the expression at the cursor
instead of just showing it at the echo area.]


[ANODE «dangerous-hyperlinks»  (to ".dangerous-hyperlinks")
  (find-blogme4node "Dangerous hyperlinks")
  [J Dangerous hyperlinks]

[SEE: [code eev.el#find-sh], [minicode eev-mini.el#find-sh]]

[P Note that these [`` hyperlinks] can do very dangerous things. If we
start to execute blindly every Lisp expression we see just because it
can do something interesting or take us to an interesting place then
we can end up running something like:

(shell-c ommand "rm -Rf ~")

which destroy all files in our home directory; not a good idea.
Hyperlinks ought to be safer than that... ]

[P The modern approach to safety in hyperlinks --- the one found in
web browsers, for example --- is that following a hyperlink can
execute only a few kinds of actions, all known to be safe; the
[`` target] of a hyperlink is something of the form [QQ http://...],
[QQ ftp://...], [QQ file://...], [QQ info://...], [QQ mailto:...] or
at worst like [QQ javascript:...]; none of these kinds of actions can
even erase our files. That approach limits a lot what hyperlinks can
do, but makes it harmless to hide the hyperlink action and display
only some descriptive text.]

[P Eev's approach is the opposite of that. I wrote the first functions
of eev in my first weeks after installing GNU/Linux in my home machine
and starting using GNU Emacs, in 1994; before that I was using mostly
Forth (on MS-DOS), and I hadn't had a lot of exposure to *nix systems
by then --- in particular, I had tried to understand *nix's notions of
user IDs and file ownerships and permissions, and I felt that they
were a thick layer of complexity that I wasn't being able to get

[P Forth's attitude is more like ``the user knows what he's doing'';
the system is kept very simple, so that understanding all the
consequences of an action is not very hard. If the user wants to
change a byte in a critical memory position and crash the machine he
can do that, and partly because of that simplicity bringing the
machine up again didn't use to take more than one minute (in the good
old days, of course). Forth people developed good backup strategies to
cope with the insecurities, and --- as strange as that might sound
nowadays, where all machines are connected and multi-user and crackers
abound --- using the system in the Forth way was productive and fun.]

[P *NIX systems are not like Forth, but when I started using them I
was accustomed to this idea of achieving simplicity through the lack
of safeguards, and eev reflects that. The only thing that keeps eev's
hyperlinks reasonably safe is [IT transparency]: the code that a
hyperlink executes is so visible that it is hard to mistake a
dangerous Lisp expression for a [`` real] hyperlink. Also, all the safe
hyperlink functions implemented by eev start with `[QQ find-]', and
all the `[QQ find-]' functions in eev are safe, except for those with
names like `[QQ find-xxxsh]' and `[QQ find-xxxsh0]: for example,

(find-sh "wget --help" "recursive download")

executes [`` [QQ wget --help]], puts the output of that in an Emacs
buffer and then jumps to the first occurrence of the string [`` [QQ
recursive download]] there; other `[QQ find-xxxsh]' functions are
variations on that that execute some extra shell commands before
executing the first argument --- typically either switching to another
directory or loading an initialization file, like [QQ ~/.bashrc] or
[QQ ~/.zshrc]. The `[QQ find-xxxsh0]' functions are similar to their
`[QQ find-xxxsh]' counterparts, but instead of creating a buffer with
their output they just show it at Emacs's echo area and they use only
the first argument and ignore the others (the pos-spec).]


[ANODE «generating-hyperlinks»  (to ".generating-hyperlinks")
  (find-blogme4node "Generating Hyperlinks")
  [J Generating Hyperlinks]

[SEE: [code eev-insert.el]]

[P Do we need to remember the names of all hyperlinks functions, like
[QQ find-fline] and [QQ find-node]? Do we need to type the code for
each hyperlink in full by hand? The answers are [`` no] and [`` no].]

[P Eev implements several functions that create temporary buffers
containing hyperlinks, that can then be cut and pasted to other
buffers. For example, `[QQ M-h M-f]' creates links about an Emacs Lisp
function: typing `[QQ M-h M-f]' displays a prompt in a minibuffer
asking for the name of an Elisp function; if we type, say, `[QQ
find-file]' there (note: name completion with the TAB key works in
that prompt) we get a buffer like the one in figure 1.]

|# (find-efunction-links 'find-file)                      |
|                                                         |
|# (where-is 'find-file)                                  |
|# (describe-function 'find-file)                         |
|# (find-efunctiondescr 'find-file)                       |
|# (find-efunction 'find-file)                            |
|# (find-efunctionpp 'find-file)                          |
|# (find-efunctiond 'find-file)                           |
|# (find-eCfunction 'find-file)                           |
|# (find-estring (documentation 'find-file))              |
|# (find-estring (documentation 'find-file t))            |
|                                                         |
|# (Info-goto-emacs-command-node 'find-file)              |
|# (find-enode "Command Index" "* find-file:")            |
|# (find-elnode "Index" "* find-file:")                   |
|                                                         |
|                                                         |
|                                                         |
|--:**  *Elisp hyperlinks*   All L18    (Fundamental)-----|

 Figure 1: the result of typing M-h M-f find-file
[# (find-eevfile "article/ss-m-h.png")
   (find-eevex "screenshots.e" "fisl-screenshots-M-h")

[P The first line of that buffer is a hyperlink to that
dynamically-generated page of hyperlinks. Its function --- `[QQ
find-efunction-links]' --- has a long name that is hard to remember,
but there's a shorter link that will do the same job:]

[# «eek» (find-eev "eev-mini-steps.el" "eek")
[NAME eek]
(eek "M-h M-f find-file")

[P The argument to `eek' is a string describing a sequence of keys in
a certain verbose format, and the effect of running, say, [QQ (eek
"M-h M-f find-file")] is the same as of typing `[QQ M-h M-f

[P ((M-h is a prefix; [QQ (eek "M-h C-h")] shows all the sequences
with the same prefix.))]

[P ((Exceptions: [Q M-h M-c], [Q M-h M-2], [Q M-h M-y]. Show examples
of how to edit hyperlinks with [Q M-h M-2] and [Q M-h M-y].))]

[P ((Mention hyperlinks about a key sequence? [QQ (eek "M-h M-k C-x
[P ((Mention hyperlinks about a Debian package? [QQ (eek "M-h M-d


[ANODE «returning»  (to ".returning")
  (find-blogme4node "Returning from Hyperlinks")
  [J Returning from Hyperlinks]

[P ((Mention M-k to kill the current buffer, and how Emacs asks for
confirmation when it's a file and it's modified))]

[P ((Mention M-K for burying the current buffer))]

[P ((Mention what to do in the cases where a hyperlink points to the
current buffer (section 16); there used to be an [`` ee-back] function
bound to M-B, but to reactivate it I would have to add back some ugly
code to `to'... (by the way, that included Rubikitch's

[P ((Web browsers have a way to [`` return] from hyperlinks: the
[`` back] button... In eev we have many kinds of hyperlinks, including
some that are unsafe and irreversible, but we have a few kinds of
[`` back]s that work... 1) if the hyperlink opened a new file or
buffer, then to kill the file or buffer, use M-k (an eev binding for
kill-this-buffer); note that it asks for a confirmation when the
buffer is associated to a file and it has been modified --- or we can
use bury-buffer; M-K is an eev binding for bury-buffer. ((explain how
emacs keeps a list of buffers?)) Note: if the buffer contains, say, a
manpage, or an html page rendered by w3m, which take a significant
time to generate, then M-K is better is than M-k. 2) if the hyperlink
was a `to' then it jumped to another position in the same file... it
is possible to keep a list of previous positions in a buffer and to
create an `ee-back' function (suggestion: bind it to M-B) but I haver
never been satisfied with the implementations that I did so we're only
keeping a hook in `to' for a function that saves the current position
before the jump))]

[P ((dto recommended winner-undo))]


[ANODE «local-copies»  (to ".local-copies")
  (find-blogme4node "Local copies")
  [J Local copies of files from the internet]

[SEE: [code rcfiles/.bashrc-psne],
      [code rcfiles/.zshrc-psne],
      [AL eev-current/eev-rctool#new_block_bashrc eev-rctool],
      [m.list 2005-06/msg00000.html],
      [gmane 9]]

[P Emacs knows how to fetch files from the internet, but for most
purposes it is better to use local copies. Suppose that the
environment variable [QQ $S] is set to [QQ ~/snarf/]; then running
this on a shell

mkdir -p $S/http/www.gnu.org/software/emacs/
cd       $S/http/www.gnu.org/software/emacs/
wget http://www.gnu.org/software/emacs/emacs-paper.html

# (find-fline "$S/http/www.gnu.org/software/emacs/emacs-paper.html")
# (find-w3m   "$S/http/www.gnu.org/software/emacs/emacs-paper.html")

creates a local copy of [QQ emacs-paper.html] inside [QQ
~/snarf/http/]. The two last lines are hyperlinks to the local copy;
`[QQ find-w3m]' opens it [`` as HTML], using a web browser called w3m
that can be run either in standalone mode or inside Emacs; `[QQ
find-w3m]' uses w3m's Emacs interface, and it accepts extra arguments,
which are treated as a pos-spec-list.]

[P Instead of running the `[QQ mkdir]', `[QQ cd]' and `[QQ wget]'
lines above we can run a single command that does everything:

psne http://www.gnu.org/software/emacs/emacs-paper.html

which also adds a line with that URL to a log file (usually [QQ
~/.psne.log]). It is more convenient to have a `[QQ psne]' that
changes the current directory of the shell than one that doesn't, and
for that it must be defined as a shell function.]

[# «rcfiles»  (to ".rcfiles")
[NAME rcfiles]

[P Eev comes with an installer script, called [QQ eev-rctool], that
can help in adding the definitions for eev (like the [`` [QQ function ee
() { source ~/ee.sh; }]] of section 3) to initialization files like
[QQ ~/.bashrc] (such initialization files are termed [`` rcfiles]).
Eev-rctool does [IT not] add by default the definitions for `[QQ
psne]' and for [QQ $S] to rcfiles; however, it adds commented-out
lines with instructions, which might be something like:]

# To define $S and psne uncomment this:
#   . $EEVTMPDIR/psne.sh
# (find-eevtmpfile "psne.sh")

[P ((See: [R


[ANODE «glyphs»  (to ".glyphs")
  (find-blogme4node "Glyphs")
  [J Glyphs]

[SEE: [code eev-glyphs.el],
      [code eev-math-glyphs.el],
      [minicode eev-mini.el#eev-glyph-face-red]
      [flipbook ee-glyph.html]]

[P Emacs allows redefining how characters are displayed, and one of
the modules of eev --- eev-glyphs --- uses that to make some
characters stand out. Character 15, for example, is displayed on the
screen by default as '[QQ ^O]' (two characters, suggesting
[`` control-O]), sometimes in a different color from normal text(3).]

[P Eev changes the appearance of char 15 to make it be displayed as a
red star. Here is how: Emacs has some structures called [`` faces] that
store font and color information, and `[QQ eeglyphs-face-red]' is a
face that says [`` use the default font and the default background
color, but a red foreground]; eev's initialization code runs this,

(eev-set-glyph 15 ?* 'eev-glyph-face-red)

which sets the representation of char 15 to the [`` glyph] made of a
star in the face eeglyphs-face-red. ]

[P For this article, as red doesn't print well in black and white, we
used this instead:

(eev-set-glyph 15 342434)

this made occurrences of char 15 appear as the character 342434, `[QQ
*]' (note that this is outside of the ascii range), using the default
face, i.e., the default font and color.]

[P Eev also sets a few other glyphs with non-standard faces. The most
important of those are `[QQ «]' and '[QQ »]', which are set to appear
in green against the default background, with:

(eev-set-glyph 171 171 'eev-glyph-face-green)
(eev-set-glyph 187 187 'eev-glyph-face-green)

There's a technical point to be raised here. Emacs can use several
[`` encodings] for files and buffers, and `[QQ «]' and `[QQ »]' only
have character codes 171 and 187 in a few cases, mainly in the
`raw-text' encoding and in [`` unibyte] buffers; in most other
encodings they have other char codes, usually above 255, and when they
have these other codes Emacs considers that they are other characters
for which no special glyphs were set and shows them in the default
face. This visual distinction between the below-255 `[QQ «]' and `[QQ
]' and the other `[QQ «]' and `[QQ »]'s is deliberate --- it helps
preventing some subtle bugs involving the anchor functions of section

[P (3). Determined by the [`` face] escape-glyph-face, introduced in
GNU Emacs in late 2004.]


[ANODE «compose-pairs»  (to ".compose-pairs")
  (find-blogme4node "Compose Pairs")
  [J Compose Pairs]

[SEE: [code eev-compose.el]]

[P To insert a `[QQ *]' in a text we type `[QQ C-q C-o]' --- [QQ C-q]
[`` quotes] the next key that Emacs receives, and `[QQ C-q C-o]'
inserts a [`` literal C-o], which is a char 15. Typing `[QQ «]' and
`[QQ »]'s --- and other non-standard glyphs, if we decide to define
our own --- involves using another module of eev: eev-compose.]

[P Eev-compose defines a few variables that hold tables of [`` compose
pairs], which map pairs of characters that are easy to type into
other, weirder characters; for example, `eev-composes-otheriso' says
that the pair "[QQ <<]" is mapped to "[QQ «]" and that "[QQ >>]" is
mapped to "[QQ »]", among others. When we are in [`` eev mode] the
prefix `[QQ M-,]' can be used to perform the translation: typing `[QQ
M-, < <]' enters `[QQ «]', and typing `[QQ M-, > >]' enters `[QQ »]'.]

[P The variable `[QQ eev-composes-accents]' holds mappings for
accented chars, like "[QQ 'a]" to "[QQ á]" and "[QQ cc]" to "[QQ ç]";
`[QQ eev-composes-otheriso]' takes care of the other mappings that
still concern characters found in the ISO8859-1 character set, like
`[QQ «]' and '[QQ »]' as above, "[QQ _a]" to "[QQ ª]", "[QQ xx]" to
"[QQ ×]", and a few others; `[QQ eev-composes-globalmath]' and `[QQ
eev-composes-localmath]' are initially empty and are meant to be used
for used-defined glyphs. The suffix `[QQ math]' in their names is a
relic: Emacs implements its own ways to enter special characters,
which support several languages and character encodings, but their
code is quite complex and they are difficult to extend; the code that
implements eev's `[QQ M-,]', on the other hand, takes about just 10
lines of Lisp (excluding the tables of compose pairs) and it is
trivial to understand and to change its tables of pairs. `[QQ M-,]'
was created originally to enter special glyphs for editing
mathematical texts in TeX, but it turned out to be a convenient hack,
and it stuck.]


[ANODE «delimited-regions»  (to ".delimited-regions")
  (find-blogme4node "Delimited regions")
  [J Delimited regions]

[SEE: [code eev-bounded.el],
      [minicode eev-mini.el#eeb-default],
      [shot doc/shot-f3.png],
      [anim gdb.anim.html]]

[P Sometimes it happens that we need to run a certain (long) series of
commands over and over again, maybe with some changes from one run to
the next; then having to mark the block all the time becomes a hassle.]

[P One alternative to that is using a variaton on `[QQ M-x eev]': `[QQ
M-x eev-bounded]'. It saves the region around the cursor up to certain
delimiters instead of saving what's between Emacs's [`` point] and
[`` mark].]

[P The original definition of eev-bounded was something like this:

(defun eev-bounded ()
  (eev (ee-search-backwards "\n#*\n")
       (ee-search-forward   "\n#*\n")))

the call to `[QQ ee-search-backwards]' searches for the first
occurrence of the string "[QQ \n#*\n]" (newline, hash sign, control-O,
newline) before the cursor and returns the position after the "[QQ
\n#*\n]", without moving the cursor; the call to [QQ
ee-search-forward] does something similar with a forward search. As
the arguments to `[QQ eev]' indicate the extremities of the region to
be saved into the temporary script, this saves the region between the
first "[QQ \n#*\n]" backwards from the cursor to the first "[QQ
\n#*\n]" after the cursor.]

[P The actual definition of `[QQ eev-bounded]' includes some extra
code to highlight temporarily the region that was used; see Figure
((fig:F3)). Normally the highlighting lasts for less than one second,
but here we have set its duration to several seconds to produce a more
interesting screenshot.]

 ____________________ emacs@localhost _______________________ 
|                                                _________ xterm __________ 
|#*                                             |/home/edrx(edrx)# ee      |
|# Global variables                             |# Global variables        |
|lua50 -e '                                     |lua50 -e '                |
|  print(print)                                 |  print(print)            |
|  print(_G["print"])                           |  print(_G["print"])      |
|  print(_G.print)                              |  print(_G.print)         |
|  print(_G)                                    |  print(_G)               |
|  print(_G._G)                                 |  print(_G._G)            |
|'                                              |'                         |
|#*                                             |function: 0x804dfc0       |
|# Capture of local variables                   |function: 0x804dfc0       |
|lua50 -e '                                     |function: 0x804dfc0       |
|  foo = function ()                            |table: 0x804d420          |
|    local storage                              |table: 0x804d420          |
|    return                                     |/home/edrx(edrx)#         |
|      (function () return storage end),        |__________________________|
|      (function (x) storage = x; return x end)              |              
|  end                                                       |
|  get1, set1 = foo()                                        |
|  get2, set2 = foo()               -- Output:               |
|  print(set1(22), get1())          -- 22 22                 |
|  print(set2(33), get1(), get2())  -- 33 22 33              |
|'                                                           |
|#*                                                          |
|                                                            |
|-:--  lua5.e   91% L325    (Fundamental)--------------------|

  Figure 2: sending a delimited block with F3
  (find-fline "ss-lua.png")
  (find-eevex "screenshots.e" "fisl-screenshots")

[P Eev binds the key F3 to the function `[QQ eeb-default]', which runs
the current [`` default bounded function] (which is set initially to
`[QQ eev]', [IT not] `[QQ eev-bounded]') on the region between the
current default delimiters, using the current default
[`` highlight-spec]; so, instead of typing `[QQ M-x eev-bounded]'
inside the region to save it we can just type F3.]

[P All these defaults values come from a single list, which is stored
in the variable `[QQ eeb-defaults]'. The real definition of `[QQ
eev-bounded]' is something like:]

(setq eev-bounded
  '(eev ee-delimiter-hash nil t t))

(defun eev-bounded ()
  (setq eeb-defaults eev-bounded)

[P Note that in Emacs Lisp (and in most other Lisps) each symbol has a
value as a variable that is independent from its [`` value as a
function]: actually a symbol is a structure containg a name, a
[`` value cell], a [`` function cell] and a few other fields. Our
definition of `[QQ eev-bounded]', above, includes both a definition of
the function `[QQ eev-bounded]' and a value for the variable `[QQ

[P Eev has an auxiliary function for defining these [`` bounded
functions]; running

(eeb-define 'eev-bounded 'eev 'ee-delimiter-hash nil t t)

has the same effect as doing the `[QQ setq]' and the `[QQ defun]'

[P As for the meaning of the entries of the list `[QQ eeb-defaults]',
the first one (`[QQ eev]') says which function to run; the second one
(`[QQ ee-delimiter-hash]') says which initial delimiter to use --- in
this case it is a symbol instead of a string, and so `[QQ
eeb-default]' takes the value of the variable `[QQ
ee-delimiter-hash]'; the third one (nil) is like the second one, but
for the final delimiter, and when it is nil `[QQ eeb-default]'
considers that the final delimiter is equal to the initial delimiter;
the fourth entry ([QQ t]) means to use the standard highlight-spec,
and the fifth one ([QQ t], again) tells `[QQ eeb-default]' to make an
adjustment to the highlighted region for purely aestethical reasons:
the saved region does not include the initial "[QQ \n]" in the final
delimiter, "[QQ \n#*\n]", but the highlighting looks nicer if it is
included; without it the last highlighted line in Figure 2 would have
only its first character --- an apostrophe --- highlighted.]

[P Eev also implements other of these [`` bounded] functions. For
example, running `[QQ M-x eelatex]' on a region saves it in a
temporary LaTeX file, and also saves into the temporary script file
the commands to process it with LaTeX; `[QQ eelatex-bounded]' is
defined by

(eeb-define 'eelatex-bounded 'eelatex
  'ee-delimiter-percent nil t t)

where the variable `[QQ ee-delimiter-percent]' holds the string "[QQ
\n%*\n]"; comments in LaTeX start with percent signs, not hash signs,
and it is convenient to use delimiters that are treated as comments.]

[P ((The block below ... tricky ... blah. How to typeset `[QQ *]' in
LaTeX. Running eelatex-bounded changed the defaults stored in
eeb-defaults, but ee-once blah doesn't.))]

% (eelatex-bounded)
% (ee-once (eelatex-bounded))
  \hbox to \wd0{\hss#1\hss}%
\catcode`*=13 \def*{\myttbox{$\bullet$}}

[P ...for example eelatex, that saves the region (plus certain
standard header and footer lines) to a [`` temporary LaTeX file] and
saves into the temporary script file the commands to make `ee' run
LaTeX on that and display the result. The block below is an example of

[P ...The block below shows a typical application of [QQ

# (find-es "lua5" "install-5.0.2")
# (find-es "lua5" "install-5.0.2" "Edrx's changes")

# (code-c-d "lua5" "/tmp/usrc/lua-5.0.2/")
# (find-lua5file "INSTALL")
# (find-lua5file "config" "support for dynamic loading")
# (find-lua5file "config")
# (find-lua5file "")
rm   -Rv ~/usrc/lua-5.0.2/
mkdir -p ~/usrc/lua-5.0.2/
tar   -C ~/usrc/ \
   -xvzf $S/http/www.lua.org/ftp/lua-5.0.2.tar.gz
cd       ~/usrc/lua-5.0.2/
cat >> config <<'---'
DLLIB= -ldl
EXTRA_LIBS= -lm -ldl
make test  2>&1 | tee omt
./bin/lua -e 'print(loadlib)'

it unpacks a program (the interpreter for Lua), changes its default
configuration slightly, then compiles and tests it.]

[P ((Comment about the size: the above code is [`` too small for being a
script], and the hyperlinks are important))]

[P gdb (here-documents, gcc, ee-once)]

[P (alternative: here-documents, gcc, gdb, screenshot(s) for gdb)]


[ANODE «channels»  (to ".channels")
  (find-blogme4node "Communication channels")
  [J Communication channels]

[SEE: [code eev-steps.el],
      [code eegchannel],
      [minicode eev-mini-steps.el],
      [anim channels.anim.html]]

[P The way that we saw to send commands to a shell is in two steps:
first we use [QQ M-x eev] in Emacs to [`` send] a block of commands,
and then we run `[QQ ee]' at the shell to make it [`` receive] these
commands. But there is also a way to create shells that [`` listen] not
only to the keyboard for their input, but also to certain
[`` communication channels]; by making Emacs send commands through
these communication channels we can skip the step of going to the
shell and typing `[QQ ee]' --- the commands are received immediately.]

 _________emacs@localhost____________   ___________channel A______________
|                                    | |/tmp(edrx)# # Send things to port |
|* (eechannel-xterm "A") ;; create   | | 1234                             |
|* (eechannel-xterm "B") ;; create   | |/tmp(edrx)# {                     |
|# Listen on port 1234               | |>   echo hi                       |
|netcat -l -p 1234                   | |>   sleep 1                       |
|*                                   | |>   echo bye                      |
|* (eechannel "A") ;; change target  | |>   sleep 1                       |
|# Send things to port 1234          | |> } | netcat -q 0 localhost 1234  |
|{                                   | |/tmp(edrx)#                       |
|  echo hi                           | |/tmp(edrx)#                       |
|  sleep 1                           | |__________________________________|
|  echo bye                          |  ___________channel B______________
|  sleep 1                           | |/tmp(edrx)# # Listen on port 1234 |
|} | netcat -q 0 localhost 1234      | |/tmp(edrx)# netcat -l -p 1234     |
|                                    | |hi                                |
|-:--  screenshots.e   95% L409   (Fu| |bye                               |
|_Wrote /home/edrx/.eev/eeg.A.str____| |/tmp(edrx)#                       |
                                       |                                  |
 Figure 3: sending commands to two xterms using F9
 (find-eevex "screenshots.e" "fisl-screenshots")
 (find-eevfile "article/ss-f9.png")

[P The screenshot at Figure 3 shows this at work. The user has started
with the cursor at the second line from the top of the screen in the
Emacs window and then has typed F9 several times. Eev binds F9 to a
command that operates on the current line and then moves down to the
next line; if the current line starts with `[QQ *]' then what comes
after the `[QQ *]' is considered as Lisp code and executed
immediately, and the current line doesn't start with `[QQ *]' then its
contents are sent through the default communication channel, or though
a dummy communication channel if no default was set.]

[P The first F9 executed `[QQ (eechannel-xterm "A")]', which created
an xterm with title [`` [QQ channel A]], running a shell listening on
the communication channel [`` [QQ A]], and set the default channel to
A; the second F9 created another xterm, now listening to channel [QQ
B], and set the default channel to [QQ B].]

[P The next two `[QQ F9]'s sent each one one line to channel [QQ B].
The first line was a shell comment ([`` [QQ # Listen...]]); the second
one started the program [QQ netcat], with options to make [QQ netcat]
[`` listen to the internet port 1234] and dump to standard output what
it receives.]

[P The next line had just `[QQ *]'; executing the rest of it as Lisp
did nothing. The following line changed the default channel to A.]

[P In the following lines there is a small shell program that outputs
[`` [QQ hi]], then waits one second, then outputs [`` [QQ bye]], then
waits for another second, then finishes; due to the [`` [QQ |
netcat...]] its output is redirected to the internet port 1234, and
so we see it appearing as the output of the netcat running on channel
[QQ B], with all the expected delays: one second between [`` [QQ hi]]
and [`` [Q bye]], and one second after [`` [QQ bye]]; after that last
one-second delay the netcat at channel [QQ A] finishes receiving input
(because the program between `[QQ {]' and `[QQ }]' ends) and it
finishes its execution, closing the port 1234; the netcat at [QQ B]
notices that the port was closed and finishes its execution too, and
both shells return to the shell prompt.]

[P There are also ways to send whole blocks of lines at once through
communication channels; see Section ((bigmodular)).]


[ANODE «channels-implementation»  (to ".channels-implementation")
  (find-blogme4node "Implementation of channels")
  [J The Implementation of Communication Channels]

[SEE: [code eev-steps.el],
      [code eegchannel],
      [minicode eev-mini-steps.el],
      [anim channels.anim.html]]

[SMALL [P [IT [<]2007: There's a much better explanation, with nice
ascii diagrams, at [R eev-current/anim/channels.anim.html
channels.anim]; it should be merged here.[>]]]]

[P Communication channels are implemented using an auxiliary script
called `eegchannel', which is written in Expect ([REF L90] and [REF
L95]). If we start an xterm in the default way it starts a shell (say,
[QQ /bin/bash]) and interacts with it: the xterm sends to the shell as
characters the keystrokes that it receives from the window manager and
treats the characters that the shell sends back as being instructions
to draw characters, numbers and symbols on the screen. But when we run
`[QQ (eechannel-xterm "A")]' Emacs creates an xterm that interacts
with another program --- [QQ eegchannel] --- instead of with a shell,
and [QQ eegchannel] in its turn runs a shell and interacts with it.]

[P Eegchannel passes characters back and forth between the xterm and
the shell without changing them in any way; it mostly tries to pretend
that it is not there and that the xterm is communicating directly with
the shell. However, when eegchannel receives a certain signal it sends
to the shell a certain sequence of characters that were not sent by
the xterm; it [`` fakes a sequence of keystrokes].]

[P Let's see a concrete example. Suppose than Emacs was running with
process id ([`` pid]) 1000, and running [QQ (eechannel-xterm "A")] in
it made it create an xterm, which got pid 1001; that xterm ran
eegchannel (pid 1002), which ran /bin/bash (pid 1003). Actually Emacs
invoked xterm using this command line:]

xterm -n "channel A" -e eegchannel A /bin/bash

[P and xterm invoked eegchannel with [`` [QQ eegchannel A /bin/bash]];
eegchannel saw the `[QQ A]', saved its pid (1002) to the file [QQ
~/.eev/eeg.A.pid], and watched for [QQ SIGUSR1] signals; every time
that it (the eegchannel) receives a [QQ SIGUSR1] it reads the contents
of [QQ ~/.eev/eeg.A.str] and sends that as fake input to the shell
that it is controlling. So, running]

echo 'echo $[1+2]' > ~/.eev/eeg.A.str
kill -USR1 $(cat ~/.eev/eeg.A.pid)

[P in a shell sends the string [`` [QQ echo $[1+2]]] (plus a newline)
[`` through the channel A]; what Emacs does when we type F9 on a line
that does not start with `[QQ *]' corresponds exactly to that.]


[ANODE «anchors»  (to ".anchors")
  (find-blogme4node "Anchors")
  [J Anchors]

[SEE: [code eev.el#ee-goto-anchor]]

[P The function `[QQ to]' can be used to create hyperlink to certain
positions --- called [`` anchors] --- in the current file. For

# Index:
# «.first_block»        (to "first_block")
# «.second_block»       (to "second_block")

# «first_block»  (to ".first_block")
echo blah
# «second_block»  (to ".second_block")
echo blah blah

[P What `to' does is simply to wrap its argument inside `[QQ «]' and
`[QQ »]' characters and then jump to the first occurrence of the
resulting string in the current file. In the (toy) example above, the
line that starts with [`` [QQ # «.first_block»]] has a link that jumps
to the line that starts with [`` [QQ # «first_block»]], which has a
link that jumps back --- the anchors and [`` [QQ (to ...)]]s act like
an index for that file.]

[P The function `[QQ find-anchor]' works like a `[QQ to]' that first
opens another file. For example,]

(find-anchor "~/.zshrc" "update-homepage")

[P does roughly the same as:]

(find-fline "~/.zshrc" "«update-homepage»")

[P Actually `[QQ find-anchor]' consults a variable, `[QQ
ee-anchor-format]', to see in which strings to wrap the argument. Some
functions modify `[QQ ee-anchor-format]' temporarily to obtain special
effects; for example, a lot of information about the packages
installed in a Debian GNU system is kept in a text file called [QQ
/var/lib/dpkg/info/status]; [QQ (find-status "emacs21")] opens this
file and searches for the string "[QQ \nPackage: emacs21\n]" there ---
that string is the header for the block with information about the
package [QQ emacs21], and it tells the size of the package,
description, version, whether it is installed or not, etc, in a format
that is both machine-readable and human-readable.]


[ANODE «e-scripts»  (to ".e-scripts")
  (find-blogme4node "E-scripts")
  [J E-scripts]

[P The best short definition for eev that I've found involves some
cheating, as it is a circular definition: [`` eev is a library that adds
support for e-scripts to Emacs] --- and e-scripts are files that
contain chunks meant to be processed by eev's functions. Almost any
file can contain parts [`` meant for eev]: for example, a [QQ HOWTO] or
[QQ README] file about some program will usually contain some example
shell commands, and we can mark these commands and execute them with
[QQ M-x eev]; and if we have the habit of using eev and we are writing
code in, say, C or Lua we will often put elisp hyperlinks inside
comment blocks in our code. These two specific languages (and a few
others) have a feature that is quite convenient for eev: they have
syntactical constructs that allow comment blocks spanning several
lines --- for example, in Lua, where these comment blocks are
delimited by [`` [QQ --((]] and [`` [QQ --))]]s, we can have a block

# This file: (find-fline "~/LUA/lstoindexhtml.lua")
# A test:
cd /tmp/
ls -laF | col -x \
  | lua50 ~/LUA/lstoindexhtml.lua tmp/ \
  | lua50 -e 'writefile("index.html", io.read("*a"))'

[P in a Lua script, and the script will be at the same time a Lua
script and an e-script.]

[P When I started using GNU and Emacs the notion of an e-script was
something quite precise to me: I was keeping notes on what I was
learning and on all that I was trying to do, and I was keeping those
notes in a format that was partly English (or Portuguese), partly
executable things --- not all of them finished, or working --- after
all, it was much more practical to write]

rm -Rv ~/usrc/busybox-1.00/
tar -C ~/usrc/ -xvzf \
cd ~/usrc/busybox-1.00/
cp -iv ~/BUSYBOX/myconfig .config
make menuconfig
make       2>&1 | tee om

[P than to write]

Unpack BusyBox's source, then run "make menuconfig"
and "make" on its main directory

[P because if I had the second form in my notes I would have to
translate that from English into machine commands every time... So,
those files where I was keeping my notes contained [`` executable
notes], or were [`` scripts for Emacs], and I was quite sure that
everyone else around were also keeping notes in executable formats,
possibly using other editors and environments (vi, maybe?) and that if
I showed these people my notes and they were about some task that they
were also struggling with then they would also show me [IT their]
notes... I ended up making a system that uploaded regularly all my
e-scripts (no matter how messy they were) to my home page, and writing
a text --- [`` The Eev Manifesto] ([REF O99]) --- about sharing these
executable notes.]

[P Actually trying to define an e-script as being [`` a file containing
executable parts, that are picked up and executed interactively]
makes the concept of an e-script [IT very] loose.]

[P Note that we [IT can] execute the Lua parts in the code above by
running the Lua interpreter on it, we [IT can] execute the elisp
one-liner with [QQ M-e] in Emacs, and we [IT can] execute the shell
commands using F3 or [QQ M-x eev]; but the code will do nothing by
itself --- it is passive.]

[P A piece of code containing instructions in English on how to use it
is also an e-script, in a sense; but to execute these instructions we
need to invoke an external entity --- a human, usually ourselves ---
to interpret them. This is much more flexible, but also much more
error-prone and slow, than just pressing a simple sequence of keys
like M-e, or F9, or F3, alt-tab, e, e, enter.]


[ANODE «splitting-eev.el»  (to ".splitting-eev.el")
  (find-blogme4node "Splitting eev.el")
  [J Splitting eev.el]

[SEE: [code eev.el#find-man],
      [minicode eev-mini.el#find-man]]

[P When I first submittted eev for inclusion in GNU Emacs, in 1999,
the people at the FSF requested some changes. One of them was to split
eev.el --- the code at that point was all in a single Emacs Lisp file,
called eev.el --- into several separate source files according to
functionality; at least the code for saving temporary scripts and the
code for hyperlinks should be kept separate.]

[P It turned out that that was the wrong way of splitting eev. The
frontier between what is a hyperlink and what is a block of commands
is blurry:]

man foo
man -P 'less +/bar' foo
# (eev "man foo")
# (eev "man -P 'less +/bar' foo")
# (find-man "foo" "bar")

[P The two `[QQ man]' commands above can be considered as hyperlinks
to a manpage, but we need to send those commands to a shell to
actually open the manpage; the option "[QQ -P 'less +/bar']" instructs
`[QQ man]' to use the program `[QQ less]' to display the manpage, and
it tells `[QQ less]' to jump to the first occurrence of the string
[`` [QQ bar]] in the text, and so it is a hyperlink to a specific
position in a manpage. Each of the two `[QQ eev]' lines, when
executed, saves one of these `[QQ man]' commands to the temporary
script file; because they contain Lisp expressions they look much more
like hyperlinks than the `[QQ man]' lines. The last line, `[QQ
find-man]', behaves much more like a [`` real] hyperlink: it opens the
manpage [IT inside Emacs] and searches for the first occurrence of
`[QQ bar]' there; but Emacs's code for displaying manpages was tricky,
and it took me a few years to figure out how to add support for
pos-spec-lists to it...]

[P So, what happens is that often a new kind of hyperlink will begin
its life as a series of shell commands (another example: using `[QQ gv
--page 14 file.ps]' to open a PostScript file and then jump to a
certain page) and then it takes some time to make a nice hyperlink
function that does the same thing; and often these functions are
implemented by executing commands in external programs.]

[P There's a much better way to split conceptually what eev does,
though. Most functions in eev take a region of text (for example
Emacs's own [`` selected region], or the extent of Lisp expression
coming before the cursor) and [`` execute] that in some way; the kinds
of regions are]

Emacs's (selected) region   | M-x eev, M-x eelatex (sec. 4)
last-sexp (Lisp expression  | C-x C-e, M-E         (sec. 5)
at the left of the cursor)  | 
sexp-eol (go to end of      | C-e C-x C-e, M-e     (sec. 7)
line, then last-sexp)       |
bounded region              | F3, M-x eev-bounded,
                            | M-x eelatex-bounded (sec. 14)
bounded region around       | (ee-at [`` anchor] ...)
anchor                      |                     (sec. 20)
current line                | F9                  (sec. 15)
no text (instead use the    | F12                 (sec. 19)
next item in a list)        |

Actions (can be composed):
  * Saving a region or a string into a file
  * Sending a signal to a process
  * Executing as Lisp
  * Executing immediately in a shell
  * Start a debugger

[P ((Emacs terminology: commands))]


[ANODE «eesteps»  (to ".eesteps")
  (find-blogme4node "Steps")
  [J Steps]

[SEE: [code eev-steps.el#eesteps],
      [minicode eev-mini-steps.el#eesteps],
      [flipbook eesteps.html]]

[P ((Simple examples))]

[P ((writing demos))]

[P ((hyperlinks for which no short form is known))]

[P ((producing animations and screenshots))]


[ANODE «eepitch»  (to ".eepitch")
  (find-blogme4node "eepitch")
  [J Sending lines to processes running in Emacs buffers]

[# (find-es "davinci" "eepitch-gdb")

[P [IT (These sections - 20 to 24 - are very new (handwritten in
2007jul12, typed a few days later). They are early drafts, full of
errors, describing some code that does not yet exist (ee-tbr), etc.
Also, I don't know Rubikitch's real name, so I used a random Japanese

[P Emacs can run external programs interactively inside buffers; in
the screenshot in Figure 5 there's a shell running in the buffer
"*shell*" in the lower window. Technically, what is going on is much
more complex than what we described in the previous section. The shell
runs in a pseudo-terminal (pty), but ptys are usually associated to
rectangular grids of characters with a definite width and height,
while in an Emacs buffer the width of each line, and the total number
of lines,are only limited by memory constraints. Many interactive
programs expect their input to come through their more-or-less
minimalistic line editors, that may try to send to the terminal
commands like "clear the screen" or "go to column x at line y"; how
should these things be handled in a shell buffer? Also, the user can
move freely in a shell buffer, and edit its contents as text, but the
"Return" key becomes special: when it is hit in a shell buffer Emacs
takes the current line - except maybe some initial characters that are
seen as a prompt - and sends that to the shell process, as if the user
had typed exactly that; so, Emacs takes over the line editor of the
shell process completely. The translation between character sequences
going through the pty and buffer-editing functions is very tricky,
full of non-obvious design choices, and even though it has been around
for more than 20 years it still has some (inevitable) quirks.]

[P I almost never used shell buffers, so I found the following idea,
by OGAMI Itto, very surprising when he sent it to the eev mailing list
in 2005.]

(Figure 5 will be a screenshot that I haven't taken yet.)
(It will be simpler than the screenshot from Fig. 6,
 that is this: http://angg.twu.net/IMAGES/eepitch-gdb.png )

[P The current window, above in Figure 5, is editing an e-script, and
the other window shows a shell buffer - that we will refer to as the
"target buffer". When the user types a certain key - by default F8 -
the current line is sent to the target buffer, and the point is moved
down to the next line; pressing F8 n times in sequence sendsn lines,
one by one.]

[P One detail: "sending a line" means inserting its contents - except
the newline - at the current position in the target buffer, and then
running there the action associated to the "Return" key. "Return" is
almost always a special key, bound to different actions in different
major modes, so just inserting a newline would not work - that would
not simulate what happens when a user types "Return".]

[NAME F8-is-simpler-than-F9]
[#   «F8-is-simpler-than-F9» ]

[P Note that, in a sense, the action of F8 is much more complex than
that of F9, described in the last section; but user might perceive F8
as being much simpler, as there are no external programs involved
(Expect, eegchannel, xterm), and no setup hassles - all the machinery
to make Emacs buffers invoke external processes in buffers pretending
to be terminals ("comint mode") comes built-in with Emacs since the
early 1980s.]

[P Ogami's idea also included three "bonus features": window setup,
reconstruction of the target buffer, and star-escapes. In the default
Emacs setting some commands - M-x shell between them - might split the
current Emacs frame in two windows; none of eev's hyperlink functions
do that, and I have always felt that it is more natural to use eev with
a setting (pop-up-windows set to nil) that disables window splittings
except when explicitly requested by the user. Anyway: M-x shell
ensures that a "*shell*" buffer is visible in a window, and that a
shell process is running in it; this setup code for F8,]

[QQQ (eepitch '(shell))]

[P splits the window (if the frame has just one window), and runs
`(shell)' in the other window - with the right defaults - to force
that window to display a shell buffer with a live shell process
running in it; it also sets a variable, `eepitch-target-buffer', to
that buffer, so that the next `F8's will have a definite buffer to
send lines too - as target buffers need not necessarily be shell

[P As for the star-escapes, it's the same idea as with F9: when a line
starts with a red star glyph, running F8 on it executes everything on
it - after the red star - as Lisp, and if there are no errors the
point is moved down. So lines starting with a red star can be used to
set up an eepitch target, to switch to another target, or to do
special actions - like killing a certain target so that it will be
reconstructed anew by the next F8. Note that once that we recognize
that a region of an e-script is to be used by eepitch there is only
one key to be used to "run" each of its lines, both the ones with red
stars and the ones without: F8. However, as with F9, the user must
know what to expect after each step. A badly-written e-script for
eepitch may try, for example, to "cd" into a directory that does not
exist, and if the next line is, say, "[TT tar -xvzf
$S/http/foo/bar.tgz]" then it will try to unpack a tarball into the
wrong place, creating a big mess.]


[ANODE «eepitch-unprepared»  (to ".eepitch-unprepared")
  (find-blogme4node "eepitch to unprepared shells")
  [J Using eepitch to control unprepared shells]

# (find-eevfile "eev.el" "EEVDIR")
# (find-eevfile "eev.el")

[P As we have seen in section 4, M-x eev sends the region to a
"prepared shell"; if the shell has the right settings for the
environment variables $EEVTMPDIR and $EE, and if it has the shell
function `ee', then running `ee' in the shell "sources" the temporary
script - corresponding to the regin - in verbose mode. Well, if Emacs
loads eev.el and the environment variables $EEVDIR, $EEVTMPDIR and $EE
are not set, then they are set, respectively, to the directory where
eev.el was read from, to the subdirectory of it given by $EEVDIR/tmp,
and to the file $EEVTMPDIR/ee.sh. Processes started from Emacs inherit
these environment variables, so a shell buffer created by running F8
on these two lines,]

* (eepitch-shell)
function ee () { set -v; . $EE; set +v; }

[P will be running a prepared shell. Such buffers can be used to let
users understand better how prepared shells work, and decide if they
want to patch their initialization files for the shell (see
eev-rctool) so that their shells will be "prepared" by default.]

[P [IT (Note: I haven't yet played much with this idea - discuss
running eev-rctool on such shells (and a function that creates a
buffer with an e-script for that), and loading psne.sh from an
unprepared shell).]]


[ANODE «eepitch-gud»  (to ".eepitch-gud")
  (find-blogme4node "eepitch and GUD")
  [J Controlling debuggers with eepitch]

[SEE: [AL http://angg.twu.net/.emacs.html#eepitch-gdb .emacs],
      [m.list 2007-07/msg00000.html],
      [gmane 47]]

# (find-node "(emacs)Debuggers")
# (find-node "(gdb)Top")
# (find-angg ".emacs" "eepitch-gdb")

[P On *NIX it is common to keep debuggers separated into two parts: a
back-end, with a simple textual interface, and a front-end, that
controls the back-end via its textual interface but presents a better
interface, showing source files and breakpoints in a nice way, etc.
The GNU Debugger, GDB, is a back-end, and it can be used to debug and
single-step several compiled languages; the "Grand Unified Debugger"
mode of Emacs, a.k.a. GUD, is a front-end for GDB and other

[P Usually, GUD splits an Emacs frame into two windows, one for
interaction with GDB (or other back-end, but let's say just "GDB" for
simplicity), and another one for displaying the source file where the
execution is. Some of the output of GDB - lines meaning, e.g., "we're
at the source file foo.c, at line 25" - are filtered by GUD and are
not shown in the GUD buffer; and the user can press special key
sequences on source files that generate commands to GDB - like, "set a
breakpoint on this line".]

[P In order to control GDB with eepitch we need a window setting with
three windows, like in the screenshot in Figure 6.]

^ Figure 6 will be like the screenshots (real and asciified)
  in this message to the mailing list

[P The way to set up that does not integrate very well with the
"standard" eepitch at this moment, but that should come with time.]


[ANODE «eepitch-gdb»  (to ".eepitch-gdb")
  (find-blogme4node "eepitch and GDB")
  [J E-scripting GDB with eepitch]

# (find-node "(gdb)Set Breaks" "`tbreak ARGS'")
# (find-node "(elisp)The Buffer List")
# (find-es "lua5" "lua-api-from-gdb")
# (find-TH "luaforth" "lua-api-from-gdb")

[P We can use elisp hyperlinks to point to specific lines in source
files - and we can combine these hyperlinks with the code to set up
breakpoints, in two ways.]

*;(find-lua51file "src/lvm.c" "case OP_CLOSE:" 1)
* (find-lua51file "src/lvm.c" "case OP_CLOSE:" 1 '(ee-tbr))

[P The first line above contains an elisp hyperlink to a line in the
source of Lua. Actually, it points to the code for an opcode in Lua's
virtual machine that most people find rather mysterious. As the line
starts with `*;', an F8 on it executes a Lisp comment - i.e., does
nothing - and moves down; only a `M-e' (or a `C-e C-x C-e') on that
line would follow the hyperlink.]

[P The second line, when executed with F8, would go to that line in
the source, then run `(ee-tbr)' there; ee-tbr invokes gud-tbr to set a
temporary breakpoint on that source line (i.e., one that is disabled
when the execution stops there for the first time), and then buries
the buffer - the one with "lmv.c" - like a `M-K' would do; the effect
is that the buffer in that window - the top-left window in a situation
like in Figure 6 - does not change, it will still show the e-script.]

[P A variation on this is to wrap the hyperlink in an ee-tbr:]

* ;        (find-lua51file "src/lvm.c" "case OP_CLOSE:" 1)
* (ee-tbr '(find-lua51file "src/lvm.c" "case OP_CLOSE:" 1))

[P When ee-tbr is called with an argument it evaluated the argument
inside a save-excursion, and sets a breakpoint there; the effect is
almost the same as the previous case, but this does not change the
order of the buffers in the buffer list.]


[ANODE «little-dbg-langs»  (to ".little-dbg-langs")
  (find-blogme4node "Two little languages for debugging")
  [J Two little languages for debugging]

[P E-scripts for eepitch and GDB can be used to bring programs to a
certain point (and to inspect their data structures there; we will
have more to say about this in the next section). In a sense, as in
[BF ((Bentley))], these e-scripts are written in a language that
describes states of running programs - and they can be executed step
by step.]

[P These e-scripts, being executable, can be used in e-mails to
communicate particular states of programs - say, where a certain bug
occurs. Unfortunately, they are too fragile and may cease working
after minimal changes in the program, and they are almost impossible
to read...]

[P However, the screenshot in Figure 5 suggests another language for
communicating controlling programs with GDB: the contents of the
"*gud*" buffer. After removing some excess verbosity by hand we get
something that is readable enough if included in e-mails - and to
extract the original commands from that we just have to discard the
lines that don't start with "(gdb)", then remove the "(gdb)" prompts.
As for the hyperlinks with `(ee-tbr)', they may need to be copied to
the GUD buffer, and not filtered out; we still need to experiment with
different ways to do that to be able to choose one.]


[ANODE «inspecting-data»  (to ".inspecting-data")
  (find-blogme4node "Inspecting data in running programs")
  [J Inspecting data in running programs]

[P Almost anyone who has learned a bit of Lisp should be familiar with
this kind of box diagrams. After running]

(setq x '(5 "ab"))
(setq y (list x x '(5 "ab")))

[P the value of y can be represented by:]

 ___ ___       ___ ___             ___ ___    
|___|___| --> |___|___| --------> |___|___| --> nil
  | ___________/                    |
  |/                                |
 _v_ ___       ___ ___             _v_ ___       ___ ___       
|___|___| --> |___|___| --> nil   |___|___| --> |___|___| --> nil
  |             |                   |             |
  v             v                   v             v
  5            "ab"                 5            "ab"               

[P This representation is verynice - it omits lots of details that are
usually irrelevant, like the address in the memory of each cons, and
the exact names of each struct in C and their fields. But sometimes we
need to understand the implementation in C, and a more complete
diagram would be convenient. At least, we would like to know how to
get, in the C source of Emacs, from the address of the leftmost cons
in the top line to the rightmost "ab" in the bottom line - but how do
we express following the "cdr" arrows, the "car" arrows, and
extracting the contents of a string object in elisp, One solution is
to use GDB, and e-scripts for it:]

[QQQ ...]

[P A "complete diagram" corresponding to the one above, whatever the
format that we choose to draw it, should include some information
explaining that "cdr" arrows correspond to "->cdr", "car" arrows
correspond to ..., and each string object corresponds to another kind
of box different from the cons boxes; to get to the C string stored in
an elisp string object we should examine its "foo" field, i.e., do a

[P Obviously, this same idea applies also to other programs with
complex data structures - and for some programs we may even have
fancier ways to explore their data structures; for example, in a
graphic toolkit it might be possible to change the background of a
button to orange from GDB.]


[ANODE «iskidip»  (to ".iskidip")
  (find-blogme4node "Internet Skills for Disconnected People")
  [J Internet Skills for Disconnected People]

[P Suppose that we have a person [IT P] who has learned how to use a
computer and now wants to learn how the internet works. That person
[IT P] knows a bit of programming and can use Emacs, and sure she can
use e-mail clients and web browsers by clicking around with the mouse,
but she has grown tired of just using those things as black boxes; now
she wants to experiment with setting up HTTP and mail servers, to
understand how data packets are driven around, how firewalls can block
some connections, such things.]

[P The problem is that [IT P] has never had access to any machine
besides her own, which is connected to the internet only through a
modem; and also, she doesn't have any friends who are computer
technicians or sysadmins, because from the little contact that she's
had with these people she's got the impression that they live lifes
that are almost as grey as the ones of factory workers, and she's
afraid of them. To add up to all that, [IT P] has some hippie job that
makes her happy but poor, so she's not going to buy a second computer,
and the books she can borrow, for example, Richard Stevens' series on
TCP/IP programming, just don't cut.]

[P One of eev's intents isto make life easier for autodidacts. Can it
be used to rescue people in positions like [IT P]'s(4)? It was
thinking on that that I created a side-project to eev called [``
Internet Skills for Disconnected People]: it consists of e-scripts
about running a second machine, called the [`` guest], emulated inside
the [`` host], and making the two talk to each other via standard
internet protocols, via emulated ethernet cards. Those e-scripts make
heavy use of the concepts in the last section ((...))]

  Figure 6: a call map
  (find-fline "iskidip.png")
  (find-eimage0 "./iskidip.png")

% (find-eevex "busybox.e" "bb_chroot_main")
% (find-eevex "busybox.e" "bbinitrd-qemu-main")
% (find-eevex "busybox.e" "iso-qemu-main")
% (find-eevex "busybox.e" "iso-qemu-main-2")

[P (4). by the way, I created [IT P] inspired on myself; my hippie job
is being a mathematician.]


[ANODE «what-is-automating»  (to ".what-is-automating")
  (find-blogme4node "What is automating")
  [J What is automating]

Reversible actions

If we have the following line in a buffer,

 (find-node "(emacs)Kill Buffer")

then executing it opens an info buffer; killing that buffer makes
Emacs go back to a state very similar to the previous one.

Equivalent actions

Typing C-x C-f /tmp/foo is equivalent to running this sexp:

 (find-file "/tmp/foo")

and one way to run that sexp explicitly is by typing:

 M-: (find-file SPC "/tmp/foo") RET

one way to run the key sequence C-x C-f /tmp/foo from a sexp is with:

 (eek "C-x C-f /tmp/foo")

Formalizing Equivalence Fails

The notion of equivalence of actions that we have just alluded to
cannot be formalized in a natural way. In this section we will see
why, and in the next section we will see how to work with a notion of
equivalence that is only loosely defined.

Actions can be applied to states of Emacs to produce other states,

   state  |--------> state
  (before)          (after)

and equivalent actions applied to equivalent "before" states should
produce equivalent "after" states.

We need a way to represent states of Emacs; a state should be a
structure from which we can at least (1) determine what Emacs shows at
the screen when in that state, and (2) it should be possible to define
an "application function" for it; application takes a "before" state
and an action and produces an "after" state.

               action 1             action 2
     state 1 |----------> state 2 |----------> state 3
        -                    -                    -
        |                    |                    |
        v                    v                    v
   screenshot 1         screenshot 2         screenshot 3

It is obvious that a state needs to store at least information about
all the buffers, frames, windows, keymaps, defuns and values of
variables; but consider the three "sexp actions" actions below:

   (insert-file "/tmp/foo")
   (insert (format-time-string "%Y-%m-%d %H:%M"))
   (find-sh "wget -q -O - http://www.gnu.org/")

Their effects depend on the contents of files in the filesystem, on
the current date and time, and on the contents of a webpage, that we
retrieve from a remote machine via HTTP. Clearly, when we use the idea
of two states being equivalent when they react in the same way (modulo
equivalence!) to all actions, we should not allow _all_ actions...
Also, if we allow incomplete key sequences, like C-x, as actions, then
we will have to deal with "mid-command states"; and states in which
some standard keybindings or functions have been redefined will react
weirdly to, say, C-x C-f /tmp/foo or to (find-file "/tmp/foo"), and
they may even consider as incomplete some key sequences that usually
are complete... so, we want to avoid considering both "weird states"
and "weird actions"...

Equivalence in Particular Cases

There are several ways to put Emacs in a state where it displays two
windows side by side on the current frame, one visiting the file
/tmp/foo, and another one visiting /tmp/bar

[ANODE «availability»  (to ".availability")
  (find-blogme4node "Availability and resources")
  [J Availability and resources]

[P Eev can be downloaded from the author's homepage, [R
http://angg.twu.net/]. That page also contains lots of examples, some
animations showing some of eev's features at work, a mailing list,

[P Eev is in the middle of the process of becoming a standard part of
GNU Emacs; I expect it to be integrated just after the release of GNU
Emacs 22.1 in mid-2007. Eev's copyright has already been transferred
to the FSF; it is distributed under the GPL license.]


[ANODE «acknowledgments»  (to ".acknowledgments")
  (find-blogme4node "Acknowledgments")
  [J Acknowledgments]

[P I would like to thank David O'Toole, Diogo Leal and Leslie Watter
for our countless hours of discussions about eev; many of the recent
features of eev --- almost half of this article --- were conceived at
our talks.]

[P ((Thank also the people at #emacs, for help with the code and for
  small revision tips))]


[ANODE «references»  (to ".references")
  (find-blogme4node "References")
  [J References]

[L90] - Libes, D. - Expect: Curing Those Uncontrollable Fits of
Interaction. 1990. Available online from http://expect.nist.gov/ .

[L95] - Libes, D. - Exploring Expect. O'Reilly, 1995.

[O99] - Ochs, E. - The Eev Manifesto

[S79] - Stallman, R. - EMACS: The Extensible, Customizable Display
Editor. (http://www.gnu.org/software/emacs/emacs-paper.html)

[ANODE «install-debian»  (to ".install-debian")
  (find-blogme4node "Installation on Debian")
  [J Installation on Debian]

[lua: blogme_output = tt:full_texi() ]
 # Local Variables:
 # coding: raw-text-unix
 # modes: (fundamental-mode blogme-mode)
 # End: