Org-transclusion -- now on ELPA!

Thanks. I’m curious and this workflow seems to be a fruitful path; but can you elaborate a bit more, please?

M-x org-transclusion-select-source and M-x org-insert-link-dwim don’t currently exist, do they? I mean I know the former doesn’t :wink:

I don’t have dwim func in my Emacs. Is it a 9.5 addition?

What is GitHub UI? Is it the GitHub website for the source code where you can highlight a range of lines and copy a permalink URL to your clipboard?

Sure, those functions are not yet there. But I think it will be very useful to use the feature of the latest updates on org-transclusion.

Currently, if the user M-x org-store-link, with the mark on the paragraph, and M-x org-insert-link, it will generate things like this:

   [[file:daily/2021-08-01.org::Thanks for the updates!][demo]]

It seems to me, to transclude with a line number range, the user has to do it manually.


What we need to tweak the org-store-link are:

  1. only leave the file name

  2. detect line numbers from the select region

  3. insert the correct information that can be understood by org-transclusion

Here’s the idea workflow: capture from your video about 8 minutes.

Here’s what I mean GitHub UI:


1 Like

I see. Thank you. Let me think. Also… PR and/or extensions are welcome, too.

Hi Nobie:

Here’s a simple one:

(defun trival/org-transclusion-select-source (beg end)
  "Send transclusion information to kill-ring. See
    https://org-roam.discourse.group/t/alpha-org-transclusion/830/122"
  (interactive "r")
  (let ((lbeg (line-number-at-pos beg))
        (lend (line-number-at-pos end))
        (filename (concat "~/"(string-remove-prefix (file-truename "~/") (buffer-file-name)))))
    (with-temp-buffer
        (progn
          (insert "#+transclude: [[file:")
          (insert filename)
          (insert (format "]] :lines %d-%d" lbeg lend))
          (clipboard-kill-region (point-min) (point-max))))
    (message "A transcluded link has been sent to your kill-ring.")))
1 Like

Having a bit of trouble with transclusion. When I attempt to execute org-transclusion-add I get the No content found with "id: ...." message.

It also seems like org-id-find is returning the appropriate file. Strange.

:PROPERTIES:
:ID:       6f7881e4-95dd-4478-8d61-c09bd7953a5d
:ROAM_ALIASES: "TrxG"
:END:
#+title: Trithorax Group

The Trithorax group (TrxG) proteins are genetically antagonistic to [[id:6c67a648-09ab-4d01-9216-2d1cefee7a67][PcG]] proteins. They can remodel and modify histones, activating genes and keeping them active (cite:schuettengruber2017).

See [[id:f9dc09a3-8bdf-4b20-a4fd-365ddf71aa44][Composition and Evolution of PcG and Trx Complexes]]

#+transclude: [[id:f9dc09a3-8bdf-4b20-a4fd-365ddf71aa44][Composition and Evolution of PcG and Trx Complexes]]

#+begin_src elisp
(org-id-find "f9dc09a3-8bdf-4b20-a4fd-365ddf71aa44")
#+end_src

#+RESULTS:
: (~/Insync/<email>/gdrive/slipbox/20210806153439-composition_and_evolution_of_pcg_and_trx_complexes.org . 1)

Does it have any content in the pace ID points to, after the filter has been applied? It can be empty.

Not sure if you are referring to the contents of the linked file or the contents of the transcluded block?

Here is the contents of the linked file:

:PROPERTIES:
:ID:       f9dc09a3-8bdf-4b20-a4fd-365ddf71aa44
:END:
#+title: Composition and Evolution of PcG and Trx Complexes
#+filetags: figure

[[./images/schuettengruber2017_fig1.png]]

Fig. 1 from cite:schuettengruber2017

The transclusion fails when I try to run org-transclude-add:

Try adding (setq org-transclusion-include-first-section t). It’s nil by default.
Your file has content only before the first headline (so no content found). Refer to this section of README as well.

Ah, apologies - it works! Always a good idea to RTFM :grin:. Thank you!

No worries. I don’t adhere to RTFM, either. But I have tried my best for my README documentation – it can take longer than actual development (×1.5-2 is my estimate), so I’d appreciate your making use of it as well as the program itself :wink:

1 Like

It’s a really wonderful piece of software - thank you for all of your work on it!

1 Like

Thank you. Could I ask what is your primary use and how you use it? If you do not wish to write it in this public place, I’d appreciate a direct message or email (in the program header). I am trying to have a better feel of how people are actually using the package.

Sure - I’ve just started messing around with it but I can give a brief explanation for how I’ve started to use it. I’m starting a PhD so I am reading a lot of literature to come up with my thesis project. When I want to capture a figure from a paper, I put the link in its own org file, cite its reference, and add any commentary on the figure (like how skeptical I am of their data, etc.). Then, I can use org-transclusion to include that figure in multiple notes and view the figure in-line, and keep that commentary and the reference. Super helpful!

1 Like

Oh that’s a very cleaver usage. I like the fact you can have a figure, reference, and commentary separately and together at the same time; and then can just transclude the figure only in some other places…

Thank you.

1 Like

Is it possible to copy the headline related with the org-id only ? When taking note , I wanna keep the main idea in the headline and use org-transclusion to sync it. :revolving_hearts:

Yes, Org-transclusion copies the whole subtree identified by an Org-ID. You can exclude sub-headlines if you really want just the top headline level for an ID. I suggest that you refer to README of the repo for detail.

1 Like

Org-transclusion is now available on ELPA!

Thank you for contributing your ideas and participating in discussions. And if you are a user, thank you for using it.

Functionally, it has been stable. As I publish it on ELPA, I released it as version 1 and declare that it’s out of “alpha”. Yay!

Next step, I’ll work on documentation (it still says it’s NOT available on ELPA but it is :blush: ) and try to address issues around org-element’s cache (for Org v9.6).

If you are using it, I’d love to know your feedback and how you use it in your workflow.

Also… If you are interested in maintaining it (or contribute to its source code), let me know… I don’t really know what to expect as it is my first open source project and very first package I publish in such a public place. I guess it will be an enjoyable learning experience together…

7 Likes

Are there any attempts at creating a digital interface emulating a physical Luhmann slipbox? I think cards being “before and after” one another is something we are sorely missing in org-roam, and having something like that would be very nice. For instance, right now it’s hard to make ‘anonymous’ notes; some concepts cannot be named, like certain theorems in math. But anonymous notes would be of value if they were before or after certain notecards, with context generating its value.

I tried to do this with a bunch of windows (e.g. 4 horizontal windows) that scroll through the slipbox, but it seems org-transclusion is a much better alternative for implementing something like this.

Slipbox with buffers:

Slipbox with org-transclusion (needs more work like hiding transcluded blocks to just title, etc.)

EDIT: Is the imgur link (first gif) not working for others?

didn’t work for me
but I just opened its url

1 Like

Love your work Nobiot. I’m just figuring out how to incorporate transclusion into my processes now. I would like to second the ability to include notes without the top heading. Here are my current experiences just to add to the discussion.

At this stage it seems that :only-contents is the best way although it also removes any nested subheadings (but keeps their content). So for the moment that just means that I need to transclude each heading separately.

The benefit of adding the headings manually in the destination file is that it seems that they play better with moving other headings around an org file. For example, if I transclude Heading C into this structure, and then use org-metaup to move Heading D above Heading C then Heading D disappears.

* Heading A
** Heading B
** Heading C 
This line of text, and it's heading, have been transcluded in.
** Heading D

The other benefit of using :only-contents is that it lets me add more notes that make sense within this destination document’s heading, but would not make sense within the source document if they were included within the transclusion.

*Fruits I like.
** Apples.
** Bananas
This line of text is my test single line of transcluded text and will always only be one line because I said so here in my source document.
Bananas are my favourite.
** Cranberries.

So… that’s my experience. Right now I’m just testing, however its use makes a lot of sense.