Org Real
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:// protocol was based on the http:// protocol 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 protocol 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.
Roadmap
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.
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.
New preposition: on top of
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.
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.
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.
Conclusion
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.
[ comments ]