summaryrefslogblamecommitdiffstats
path: root/2023/captions/emacsconf-2023-ref--orgmode-workflow-informal-reference-tracking--christopher-howard--main.vtt
blob: f678c7ed06ea1c369a6fef35144fb0ceb9e59f35 (plain) (tree)
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






































































































































































































































































































































































































































































































































































































































































































































































































































                                                        
WEBVTT captioned by bhavin192, checked by sachac

NOTE Introduction

00:00:00.000 --> 00:00:04.940
Hello, this is Christopher Howard,

00:00:04.940 --> 00:00:06.520
and welcome to my talk,

00:00:06.520 --> 00:00:08.800
"Informal Reference Tracking."

00:00:08.800 --> 00:00:10.574
This is a workflow talk,

00:00:10.574 --> 00:00:12.240
so I need to explain a little bit about

00:00:12.240 --> 00:00:14.840
what my needs were.

00:00:14.840 --> 00:00:18.760
I am not a professional scholar or academic,

00:00:18.760 --> 00:00:20.200
but there are a number of subjects

00:00:20.200 --> 00:00:21.607
that I'm interested in,

00:00:21.607 --> 00:00:23.240
and I occasionally like to write

00:00:23.240 --> 00:00:25.600
gemlog posts about them.

00:00:25.600 --> 00:00:28.680
So I needed some way to keep track of references.

00:00:28.680 --> 00:00:32.960
References to webpage articles, references to books,

00:00:32.960 --> 00:00:37.280
pages in books, and notes about them.

00:00:37.280 --> 00:00:39.480
Something that was searchable,

00:00:39.480 --> 00:00:42.440
but also something that was quick and easy to use,

00:00:42.440 --> 00:00:45.200
and something that I could set up quickly.

00:00:45.200 --> 00:00:47.360
And the approach I took, it only took me

00:00:47.360 --> 00:00:49.520
about an hour or two to figure out

00:00:49.520 --> 00:00:52.160
how to put it together.

00:00:52.160 --> 00:00:53.840
I do want to emphasize

00:00:53.840 --> 00:00:56.520
that there are better ways to do this.

00:00:56.520 --> 00:00:58.960
I'm not recommending you use my code

00:00:58.960 --> 00:01:02.120
or follow my exact approach.

00:01:02.120 --> 00:01:05.940
In particular, what I'm doing was meant to be done

00:01:05.940 --> 00:01:09.240
with Org's built-in capture

00:01:09.240 --> 00:01:11.800
and templates functionality,

00:01:11.800 --> 00:01:14.907
so that's something that's more flexible,

00:01:14.907 --> 00:01:21.440
programmable, and there's also a lot of add-ins

00:01:21.440 --> 00:01:23.960
that can be tied into that.

00:01:23.960 --> 00:01:31.320
For example, tools that allow you to search for,

00:01:31.320 --> 00:01:34.480
you know, feed in a URL, and it automatically

00:01:34.480 --> 00:01:38.240
pulls all the reference data for you.

00:01:38.240 --> 00:01:39.760
And there's tools out there

00:01:39.760 --> 00:01:43.120
that are really meant for scientific writing,

00:01:43.120 --> 00:01:46.760
so if you do this professionally,

00:01:46.760 --> 00:01:49.960
you may need to keep track of dozens of details

00:01:49.960 --> 00:01:51.080
for each reference

00:01:51.080 --> 00:01:55.320
and then have some fancy system to generate that

00:01:55.320 --> 00:02:00.800
into your, or output that into your paper.

00:02:00.800 --> 00:02:02.440
So there are better systems,

00:02:02.440 --> 00:02:06.040
but this is what worked for me and what was easy.

NOTE Tip about completion frameworks

00:02:06.040 --> 00:02:11.320
I do want to emphasize that if you haven't,

00:02:11.320 --> 00:02:14.640
you really want to learn how to use helm-mode

00:02:14.640 --> 00:02:20.440
H-E-L-M, or one of the similar systems in Emacs

00:02:20.440 --> 00:02:26.440
that does fuzzy search on Emacs commands.

00:02:26.440 --> 00:02:29.340
For example, in Helm here,

00:02:29.340 --> 00:02:39.007
I input one keychord, and then I just have to remember

00:02:39.007 --> 00:02:40.720
a few characters of some command,

00:02:40.720 --> 00:02:43.479
and they don't even have to be right next to each other,

00:02:43.480 --> 00:02:47.640
like H-O-C will bring up `helm-occur`.

00:02:47.640 --> 00:02:51.360
That's based on its algorithms

00:02:51.360 --> 00:02:53.000
of what I most likely meant

00:02:53.000 --> 00:02:55.160
and the ones that I've used in the past.

00:02:55.160 --> 00:02:57.920
So it usually brings up the command that I want,

00:02:57.920 --> 00:02:59.579
or the one that I want

00:02:59.580 --> 00:03:03.080
is one or two spots away in the entry.

00:03:03.080 --> 00:03:05.074
That just saves me a lot of time

00:03:05.074 --> 00:03:06.960
[and] a lot of memorization.

00:03:06.960 --> 00:03:09.120
So if you haven't learned Helm

00:03:09.120 --> 00:03:14.919
or a similar system for Emacs, you really want to.

NOTE References file overview

00:03:14.920 --> 00:03:18.240
So what is my approach?

00:03:18.240 --> 00:03:24.880
Well, basically, what it comes down to is really

00:03:24.880 --> 00:03:27.307
fundamentally nothing more than just a list

00:03:27.307 --> 00:03:30.640
of Org entries in a file.

00:03:30.640 --> 00:03:35.579
And there's one entry per reference.

00:03:35.580 --> 00:03:37.207
Fundamentally, that's all it is.

00:03:37.207 --> 00:03:39.207
But I'll go over the parts.

00:03:39.207 --> 00:03:43.080
You can see there's the title for the entry,

00:03:43.080 --> 00:03:44.800
and that's not necessarily

00:03:44.800 --> 00:03:47.400
the title of the book or the article,

00:03:47.400 --> 00:03:50.840
but that's my perspective on it,

00:03:50.840 --> 00:03:52.720
that's what I want to remember about it,

00:03:52.720 --> 00:03:54.560
and what I'll be looking for later

00:03:54.560 --> 00:03:56.560
when I do a search on my references.

00:03:56.560 --> 00:04:06.659
There's also in here the use of Org's tags

00:04:06.660 --> 00:04:08.274
here to the right of the title,

00:04:08.274 --> 00:04:12.040
very handy for searching for entries later.

00:04:12.040 --> 00:04:18.160
I use some Org properties attached to each entry.

00:04:18.160 --> 00:04:21.740
I automatically add in here an ID

00:04:21.740 --> 00:04:24.074
that can be useful if you want to

00:04:24.074 --> 00:04:27.800
link entries together later.

00:04:27.800 --> 00:04:30.400
I automatically add in here the date

00:04:30.400 --> 00:04:31.840
that the entry was created,

00:04:31.840 --> 00:04:35.699
which can be useful to me if things

00:04:35.700 --> 00:04:38.360
got sorted in a different order at some point,

00:04:38.360 --> 00:04:39.940
I could still look through

00:04:39.940 --> 00:04:42.507
the most recent entries that I had made

00:04:42.507 --> 00:04:45.040
if I wanted to do that for some reason.

00:04:45.040 --> 00:04:48.640
And sometimes I add in this publication year field

00:04:48.640 --> 00:04:52.720
with the idea that one day I might want to do

00:04:52.720 --> 00:04:55.840
a search for entries based on the publication year

00:04:55.840 --> 00:04:57.360
of the book or the article,

00:04:57.360 --> 00:05:00.774
say, only to use recent references

00:05:00.774 --> 00:05:03.080
or something like that.

00:05:03.080 --> 00:05:05.360
And then down here below the properties

00:05:05.360 --> 00:05:10.080
is where I paste in the URL to the webpage, or

00:05:10.080 --> 00:05:13.007
type in the title and author of the book

00:05:13.007 --> 00:05:16.959
on the pages, maybe the pages that were relevant,

00:05:16.960 --> 00:05:21.640
the pages of the periodical, or something like that.

00:05:21.640 --> 00:05:23.920
And I could put anything that I want down here,

00:05:23.920 --> 00:05:25.840
some other notes about what's important

00:05:25.840 --> 00:05:29.939
about this article to me.

00:05:29.940 --> 00:05:32.200
So fundamentally, that's all it is.

00:05:32.200 --> 00:05:35.240
Of course, I've added in a bit of convenience code

00:05:35.240 --> 00:05:37.080
to make this go a lot faster

00:05:37.080 --> 00:05:39.320
rather than typing all this out.

NOTE The Emacs Lisp code

00:05:39.320 --> 00:05:45.879
For that, I'll switch back to my init.el file.

00:05:45.880 --> 00:05:49.480
There's really just five functions.

00:05:49.480 --> 00:05:52.840
The first two here are ones

00:05:52.840 --> 00:05:54.560
that I've adapted off the Internet.

00:05:54.560 --> 00:05:56.160
Honestly, I can't remember

00:05:56.160 --> 00:05:58.239
exactly where that I got them from,

00:05:58.240 --> 00:06:00.240
but basically, they're just some functions

00:06:00.240 --> 00:06:04.240
for making a block of text writable or readable.

00:06:04.240 --> 00:06:09.299
Writable or not writable, I should say.

00:06:09.300 --> 00:06:12.200
The idea there is that

00:06:12.200 --> 00:06:13.480
when I'm creating a new entry,

00:06:13.480 --> 00:06:16.307
I don't want to accidentally delete

00:06:16.307 --> 00:06:18.960
or write over some earlier entries that I've made.

00:06:18.960 --> 00:06:24.880
So I use a little bit of Emacs functionality for that.

00:06:24.880 --> 00:06:29.440
And then here are the three reference functions

00:06:29.440 --> 00:06:32.440
that I've actually written.

00:06:32.440 --> 00:06:35.040
Really trivial, basic stuff here.

00:06:35.040 --> 00:06:41.800
The core of it is the `new-reference` function.

00:06:41.800 --> 00:06:44.840
Basically, what that does is

00:06:44.840 --> 00:06:47.560
it opens up the references file,

00:06:47.560 --> 00:06:52.040
jumps to the end of the reference file,

00:06:52.040 --> 00:06:57.440
starts a new entry, inserts the asterisk.

00:06:57.440 --> 00:07:01.520
It jumps back to the previous text,

00:07:01.520 --> 00:07:03.474
and whatever previous text there is,

00:07:03.474 --> 00:07:04.880
it makes that read-only.

00:07:04.880 --> 00:07:08.120
Again, so that I don't accidentally delete that,

00:07:08.120 --> 00:07:10.800
or cut, or type over it, or something

00:07:10.800 --> 00:07:14.579
when I'm making a new reference.

00:07:14.580 --> 00:07:17.680
Then it goes back to the new reference,

00:07:17.680 --> 00:07:21.339
automatically adds in a unique ID for that,

00:07:21.340 --> 00:07:25.360
and then automatically stamps it with

00:07:25.360 --> 00:07:28.999
the date the entry was created — today's date.

00:07:29.000 --> 00:07:32.760
Now, I've got two other functions here.

00:07:32.760 --> 00:07:34.540
One is `view-references`,

00:07:34.540 --> 00:07:37.807
which does nothing but open up the reference file

00:07:37.807 --> 00:07:39.400
and switch to that buffer

00:07:39.400 --> 00:07:42.539
if you're not already on it.

00:07:42.540 --> 00:07:45.880
And then there's one other here, `edit-references`,

00:07:45.880 --> 00:07:50.159
which does the exact same thing except for

00:07:50.160 --> 00:07:53.560
it also goes over all the text in the buffer

00:07:53.560 --> 00:07:55.040
and makes it writable.

00:07:55.040 --> 00:07:58.120
So if I really do want to edit those other references,

00:07:58.120 --> 00:08:02.719
I've got a function to quickly make that possible.

NOTE Example reference to Elfeed article

00:08:02.720 --> 00:08:07.499
Let me give an example of this.

00:08:07.500 --> 00:08:13.979
I type in here, new reference.

00:08:13.980 --> 00:08:16.440
Now I've jumped to the end of my references file.

00:08:16.440 --> 00:08:19.080
See, it's ready to take the title.

00:08:19.080 --> 00:08:21.720
Well, I guess I need to have something,

00:08:21.720 --> 00:08:23.659
some content, to put in here.

00:08:23.660 --> 00:08:28.879
Let's say I was looking through Elfeed,

00:08:28.880 --> 00:08:31.600
and let's say I found this interesting article

00:08:31.600 --> 00:08:38.219
about Mars earthquakes.

00:08:38.220 --> 00:08:40.007
Let's say I open it up [and]

00:08:40.007 --> 00:08:41.159
I read through the article.

00:08:41.160 --> 00:08:43.840
First, I'd figure out what it is

00:08:43.840 --> 00:08:47.259
that I find interesting about this, what it is that

00:08:47.260 --> 00:08:51.579
I'm going to want to remember and look up later.

00:08:51.580 --> 00:08:57.479
So I come up with a quick title based on that.

00:08:57.480 --> 00:09:01.899
Let's go back to the references with `view-reference`.

00:09:01.900 --> 00:09:05.674
And, let's just call it

00:09:05.674 --> 00:09:13.879
"Study of Mars Earthquake."

00:09:13.880 --> 00:09:18.199
Now I'm going to also want to put in some tags.

00:09:18.200 --> 00:09:21.107
On my system, that's done with

00:09:21.107 --> 00:09:23.639
Control C, Control Q (`C-c C-q`).

00:09:23.640 --> 00:09:25.520
And I can put in some tags.

00:09:25.520 --> 00:09:29.160
I like to go ahead and insert the colons.

00:09:29.160 --> 00:09:30.799
You can leave those out,

00:09:30.800 --> 00:09:32.560
but they're going to get added anyway,

00:09:32.560 --> 00:09:36.779
so I'm in the habit of using them.

00:09:36.780 --> 00:09:41.120
Let's say we'll call this 'Astronomy' as one tag,

00:09:41.120 --> 00:09:47.059
and the next tag could be 'Planets'.

00:09:47.060 --> 00:09:48.400
If I wanted to use a tag

00:09:48.400 --> 00:09:50.400
that was more than one word in the tag,

00:09:50.400 --> 00:09:53.540
I'd need to use underscores or something like that.

00:09:53.540 --> 00:10:00.499
If I wanted a tag that was 'Mars Earthquakes',

00:10:00.500 --> 00:10:05.059
I could do it like that, but that's kind of silly.

00:10:05.060 --> 00:10:08.659
Now I try not to be too clever with the tags.

00:10:08.660 --> 00:10:10.600
I don't spend a lot of time thinking about them.

00:10:10.600 --> 00:10:13.107
I just come up with some general buckets

00:10:13.107 --> 00:10:15.019
to throw things in.

00:10:15.020 --> 00:10:16.880
You can see the tags were added there,

00:10:16.880 --> 00:10:19.379
to the right of the title.

00:10:19.380 --> 00:10:23.399
Now you can see down here under PROPERTIES,

00:10:23.400 --> 00:10:25.320
the ID has already been added,

00:10:25.320 --> 00:10:27.040
the Date_Created has been added.

00:10:27.040 --> 00:10:30.200
Sometimes, I'll like to put in the publication year,

00:10:30.200 --> 00:10:38.139
and for that, I use the `org-set-property` command.

00:10:38.140 --> 00:10:43.439
Publication_Year, this year in this case.

00:10:43.440 --> 00:10:46.679
And then I just need to paste in the URL.

00:10:46.680 --> 00:10:48.080
I do that manually.

00:10:48.080 --> 00:10:53.480
I use Org's bracket format for that.

00:10:53.480 --> 00:10:57.639
So I start that, go back to the article,

00:10:57.640 --> 00:11:02.099
copy the URL, paste that in.

00:11:02.100 --> 00:11:04.480
If I want, I can add it in the title

00:11:04.480 --> 00:11:07.459
with the second pair of brackets here.

00:11:07.460 --> 00:11:14.200
Don't have to, but often like to.

00:11:14.200 --> 00:11:18.560
Close that off, and there it is.

00:11:18.560 --> 00:11:20.879
That was really it.

00:11:20.880 --> 00:11:22.120
I add a return on the end here,

00:11:22.120 --> 00:11:26.619
just so the next entry comes out with the right spacing.

00:11:26.620 --> 00:11:28.307
But really, that's it,

00:11:28.307 --> 00:11:31.000
and typically, when I'm not explaining it,

00:11:31.000 --> 00:11:37.499
that only takes 20 seconds or so, or 30 seconds.

00:11:37.500 --> 00:11:41.539
Pretty quick. Pretty easy.

NOTE Searching the references

00:11:41.540 --> 00:11:45.539
What about searching later?

00:11:45.540 --> 00:11:50.474
Well, often the easiest thing is just do a simple,

00:11:50.474 --> 00:11:54.639
boring incremental search.

00:11:54.640 --> 00:11:55.880
I usually know roughly

00:11:55.880 --> 00:11:58.499
what it is that I'm looking for already.

00:11:58.500 --> 00:12:02.379
If I was looking for that wildflower article,

00:12:02.380 --> 00:12:06.000
I could just do an incremental search for wildflowers

00:12:06.000 --> 00:12:07.920
and jump through that. It's pretty simple.

00:12:07.920 --> 00:12:13.200
Not very impressive, but honestly, most of the time

00:12:13.200 --> 00:12:16.439
that gets me there pretty quick.

00:12:16.440 --> 00:12:20.360
Sometimes I find it useful to do an Occur search,

00:12:20.360 --> 00:12:23.240
more specifically a Helm Occur search.

00:12:23.240 --> 00:12:31.259
If I use the `helm-occur` command,

00:12:31.260 --> 00:12:34.680
then I like to use this to search by tag.

00:12:34.680 --> 00:12:36.760
That's where it really becomes handy.

00:12:36.760 --> 00:12:39.207
Let's say I want to narrow it down

00:12:39.207 --> 00:12:42.640
to all my astronomy references

00:12:42.640 --> 00:12:50.039
and then narrow it down a little bit more to planets.

00:12:50.040 --> 00:12:54.119
I can put spaces in between and it still works.

00:12:54.120 --> 00:12:57.199
You can see here in one window,

00:12:57.200 --> 00:13:00.239
it gives me the bottom window there.

00:13:00.240 --> 00:13:03.479
It's giving…, just because of the way

00:13:03.480 --> 00:13:06.440
the tags are formatted with the title, it gives me

00:13:06.440 --> 00:13:09.519
a list of all the titles that have those tags.

00:13:09.520 --> 00:13:11.520
And I usually find what I want pretty quick

00:13:11.520 --> 00:13:13.400
by just tapping through here.

00:13:13.400 --> 00:13:16.499
Once I find the one that I think I want,

00:13:16.500 --> 00:13:24.139
I press enter, and now I'm focused on just that entry.

00:13:24.140 --> 00:13:26.960
There is some advanced functionality, I believe,

00:13:26.960 --> 00:13:29.960
that I used in the past where you could search

00:13:29.960 --> 00:13:33.119
based on the property fields.

00:13:33.120 --> 00:13:37.880
So do something like search for publication —

00:13:37.880 --> 00:13:42.439
the most recent publications in the last 10 years.

00:13:42.440 --> 00:13:46.200
There's some kind of advanced syntax for that,

00:13:46.200 --> 00:13:48.219
which I used once or twice.

00:13:48.220 --> 00:13:51.400
Honestly, I use that so infrequently

00:13:51.400 --> 00:13:54.840
that I have to go back to the Emacs manual

00:13:54.840 --> 00:13:57.739
and figure it out each time, and figure out again

00:13:57.740 --> 00:13:59.880
how I did that the last time.

00:13:59.880 --> 00:14:02.000
But since I do it only once

00:14:02.000 --> 00:14:06.679
every three or four months, it's not a problem.

00:14:06.680 --> 00:14:11.519
So I'm not going to go over that today.

00:14:11.520 --> 00:14:16.479
That's pretty much it in a nutshell.

00:14:16.480 --> 00:14:19.974
Again, the code that I wrote, this specific approach

00:14:19.974 --> 00:14:24.279
is not really what I'm recommending.

00:14:24.280 --> 00:14:31.160
But here it is if you really do want to use it.

00:14:31.160 --> 00:14:36.239
Maybe I can make a link to the URL

00:14:36.240 --> 00:14:40.059
and share that in the chat room or something.

00:14:40.060 --> 00:14:46.759
But I consider this to be trivial code.

00:14:46.760 --> 00:14:49.799
So just use that if you want to use it.

00:14:49.800 --> 00:14:53.440
I should be signing off here now.

00:14:53.440 --> 00:14:58.259
I should be in the chat room, in the IRC chat room,

00:14:58.260 --> 00:15:01.920
or you can reach out to me by email if you'd like.

00:15:01.920 --> 00:15:04.320
Thank you very much.