:level auto and :no-initial-heading

[meedstrom]

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

[nobiot]

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?

[meedstrom]

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.

[nobiot]

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...

[meedstrom]

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: @.***>