nobiot
:level auto and :no-initial-heading
I have written some changes in my local copy of org-transclusion, to add two keywords :level auto and :no-initial-heading, and they work pretty well.
I won't know when I will have the FSF assignment done, so I can't submit a PR, but the amount of lines to write is pretty small:
- To implement :level auto:
1 file changed, 23 insertions(+), 15 deletions(-) - To implement :no-initial-heading:
1 file changed, 19 insertions(+)
OK, so what do these keywords do?
First, maybe I should explain my use-case. I made the package org-node which replaces org-roam, and it ships two convenience commands org-node-insert-transclusion and org-node-insert-transclusion-as-subtree. Source.
Why two commands? Because I heavily use subtree nodes. I get the impression that org-transclusion was made initially with single-file nodes in mind, and its behavior is complicated if the user breaks away from this paradigm. So both my commands always insert a :level N depending on the outline depth at the time the command is invoked. This is obviously fragile, in the event the user rearranges the outline tree or uses org-roam-extract-subtree/org-node-extract-subtree or refile or manually cuts and pastes...
Thus I envisioned :level auto, which always checks the current outline depth.
I would additionally propose that :level auto become default behavior, and maybe the code can be simplified by removing the :level keyword altogether, but that's not necessary, just what would make sense to me!
Second, :no-initial-heading has to do with the fact that some nodes are file-level nodes and others are subtree nodes. Without this keyword, then sometimes there is a heading inserted, and sometimes not. It becomes hard to predict the outline structure. This keyword allows you to be certain about the resulting structure, and that's also why I made org-node-insert-transclusion-as-subtree, since if you would like there to be a heading for the transclusion, it is easier to just let the heading sit outside of the actual body of the transclusion.
I.e. the command inserts something like:
*** [[id:some-file-level-node][Pterosaurs are not reptiles]]
#+transclude: [[id:some-file-level-node][Pterosaurs are not reptiles]]
which I prefer to NOT result in the heading repeat itself as in this example:
*** [[id:some-file-level-node][Pterosaurs are not reptiles]]
**** Pterosaurs are not reptiles
Blah blah
Thank you @meedstrom. I will need to find some time to study what you have done. I also feel that I may need to consult the mailing list about what we can do to incorporate the changes you created (without the formal signing of the FSF. I don't have a strong philosophical attachment to it.
I do not fully understand your use case of :no-initial-heading. If we take your example:
*** [[id:some-file-level-node][Pterosaurs are not reptiles]]
#+transclude: [[id:some-file-level-node][Pterosaurs are not reptiles]]
You simply want to keep the heading with the link and then transclude the content without the heading of the tree?
You simply want to keep the heading with the link and then transclude the content without the heading of the tree?
Exactly :)
I also feel that I may need to consult the mailing list about what we can do to incorporate the changes you created (without the formal signing of the FSF.)
If you re-write in your own way, then you have copyright claim, I believe.
I will look at your suggestion in mode detail a little later -- I am on vacation in a remote place and not able to focus on the code (I'm doing something else :)).
For :no-initial-heading, how is it different from the existing :only-contents filter?
https://nobiot.github.io/org-transclusion/#Filter-Org-elements-per-transclusion
‘:only-contents’
This property lets you exclude titles of headlines when you transclude a subtree (headline); you transclude only the contents. When the subtree contains sub-headlines, all the contents will be transcluded.
Add ‘:only-contents’ without any value like this example:
#+transclude: [[file:path/to/file.org]] :only-contents
Edit Oh, perhaps the difference is :only-contents removes ALL headings of the tree, including the subtrees, but :no-initial-heading removes only the first one!? Hmm...
If I remember correctly, :only-contents removes all headings. Whereas :no-initial-heading preserves subtree structure at levels below.
Enjoy your vacation!
On Sat, Sep 28, 2024 at 10:48 nobiot @.***> wrote:
I will look at your suggestion in mode detail a little later -- I am on vacation in a remote place and not able to focus on the code (I'm doing something else :)).
For :no-initial-heading, how is it different from the existing :only-contents filter?
https://nobiot.github.io/org-transclusion/#Filter-Org-elements-per-transclusion
‘:only-contents’
This property lets you exclude titles of headlines when you transclude a subtree (headline); you transclude only the contents. When the subtree contains sub-headlines, all the contents will be transcluded.
Add ‘:only-contents’ without any value like this example:
#+transclude: [[file:path/to/file.org]] :only-contents
— Reply to this email directly, view it on GitHub https://github.com/nobiot/org-transclusion/issues/254#issuecomment-2380570661, or unsubscribe https://github.com/notifications/unsubscribe-auth/AQNTTF257UCJHLGMRRVVBUTZYZUMBAVCNFSM6AAAAABOLMDBY6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOBQGU3TANRWGE . You are receiving this because you were mentioned.Message ID: @.***>
Hi! I got FSF paperwork done. So I hereby assign to the FSF what I have done in my fork.
Let me know if I can help somewhere.
Well... it's the standard paperwork for Emacs contributions ("all past and future works of Developer that constitute changes and enhancements to the Program").
I don't know if it applies to org-transclusion.el, since it contains a line that says "this file is not part of GNU Emacs". I'm new to this. (However, my intent is the same regardless.)
:level auto and :no-initial-heading are both in our latest development branch: Feat/transient #273.
I have changed the internal working a bit and the name (from "initial" to "first"), but I hope that I have kept the functionality.
I do not know when I can come back to Org-transclusion this year, but I am aiming to complete this branch either during the summer or by end of the year -- this is the update cycle I seem to be able to keep for a long run.
Saw that it's underway :) Looking forward to it!
Now that you mention it, maybe I'll test the functionality soon and report back.
Saw that it's underway :) Looking forward to it!
Now that you mention it, maybe I'll test the functionality soon and report back.
Please do :)