WEBVTT captioned by eduardo
Kind: captions:
Language: en-GB
00:00:00.000 --> 00:00:04.000
Hi! My name is Eduardo Ochs. I'm the author
00:00:04.000 --> 00:00:06.000
of an Emacs package called eev...
00:00:06.000 --> 00:00:10.000
and eev is about taking executable notes
00:00:10.000 --> 00:00:13.000
of everything that you do, and this
00:00:13.000 --> 00:00:16.000
presentation is about how I use this...
00:00:16.000 --> 00:00:18.000
how I finally found a way to take
00:00:18.000 --> 00:00:22.000
executable notes of what the python docs
00:00:22.000 --> 00:00:23.000
say.
00:00:23.000 --> 00:00:28.000
Let me explain that in another way. I've
00:00:28.000 --> 00:00:31.000
try to Learn Python many times, but
00:00:31.000 --> 00:00:34.000
hm, my brain is wired in a weird way, so
00:00:34.000 --> 00:00:37.000
it didn't work... and finally a few
00:00:37.000 --> 00:00:40.000
months ago I found a way of studying
00:00:40.000 --> 00:00:44.000
Python that finally clicked for me.
00:00:44.000 --> 00:00:47.000
The idea is that... well, it's here in
00:00:47.000 --> 00:00:50.000
the title - is a way to create short
00:00:50.000 --> 00:00:52.000
hyperlinks to the
00:00:52.000 --> 00:00:54.000
documentation of python.
00:00:54.000 --> 00:00:56.000
Here's an example.
00:00:56.000 --> 00:01:00.000
This file contains some some chunks
00:01:00.000 --> 00:01:03.000
of code from the Python tutorial and
00:01:03.000 --> 00:01:05.000
some links to the places in which
00:01:05.000 --> 00:01:07.000
I found these chunks of code.
00:01:07.000 --> 00:01:12.000
for example, if I run this link here
00:01:12.000 --> 00:01:14.000
it opens a certain page of the Python
00:01:14.000 --> 00:01:18.000
tutorial in my browser - note that it
00:01:18.000 --> 00:01:19.000
opens the local copy of the
00:01:19.000 --> 00:01:22.000
documentation -
00:01:22.000 --> 00:01:25.000
and if I
00:01:25.000 --> 00:01:29.000
run this link here it opens the source
00:01:29.000 --> 00:01:30.000
in .rst
00:01:30.000 --> 00:01:34.000
of the same page. So the first link opens
00:01:34.000 --> 00:01:37.000
the HTML and this one opens the
00:01:37.000 --> 00:01:39.000
RST. This is useful because in the
00:01:39.000 --> 00:01:40.000
beginning
00:01:40.000 --> 00:01:44.000
I was copying these chunks of code in
00:01:44.000 --> 00:01:46.000
the obvious way - I would simply
00:01:46.000 --> 00:01:50.000
visit the the documentation in HTML and
00:01:50.000 --> 00:01:51.000
I would mark
00:01:51.000 --> 00:01:54.000
a chunk... a snippet of code here and I
00:01:54.000 --> 00:01:58.000
would copy it to my notes.
00:01:58.000 --> 00:02:01.000
And then after a while I
00:02:01.000 --> 00:02:03.000
realized that it was much easier to
00:02:03.000 --> 00:02:07.000
simply go to the RST sources and to copy
00:02:07.000 --> 00:02:10.000
the chunks of code from there... and
00:02:10.000 --> 00:02:14.000
note that these links look quite similar.
00:02:14.000 --> 00:02:17.000
There's one difference here, that is
00:02:17.000 --> 00:02:20.000
this `r` that is prepended to the name
00:02:20.000 --> 00:02:23.000
of the function... the `r` means
00:02:23.000 --> 00:02:26.000
"open the RST"...
00:02:26.000 --> 00:02:30.000
and if I use the suffix `w` it means
00:02:30.000 --> 00:02:32.000
use the documentation on the web instead
00:02:32.000 --> 00:02:34.000
of using the local copy.
00:02:34.000 --> 00:02:36.000
So this one
00:02:36.000 --> 00:02:38.000
opens a local copy
00:02:38.000 --> 00:02:42.000
and this one
00:02:42.000 --> 00:02:46.000
takes a while
00:02:46.000 --> 00:02:49.000
and opens the
00:02:49.000 --> 00:02:52.000
the page of the documentation in the
00:02:52.000 --> 00:02:56.000
site of Python blah blah...
00:02:56.000 --> 00:02:58.000
and this thing here is
00:02:58.000 --> 00:03:02.000
executable in the usual eev sense, that
00:03:02.000 --> 00:03:05.000
we ca... if we type f8 several times here
00:03:05.000 --> 00:03:08.000
the f8s on the lines that start
00:03:08.000 --> 00:03:12.000
with red stars create a target buffer
00:03:12.000 --> 00:03:14.000
here... and in this case it creates a
00:03:14.000 --> 00:03:17.000
target buffer running Python, and if I
00:03:17.000 --> 00:03:20.000
type f8 on these other lines these are
00:03:20.000 --> 00:03:23.000
the lines are sent
00:03:23.000 --> 00:03:25.000
to that REPL.
00:03:25.000 --> 00:03:30.000
But anyway, let me go back.
00:03:30.000 --> 00:03:32.000
Most of the things that I'm going to
00:03:32.000 --> 00:03:35.000
present here are in the tutorial of this...
00:03:35.000 --> 00:03:37.000
package...
00:03:37.000 --> 00:03:41.000
we can go to the source code
00:03:41.000 --> 00:03:44.000
here in the eev directory - it's a file
00:03:44.000 --> 00:03:50.000
called eev-rstdoc.el but the best
00:03:50.000 --> 00:03:53.000
docs are in the tutorial, here...
00:03:53.000 --> 00:03:56.000
and the tutorial also has some
00:03:56.000 --> 00:03:58.000
executable
00:03:58.000 --> 00:04:02.000
chunks... some snippets of python
00:04:02.000 --> 00:04:05.000
code that are executable, but they
00:04:05.000 --> 00:04:07.000
don't have those nice colors... so
00:04:07.000 --> 00:04:11.000
apologies for that.
00:04:11.000 --> 00:04:13.000
We need to run this thing here to make
00:04:13.000 --> 00:04:15.000
everything work.
00:04:15.000 --> 00:04:17.000
This thing will define some functions
00:04:17.000 --> 00:04:19.000
with funny names that I will
00:04:19.000 --> 00:04:26.000
explain later.
00:04:26.000 --> 00:04:30.000
Let me explain something new.
00:04:30.000 --> 00:04:35.000
let's compare all these
00:04:35.000 --> 00:04:38.000
links here. They take this argument
00:04:38.000 --> 00:04:41.000
here and they expand the the argument in
00:04:41.000 --> 00:04:44.000
a certain way. For example this string is
00:04:44.000 --> 00:04:49.000
expanded to this long URL here... note that
00:04:49.000 --> 00:04:52.000
it got a prefix here,
00:04:52.000 --> 00:04:56.000
that's quite long... it got the .html here,
00:04:56.000 --> 00:04:59.000
and then the hash and the anchor here...
00:04:59.000 --> 00:05:03.000
and each one of the functions in the
00:05:03.000 --> 00:05:06.000
pydoc family expands this
00:05:06.000 --> 00:05:09.000
argument in a different way.
00:05:09.000 --> 00:05:12.000
The one that that opens the doc in the
00:05:12.000 --> 00:05:16.000
web uses another prefix -
00:05:16.000 --> 00:05:20.000
this one - and the one that opens the rst
00:05:20.000 --> 00:05:24.000
file ignores the part after the hash
00:05:24.000 --> 00:05:28.000
for technical reasons... I was never
00:05:28.000 --> 00:05:30.000
able to to find a good way to convert
00:05:30.000 --> 00:05:33.000
this hash into a string to search for,
00:05:33.000 --> 00:05:35.000
so to make something that goes to
00:05:35.000 --> 00:05:38.000
the right section in the link to the rst
00:05:38.000 --> 00:05:42.000
doc I have to convert by hand, and by
00:05:42.000 --> 00:05:46.000
trial and error, this thing here into a
00:05:46.000 --> 00:05:48.000
pointer to that section, like
00:05:48.000 --> 00:05:50.000
this one...
00:05:50.000 --> 00:05:55.000
in which the "_numeric-types:"
00:05:55.000 --> 00:05:58.000
is here.
00:05:58.000 --> 00:06:02.000
So all these links here are based on
00:06:02.000 --> 00:06:04.000
expansion, and this is easy to
00:06:04.000 --> 00:06:05.000
understand...
00:06:05.000 --> 00:06:08.000
but suppose that I want to
00:06:08.000 --> 00:06:11.000
create a link like this, or suppose that
00:06:11.000 --> 00:06:16.000
I'm browsing the docs here
00:06:16.000 --> 00:06:21.000
and I just I follow some some links...
00:06:21.000 --> 00:06:31.000
let me do something random here...
00:06:31.000 --> 00:06:34.000
suppose that I decide that this
00:06:34.000 --> 00:06:35.000
section is very interesting. How can I
00:06:35.000 --> 00:06:39.000
create a link to that? I can
00:06:39.000 --> 00:06:44.000
use this pilcrow symbol and the
00:06:44.000 --> 00:06:45.000
"Copy link address",
00:06:45.000 --> 00:06:49.000
and copy the link to
00:06:49.000 --> 00:06:51.000
my notes...
00:06:51.000 --> 00:06:55.000
and then the Python family...
00:06:55.000 --> 00:06:58.000
well, we saw the the functions in the
00:06:58.000 --> 00:07:00.000
Python family have a certain way - have
00:07:00.000 --> 00:07:03.000
several ways of expanding these
00:07:03.000 --> 00:07:06.000
short arguments... and they also have a
00:07:06.000 --> 00:07:07.000
certain way of
00:07:07.000 --> 00:07:11.000
shortening URLs like this one. If I type
00:07:11.000 --> 00:07:12.000
`M-x pdk` the message is this one.
00:07:12.000 --> 00:07:17.000
`pdk` is a mnemonic for
00:07:17.000 --> 00:07:20.000
"Python doc kill", and this
00:07:20.000 --> 00:07:23.000
"kill" means "copy to the kill ring"
00:07:23.000 --> 00:07:27.000
so if I type `M-x pdk` here it
00:07:27.000 --> 00:07:31.000
considers that this thing is a link
00:07:31.000 --> 00:07:34.000
to the python Docs, and it
00:07:34.000 --> 00:07:36.000
shortens this link in a certain way, and
00:07:36.000 --> 00:07:42.000
it kills a short link.
00:07:42.000 --> 00:07:45.000
I can insert the short link with C-y
00:07:45.000 --> 00:07:46.000
(yank)
00:07:46.000 --> 00:07:49.000
and then I can test this link to be sure
00:07:49.000 --> 00:07:52.000
that it points to where I want, and
00:07:52.000 --> 00:07:55.000
then I can delete this thing, and ta-da,
00:07:55.000 --> 00:07:57.000
now I have a short link, and of course I
00:07:57.000 --> 00:08:00.000
can modify this link by adding a suffix
00:08:00.000 --> 00:08:02.000
here...
00:08:02.000 --> 00:08:06.000
and in this case here
00:08:06.000 --> 00:08:09.000
I will have to change the identifier
00:08:09.000 --> 00:08:12.000
to something else...
00:08:12.000 --> 00:08:18.000
but I'm not going to do that now.
00:08:18.000 --> 00:08:20.000
This module of eev comes with three
00:08:20.000 --> 00:08:24.000
families predefined. One is a family that
00:08:24.000 --> 00:08:26.000
points to the the documentation of
00:08:26.000 --> 00:08:28.000
Python itself, another one points the
00:08:28.000 --> 00:08:30.000
documentation of SymPy, that is a program
00:08:30.000 --> 00:08:34.000
for symbolic computation, like for doing
00:08:34.000 --> 00:08:37.000
mathematics equations...
00:08:37.000 --> 00:08:40.000
and the other one points to the
00:08:40.000 --> 00:08:43.000
documentation of MatPlotLib.
00:08:43.000 --> 00:08:47.000
How do these families work?
00:08:47.000 --> 00:08:51.000
Each family has to be defined in two
00:08:51.000 --> 00:08:53.000
parts.
00:08:53.000 --> 00:08:55.000
Remember that
00:08:55.000 --> 00:08:58.000
eev has lots of functions
00:08:58.000 --> 00:09:03.000
like this one... this one
00:09:03.000 --> 00:09:06.000
is the most basic, and it is explained
00:09:06.000 --> 00:09:08.000
here, in this section of the main
00:09:08.000 --> 00:09:13.000
tutorial. This section explains that
00:09:13.000 --> 00:09:16.000
a sexp like this one produces lots of
00:09:16.000 --> 00:09:19.000
functions - produces a family of
00:09:19.000 --> 00:09:23.000
functions - and it does that by producing
00:09:23.000 --> 00:09:25.000
a certain chunk of code and then
00:09:25.000 --> 00:09:28.000
executing this chunk of code... and if we
00:09:28.000 --> 00:09:31.000
add a certain prefix here... `find-` and we
00:09:31.000 --> 00:09:35.000
execute this we can... instead of executing
00:09:35.000 --> 00:09:37.000
that chunk of code we can see what is
00:09:37.000 --> 00:09:39.000
that chunk of code. In the case of `code-c-d`
00:09:39.000 --> 00:09:43.000
it is this. It is a `setq`, several
00:09:43.000 --> 00:09:47.000
`defun`s, and some comments here, with
00:09:47.000 --> 00:09:49.000
links to the documentation.
00:09:49.000 --> 00:09:52.000
In the case of rstdoc it's the same.
00:09:52.000 --> 00:09:54.000
We have this function here that defines
00:09:54.000 --> 00:09:56.000
the function in the python family...
00:09:56.000 --> 00:09:59.000
and we can run this to understand what
00:09:59.000 --> 00:10:03.000
this `code-rstdoc` does.
00:10:03.000 --> 00:10:05.000
It creates this temporary buffer here...
00:10:05.000 --> 00:10:09.000
with lots of `defun`s, a `code-c-d` here,
00:10:09.000 --> 00:10:10.000
and lots of comments here... and the
00:10:10.000 --> 00:10:13.000
comments include some tests. For example
00:10:13.000 --> 00:10:16.000
we can use these functions here to test
00:10:16.000 --> 00:10:21.000
how the expansion works.
00:10:21.000 --> 00:10:23.000
And
00:10:23.000 --> 00:10:26.000
note that in this buffer here we don't
00:10:26.000 --> 00:10:28.000
have the paths that that this family
00:10:28.000 --> 00:10:31.000
uses. We don't have for example
00:10:31.000 --> 00:10:33.000
the URL that points to the site of
00:10:33.000 --> 00:10:36.000
Python, to the directory that contains
00:10:36.000 --> 00:10:40.000
the reference manual, or whatever... all
00:10:40.000 --> 00:10:42.000
these things are in another part of the
00:10:42.000 --> 00:10:44.000
definition of that family - that is a
00:10:44.000 --> 00:10:45.000
variable.
00:10:45.000 --> 00:10:48.000
If we execute this we go to the
00:10:48.000 --> 00:10:50.000
source code of eev-rstdoc,
00:10:50.000 --> 00:10:54.000
to the parts in which
00:10:54.000 --> 00:10:57.000
this variable is defined...
00:10:57.000 --> 00:10:59.000
and
00:10:59.000 --> 00:11:01.000
for each family we have a variable like
00:11:01.000 --> 00:11:02.000
this,
00:11:02.000 --> 00:11:05.000
whose value is a property
00:11:05.000 --> 00:11:07.000
list with several fields...
00:11:07.000 --> 00:11:09.000
these first fields are very easy to
00:11:09.000 --> 00:11:10.000
understand - they are used in the
00:11:10.000 --> 00:11:16.000
expansion... this one too. And these
00:11:16.000 --> 00:11:19.000
two fields are used in the shrinking -
00:11:19.000 --> 00:11:21.000
in the shortening - and
00:11:21.000 --> 00:11:25.000
this field here
00:11:25.000 --> 00:11:28.000
tells what is the name of the
00:11:28.000 --> 00:11:30.000
killing function
00:11:30.000 --> 00:11:33.000
so the fields of this thing here are
00:11:33.000 --> 00:11:34.000
used
00:11:34.000 --> 00:11:36.000
to generate...
00:11:36.000 --> 00:11:39.000
some fields are used to generate the
00:11:39.000 --> 00:11:41.000
code that appears here, and some fields
00:11:41.000 --> 00:11:44.000
are simply
00:11:44.000 --> 00:11:47.000
read by functions like this one, that
00:11:47.000 --> 00:11:51.000
consults the variable.
00:11:51.000 --> 00:11:53.000
Now the natural question is: how can we
00:11:53.000 --> 00:11:57.000
define new families? Or: how can we change
00:11:57.000 --> 00:11:59.000
a family like this one to point to
00:11:59.000 --> 00:12:03.000
another version of Python?
00:12:03.000 --> 00:12:06.000
There are some template-based functions
00:12:06.000 --> 00:12:09.000
for doing that. They are explained in
00:12:09.000 --> 00:12:10.000
this section of the tutorial...
00:12:10.000 --> 00:12:14.000
where is that?...
00:12:14.000 --> 00:12:17.000
oh God, it's far away...
00:12:17.000 --> 00:12:20.000
here.
00:12:20.000 --> 00:12:23.000
Suppose that we have a package foo, that
00:12:23.000 --> 00:12:25.000
we want to create a family that points
00:12:25.000 --> 00:12:27.000
to the docs
00:12:27.000 --> 00:12:31.000
of that package foo... so, we
00:12:31.000 --> 00:12:32.000
can execute this thing here, and it
00:12:32.000 --> 00:12:34.000
generates this
00:12:34.000 --> 00:12:37.000
this thing from a template.
00:12:37.000 --> 00:12:40.000
If we just want to modify a current
00:12:40.000 --> 00:12:42.000
definition we can run something like
00:12:42.000 --> 00:12:44.000
this - note that the family `:py`
00:12:44.000 --> 00:12:47.000
already exists, and instead of using
00:12:47.000 --> 00:12:51.000
placeholders in some of these
00:12:51.000 --> 00:12:53.000
URLs it will use the current values of
00:12:53.000 --> 00:12:55.000
the fields...
00:12:55.000 --> 00:12:59.000
so we can also use this modify
00:12:59.000 --> 00:13:01.000
existing families.
00:13:01.000 --> 00:13:05.000
Well these are the technical details.
00:13:05.000 --> 00:13:08.000
Now the natural question is: why do I
00:13:08.000 --> 00:13:12.000
want this? This doesn't
00:13:12.000 --> 00:13:14.000
any sense to me! Why should I
00:13:14.000 --> 00:13:15.000
try this?
00:13:15.000 --> 00:13:18.000
And the best answer: is for most people
00:13:18.000 --> 00:13:21.000
this way of using
00:13:21.000 --> 00:13:24.000
executable notes do not make any sense
00:13:24.000 --> 00:13:27.000
at all at first sight...
00:13:27.000 --> 00:13:30.000
so what I'm trying to do is: I'm trying
00:13:30.000 --> 00:13:33.000
to write to these tutorials with
00:13:33.000 --> 00:13:35.000
many examples that are very easy to run,
00:13:35.000 --> 00:13:38.000
and that examine data structures,
00:13:38.000 --> 00:13:40.000
and functions, and test things,
00:13:40.000 --> 00:13:46.000
and so on... so my main argument
00:13:46.000 --> 00:13:48.000
for convincing people to
00:13:48.000 --> 00:13:52.000
test this is: this is trivial to test -
00:13:52.000 --> 00:13:54.000
simply install eev and run this thing
00:13:54.000 --> 00:13:56.000
here, and run the examples, and probably
00:13:56.000 --> 00:13:58.000
you're going to find that this
00:13:58.000 --> 00:14:01.000
tutorial is fun to follow.
00:14:01.000 --> 00:14:03.000
So that's it! =)
