transclusion minor-minor mode

work in progress in progress.

basically a trimmed down version of emacs-freex mode’s embedding mechanism

made primarily to work with org-mode files

what it’s supposed to do

playground

also see

using org dynamic blocks

http://stackoverflow.com/questions/15328515/iso-transclusion-in-emacs-org-mode

http://stackoverflow.com/a/15352203

(defun org-dblock-write:transclusion (params)
  (progn
    (with-temp-buffer
      (insert-file-contents (plist-get params :filename))
      (let ((range-start (or (plist-get params :min) (line-number-at-pos (point-min))))
            (range-end (or (plist-get params :max) (line-number-at-pos (point-max)))))
        (copy-region-as-kill (line-beginning-position range-start)
                             (line-end-position range-end))))
    (yank)))

Then to include a line range from a given file, you can create a dynamic block like so:

C-c C-x C-u (org-dblock-update) will on the BEGIN/END block updates that block; org-update-all-dblocks does all in the buffer.

This is an unsatisfactory solution because it is actually just unidirectional quasi-dynamic inclusion; quasi, because the update step has no knowledge of the target until the update is invoked. It is possible to add action hooks to run updates automatically, but that is no different from export-time inclusion, which by nature assumes a unidirectional flow of information. Org already has a number of ways to achieve this, such as a sh src block that runs cat.

Transclusion is different in practice: it is the actual content, appearing at the location of transclusion.

John Kitchin’s version (requires org-mode 9)

see transcluding-org-elements.org

using org-mode MACRO syntax instead of INCLUDE

with org macros this seems to be a better option.

see https://github.com/fniessen/org-macros/blob/master/org-macros.setup

To test this, run the org-mode export process (e.g. C-c C-e then h H or t A), then find the text from LICENSE exported as well.

TODO: figure out how to make this org-compatible. Right now it is trivially easy to cause export-time conflicts due to eval

org-mode export interop test

using org’s native macro facility in normal org export

partial transclusion

{{{transclude(LICENSE,60,500)}}}

the whole thing

{{{transclude(LICENSE)}}}

transclusion addressing syntax

primary consideration is edit-time user friendliness;

for accuracy, fuzzy text anchors should be used

full

{{{transclude(file:tiny.org)}}}

line

{{{transclude(file:tiny.org:5)}}}

line range

{{{transclude(file:tiny.org:2-3)}}}

from start

{{{transclude(file:tiny.org:-2)}}}

until end

{{{transclude(file:tiny.org:7-)}}}

character index range

character range

{{{transclude(file:tiny.org:0,100)}}}

from start

{{{transclude(file:tiny.org:,100)}}}

until end

{{{transclude(file:tiny.org:50,)}}}

percent range

convert to line first

{{{transclude(file:moozorgjs.org:1%-3%)}}}

contextual target

native org links

{{{transclude(file:tiny.org::*decoy 1)}}}

exact match with range

{{{transclude(file:tiny.org:in 2101…for great justice)}}}

fuzzy file resolution -> org

these should all resolve to

huh

glob file name

{{{transclude(file:t*ny.org::*huh)}}}

fuzzy find file by name

{{{transclude(file:?tiny+.org::*huh)}}}

fuzzy find file by content

{{{transclude(grep:gg+you::*huh)}}}

{{{transclude(grep:gg you::*huh)}}}

{{{transclude(grep:gg%20you::*huh)}}}

constriction syntax

a better term than constriction / constrictor probably exists

the $constrictor should fallback to resolution logic of the colon-based content address when no constriction method is found

content based range constriction

address like:

file:$RESOLVER#$constrictor

where $constrictor …

examples using moozorgjs.org

nearest token set (fallback)

$RESOLVER#handling todo

resolve to Handling TODO

via first + best sequential match

token set range (fallback)

$RESOLVER#in 2101…for great justice

line: nearest statement / line

possibly just L

$RESOLVER#line/support+scheduled

resolve to the line,

“Support attributes like SCHEDULED:.”

Implement todo attributes

para: nearest paragraph

possibly just P

$RESOLVER#para/org.js parser converter

intro paragraph

intro paragraph

section nearest hierarchical section

need org context

$RESOLVER#section/web browser

Web Browser

Web Browser

??? nearest conceptual unit

hardest – need broader semantic analysis

$RESOLVER#unit/require org

require(“org”)

the src block with “require” within

Node.js

decoy headers

real thing

decoy 1

text in the real

fake thing

decoy 1

text in the fake

what does org do?

(org picks the first occurrence)

decoy 1 (real)

decoy 1 (fake)