Chapa 1)


Eev for (longtime) Emacs users

This page is an attempt to explain what eev is for people who have been using Emacs for a long time.

My favorite short explanation for what eev is is this one (from here):

I used to call eev a "tool for automating almost everything" and "my project to save the world with Free Software". In more concrete terms, eev is a library for Emacs that lets us create executable logs of what we do in a format that is reasonably easy to read and to modify, and that lets us "play back" those logs step by step in any order - for example, like in this video. We can even edit our executable logs in the middle of playing them back, as shown in this demo of test blocks.

but some people don't like it - they need something more concrete. So...


1. Another explanation of eev

Here it is:

Eev is what we get when we define `M-e' as an abbreviation for `C-e C-x C-e', we decide that that is the best thing in the universe, and we center our way of using Emacs around that.

When I started to use Emacs in the mid-90s I did something like this:

;; This is a simplified version of the `M-e' in:
;; (find-eev-quick-intro "2. Evaluating Lisp" "M-e")
;; (find-eev "eev-eval.el" "ee-eval-last-sexp")
(defun ee-eval-sexp-eol-mini ()
  (move-end-of-line nil)
  (eval-last-sexp nil))

(global-set-key (kbd "M-e") 'ee-eval-sexp-eol-mini)

and I saw that I could use it to "automate everything"...

1.1. "Elisp hyperlinks"

When I started using Emacs I spent most of time in it "going to places". For example, if I wanted to re-read something that I found in the manpage for gawk, or in the info pages for Make, I would have to type many, many, many keys to get there... so I defined the functions `find-man' and `find-node', and used sexps like the ones below:

# (find-man "1 gawk" "Built-in Variables")
# (find-man "1 gawk" "I/O Statements")
# (find-man "1 gawk" "String Functions")
# (find-node "(make)Automatic Variables" "$*" "stem")
# (find-node "(make)Recursion")
# (find-node "(make)Special Targets" ".PRECIOUS")
# (find-node "(make)Chained Rules" ".SECONDARY")
# (find-sh "man -d print > /dev/null")
# (find-sh "man -d print > /dev/null |& grep print")

The first sexp above,

# (find-man "1 gawk" "Built-in Variables")

would `automate the task of opening the manpage for gawk and searching for the first occurrence of the string "Built-in Variables" there'.

The functions `find-man' and `find-node' above were some of my functions that automated "going to places", and I saw that:

  • I could treat them as hyperlinks,
  • all the languages that I was using supported "elisp hyperlinks in comments".

I explained this - with nice colors - in my presentation at the EmacsConf2019. Take a look at its slides.

1.2. "Sending commands to shells"

So: the "elisp hyperlinks", shown above, automated "going to places"; I also devised some ways to automate "sending commands to shells".

  • The old way: `M-x eev'. In the 90s I was mostly using Emacs in a VT and shells on the other VTs, and sometimes I would run X and sometimes not; my favorite way of sending commands to shells at that time was with a low-level function called `M-x eev' - for "emacs-execute-verbosely" - that saved the region in a temporary file, and could only send the region to shells prepared in a certain way.
  • The new way: eepitch. All my best explanations about eepitch are in this page, with images and screenshots... please start by it!

People who are new to eev can usually learn how to use eepitch in just a few minutes, but they take much longer to learn how to create their own elisp hyperlinks... so I usually suggest this as a starting point:


1.3. "Executable notes"

The main ideas behind the concept of "executable notes" are in these two sections of the tutorials:

(find-here-links-intro "1. Alternating between \"task\" and \"notes\"")
(find-here-links-intro "1.1. Reading and writing")

My executable notes consist mostly of "elisp hyperlinks" and "lines that are sent to shell-like programs"; and some of my elisp hyperlinks "go to" temporary buffers that are generated by templates, and that "look like 5-minute hacks". My presentation on the EmacsConf 2020 was about these tricks with temporary buffers; my page on it is here.

The best way to understand what "executable notes" look like is to see some examples. If you are a longtime Emacs user then I recommend that you start by the two demos in the beige rectangle at the end of the next section - one demo is about patching xpdf and the other is about "saving hyperlinks to everything interesting". Note that the some of the links there point to the videos in which these demos appear and some other links point to the subtitles of these videos.

2. "You need to summarize in one paragraph"

Lots of people have complained that they have tried to understand from the documentation what eev is and what eev does, but they have failed, and that, aham, I need to write a one-paragraph summary explaining that.

I've tried that for years. If you are sure that everything can be summarized in one paragraph, then **** OFF - you are wasting both your time and my time.

The narrowed paragraphs below explain the main ideas behind this. They were adapted from this e-mail that I sent to the eev mailing list, and note that they say "watch the demo"; actually it is better to watch two demos - the links to them are in the beige rectangle below.

Either try more "Try it"s in the tutorial or watch the demo in my presentation in the EmacsConf2019. Compare the situation with learning what is a Turing machine in the early 80s versus playing a coin-operated video games in the early 80s - Donkey Kong, say, or Qix. It is VERY HARD to imagine that a video game can be fun, and how fun it can be, by just learning what a Turing machine can do, and then trying to imagine a video game by reading an objective description of what a video game is or what a video game does.

The slides of my presentation at the EmacsConf 2019 tell a bit of how discovering Emacs - and eval-last-sexp, of course - was a visceral experience for me, very similar to how certain video games, and some vinyls and CDs, were. The part of the video in which I present those slides is more fun because I scream at some points, but I think that you will prefer to just read the slides quickly.


Then: eev doesn't do anything by itself. Emacs comes with C-x C-e, i.e., eval-last-sexp, that is incredibly powerful, but that power is not immediately obvious to everyone. Eev makes that power slightly more accessible.

I've met at least two persons - my sister and one ex-internet friend - who thought that a monochrome screen with an unfontified sexp was something so repulsive that they couldn't stare at that for more than a few seconds with complaining or running away. Eev is certainly not for them - and so, by consequence, eev is not for everyone.

Here are the links to the two demos, and to the files with their subtitles:

Subs: (find-1stclassvideolsubs "eev2019" "13:10")
Play: (find-eev2019video "13:10" "Let me show an example of executable")
      (find-eev2019video "13:13" "notes and how to play them back.")

Subs: (find-1stclassvideolsubs "2021workshop3" "Part 2: The demo" "4:56")
Play: (find-2021workshop3video "04:56" "...a demo. In this demo I'm going to")
      (find-2021workshop3video "04:58" "show how to reconstruct")
      (find-2021workshop3video "05:00" "these notes here. I mean...")

3. Design choices, or: why eev offends modern tastes

Eev follows some design principles that "offend modern tastes" (←I took that expression from an article called "How to Make Mead"). Here they are: