Improvement: make `#+transclude` interface identical to `#+include`

[pp5x]

What?

Consider a org document using the #+include directive:

#+include: src/file.c :lines "6-7" src C

In order to move to org-transclusion, it must be adapted to:

#+transclude: [[src/file.c]] :lines 6-6 :src c

org-transclusion is almost using the same syntax as #+include with the following diff (in that example):

• file path must be a org link
• the line range is inclusive instead of being exclusive. The exclusive way is usually more common in libraries and when writing algorithms.
• src -> :src

Of course, I am not aware of all the constraints that led to the current #+transclude interface, but let me ask the question:

• Would it be possible to make #+transclude to follow the current interface of #+include?

It would be better to migrate to the transclusion package by just making a string replacement from #+include to #+transclude. And make sure that #+transclude behaves exactly the the same way as #+include.

I would be curious to know your thinking about it. Thank you!

[nobiot]

I would be curious to know your thinking about it.

There was a discussion along a similar line https://github.com/nobiot/org-transclusion/issues/83

I am still not really fixed on the current syntax, though if we were to change it, it would have to be mindful of the backward compatiblity -- meaning, we would have to support both the current API and the #+include API.... (except perhaps the line-end specifier -- as you cannot logically support both).

File path

• file path must be a org link Two considerations/reasons.
  1. #+transclude supports ID and file name. #+include, I think, only supports file name. I think it might be less confusing if we stick to the org-link syntax when you have ID and filename
  2. There is a technical / skill limitation on my side. I don't know how to reliably make the regex to extract the filename or ID reference without some indicator like the square brackets or double quotation marks. #+include supports double-quotations like "path/to/filename", right? I didn't know it can omit them. I don't know how to construct a good regex that gets only the file name when you have

#+include: src/file.c :lines "6-7" src C

Or you can have spaces in file names (I don't know if this is a valid c file name for compilation, etc. but I hope you'd get my point

+include: src/this is a c source file.c src C

Line range

• the line range is inclusive instead of being exclusive. The exclusive way is usually more common in libraries and when writing algorithms.

I am no developer. What I want to specify is this "Transclude the content from line 6 to line 10". That should be "6-10". I don't find "6-11" intuitive in this case -- that may be natural for developers who are familiar with algorithms, but for natural languages, that to me is very anti-intuitive. I developed this package originally for writing a book, so pretty much targeted at natural language use.

:src property

• src -> :src

I actually do not understand why "src" is special. It's a property to me. Other properties start with a colon ":", and I believe it's conventional for Emacs Lisp writers to use it to denote a :property-name.

In fact this is from the user manual on Include:

+INCLUDE: "./paper.org::#theory" :only-contents t

+INCLUDE: "~/.emacs" :lines "10-"

:only-contents is a property starting with a colon ":". :lines is also the same. Why is src treated differently? I am guessing there is a longer history behind it.

Lastly...

These are just my current thinking. Open to change, or adapt if that is useful.