Transcluding org-babel blocks...not so much ;)

I’ve not seen this mentioned in the YT howto videos so perhaps I’m the first one who has tried to transclude Org Babel blocks. Doesn’t work so well. Not sure it could. I’ll describe the use-case and results below.

I do a lot of technical writing along the lines of what is described in Literate DevOps. So I thought it would be super to have an Org Roam node for each of the pieces of server software I’m using regularly which include startup and teardown subsections with Org Babel shell code blocks where I start/stop the service in Docker Compose.

Then I also have what I’ll call scenario docs where I document particular configurations for said software. Figured I’d transclude in startup/teardown tagged with :noexport:, write the scenario content, and then export to other formats…usually Markdown.

This no worky. Because when you transclude the code block in and execute it will try to update the #+RESULT: but that entire part of the transcluding document is in read-only mode. “Text is read-only”. Now, I could use the keyboard shortcuts to quickly jump to that block in the transclude source doc but that’s kinda not an ideal workflow.

So that’s it. I’m not necessarily saying its a bug or it needs fixed. Just an observation about the current state of interaction between org-transclude and org-babel and my too-clever-by-half attempt at re-using content.

I’d appreciate if you could explain your use case in a bit more detail.

If you transcluded lines of code directly like this, instead of Org text and source blocks together, there is no problem – like this below.

#+transclude: [[file:python-1.py]]  :src python :rest ":results file"

I developed Org-transclusion more for writing, not for technical documentation – I am no developer and don’t write technical documents with code embedded. So it would be great if you could help me understand the friction the current implementation causes. I cannot promise I will be able to fix it but at least I can have your use case in mind for the next iteration.

Embedding directly from the source felt to me a more intuitive approach. What’s the benefit of transcluding source code from one Org file into another?

I appreciate the eyes-on. I’ll give that transclude method a try and see how that works out. Also, let me put together a couple of example files that make the use-case a bit more concrete.

Like I said I’m not even sure I’d make the case that Org Babel code blocks and transclude should work the way I’m trying to use them. It’s been more about seeing how far I could push the re-use thing as might be enabled by Org/Org Roam/org-transclude. Outside of Literate DevOps I’m also working with a team that is doing some more traditional non-technical content but relies on a backend database during static content generation. Maybe more on that later. That use-case ends up being pretty similar to the tech-writing use-case.

I think the examples I’ll cook up will probably shed some light on the motivation for why one might even attempt to do what I’m attempting as well.

1 Like