Eepitch

1. Introduction

Eepitch is one of main "killer features" of eev. Eev is an Emacs package (in ELPA!) that lets you keep "executable logs" of everything that you do; these "executable logs" are mostly composed of elisp hyperlinks and "eepitch blocks". An eepitch block looks like this:

* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)
def square (x):
    return x*x

print(square(5))

The first three lines - the ones that start with red stars - set up a "target buffer" when they are executed, and the "non-red star lines" are sent to the target buffer.

Update, 2022dec09: take a look at this page: "Eev: videos".

Index:

• 1. Introduction
• 2. Test blocks
• 3. Trying it
• 4. Tutorials
• 5. Comparison with Org Mode
• 6. Other targets
• 7. How eev downloads videos
• 8. Understanding the first two lines
• 9. Using bullets instead of red stars
• 10. Making eepitch ignore certain prefixes
• 11. Eepitch on M$ Windows

2. Test blocks

My presentation at the EmacsConf2021 was about "test blocks", and it included a very good visual explanation of how eepitch works in the pages 3, 4, 5, 6, and 10 of the PDF; click on the thumbnails below to open the PDF.

To watch the full presentation on Youtube click here; its index is here. To watch a 30-second explanation of eepitch, start at 0:14.

If you have eev installed you can also watch that video with `M-x find-eev2021video' or with sexps like (find-eev2021video "0:00") or (find-1stclassvideo-links "eev2021"); if you don't have eev, you can download the video using the wgets below:

# See:  http://anggtwu.net/eev-videos.html
#       http://anggtwu.net/eev-videos.html#mpv-keys
# Play: (find-eev2021video "0:00")
# Info: (find-1stclassvideo-links "eev2021")
# Subs: (find-1stclassvideolsubs  "eev2021")

wget -nc http://anggtwu.net/eev-videos/emacsconf2021.mp4
wget -N  http://anggtwu.net/eev-videos/emacsconf2021.vtt
mpv --fs --osd-level=2 emacsconf2021.mp4

3. Trying it

If you are looking for instructions for trying eepitch, here they are:

1) Install eev with `M-x list-packages' or something similar. If you use straight.el, see this..
2) Run `M-x eev-beginner'. This will open this tutorial: (find-eev-quick-intro).
3) Follow the instructions in the sections 6.1 and 6.3 of the main tutorial.

That's it! 🙂

Note that I consider <f8> as "the fourth of the three main keys of eev"; the three main keys are M-e (evaluate/execute), M-j (eejump), and M-k (kill buffer). The two most beginner-friendly ways to see the list of keys of eev are: 1) click with the middle mouse button on the "eev" in the mode line; this will show a help buffer like the one in the left half the screenshot below, and 2) type `M-2 M-j' - this will show (find-emacs-keys-intro), as in the right half of the screenshot below.

Note that both halves of that screenshot have lots of elisp hyperlinks. To follow an elisp hyperlink, type M-e; to go back, (usually) type M-k.

If the keybindings in eev-mode interfere with your usual keybindings you can use `M-x eev-mode' to turn eev-mode on and off.

4. Tutorials

I have a few "eepitch-based tutorials" that are made mostly of executable examples (in eepitch blocks) and links to real tutorials (in sexp hyperlinks). There is a big one for Lua here, a small one for Python here (it uses eev-rstdoc.el), and I am starting to write one for Eshell. See: 1) this message to help-gnu-emacs in which I asked for snippets, 2) this block of examples, and 3) click on the thumbnail below to see a screenshot.

5. Comparison with Org Mode

Org mode includes support for both executing and exporting "code blocks". Eepitch can be used as a very lightweight alternative to the "executing" part - all these targets work out of the box, and adding a new target usually takes just one line of code - but eev and eepitch don't have support for "exporting" in Org's sense (1).

Org files are exportable. This means that they need by parseable, and that Org needs to be also a markup language... and it turns out that Org's markup language is quite hard to parse: see Karl Voit's work on Orgdown for details. In contrast, eev works on files that are free-form, and that can be any mix of code, text, lines with sexp hyperlinks, eepitch blocks, Org markup, and whatever else; here's a simple example. To make eev follow the sexp hyperlink in the current line we type M-e, and to make eev "execute" an eepitch block, we type f8s on the lines that we want to execute; that's it. M-e and f8 usually only care about the current line (2).

Here is an example of how to use eev's "markup language" inside an Org file:

# (find-orgnode "Comment Lines")
#+begin_comment
* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)

#+end_comment

(TODO: rewrite this section! NOTES: 1) I have an htmlizer that recognizes some eev-isms, but it is an ugly hack that is only used at http://angg.twu.net/, 2) the main exception to that is when we use M-e to eval sexps that are more than one line long.)

6. Other targets

The main tutorial of eev explains eepitch-shell first - in section 6.1 - and then it gives a single example of using "another target": eepitch-python, in section 6.2. Most of the "other targets" that come predefined in eev are defined in exactly the same way as eepitch-shell and eepitch-python, in any of these two equivalent ways:

(defun eepitch-python () (interactive)
  (eepitch-comint "python3" "python3"))

(defun eepitch-python () (interactive)
  (eepitch '(find-comintprocess "python3" "python3")))

You can see their definitions in eepitch.el here.

A few other targets need vterm instead of comint - they are are explained, with links to the source code, here - and a very few other targets need hacky setups in which one or more of these operations need to be performed by special code: 1) create the target buffer, 2) switch to the target buffer, 3) send a line of input to the target "as if the user had typed it". At this moment eev comes with only three of these "hacky other targets": Eshell, Ielm, and Sly, and all three of them only need special ways to create the target buffer and switch to it, but I occasionally use "much hackier other targets" in personal projects - for example, in emlua.

7. How eev downloads videos

One of the principles behind eev is that it NEVER creates or modifies files without making the user see very clearly what it is doing... and showing a textual explanation and then asking a yes/no question is not "very clearly" enough.

Eev only downloads files by showing a script to the user, and making him run a wget with eepitch. For example:

Update, 2022dec09: take a look at this page: "Eev: videos".

See also: find-yttranscript-links.

8. Understanding the first two lines

The effect of these three lines

* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)

is very easy to understand if you just type <f8> three times very quickly - the three lines together create a new target buffer running Python... but if you try to understand what the first two lines do individually you will see that they are quite tricky. They are explained here.

9. Using bullets instead of red stars

This is a hack that I wrote in may/2021 inspired by this e-mail by Tomas Hlavaty; I answered him with this prototype, and in sep/2021 I added to eev a way to let people learn how this hack works. If they run M-x find-red-star-links this will create a temporary buffer like the one in the screenshot below (click on it to enlarge):

that explains - "without magic" - all the innards of how red stars and bullets work, and once people understand the details they can use just M-x ee-use-red-stars and M-x ee-use-red-bullets to change the default.

Long story short: eepitch considers that red stars ("*"s) and bullets ("•"s or "•"s) are equivalent. Bullets are better for copying and pasting from a browser to Emacs; if you copy-and-paste this to an Emacs buffer,

• (eepitch-shell)
• (eepitch-kill)
• (eepitch-shell)
echo hello

it will work as eepitch block, even if its "•"s become "•"s. To control the color of bullets in Emacs, run `M-x find-red-star-links'.

10. Making eepitch ignore certain prefixes

This is a hack that I implemented in dec/2021. I explained it in this page, that is mostly about how to use eepitch blocks in makefiles, and in the section about the function `eepitch-preprocess-line' in (find-eepitch-intro). In apr/2022 there was a discussion in the eev mailing list about the default behavior of `eepitch-preprocess-line'; my main messages were these ones: 3, 9.

11. Eepitch on M$ Windows

On Windows many of the "other targets" don't work. See this question that I sent to help-gnu-emacs, and eev-wconfig.

Note: I created this page in 2022jun05 because I discovered that when people googled for just the word "eepitch" Google would suggest pages that were hard to understand... I still need to add lots of things here.