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.
