org-transclusion-live-sync-start inconsistent behavior with org heading entries.

[ffsammak]

live-sync is a game-changer by all means, but I noticed different treatment of heading entries given the two use scenarios below:

Scenario 1: #+transclude: [[file:<filename>]] :lines 6-8
you transclude a range of lines including a heading, live-sync works as expected, yet I cannot do P or D to promote or demote the transcluded entry.

Scenario 2: #+transclude: [[file:<filename>::*Heading][sometext]] :level 3
You can P and D the transcluded entry, yet you cannot do live-sync on it.

Is this a limitation or a bug on my end only. Thanks for the great work behind this must-transclude package in your emacs setup.

Emacs: GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.33, cairo version 1.16.0)
of 2023-03-02
Framework: vanilla emacs
Org: Org mode version 9.6.1
Org-transclusion: Version: 1.3.2 on 05 March 2023

[nobiot]

Scenario 1
I think what's happening is that when you have :lines prop, the transclusion will treat the transcluded region as coming from a plain text file (not Org file), even when the transclusion source is an Org element/file. P and D works because it adds the :level property. However, the level property works only when the transcluded region is treated as an Org, not a plain text file.

Between :level and :lines properties, the default is to treat the latter priority. See the sequence of list in the variable org-transclusion-add-functions -- org-transclusion-add-src-lines does the :lines and it should be the head of the list (priority 1).

You could change the priority, but then the :lines property would not work when other add-function takes precedent.

Scenario 2
Live sync works better when the transclusion is plain text. When it is an Org (Scenario 2 is for Org), only a certain Org element works with live-sync. This is described in user manual section 6 Known Limitations. The technical limitation is described more in detail in this thread.

[ffsammak]

Thanks for the feedback. I went through the limitations actually before filing this issue here and I couldn't find "heading entries" as one of the org-elements beside others:

It is known that live-sync does not work for the other Org
elements: comment-block, export-block, example-block,
fixed-width, keyword, src-block, and property-drawerd.

So the headings element can also be added to the above list I guess. I hope one day you would overcome these limitations. So I will continue using scenario 2 but edit the source, then g on transclusion(s) to update till these limitations are dealt with. Thanks again.

[nobiot]

So the headings element can also be added to the above list I guess.

Thank you. I am thinking along the following lines. Your thoughts will be appreciated.

The limitation section also has the positive list of elements that are known to work. I am considering just keeping it only and removing the negative list of those that do not work. I included the negative list in the hope that it would help the reader. But your comment is perhaps an indication that it was rather more confusing than clarifying. What do you think?

   • ‘org-transclusion-live-sync-start’ does not support all Org
     elements For transclusions of Org elements or buffers, live-sync
     works only on the following elements: ‘center-block’, ‘drawer’,
     ‘dynamic-block’, ‘latex-environment’, ‘paragraph’, ‘plain-list’,
     ‘quote-block’, ‘special-block’, ‘table’, and ‘verse-block’.

[ffsammak]

Yes, I fully support your notion. The positive list is easier to maintain and will notify the reader what org-element has been editable so far as this list would continue to grow.

[nobiot]

@ffsammak Thank you for you feedback.
Just in case I had not been clear: For scenario 2, the current design is not to let you live-edit the whole headline but, as shown in the GIF demo in README, you can do live-edit one paragraph by paragraph (or element by element that is live-sync is possible).

So you may not be able to go in to the live-edit mode when the point is on the headline title (the line where you have the star(s) "*" but you should be able to do so within in the subtree -- I am not sure if I would like the entire headline to be editable at once... This is my current thinking.