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".
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.
One of my missions on Earth is to
convince more people 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.
Anyway, let me go back.
One more thing before starting...
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
actually a book.
Using info mode you can navigate
through it - through its chapter, sections,
and so on.
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.
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 -
That's it. So: a zillion of sections.
Eev comes with a very short tutorial
on Emacs Lisp that you can
access by just typing M-7 M-j.
Here - let's see its size. Let me
turn on the scroll bar here...
if we scroll here, and go
to the end of the tutorial - it's here
it has just a bit more than 600 lines.
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." 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...
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 -
and in this video i'm going to explain why.
This tutorial here - this short one - is what
I would have liked to have had access to
when I started learning Emacs Lisp.
Let me go back a second.
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:
`Oh, okay, 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'.
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
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'.
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...
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
that... here it shows some of the main
targets - that have numbers assigned to them
and here you can see the other targets.
So this line here means that
if you type M-j with the numeric prefix 7
it is going to execute this thing here,
that goes to the Elisp tutorial...
and these are the the things that are
most basic that beginners learn first.
These things here - this one here, M-5 M-j,
is the basic tutorial, called
(find-eev-quick-intro),
this one, M-2 M-j, is a fake tutorial
that is mostly an index of keys,
and this one here - M-1 M-j -
opens a buffer with our notes...
I always say to the beginners
that in the beginning they should put all
their notes in this buffer here - ~/TODO -
and that they shouldn't mind if their
notes are messy - they can clean
them up later -
and this thing here also shows some keys
for opening the file with the notes in
the window at the right from any place...
so, for example if we are in the
elisp tutorial, here, and we find
something interesting, say, on
section 3 - for example this block here -
we can run this thing here, show our
buffer with notes at the window at the
right, and we can copy the thing here to
our notes.
Just one comment before showing other things...
M-7 M-j goes to the elisp tutorial,
and the last line of this header
says that you can open this tutorial
or recreate it with M-7 M-j...
It is a sandbox, in the sense that you
can make any mess here
and then recreate it.
Some other tutorials have numbers,
like this. For example, this 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.
One important thing is that people can
create links to the sections of the...
of my elisp tutorial very easily.
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, and you
think that there's something interesting
in this section here - section 5.
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 -
and you can copy the title
to this position here.
Now you have something that you if
execute... if you execute this you
go exactly to this section here.
But let me go back...
Let me now explain some
differences in style between the
standard tutorial and my tutorial.
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 can execute by
just typing M-e.
It felt non-Emacs-y.
I also said that this is huge... this is
the menu with the chapters and sections
and subsections and so on...
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
if we copy a part of this to our notes
and we save our notes
then the faces are going to disappear -
the the thing is going to become plain
text without the
the different fonts.
Also, the manual is full of
examples like this, that are not complete
chunks of code, they are just
excerpts from bigger functions.
So, in short: it is big,
it is hard to navigate because it has
zillion of sections, it uses faces, it is
read-only -
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 this is a sandbox where you can execute
things, and this does not happen
in the Emacs Lisp Intro.
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...
and one thing that really bothered me is
that I prefer to believe that Emacs
was made in two levels: first people took
a Lisp interpreter -
no, sorry, three levels - people first took
at 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...
and at one point they had a very basic
editor that had Lisp inside,
and they they could change its Lisp code
interactively using the editor itself...
and then they started to build
an editor that was much more powerful,
and also to extend the Lisp with
more advanced features...
but I prefer to think that that we have
this division, with basic Lisp on the
bottom, and then basic editing functions
on top, and then
a huge structure with zillions of
editing functions -
and the Emacs Lisp tutorial does not make
this distinction very clearly
and it explains basic Lisp at the
same time as the
as editing functions, because
it wants to explain
how how people can write useful
functions, and useful functions are
usually
functions that edit things.
Another thing that I really didn't like
in it is that it has
very few links to the primary sources.
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.
Also, here we have links to the Wikipedia,
and in other places with we have links
to the Emacs manual...
and I think that in a couple of places
we have links to the source code too -
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.
And the main point - and this is something
that very people have noticed -
is that my tutorial works in two ways.
It has some contents 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...
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.
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.
They can also put just a bit of text
instead of having to explain lots of
things, and they are also -
I hope -
they will also
try to use this style here,
in which we put important links
to everything that that we find, so
instead of trying to reproduce the
explanations
with our own words
we just put the links to
the sources where we can find the
full explanations.
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 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 -
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.
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...
and it's very extensible.
And, by the way -
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.
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...
And I confess that I always find the
reactions to my tutorial
quite puzzling, because I think that my
tutorial is very nice -
but sometimes I participate in
discussions in the Emacs mailing
lists and someone asks: "how
how do i do this? How can i learn" - for
example - "how to use back quote?"
and people say: there's blah blah blah,
there's this link to the manual, this link to
the other manual, and so on... and I recommend
trying the examples in my tutorial -
"you just need to learn the keys
such and such" -
and go to the section - let me see -
Backquote, section 10
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 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.
And this video is - hopefully -
a first step
to make my tutorial less mysterious.
So: that's it. That's what I wanted to
show. Bye! =)