Workshop: Creating and Saving Elisp Hyperlinks
Long story short: I gave a series of workshops on "creating and saving elisp hyperlinks" in 2021 because I needed to get feedback on some parts of eev. Very few people attended but I produced a lot of material, both before and after the workshops. Parts of this material were polished later, but I also made six videos in a hurry because there was a chance that a few advanced users would pop up in the last workshop, and I wanted to be prepared. The advanced users didn't come and there are links to some of these videos in (find-saving-links-intro), so I sort of "have to" keep those videos in the list of first-class videos even though I find them embarassing.
If you execute `M-x find-1stclassvideos' you will see that:
1) there are six videos called 2021workshop1,
2, 3, 4, 5, 6,
2) they appear near the top of the list - and so they look important,
3) their comment fields say "Very bad - don't watch!".
Update, 2023jan02: I added subtitles to the videos, and with subtitles I don't think that they are bad anymore! See this page. 🙂
The rest of this page is old.
TL;DR: I will give a workshop on Emacs on the saturday, 04-dec-2021. Come! Everyone's welcome! The instructions are at the end of this section! =)
1. A short explanation
This was the abstract of my presentation at the EmacsConf2019:
Title:
How to record executable notes with eev - and how to play them backAbstract:
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>.
Note the part in red: "tools that let us create and modify elisp hyperlinks with very few keystrokes". Until some time ago these tools were very hard to learn; a few people were able to figure out from the documentation how to use them fluently, but most people weren't. I think that I found a way to teach them in a way that is both quick and reasonably fun, that is somewhat inspired by how string instruments are taught - and much closer to the Suzuki way than to the Sevcik way. See also this - I especially like the part in which he says "there is a moment in which most of the learning takes place".
When we are learning a string instrument we have to coordinate a lot of fingers (too many to count), a lot of arms (2), a lot of elbows (2), our head (1) - that is usually pressing the chin rest too hard - the bow, and our eyes, and we have to try to read the music while we try to play in time. A good teacher can help us make the fingers, the arms, etc, work well using less of our attention, and when this happens it frees some of our mental space and lets us concentrate on the music and on making it sound like music, not like struggling.
I believe that in the right setting, and with the right tricks, people will be able to concentrate on selecting and copying the right hyperlinks instead of just struggling to memorize the key sequences. One of these tricks is to copy the diagram of the exercise to the notes buffer, as you can see in the second video below at 3:07.
I am still writing the material that we will use in the workshop. The core of the material will consist on 4 or 5 very short videos like the first two ones above and a series of diagrams like the one here. The non-core material will consist of lots of explanations and elisp hyperlinks, like this. In the next few hours I plan to record two videos about the basic exercises and reorganize this completely.
What: the main theme will be to "save elisp hyperlinks to everything that is interesting". To see what this looks like, run:
mpv --start=5:00 --speed=8 http://angg.twu.net/eev-videos/2021-workshop-3.mp4
Where: the workshop will happen on Telegram. I'm @eduardoochs
on Telegram - if you want to participate just add me there and
send me a "hi" and I'll add you to the group in which the
workshop will happen, or join the group using this link. For other ways to
contact me, see here. Update: the workshop will happen on IRC too! if you prefer IRC just
join the channel #eev on LiberaChat!
How: a workshop by Telegram is like a workshop by IRC, but
by Telegram. I will have lots of things to suggest, but there
will be people of different levels talking at the same time and
asking different questions and it will take a while until they
converge on questions that interest several people.
When: the workshop will happen on 2021-dec-04 from 15:00 to
18:00 in the timezone of São Paulo. Look at the table below to
see how this converts to other timezones.
America/Vancouver: Sat Dec 4 10:00:00 PST 2021 America/Chicago: Sat Dec 4 12:00:00 CST 2021 America/Toronto: Sat Dec 4 13:00:00 EST 2021 America/Sao_Paulo: Sat Dec 4 15:00:00 -03 2021 GMT: Sat Dec 4 18:00:00 GMT 2021 Europe/London: Sat Dec 4 18:00:00 GMT 2021 Europe/Berlin: Sat Dec 4 19:00:00 CET 2021 Asia/Kolkata: Sat Dec 4 23:30:00 IST 2021 Asia/Singapore: Sun Dec 5 02:00:00 +08 2021 |
2. Old notes
In october/2021 I prepared a workshop on Emacs for beginners, where these "beginners" would include "M$ Windows users who had never used terminals in their lives". The workshop itself was apparently a failure, for reasons that I will explain in the next section, but 1) I learned a lot with it, 2) my real, semi-hidden, non-altruistic intent with that workshop was to do a kind of social engineering in the good sense: I was trying to become friends with people who know how to use things that I find incredibly hard to learn, and I made a lot of progress on that. Let me explain.
The first programming language that really clicked for me was Forth. It was "simple" in a way that is unusual today:
My personal impression is that Forth's main points were not the ones that I listed at the beginning of this section, and that I said that were easy to quantify; rather, what was most important was that nothing was hidden, there were no complex data structures around with "don't-look-at-this" parts (think on garbage collection in Lua, for example, and Lua's tables - beginners need to be convinced to see these things abstractly, as the concrete details of the implementation are hard), and everything - code, data, dictionaries, stacks - were just linear sequences of bytes, that could be read and modified directly if we wished to. We had total freedom, defining new words was quick, and experiments were quick to make; that gave us a sense of power that was totally different from, say, the one that a Python user feels today because he has huge libraries at his fingertips.
A sizeable part of Emacs is "simple" in the sense above, and my workshop was going to be about that.
Many of the tools that most people find "simple" nowadays are very hard for me, for reasons that I only understood clearly very recently. My two favorite examples of Python and Org Mode - or, more precisely, Python classes and source blocks in Org Mode. Every time that I tried to learn Python I got stuck at the same point: I was never able to form a clear mental image of what a Python class is, so I would try to understand the details, and when I tried to ask for help the answer was always: "you are asking the wrong questions - you should try to use classes instead". And when I tried to learn some non-basic parts of Org Mode, like code blocks, a similar thing happened - I tried to understand how code blocks are implemented, but the souce code was written in a way that I found too hard...
So: I'm trying to become friends with people who know how to use these things, and I'm trying to become someone who deserves their help and their patience.
I sometimes produce material like this when I finally learn something that I found too hard,
so some people know that helping me is good karma. But let me go back to eev.
The main idea behind eev is that we can alternate between "task" and "notes", and we can take "executable notes" instead of just taking notes in English. My presentation at the EmacsConf2019 included a demo of how to "play back" "executable notes" - it starts at 13:10 in the video - and some of my later videos sort of explain how to create elisp hyperlinks, but I still don't have much material on this:
Eev takes an intermediate stance between "notes by hand" and "automatic notes". It is possible to do "task"+"notes" with just a few more keystrokes than for doing just "task", but that requires learning some tricks, and having some practice.
More precisely: "taking executable notes" consists mostly of 1) saving commands that are sent to "shell-like programs" and 2) saving hyperlinks to everything that is interesting. "Saving hyperlinks to everything that is interesting" consists of 2a) deciding what is interesting and what is not, 2b) saving URLs, 2c) saving elisp hyperlinks; and "saving elisp hyperlinks" consists of 2c1) making eev generate "hyperlinks to here", 2c2) selecting the right elisp hyperlink, 2c3) optionally refining the hyperlink, 2c4) copying it to our notes. If we organize this as a tree, we get:
"Taking executable notes" can be split into:
- saving commands that are sent to "shell-like programs" (1)
- saving hyperlinks to everything that is interesting (2)
- deciding what is interesting and what is not (2a)
- saving URLs (2b)
- saving elisp hyperlinks (2c)
- making eev generate "hyperlinks to here" (2c1)
- selecting the right elisp hyperlink (2c2)
- optionally refining the hyperlink (2c3)
- copying it to our notes (2c4)
I have the impression that people can learn the items 2c1-2c4 very quickly if they do some exercises on series of actions - similar to how string instruments are taught; see this video. These exercises will make some series of actions, that are initially "totally alien", become "vaguely familiar", and this is enough to free some mental space, and let people pay attention to other things. If people learn how to use diagrams like this one - click on the video (obs: the current video is a stub, and will be replaced later!) for a demo -
|
|
|---|
then being "vaguely familiar" with the key sequences should be enough - memorizing them is not necessary.
(..)
TODO: cite some talks from the EmacsConf2021 - the ones by Greta, Prot, Grant, which other ones? -, point to (find-eev-exercises-intro), explain that I will add MANY other exercises to that intro, make a video explaining the diagram, explain the prerequisites for the workshop - they are essentially just this - and finish this page.
November: Introduction to Free Software (with Emacs and Eev)
In october/2021 I started to prepare a workshop on Emacs and eev that would probably be attended mostly by Windows users who had never used terminals in their lives. I explained my plans in these two posts to help-gnu-emacs:
- https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00037.html
- https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00045.html
- installation and navigation with M-e, M-j, and M-k
- undo, windows, files and buffers
- cutting and pasting; putting notes and links in ~/TODO
- sharing notes and links via Telegram
- this tutorial on elisp
- How to use the [Video links:] blocks in the tutorials
- How to download local copies of files from the internets
The workshop happened in 2021nov06 and it didn't work as I expected. The items "putting notes and links in ~/TODO" and "sharing notes and links via Telegram" were FAR more important than the other ones, but no one who attended the workshop seemed to be able to focus on them... so after the workshop I realized that this was my fault - I needed to prepare exercises on that, and in the next workshop I would have to tell everyone that sharing notes would be not only VERY IMPORTANT but also REQUIRED, and after, say, two hours of the workshop, the people who aren't sharing their notes would be simply KICKED OUT.
After the workshop I restructured the documentation for MWUs and it became this:
(find-windows-beginner-intro "0. Introduction")
(find-windows-beginner-intro "1. Download and install Emacs")
(find-windows-beginner-intro "2. Key sequences and how to quit")
(find-windows-beginner-intro "3. Using M-x and installing eev")
(find-windows-beginner-intro "4. Understanding buffers and the mode line")
(find-windows-beginner-intro "5. More on modes")
(find-windows-beginner-intro "5.1. Eev mode")
(find-windows-beginner-intro "5.2. Help Mode")
(find-windows-beginner-intro "5.3. Info Mode")
(find-windows-beginner-intro "5.4. Dired Mode")
(find-windows-beginner-intro "5.5. Shell Mode")
(find-windows-beginner-intro "5.6. Eshell")
(find-windows-beginner-intro "6. Video links")
(find-windows-beginner-intro "7. eev-on-windows.el")
(find-windows-beginner-intro "7.1. `ee-use-windows'")
(find-windows-beginner-intro "7.2. Testing wget.exe")
(find-windows-beginner-intro "7.3. Lua")
(find-windows-beginner-intro "7.4. Downloading videos")
(find-windows-beginner-intro "7.5. Downloading PDFs")
(find-windows-beginner-intro "7.6. Saving your settings")
(find-windows-beginner-intro "7.7. Testing your settings")
(find-windows-beginner-intro "7.8. Saving your settings to your ~/.emacs")
(find-windows-beginner-intro "8. Summary")
(find-video-links-intro "1. Introduction")
(find-video-links-intro "2. From the HTML")
(find-video-links-intro "3. `find-youtube-video'")
(find-video-links-intro "4. Configuring the browser")
(find-video-links-intro "5. Local copies")
(find-video-links-intro "6. Configuring Mpv")
(find-video-links-intro "7. `find-eev-video'")
(find-video-links-intro "8. Windows")
(find-video-links-intro "9. First-class videos")
(find-video-links-intro "10. Second-class videos")
(find-video-links-intro "11. Hardcoded paths")
I also recorded a video in Portuguese with basic exercises on the items "putting notes and links in ~/TODO" and "sharing notes and links via Telegram", but I haven't recorded a version in English of it yet... I am also preparing other videos with exercises, and my plan is to first get feedback on them and only after that I will record something similar in English.
The page in Portuguese about the workshop is here. The first three images at its the bottom are links to videos in Portuguese.