Chapa 1)


Why eev has a weird elisp tutorial and how to use it

Main links:
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

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

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

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

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

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

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

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

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

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

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

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! =)