1 files changed, 853 insertions, 0 deletions
diff --git a/2022/captions/emacsconf-2022-python--short-hyperlinks-to-python-docs--eduardo-ochs--main.vtt b/2022/captions/emacsconf-2022-python--short-hyperlinks-to-python-docs--eduardo-ochs--main.vtt
new file mode 100644
index 00000000..904762a5
--- /dev/null
+++ b/2022/captions/emacsconf-2022-python--short-hyperlinks-to-python-docs--eduardo-ochs--main.vtt
@@ -0,0 +1,853 @@
+WEBVTT
+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! =)
+