(Chapa 1)


Eev @ EmacsConf 2019

This is what I submitted to the EmacsConf 2019:

How to record executable notes with eev - and how to play them back

In the old times we would take notes about a task - think on fieldnotes - by using paper notebooks. Nothing was automatic then: we had to decide what to write and how to write it, we had to switch between "task" and "notes", we had to learn how to write both readably and concisely, and we had to learn how to switch between task and notes without losing focus. Learning these things usually took years.

In this talk I will present a package called "Eev" that lets us do a modern version of this. Some of its lower-level modules implement support for many kinds of elisp hyperlinks and a variant of `isend-mode' called `eepitch' that lets us select an interpreter and send lines of the current buffer to it; on top of that it has tools that let us create and modify elisp hyperlinks with very few keystrokes. I will show 1) how to use the elisp hyperlinks and eepitch blocks in already existing notes, 2) how to create elisp hyperlinks and eepitch blocks with very few keystrokes, 3) how to use this to do "task"+"notes" with just a few more keystrokes than we would use to do just "task", 4) how I've been using this to teach Emacs to total beginners.

The Eev homepage is at <http://angg.twu.net/#eev>.

The EmacsConf 2019 was a virtual conference (modulo satellite events at Zurich and Boston), and most people prerecorded their presentations. I told the organizers that I would prepare a short one and a long one, but I didn't finish the long one in time (and still haven't finished it)...

My short presentation: slides, video.

The short presentation is focused on the history of eev, on some design decisions, and on the items 1 and 4 of the abstract above:
1) how to use the elisp hyperlinks and eepitch blocks in already existing notes,
4) how I've been using this to teach Emacs to total beginners.
It ends with an analysis of my executable notes on patching xpdf.

Links to some points of the video:
0:00 Title page
0:15 Prehistory 1: eev appeared by accident
1:08 Prehistory 2: my notes started to have lots of elisp hyperlinks
2:35 Prehistory 3: M-x eev
3:04 Prehistory 4: several other kinds of elisp kyperlinks
4:05 Prehistory 5: these elisp hyperlinks could be put in comments
5:34 Prehistory 6: variants of M-x eev
5:41 Prehistory 7: several megabytes of scripts and notes (here)
6:41 Prehistory 8: I was sure that everybody was using Emacs like that
7:52 Prehistory 9: "users should not be forced to see Lisp"
9:22 Eev as an ELPA package
10:51 Eev as an ELPA package (2)
11:20 M-j - and how beginners should use it
12:54 A demo
13:10 Demo: patching xpdf (e-script)
14:01 Demo: the `find-man' links
14:45 Demo: the `find-apt-get-source-links'
15:11 Demo: the eepitch block (in red star lines) (see this)
15:48 Demo: eepitch on non-red star lines
15:56 Demo: eepitch in action
16:47 Demo: the `find-fline's to the source directory
17:07 Demo: `code-c-d' (see this)
17:22 Demo: `find-xpdffile'
17:32 Demo: `find-xpdfsh'
17:44 Demo: `find-xpdfgrep'
18:32 Demo: the second `find-xpdfgrep'
18:46 Demo: the relevant occurrence / direct link to it
19:18 Links

A transcription of what I say in the final part (i.e., in the demo):
13:11 Let me show you an example of "executable notes and how to play them back".
13:18 I will only be able to explain how to _record_ these executable notes in the longer video.
13:25 Anyway: when I was recording this video I realized that xpdf was behaving in a very annoying way -
13:34 it was changing the page in moments that I didn't want it to...
13:39 and the problem was that when my finger was at the right side of the touchpad
13:45 and I moved it up or down this would be interpreted as a _mousewheel scroll_,
13:52 that would be interpreted as PageUp or PageDown,
13:57 and I wanted to disable that - I wanted to disable the support for mousewheel scroll in xpdf.
14:01 So I took a look at the man page for xpdf - here -
14:06 I didn't find a simple way to change that by changing a configuration file
14:11 but I found a section that described all the default mouse bindings - here -
14:18 I found a line that seemed to be relevant - this one -
14:21 I created a hyperlink that pointed directly to that line - this one -
14:30 and I also found an explanation for what this function does
14:35 and the explanation says that this function either scrolls up by some pixels
14:41 or it moves to the previous page - which means PageUp.
14:46 So the _quickest_ way to change xpdf - because I was in a hurry -
14:51 was by downloading and recompiling the Debian source with some changes.
14:56 I used this hyperlink here, that uses a template, to generate several links
15:01 and several shell commands for downloading and recompiling a debian source package.
15:08 I copied these lines to my notes with some small changes,
15:15 and this part - here - uses the alternative to M-x eev...
15:20 remember that I said that my old way of sending lines to the shell was by using M-x eev,
15:27 that was very clumsy: it needed several keystrokes, and it was difficult to install
15:34 because we would need to change an rcfile.
15:38 So, the new alternative to it uses just <f8>,
15:43 that behaves in one way in lines that start with a red star - like these ones -
15:49 and in another way in lines that do not start with a red star.
15:54 Let me change the font to a smaller one to show how it works.
16:00 If I type <f8> in these three lines - here -
16:03 this will set up a target buffer - here - running a shell,
16:08 and if I type <f8> in these lines - here - this will send these commands to the shell.
16:14 This command, in particular, it downloads - sorry, it _makes sure_ that I have
16:20 all the Debian packages that I need to be able to compile the source for xpdf,
16:27 and this command - here - downloads the source package for xpdf
16:34 and unpacks it. It takes a few seconds - here.
16:40 I do not want to execute this thing now - this thing would recompile the source.
16:49 So, this hyperlink - here - opens this temporary directory,
16:54 and it turns out that the source package was unpacked in this subdirectory - here -
17:04 so this hyperlink points to the subdirectory,
17:07 and this s-expression - here - defines several shorter hyperlinks with "find-xpdf" in their names
17:17 that operate in this subdirectory - here.
17:22 So, this hyperlink - here - opens that directory,
17:30 this one - here - runs these shell commands in that directory
17:37 to list all the files - remember that I haven't compiled anything yet,
17:41 so all these files belong to the source package,
17:46 and this one is much more interesting - it runs a grep in that directory.
17:51 Remember that I discovered that the name of the mouse event that was bound to
17:57 PageUp, or to the _bad_ PageUp in the bad PageDown,
18:02 was MousePress4 (and MousePress5)...
18:06 So this grep here searches for all the occurrences of MousePress4
18:12 in the source... and it shows that there are only two occurrences,
18:18 one of them in the source for the man page and the other one
18:22 in the rendered version of that source, which is not good...
18:27 Let me change to the bigger font again.
18:31 So I decided to search for the function that was associated to that mouse event -
18:39 this function here - and I found several occurrences of that string,
18:45 and it turned out that _this_ is a relevant occurrence,
18:49 so I created a direct link to that source file,
18:53 and I discovered that if I commented out these lines by hand
19:03 and recompiled everything and installed the new debian binary package
19:09 then I would get an xpdf that does not have the annoying behavior. But...
19:15 That's it.

My longer presentation: slides (work in progress!!!)

The longer presentation will complement the shorter one, and will be mainly about:
2) how to create elisp hyperlinks and eepitch blocks with very few keystrokes,
3) how to use this to do "task"+"notes" with just a few more keystrokes than we would use to do just "task",
how to switch between "task" and "notes" without losing focus,
other design decisions - like the sexp-based interface - and why some people hate them.

On integrating eev and Org
After the conference I started to work on this: (find-org-intro)
See https://orgmode.org/ and these threads: 2013-11, 2019-11.