This post started as a place for me to perform analaysis on my existing blogging ecosystem. The goal is to consolidate where I’m “storing” information. The strategy is moving elements of my blogging ecosystem into my Personal Knowledge Management (PKM 📖) system; and then exporting those back to my blog.
Writing to Think Through the Problem
At present I store my glossary in a YML file. Table 240: Take on Rules's Glossary Entity Attributes describles the attributes.
| Attribute | Status | Description |
|---|---|---|
| abbr | Optional | A short-hand means of referencing the entity; it’s abbreviation |
| auto_mention | To Remove | Used by `glossary:autoMention` rake task |
| content_disclaimers | Optional | Connects this entry to a content disclaimer |
| described | To Remove | Have we already described this node; useful for preventing repeat querying of Wikidata |
| description | Optional | A terse explanation of the entry; often imported from Wikidata |
| game | Optional | Indicates the entry is a game; the value should be the entry’s key |
| itemid | Optional | A URL that disambiguates this entry ; From https://schema.org |
| itemtype | Optional | Further specification on the classification of this entry; From https://schema.org |
| key | Required | How we programatically reference this entry |
| mention_as | Optional | When we add a mentionAs attribute use this value; From https://schema.org |
| offer | Optional | The URL from which you can buy the item; From https://schema.org |
| plural_abbr | Optional | The plural form of the abbreviation |
| plural_title | Optional | The plural form of the title |
| same_as | Optional | Connect the item to a more verbose description (e.g. a Wikipedia article) |
| tag | Optional | When used as a tag, add a "mention" node |
| title | Required | How we linguistically reference this entry |
| verbose_title | Optional | A more expressive title |
Considerations for Migrating Glossary into Org Ecosystem
What would it look like to move the glossary into my Org ecosystem?
Let’s consider the following:
- What would be the benefit?
- What would be the storage strategy?
- How to map the YAML entry to the Node’s data structure?
- What are the ways in which Take on Rules references the glossary?
What Would be the Benefit?
The primary benefit that I see is in consolidation. Right now the benefits of the glossary are only available in my blogging ecosystem. And the “capture” process for those entries is outside of my normal capture process.
Further, in consolidation there is the process of thinking through the “problem” and designing a solution. The very thought exercise itself is enriching.
What Would Be the Storage Strategy?
I see two options: ./glossary or ./refs. The advantages of ./glossary is crisp demarkation. However I envision “promotion” or “drift” of refs into glossary items.
- Decision
- Store nodes in
./refsand add tag:glossary:
How to map the YAML entry to the Node’s data structure?
There is an analogy between my Epigraphs and my Glossary setup. An Epigraph has properties and it’s textual content (see Even if you decide never to write a single…).
In the case of a Glossary entry, the body of the node would be my additional notes. The node’s #+title: line would be it’s title property.
What Are the Ways in Which Take on Rules References the Glossary?
The following short-codes, part of the TakeOnRules Hugo Theme reference the glossary data:
themes/hugo-tufte/layouts/shortcodes/blockquote.html- when quoting a game, I add a purchase link to the citation.
themes/hugo-tufte/layouts/partials/header/contentDisclaimers.html- when a post has a glossary tag that has a content disclaimer, I look that up.
themes/hugo-tufte/layouts/shortcodes/glossary.html- this is where the major heavy liftin occurs; a glossary entry can be an abbreviation, mention, link, etc.
themes/hugo-tufte/layouts/_default/list.html
:
themes/hugo-tufte/layouts/_default/single.html
:
My assumption is that I would generate the ./data/glossary.yml file from my Org ecosystem.
To continue to leverage the ./data/glossary.yml as-is I would want to have means in my Org ecosystem to declare each of these.
Design
There are two major design considerations:
- Registering New Link Types in Org-Mode
- Data Migration
Registering New Link Types in Org-Mode
Org-Mode 📖 has different link handlers. One example is the roam: scheme; a scheme added by Org-Roam 📖.
The org-link-set-parameters exposes a means of registering new schemes.
I have two “links” that I want to add: abbr: and abbr-plural:. The goal is to use my glossary to “link” to an entry that has an abbreviation and then at the point of export expand that abbreviation.
Reading the org-link-parameters documentation there are functions I want to set for both abbr: and abbr-plural::
:complete- What are the possible entries I have that meet the criteria? (e.g. have an abbreviation?)
:export- When I export this link, what should logic should I use? (e.g. for HTML 📖, I should use an ABBR-tag, for other things the
title (abbreviation)is perhaps best) :follow- When I “click” on the link in my Org-Mode document, how should it resolve? Where should it go?
Data Migration
I want to export my ./data/glossary.yml to Org-Mode. There are some glossary entries that already have nodes in Org-Roam; for those I need to reconcile and adjust. For the others, I need to create a node for each glossary entry.
Once that is complete, I will stop adding and editing entries in ./data/glossary.yml; instead I will export them from my org repository to that file. An ideal test is that when I complete the round trip, my ./data/glossary.yml is unchanged.
I already do this for Epigraphs, so follow a similar “public” api process.
Conclusion
After a bit of time and exploration, I have enriched my understanding of the Org-Mode / Org-Roam ecosystem and further worked towards treating my blog as a “consumer” of my PKM system.
I’ve also solidified my love of cl-defun, &key parameters, and providing defaults. This helps me repurpose functions and think about their interactions. It’s a pattern I’ve also applied in my Ruby code.
An example perhaps? The following is a method signature: (cl-defun jf/org-roam-external-url-for (&key node (scheme "http"))
To call that method I write the following: (jf/org-roam-external-url-for :node the_node); where the_node is an Org-Roam node. By default I’m looking for URLs that start with the http scheme.
Instead of burying the default http in the method definition, I parameterize it and specify the default.
All of this is in service to sharpening my tools.