summaryrefslogtreecommitdiffstats
path: root/2022/captions/emacsconf-2022-python--short-hyperlinks-to-python-docs--eduardo-ochs--main.vtt
blob: 21f8c5603d5bc2fe3b746be2d26e523559f518ae (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
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! =)