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

The main page about this video is here.
Its index is here.
Its subtitles in Lua are here.
The rest of this page contains a conversion of the subtitles in Lua
to a slightly more readable format.

00:00 Hi! My name is Eduardo Ochs, I'm the author
00:03 of an Emacs package called eev,
00:05 and the title of this video is: "Why eev
00:09 comes with a weird elisp tutorial and
00:11 how to use it".

00:13 Before starting let me just explain what
00:15 is this image here.
00:18 It's a frame from my most
00:21 favorite animation movie ever. Its title
00:24 in English is "Gwen, or the book of sand"
00:27 and it's available on youtube; you can
00:30 watch it there.

00:33 One of my missions on Earth is to
00:35 convince more people to watch that
00:37 movie.

00:39 I've watched it more than 30 times. I've
00:41 shown it to many people, and every
00:43 time that I watch it it blows my mind in
00:45 different ways.
00:47 Anyway, let me go back.
00:50 One more thing before starting...

00:53 Emacs comes with an Emacs Lisp
00:55 tutorial that is very famous -
00:58 it's called "An Introduction to
01:00 Programming in Emacs Lisp".
01:03 It comes as an info manual, and it's
01:06 actually a book.

01:09 Using info mode you can navigate
01:11 through it - through its chapter, sections,
01:13 and so on.

01:15 If you're a beginner you're probably
01:17 going to use these, uh,
01:20 things here in the toolbar; if you're not
01:22 a beginner you can use,
01:25 for example, the
01:27 square brackets to navigate to the
01:29 previous and the next section in a
01:31 certain order.

01:33 Let me use that now to show how big this
01:35 manual is.
01:39 These are all its sections and
01:41 subsections and so on,
01:44 and it's huge -
01:46 very huge -
01:48 oh no, it never ends -
01:52 That's it. So: a zillion of sections.

02:02 Eev comes with a very short tutorial
02:07 on Emacs Lisp that you can
02:09 access by just typing M-7 M-j.

02:13 Here - let's see its size. Let me
02:18 turn on the scroll bar here...
02:20 if we scroll here, and go
02:23 to the end of the tutorial - it's here
02:27 it has just a bit more than 600 lines.

02:34 I say here that "This is a very quick
02:38 introduction to Emacs Lisp.
02:41 My intent here is not to teach people
02:43 how to _write_ Elisp code, only to teach
02:45 them to _read_ Elisp code." I consider that
02:47 reading and writing are two different
02:49 stages, and in the beginning people are
02:52 mostly going to want to read things...
02:55 like to understand what the
02:57 source code means, or
03:00 to understand how a certain template is
03:03 prepared, and so on...

03:06 And I say here that `Different people
03:08 prefer different kinds of tutorials'
03:11 and many people - actually most people -
03:13 love the the introduction to Emacs Lisp -
03:15 this one here - but i don't -
03:23 and in this video i'm going to explain why.

03:26 This tutorial here - this short one - is what
03:29 I would have liked to have had access to
03:31 when I started learning Emacs Lisp.
03:37 Let me go back a second.

03:42 I started to write to this tutorial
03:44 because I was invited to teach a minicourse
03:47 on LaTeX to
03:49 students that had never used Emacs
03:52 before, and I said:
03:54 `Oh, okay, I'm going to teach it, but
03:56 everybody is going to be forced to use
04:01 Emacs and eev - but I'm going to do it in a
04:03 certain way in which it's not going to be
04:05 very painful'.

04:07 And so, I used eev to make people learn Emacs
04:11 in a certain way,
04:13 and every time that a person
04:16 had a curiosity about something in Lisp
04:18 and wanted to understand the syntax
04:22 or the defuns, or backquotes,
04:25 or whatever, I said `oh, look at the
04:30 sections such and such
04:32 in my Elisp tutorial'.

04:38 So these people knew very few
04:41 keys of Emacs in the beginning
04:43 they basically knew the three most basic
04:46 keys, that are M-e, M-k, and M-j...
04:50 M-e executes the
04:52 sexp in the current line,
04:56 M-k can be used to to kill the current
04:59 buffer, which usually means to go back,
05:03 and M-j jumps to several different places...

05:08 and if you run M-j without a numerical
05:10 argument it shows this temporary buffer here
05:14 that... here it shows some of the main
05:18 targets - that have numbers assigned to them
05:24 and here you can see the other targets.

05:27 So this line here means that
05:31 if you type M-j with the numeric prefix 7
05:36 it is going to execute this thing here,
05:39 that goes to the Elisp tutorial...

05:43 and these are the the things that are
05:45 most basic that beginners learn first.

05:51 These things here - this one here, M-5 M-j,
05:56 is the basic tutorial, called
06:00 (find-eev-quick-intro),

06:04 this one, M-2 M-j, is a fake tutorial
06:07 that is mostly an index of keys,
06:12 and this one here - M-1 M-j -
06:15 opens a buffer with our notes...

06:20 I always say to the beginners
06:23 that in the beginning they should put all
06:27 their notes in this buffer here - ~/TODO -
06:33 and that they shouldn't mind if their
06:35 notes are messy - they can clean
06:37 them up later -

06:41 and this thing here also shows some keys
06:44 for opening the file with the notes in
06:47 the window at the right from any place...

06:53 so, for example if we are in the
06:55 elisp tutorial, here, and we find
06:59 something interesting, say, on
07:02 section 3 - for example this block here -
07:08 we can run this thing here, show our
07:12 buffer with notes at the window at the
07:15 right, and we can copy the thing here to
07:17 our notes.

07:23 Just one comment before showing other things...
07:29 M-7 M-j goes to the elisp tutorial,
07:34 and the last line of this header
07:36 says that you can open this tutorial
07:42 or recreate it with M-7 M-j...

07:46 It is a sandbox, in the sense that you
07:48 can make any mess here
07:52 and then recreate it.

07:59 Some other tutorials have numbers,
08:02 like this. For example, this is the
08:04 fake tutorial that is just an index,
08:07 and it says that you can access this
08:09 thing with M-5 M-0 M-j...
08:13 and these other ones I have already shown.

08:23 One important thing is that people can
08:28 create links to the sections of the...
08:31 of my elisp tutorial very easily.

08:35 For example, suppose that you're one of
08:42 the students in my workshop, you are
08:44 starting to learn Emacs today,
08:47 and you learned the basic ideas of how
08:50 to create elisp hyperlinks, and you
08:56 think that there's something interesting
08:58 in this section here - section 5.

09:02 So you can create a link to it by hand.
09:04 For example you can simply type this
09:09 (find-elisp-intro ...)
09:14 initially by hand; later you can learn
09:17 the tricks for generating
09:19 this automatically -

09:22 and you can copy the title
09:25 to this position here.

09:27 Now you have something that you if
09:29 execute... if you execute this you
09:32 go exactly to this section here.
09:43 But let me go back...

09:49 Let me now explain some
09:52 differences in style between the
09:54 standard tutorial and my tutorial.

10:01 I think that the first thing that made
10:03 me dislike the Emacs Lisp Intro
10:06 is that it is "An introduction to
10:10 programming in Emacs Lisp
10:13 _for people who are not programmers_",

10:16 and I was trying very hard to become a
10:18 programmer, i was really thinking like a
10:20 programmer, and I was taking notes and
10:23 creating exercises and so on...
10:25 and so this thing felt
10:27 more like a book that
10:30 should be read like a book, not like
10:32 code that you can execute by
10:35 just typing M-e.
10:39 It felt non-Emacs-y.

10:44 I also said that this is huge... this is
10:48 the menu with the chapters and sections
10:51 and subsections and so on...
10:56 in some situations it has
11:01 faces here - in the sense of different
11:03 fonts -
11:05 and sometimes it's not totally clear if
11:07 this difference is important or not, and
11:13 if we copy a part of this to our notes
11:18 and we save our notes
11:20 then the faces are going to disappear -
11:22 the the thing is going to become plain
11:24 text without the
11:26 the different fonts.

11:32 Also, the manual is full of
11:37 examples like this, that are not complete
11:39 chunks of code, they are just
11:45 excerpts from bigger functions.

11:55 So, in short: it is big,
11:58 it is hard to navigate because it has
12:01 zillion of sections, it uses faces, it is
12:04 read-only -

12:06 remember that in my tutorial you can
12:11 duplicate a line, for example, and check
12:14 what happens if you change
12:18 one item of a list by something else -

12:21 for example what happens
12:23 if you change this by 40 or by a string,
12:26 and you can execute these things here...

12:29 so this is a sandbox where you can execute
12:31 things, and this does not happen
12:34 in the Emacs Lisp Intro.

12:40 Also, the Emacs Lisp Intro has just a
12:43 few executable examples per page,
12:46 while my tutorial has many -
12:49 for example here: all these things
12:51 are different examples...

12:57 and one thing that really bothered me is
13:02 that I prefer to believe that Emacs
13:08 was made in two levels: first people took
13:12 a Lisp interpreter -

13:14 no, sorry, three levels - people first took
13:17 at Lisp interpreter, and then they
13:22 programmed in it a handful
13:24 of functions for dealing with keys,
13:28 buffers, files, windows and so on; just a
13:31 few basic things...

13:33 and at one point they had a very basic
13:35 editor that had Lisp inside,
13:37 and they they could change its Lisp code
13:40 interactively using the editor itself...

13:44 and then they started to build
13:47 an editor that was much more powerful,
13:50 and also to extend the Lisp with
13:53 more advanced features...

13:56 but I prefer to think that that we have
13:58 this division, with basic Lisp on the
14:01 bottom, and then basic editing functions
14:03 on top, and then
14:07 a huge structure with zillions of
14:10 editing functions -

14:12 and the Emacs Lisp tutorial does not make
14:15 this distinction very clearly
14:18 and it explains basic Lisp at the
14:21 same time as the
14:23 as editing functions, because
14:25 it wants to explain
14:27 how how people can write useful
14:29 functions, and useful functions are
14:31 usually
14:33 functions that edit things.

14:36 Another thing that I really didn't like
14:39 in it is that it has
14:42 very few links to the primary sources.
14:45 Here we are inside Emacs, and it's
14:48 very easy to access
14:53 each one of the manuals
14:55 and the source code.

14:57 For example, here
15:01 I have a section of my tutorial that
15:03 ends with this block here: it says
15:07 "for more info on the other types of
15:10 list objects..." - oops, it's Lisp
15:13 objects, sorry there's a typo here -
15:16 "see blah blah" and each of these things
15:18 is a link to the Emacs Lisp manual.

15:25 Also, here we have links to the Wikipedia,
15:29 and in other places with we have links
15:31 to the Emacs manual...

15:36 and I think that in a couple of places
15:38 we have links to the source code too -
15:44 and the Emacs Lisp Intro does not
15:47 do that.

15:49 It is made to be
15:51 the online version of a book, and I
15:55 think that this is a bit frustrating.

15:58 And the main point - and this is something
16:01 that very people have noticed -
16:03 is that my tutorial works in two ways.

16:09 It has some contents here, so people can
16:12 _read_ it
16:14 but it also has lots of design choices
16:17 and stylistical choices - I decided to
16:20 present things in a certain way...
16:24 and when people
16:28 run these examples
16:30 they're probably going to
16:32 become familiar with these
16:35 stylistical choices, and
16:37 when they start to take their own notes
16:40 they are probably going to use
16:42 some of these ideas on their notes.

16:44 So they are going to do something like
16:48 this, in which they put
16:50 several similar examples close to
16:54 one another, starting by the most basic
16:56 ones.

16:58 They can also put just a bit of text
17:02 instead of having to explain lots of
17:04 things, and they are also -
17:07 I hope -

17:09 they will also
17:11 try to use this style here,
17:14 in which we put important links
17:17 to everything that that we find, so
17:21 instead of trying to reproduce the
17:23 explanations
17:25 with our own words
17:27 we just put the links to
17:29 the sources where we can find the
17:32 full explanations.

17:35 The idea is that when people
17:38 are learning some
17:41 more advanced things that are not in the
17:43 manual they can
17:46 write their notes in this format
17:49 and they can even share these notes with
17:51 other people -

17:53 and in my workshops I often have
17:58 some moments in which people share their
18:00 notes, and of course people would
18:05 want to write notes that are
18:07 useful to other people, and notes that
18:10 are easy to change, and easy to
18:12 collaborate on -

18:14 and so one of the intentions of my
18:16 tutorials was to suggest a certain style
18:20 and convince people that they could
18:23 write their notes in this style.

18:27 This tutorial is very incomplete - it just
18:30 teaches the basic ideas -
18:32 but it also has a link here at the end
18:36 to another tutorial,
18:39 that is a tutorial on
18:43 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
18:58 eev I have examples that follow exactly
19:02 these same conventions, but they
19:04 appear in comments.

19:06 So people can also execute these
19:08 examples in comments
19:10 to understand ideas step by by step,
19:14 starting from the
19:16 most basic cases and then building more
19:19 complex functions on top of that.
19:24 Let me see...

19:29 so, yeah, that's what I wanted to
19:31 present. My tutorial is
19:33 much more "do-it-yourself-ish"
19:36 than the Emacs Lisp Intro...

19:46 And I confess that I always find the
19:48 reactions to my tutorial
19:52 quite puzzling, because I think that my
19:54 tutorial is very nice -

19:56 but sometimes I participate in
19:59 discussions in the Emacs mailing
20:01 lists and someone asks: "how
20:04 how do i do this? How can i learn" - for
20:07 example - "how to use back quote?"
20:09 and people say: there's blah blah blah,
20:11 there's this link to the manual, this link to
20:13 the other manual, and so on... and I recommend
20:15 trying the examples in my tutorial -
20:18 "you just need to learn the keys
20:21 such and such" -
20:23 and go to the section - let me see -
20:28 Backquote, section 10

20:32 and I never get any answers... I have the
20:35 impression that people
20:37 think that my tutorial is
20:40 far too weird, it's
20:42 like the product of a totally alien
20:45 mind, and no one uses it,

20:47 no one comments on it, and
20:50 then it's always...
20:53 I don't know, something
20:55 that just has to be ignored when I
20:57 mention it - and I want to fix this.

21:00 And this video is - hopefully -
21:04 a first step
21:06 to make my tutorial less mysterious.

21:08 So: that's it. That's what I wanted to
21:11 show. Bye! =)