In Praise of Recfiles

Recfiles let you write and check plain-text notes. They look like this:

%rec: Book
%key: slug
%sort: year month

slug: thinkingexperience
author: H. H. Price
title: Thinking and Experience
year: 1953
publisher: Harvard University Press, Cambridge

slug: yugocaves
author: Dr Neven Krešić
title: Karst I Pećine Jugoslavije
year: 1988
publisher: Naučna Knjiga

slug: metaphysicscontemporaryintro
author: Michael J. Loux
title: Metaphysics: A Contemporary Introduction
year: 1998
publisher: Routledge, London

This ability to write-plain text notes without a 'gotcha' seems strangely rare. Writing the same format in .csv? That won't work for this entry:

Harvard University Press, Cambridge

The comma indicates a new cell, and 'Cambridge' will be transferred to something else, creating a cascade of misinformation. You might switch to putting everything in double-quotes, so your CSV will look like this:

1"thinkingexperience","H. H. Price","Thinking and Experience","1953","Harvard University Press, Cambridge"

But that brings up more 'gotchas': a lot of programs will keep those quotes when processing the CSV, and you can't use the double-quotes inside the field. People use double-quotes a lot, so that's an accident waiting to happen.

Many use json for plain-text data, and it's fine for a lot of structured data, but the reliance on double-quotes means the same problem again, and a few new ones which mean nobody can realistically type out information in json. Look at all those double-quotes you'd have to type if you actually used this format:

 1[
 2{
 3  "slug": "thinkingexperience",
 4  "author": "H. H. Price",
 5  "title": "Thinking and Experience",
 6  "year": 1953,
 7  "publisher": "Harvard University Press, Cambridge"
 8}
 9{
10  "slug": "yugocaves",
11  "author": "Dr Neven Krešić",
12  "title": "Karst I Pećine Jugoslavije",
13  "year": 1988,
14  "publisher": "Naučna Knjiga"
15},

Seems a shame to use something nobody can actually use when it's not necessary. Did you spot the mistake? There's a missing square bracket. The square brackets don't indicate anything about the books - they're non-functional, but they're standard in json, so you need to get them right. Also, the last entry doesn't end in a comma. This last comma also doesn't tell you anything about the books - it only tells the machine that this is not the last item on the list.¹ Recfiles are clever enough to count which items are in a set without anyone telling them which one is the last one, and without any square brackets.

Then there's yaml. It'll let you write easily enough in single file:

 1- slug: thinkingexperience
 2  author: H. H. Price
 3  title: Thinking and Experience
 4  year: 1953
 5  publisher: Harvard University Press, Cambridge
 6- slug: yugocaves
 7  author: Dr Neven Krešić
 8  title: Karst I Pećine Jugoslavije
 9  year: 1988
10  publisher: Naučna Knjiga

Unfortunately you can't transfer that information to other yaml files until you've checked the indentation levels of the file they're coming from, then the file they're going to. Also this isn't proper yaml according to all versions, and each tool uses a different version. Sometimes they'll require quotes around words, sometimes they don't.

With recfiles, the relationships between data is just stated at the top. So another recfile might contain lists of essays, including a link to these books:

%rec: Essay
%type: reference rec Book

title: Metaphysics ain't Physics
subject: Philosophy
date: Sun 28 Jun 11:25:27 CEST 2027
reference: thinkingexperience
reference: metaphysicscontemporaryintro
reference: pluralityworlds

That's enough for recfiles to link the essay's references to their publisher and year of publication.

So far I've found only a single gotcha with recfiles: they only process a single relation. Once you join essays to their reference, that's that - you can't make notes about the Philosophy class they're attached to.