Open pp5x opened 1 year ago
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 must be a org link Two considerations/reasons.
#+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- 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
- 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
->: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:
: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.
These are just my current thinking. Open to change, or adapt if that is useful.
What?
Consider a org document using the
#+include
directive:In order to move to org-transclusion, it must be adapted to:
org-transclusion is almost using the same syntax as
#+include
with the following diff (in that example):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:#+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!