Org Real

Table of Contents

Building an ascii layout manager in elisp was difficult, to say the least.


Figure 1: Opening real links

I was really motivated by the positive feedback I got for the box drawing logic and pushed myself through the final roadblocks to getting an minimally viable product out to the masses.

I'm releasing the alpha version of org-real today.

What is it?

I'm not exactly sure myself. At an abstract level, what this package does is take a one-dimensional description and render it as a three-dimensional ascii drawing. This is similar to how communicating locations of things in real life works: the knowledgeable party forms a one-dimensional sentence that describes a thing and the receiving party forms a three-dimensional image in their mind. This mental image arranges the nouns from the sentence according to the prepositions surrounding them.

Hence, why I've named it org-real.

Supported prepositions

The list of supported prepositions is foundational to the package. Each preposition is handled differently in the drawing process, so it's quite difficult to add a new one.


Figure 2: Available prepositions

However, aliases are relatively easy and I already have one: "in" and "on" are handled the same way. I also have plans to add "on top" which will work similarly to "in front". Feedback and suggestions in this area would be greatly appreciated.

A real link

The real:// url scheme was based on the http:// scheme with some differences.

There is no "host" component; all components in a real URL are treated identically and are called containers. Each container can have a query string, whereas the http scheme can only have one query string at the end of a URL. And finally, spaces are allowed in component names.

real://bathroom cabinet/third shelf?rel=in/razors?rel=above/toothbrush?rel=to the left of

Real links are read from the most general to the most specific, so in this example the bathroom cabinet is the top most component and has a child third shelf with a relationship of "in". The relationship query parameter is in regard to the container immediately to the left, so this tells org-real that the third shelf is in the bathroom cabinet.

Completing read

One of the most interesting emergent properties of real links is composability. I realized that if a link is completed in reverse, from the most specific to the most general, all the context from an existing link can be added to the completion. For example, if you already know that the car is in the garage, adding a link to the air freshener in the car will automatically add the extra context of being in the garage.


TODO ERT tests

The test files are in org-mode right now and can only be evaluated visually. I'd like to run E2E and unit tests using ERT to enhance the continuous integration pipeline.

DONE Editing links

It should be possible, when editing a link, to replace all occurences of containers that have been edited in the current buffer. For example, if you move the car out in front of the garage, the air freshener should also be updated with the new context. I plan on adding a prompt to allow a user to do just that.

DONE New preposition: on top of

DONE Customizeable padding and margin

The padding and margin variables only work at their current values because I've obviously hardcoded it in some places without realizing it. I'd like to allow users to space out their things as desired by customizing these two variables.

TODO Stylizing boxes

The query string for each container is extensible and arbitrary style properties can be specified. One limitation is that the background color can't be set (to my satisfaction) because the box drawing caharacters are placed in the middle of a character, so there will always be a bleed around the box.

I want to see how people use this package and how I use this package in my daily life before deciding which styling properties should be added.

SOMEDAY Merge into org-mode

This is the ultimate goal; to become a contributor to the org mode project and hopefully continue to enhance emacs in any way I can.


I love challenges, and building this package presented more than a fair share. I hope to get as much feedback as possible to see how people decide to use org-real. I'm curious if most will stick to actually describing real things or maybe create abstract diagrams for some other purpose!

Postscript: Call for help

I've tried to make the codebase as accessible as possible, but it is a little dense. I have some implementation questions I'd love to bounce off of other elisp developers and plenty of bugs and features to delegate. Please contact me through gitlab, the System Crafters Discord, or at tylergrinn@gmail.com.