Why eev has a weird elisp tutorial and how to use it
Main links:
(find-elisp-intro)
Gwen, ou le livre de sable
To watch the video in .mp4, click on the first thumbnail below.
To watch the video on Youtube, click on any of the timestamps.
If you can only watch a few parts, each a few seconds long, my recommendations are:
7:46 It is a sandbox, in the sense that you can make any mess here and
then recreate it
9:02 you can create a link to that section by hand
12:06 ...you can duplicate a line, and check what happens if you change...
15:58 that very few people have noticed ... that my tutorial works in two ways
When I announced this on an Emacs mailing list the feedback was quite bad. See the thread.
You can download the video with subtitles using either this sexp - (find-1stclassvideo-links "2022findelispintro") - or the two wgets below:
# See: http://anggtwu.net/eev-videos.html # http://anggtwu.net/eev-videos.html#mpv-keys # Play: (find-2022findelispintrovideo "0:00") # Info: (find-1stclassvideo-links "2022findelispintro") # Subs: (find-1stclassvideolsubs "2022findelispintro") wget -nc http://anggtwu.net/eev-videos/2022-find-elisp-intro.mp4 wget -N http://anggtwu.net/eev-videos/2022-find-elisp-intro.vtt mpv --fs --osd-level=2 2022-find-elisp-intro.mp4 |
Here is a full transcript:
0:00 Hi! My name is Eduardo Ochs, I'm the author of an Emacs package called eev, and the title of this video is: "why eev comes with a weird elisp tutorial and how to use it". 0:13 Before starting let me just explain what is this image here. It's a frame from my most favorite animation movie ever. Its title in English is "Gwen, or The Book of Sand", and it's available on youtube; you can watch it there. 0:33 One of my missions on earth is to convince more people to to watch that movie. I've watched it more than 30 times. I've shown it to many people, and every time that I watch it it blows my mind in different ways. 0:47 Anyway, let me go back. One more thing before starting... 0:53 Emacs comes with an Emacs Lisp tutorial that is very famous - It's called "An Introduction to Programming in Emacs Lisp". It comes as an info manual, and it's an actually a book. 1:09 Using Info Mode you can navigate through is - through its chapters, sections and so on. 1:15 If you're a beginner you're probably going to use these, uh, things here in the toolbar; if you're not a beginner you can use, for example, the square brackets to navigate to the previous and the next section in a certain order. 1:32 Let me use that now to show how big this manual is. These are all its sections and subsections and so on, and it's huge - very huge oh no it never ends - 1:53 That's it. So: a zillion of sections 2:02 Eev comes with a very short tutorial on Emacs Lisp that you can access by just typing M-7 M-j. 2:13 Here - let's see its size. Let me turn on the scroll bar. If we scroll here we go to the end of the tutorial... it's here - it has just a bit more than 600 lines. 2:36 I say here that "This is a very quick introduction to Emacs Lisp my intent here is not to teach people how to _write_ elisp code only to teach them to _read_ elisp code". 2:47 I consider that reading and writing are two different stages, and in the beginning people are mostly going to want to read things, like to understand what the source code means, or to understand how a certain template is prepared, and so on... 3:06 And i say here that "Different people prefer different kinds of tutorials" and many people - actually most people - love the "The Introduction to Emacs Lisp" - this one here - but I DON'T - 3:22 and in this video I'm going to explain why. 3:25 This tutorial here - this short one - is what I would have liked to have had access to when I started learning Emacs Lisp. 3:37 Let me go back a second. 3:41 I started to write to this tutorial because I was invited to teach a minicourse on LaTeX to students that had never used Emacs before, and I said: 3:54 "Ok, I'm going to teach it, but everybody is going to be forced to use Emacs and eev - but i'm going to do it in a certain way in which it's not going to be very painful" 4:08 And so, I used eev to make people learn Emacs in a certain way, and every time that a person had a curiosity about something in Lisp 4:18 and wanted to understand the syntax, or the defuns, or backquotes, or whatever, I said "oh, look at the sections such and such in my Elisp tutorial". 4:38 So these people knew very few keys of Emacs - in the beginning they basically knew the three most basic keys, that are M-e, M-k, and M-j 4:49 M-e executes the sexp in the current line, M-k can be used to to kill the current buffer, which usually means to go back, and M-j jumps to several different places, and if you run M-j without a numerical argument it shows this temporary buffer here 5:14 that... here it shows some of the main targets that have numbers assigned to them, 5:24 and here you can see the other targets. This line here means that if you type M-j with the numeric prefix 7 it is going to execute this thing here - the (find-elisp-intro) - that goes to the Elisp tutorial, 5:42 and these are the things that are most basic, that beginners learn first. These things here - 5:55 this one here - M-5 M-j - is the basic tutorial, called (find-eev-quick-intro), 6:04 this one - M-2 M-j, (find-emacs-keys-intro) - is a fake tutorial that is mostly an index of keys, 6:12 and this one here - M-1 M-j, (find-fline "~/TODO") - opens a buffer with our notes... 6:19 I always say to the beginners that in the beginning they should put all their notes in this buffer here - ~/TODO 6:33 and that they shouldn't mind if their notes are messy - they can clean them up later 6:41 and this thing here also shows some keys for opening the the file with the notes in the the window at the right from any place 6:53 so, for example, if we are in the elisp tutorial and we find something interesting, say on section 3 - for example this block here - 7:08 we can run this thing here, show our buffer with notes at the window at the right, and we can copy this thing here to our notes. 7:23 Just one comment before showing other things. M-7 M-j goes to the elisp tutorial 7:35 and the last line of the this header says that "you can open this tutorial _or recreate it_ with M-7 M-j". 7:46 It is a sandbox, in the sense that you can make any mess here and then recreate it 7:59 Some other tutorials have numbers, like this. For example this - (find-emacs-keys-intro) - is the fake tutorial that is just an index, and it says that you can access this thing with M-5 M-0 M-j... and these other ones I have already shown. 8:23 One important thing is that people can create hyperlinks to the sections of the... of my elisp tutorial very easily. 8:35 For example, suppose that you're one of the students in my workshop, you are starting to learn Emacs today, and you learned the basic ideas of how to create elisp hyperlinks 8:56 and you think that there's something interesting in this section here - section 5. 9:02 So you can create a link to it by hand. For example you can simply type this (find-elisp-intro "...") - initially by hand; later you can learn the tricks for generating this automatically - 9:22 and you can copy the title to this position here. Now you have something that if you execute... if you execute this you go exactly to this section here. 9:31 But let me go back... 9:49 Let me now explain some differences in style between the standard tutorial and my tutorial. 10:00 I think that the first thing that made me dislike the Emacs Lisp Intro is that it is "An introduction to programming in Emacs Lisp _for people who are not programmers_", and I was trying very hard to become a "programmer", I was really thinking like a "programmer", and I was taking notes, and creating exercises, and so on, and so this thing felt more like a book that should be read like a book, not like code that you that you can execute by just typing M-e - and it felt non Emacs-y. 10:44 I also said that this is HUGE... this is the menu with the chapters and sections and subsections and so on... 10:56 In some situations it has faces here - in the sense of different fonts - and sometimes it's not totally clear if this difference is important or not, and 11:13 if we copy a part of this to our notes and we save our notes then the faces are going to disappear - the thing is going to become plain text without the different fonts. 11:32 Also, the manual is full of examples like this, that are not complete chunks of code, they are just excerpts from bigger functions. 11:55 So, in short: it is big, it is hard to navigate because it has zillion of sections, it uses faces, it is read-only - 12:06 remember that in my tutorial you can duplicate a line, for example, and check what happens if you change one item of a list by something else - for example what happens if you change this by 40 or by a string, and you can execute these things here... so 12:29 this is a sandbox where you can execute things, and this does not happen in the Emacs Lisp Intro. 12:40 Also, the Emacs Lisp Intro has just a few executable examples per page, while my tutorial has many - for example here: all these things are different examples 12:57 and one thing that really bothered me is that 13:03 I prefer to believe that Emacs was made in two levels: first people took a lisp interpreter - 13:14 no, sorry, three levels - people first took a Lisp interpreter and then they programmed in it a handful of functions for dealing with keys, buffers, files windows, and so on; just a few basic things 13:32 and at one point they had a very basic editor that had Lisp inside, and they could change its Lisp code interactively using the editor itself... 13:44 and then they started to build an editor that was much more powerful, and also to extend the Lisp with more advanced features... 13:56 but i prefer to think that that we have this division with basic Lisp on the bottom, and then basic editing functions on top of that, and then a huge structure with zillions of editing functions - 14:12 and the Emacs Lisp tutorial does not make this distinction very clearly 14:18 and it explains basic Lisp at the same time as the as the editing functions, because it wants to explain how people can write useful functions, and useful functions are usually functions that edit things. 14:36 Another thing that i really didn't like in it is that it has very few links to the primary sources. 14:45 Here we are inside Emacs, and it's very easy to access each one of the manuals and the source code. For example, here I have a section of my tutorial that ends with this block here: it says "for more info on the other types of list objects" - oops, it's Lisp objects, sorry there's a typo here - "see blah blah", and each of these things is a link to the Emacs Lisp manual. 15:25 Also, here we have links to the Wikipedia, and in other places have links to the Emacs manual... and i think that in a couple of places we have links to the source code too - 15:44 and the Emacs Lisp Intro does not do that. It is made to be the online version of a book, and I think that this is a bit frustrating. 15:58 And the main point - and this is something that very people have noticed - is that my tutorial works in two ways. 16:09 It has some comments here, so people can _read_ it - but it also has lots of design choices and stylistical choices - I decided to present things in a certain way... 16:24 and when people run these examples they're probably going to become familiar with these stylistical choices, and when they start to take their own notes they are probably going to use some of these ideas on their notes. 16:44 So they are going to do something like this, in which they put several similar examples close to one another, starting by the most basic ones. 16:57 They can also put just a bit of text instead of having to explain lots of things - 17:04 and they are also - i hope - they will also 17:11 try to use this style here, in which we put important links to everything that we find; so instead of trying to reproduce the explanations with our own words 17:27 we just put the links to the sources where we can find the full explanations. 17:35 The idea is that when people are learning some more advanced things that are not in the manual they can write their notes in this format and they can even share these notes with other people - and 17:53 in my workshops I often have some moments in which people share their notes, and of course people would want to write notes that are useful to other people, and notes that are easy to change, and easy to collaborate on - 18:14 and so one of the intentions of my tutorials was to suggest a certain style and convince people that they could write their notes in this style. 18:27 This tutorial is very incomplete - it just teaches the basic ideas - but it also has a link here at the end to another tutorial, that is a tutorial on lexical binding... 18:49 and it's very extensible. 18:52 And, by the way - 18:56 in several places in the source code of eev I have examples that follow exactly these same conventions, but they appear in comments. So people can also execute these examples in comments to understand ideas step by by step, starting from the most basic cases and then building more complex functions on top of that. 19:24 Let me see... so: yeah, that's what I wanted to present. My tutorial is much more "do-it-yourself-ish" than the Emacs Lisp Intro... 19:44 and I confess that I always find the reactions to my tutorial quite puzzling, because I think that my tutorial is very nice - 19:56 but sometimes I participate in discussions in the Emacs mailing lists and someone asks: "how do I do this? How can i learn" - for example - "how to use backquote?" 20:09 and people say: there's blah blah blah, there's this link to the manual, this link to this other manual, and so on... and I recommend trying the examples in my tutorial - "you just need to learn the keys such and such" 20:23 and then go to the section - let me see - Backquote, section 10 20:32 and I never get any answers... I have the impression that people think that my tutorial is far too weird, it's like the product of a totally alien mind, and 20:47 no one uses it, no one comments on it, and then it's always... I don't know, something that just has to be ignored when I mention it - and i want to fix this. 21:00 And this video is - hopefully - a first step to make my tutorial less mysterious. 21:08 So: that's it. That's what i wanted to show. Bye! =)