path: root/2023/captions/emacsconf-2023-ref--orgmode-workflow-informal-reference-tracking--christopher-howard--main.vtt

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.