Org-transclusion -- now on ELPA!

[gcoladon]

First off, thank you @nobiot for creating this cool package, and secondly thank you for spending time to help me debug my use of it

@nobiot

Try this to see if you get a marker returned.

(org-id-find "210504_080047")

LOL, not only do I not get a marker returned, but I guess I have some other issue I need to resolve as well

(error "Invalid value of ‘org-agenda-files’")

OK now that the issue of an extra apostrophe has been resolved (and all of you now know my secret, that I am too far behind on my agenda to have tried using it lately ), now org-id-find actually works, and the transclusion works as well. I probably also have problems with not all of my IDs being registered with org-id, but I don’t believe the underlying reason in this case was that reason? Is it possible that org-id-find failing with an error would produce the observed error message from org-transclusion? I have not tried putting the error I had back, and stepping through the org-transclusion code to see how that error is raised and handled.

[gcoladon]

As an aside, when I type the word transclusion, my browser (Brave on MacOS) underlines it as if its a typo:

despite the fact that when I right click it and choose “Look up transclusion”, I get a definition for it…

Go figure …

[nobiot]

@gcoladon

I probably also have problems with not all of my IDs being registered with org-id

Try this to fix the registered IDs
(org-id-update-id-locations (org-roam--list-all-files))

@gcoladon

Is it possible that org-id-find failing with an error would produce the observed error message from org-transclusion ?

Yes. It’s not an error in the program. The function simply returns nil.

For an ID link, Org-transclusion tries org-id-find, and if nil gets returned, it will still continue the program at the moment. It will find no content of course, and gets you the error you observed in a different place in the program. At least this is a plausible program flow. I think I will update the code and catch the org-id-error to provide a more relevant message for Org-ID. It’s one of the most frequent issues for support now

[nobiot]

@gcoladon

As an aside, when I type the word transclusion, my browser (Brave on MacOS) underlines it as if its a typo:

My understanding is that Chromium browser (which Brave is built on) uses dictionaries from the hunspell project (lost a link, but you can get to the public directory within the chromium project). The English dictionaries there (variations exist) need updating

[sva]

Thanks a lot. That was an easy fix.

[gcoladon]

@nobiot

I think I will update the code and catch the org-id-error to provide a more relevant message for Org-ID. It’s one of the most frequent issues for support now

Good idea – you might even want to include this code snippet in your error message, so it’s there in the *Messages* buffer for people to directly evaluate

@nobiot

(org-id-update-id-locations (org-roam--list-all-files))

[wuqui]

Hey, thanks again for this amazing package as well as your great documentation and support efforts!

A small question here because I it probably doesn’t deserve a dedicated GitHub Issue: Is it possible to transclude a heading section without transcluding the heading itself? Or specifying a different heading title at least? I usually want to transclude subtrees since that’s much more practical than paragraphs, but very often these need to have a different heading in the new context.

And another small comment: The marks on the fringes are almost invisible on my Doom standard themes (one: light & dark), neither on the Solarized themes. They are simply way too narrow. Is there a way I can customize that?

I found the following variables in the readme, but I can’t seem to edit these.

* org-transclusion-source-fringe
* org-transclusion-source
* org-transclusion-source-edit
* org-transclusion-fringe

[nobiot]

@wuqui,

I think it would have been a good GitHub issue; but it is fine here, too. No stress

@wuqui

Is it possible to transclude a heading section without transcluding the heading itself

At the moment, Org-transclusion does not have an out-of-the-box way to do this. I realise #+include has content-only option for it. I am not using its logic, so for me, it would require re-engineering / re-factoring of the whole copy engine – at least, that’s my gut feeling before investigating any further.

I might consider this, though. I was not good a reading the code back when I started writing Org-transclusion. #+include is in ox.el and it’s not necessarily written in a composabile way for me to borrow parts of it. I will think about how I might go about this idea – I am thinking this re-factoring might help Org-transclusion as a whole.

Re the fringe not visible on Doom, please have a look at my comment on this GH issue. In it, I am suggesting to make use of the custom faces: org-transclusion-fringe and org-transclusion-source-fringe. They should give you something like this:

I will appreciate it if you can try these custom faces and let me know if it works for you or not.

[gcoladon]

@nobiot

Re the fringe not visible on Doom, please have a look at my comment on this GH issue . In it, I am suggesting to make use of the custom faces: org-transclusion-fringe and org-transclusion-source-fringe . They should give you something like this:

I couldn’t see the fringe on my transclusions in Doom either, so I’ll try this too to see if that makes them visible.

[gcoladon]

That worked like a charm! And, it was the first time I ever tried customizing a face.

Thank you for creating this package @nobiot , I look forward to coming up with ways to make use of it.

[wuqui]

Regarding sections without headings: Thanks for considering it! I do think it would be very advantageous to leave control of the headings to the target buffer. Besides the actual phrasing of the headine, this would make sure you can control things like tags and header properties of the transcluded elements depending on the target context. The point of transclusion to me is to use certain snippets in different contexts, so this flexibility would be great.

Regarding custom faces: Thanks for this tip! I have never used custom faces before, so that’s also why I didn’t know how to change these. I was looking for variables with those names and couldn’t find them. Could you maybe give me an example of a code snippet I could use in my config? I’ve googled it, but I can only see how I would do this using ‘customize’ and I try to not use that but put everything in my config because it seems more robust/reproducible to me. I think that might also be great for the Readme since there should be quite a big Doom community among org-transclusion/org-roam users.

By the way, I like the new version. Good job!

[nobiot]

@wuqui

I like the new version. Good job!

Thank you

@wuqui

Could you maybe give me an example of a code snippet I could use in my config? I’ve googled it, but I can only see how I would do this using ‘customize’ and I try to not use that but put everything in my config because it seems more robust/reproducible to me

I tend to use M-x customize-face but with Elisp, something like this?
I think the color (where “green” is) can be like “#62c86a” (hex RGB, I guess?).

(set-face-attribute
 'org-transclusion-fringe nil
 :foreground "green"
 :background "green")

[wuqui]

@nobiot

I tend to use M-x customize-face but with Elisp, something like this?
I think the color (where “green” is) can be like “#62c86a” (hex RGB, I guess?).

(set-face-attribute
 'org-transclusion-fringe nil
 :foreground "green"
 :background "green")

That’s perfect, thanks a lot! This improves the user experience quite significantly, actually

[arozbiz]

Another benefit of sections without headings is that would enable linking directly to paragraphs through IDs (as long as the heading only has one paragraph). Related to this: Linking to a paragraph with an ID link · Issue #66 · nobiot/org-transclusion · GitHub.

[nobiot]

Please be notified of upcoming (breaking) changes and new features of Org-transclusion.

• The breaking changes are not big and should not cause major issues.
• The new features include :only-contents support – stripping off headline titles (screen shot in the GitHub issue below)

Any questions, let me know.
Thank you.

⚠ NOTICE: Upcoming breaking changes and new features with v0.2.0

[nobiot]

New video is up today.

v0.2.0 adds :only-contents and :exclude-elements properties per transclusion

Org-transclusion (alpha v0.2.0) Demo #8

[nobiot]

Have a look at the latest v0.2.0. With the :only-contents property, you should be able to achieve “directly linking to paragraphs”. Let me know how you go.

@wuqui you should also be able to do this now

@wuqui

Regarding sections without headings : Thanks for considering it! I do think it would be very advantageous to leave control of the headings to the target buffer. Besides the actual phrasing of the headine, this would make sure you can control things like tags and header properties of the transcluded elements depending on the target context. The point of transclusion to me is to use certain snippets in different contexts, so this flexibility would be great.

[wuqui]

Ah, cool that you’ve implemented this already. Great

I was originally just referring to the one heading that the link is targeting, but I guess one might be able to just exclude this one and show all the others using the new options, right? Anyway, thanks!

[nobiot]

v0.2.1 is merged with main today 2021-08-01.
This update adds new features for source and text files.

Org-transclusion (alpha v0.2.1) Demo #9

[cool_ran]

Thanks for the updates!

I think the feature of transclusion with a specific line number the range can be improved by writing a selecting function from the source.

On the source file, the user selects a region, M-x org-transclusion-select-source. Then, goto to the org-mode buffer, M-x org-insert-link-dwim, everything is done. Pretty much a similar experience with GitHub UI.