jorana.org

jorana.el - Reverse Literate setup using org-transclude.

Overview:

About the name:

Jorana is an english approximation for the Hindi word meaning to connect, interweave, join, unite. And yes, this is the only Hindi word I know about.

Rational:

There are downsides to the standard literate style config:

• Colaboration.
• need to have all code in file to tangle.
• eventually with a big enough project, tangling can get a little slow.
• testing can be tricky.

jorana.el is my attempt to remedy that a bit, using the excellent org-transclusion package.

Variables

workflow:

Transient magic interface

writing new code from org narrative

One of the neat things of literate programming is that you can structure your code the same way as you think about it. Or really any way at all.

And it makes it straight-forward to remember how to set up the project, and writing a blog post of your work happens “for free”.

Something I want to be as quck and seamless as possible is adding new code and linking code from the narrative.

Including already written code from org narrative

• for finding: find-and-insert-transclusion find-file -> consult-line -> include and activate transclusion

This will tag the line with an id so that the link doesn’t break on renames or refactorings.

the magic happens mostly here:

modify name extraction to not include ID

in org-transclude pull request, target navigation

say in your source you have this:

(ns (:require
   ,,,
;;matrix  ;<id:1673570549>
   [tiltontec.cell.core :refer [cF cF+ cF_ cI]]
   [tiltontec.cell.observer :refer [fn-obs]]
   [tiltontec.model.core :refer [mget mset! mswap! fm*] :as md]
   [tiltontec.flutter-mx.core :refer [as-dart-callback] :as fx]
   [tiltontec.util.base :refer [dprn dp dpx]]
   [tiltontec.cell.base :refer [cinfo minfo] :as cty]
   [tiltontec.cell.integrity :refer [with-integrity]]))

the ideal target is going to be the first sexp under the id, but in this:

(ns (:require
   ,,,
   [tiltontec.cell.core :refer [cF cF+ cF_ cI]]
   [tiltontec.cell.observer :refer [fn-obs]]
   [tiltontec.model.core :refer [mget mset! mswap! fm* #_(<id:1673571805>)] :as md]
   [tiltontec.flutter-mx.core :refer [as-dart-callback] :as fx]
   [tiltontec.util.base :refer [dprn dp dpx]]
   [tiltontec.cell.base :refer [cinfo minfo] :as cty]
   [tiltontec.cell.integrity :refer [with-integrity]]))

The ideal probably would be [mget mset! mswap! fm* #_(<id:1673571805>)].

but why not allow a Navigator lambda? Then the world is your oyster as they say. TODO ^ as org-transclusion pull request

At code, want to include into narrative

Say I’m already looking at code or writing code in some file. I want to be able to instantly transclude the thing at point into the narrative.

Probably want it to default to last point in the narrative, and have org-refile style navigation ready to go.

Better yet, use recursive-edit so that the user can navigate however they like.

jumping hither and yon

say you have a src block like so with your cursor after the 'w':

(defn hello-world ()
   (message "Hellow| world!"))

I want to be able to instantly jump back and forth from the source. So:

Getting the relavant transclusion info is a bit convoluted at the moment; this could use a refactor…

converting existing literates to jorana

easiest route: Add id, and end line to match

trickier: count THINGS in range and only add id on top

things:

update links to ids.

• test if link is dead
• search project for id

allow new heading creation when tc is open

detect comment type from major mode

custom variables for auto-jump-on-edit

magically transclude remote when narrative does not yet have tc added

auto-jump-on-edit could mirror the mark for better translation of intent

inferred narrative file from followed id lookup

transient: adjust COUNT of things at point

file-at-point

select range and transclude, inserting markers or counting things

transcluding from other org files

Modify transclusion at point – change target

Expand hidden region on jump

implimentation details:

writing an emacs package:

This is my very first emacs package.