Open alejandrogallo opened 1 year ago
Hi, great to see that Org-transclusion can work with other packages to help you realize your own workflow.
I am on holidays travelling at the moment so I can only have a quick look. Having said this, I think the way you have done is exactly how I envisage for other packages to work with Org-transclusion — I am referring to your usage of org-transclusion-add-functions
.
Just one thing I noticed: for Emacs, I think it’s conventional to use add-hook
rather than directly adding to the list (org-transclusion-add-functions
is an abnormal hook).
I will try to improve the documentation about “APIs” — i am not really a software person, so I guess I am not sensitive to these matters. Thank you for reporting your requirements in this thread.
Hi,
that's alright, thank you for answering so promptly.
I think the pattern of org-transclusion would be to run a hook with arguments
until success run-hook-with-args-until-success
https://www.gnu.org/software/emacs/manual/html_node/elisp/Running-Hooks.html.
Changing it to this would be more intuitive for people because then you don't have to explain what the mechanism is, i.e., that every function will run with the arguments until one of them returns non-nil, this is all implicit when one says that run-hook-with-args-until-success
is being used.
I could take a look at it and prepare a pull request with the changes if you'd like.
Yes, that’s exactly what is done (?): https://github.com/nobiot/org-transclusion/blob/main/org-transclusion.el#L425
Let me know if I have misunderstood what you are saying. Happy to discuss a PR further with you.
Ah I missed that, that's good then, the only thing that you could simply do is renaming the variable appending a suffix, -hook
, that's it. But not even this would be necessary.
Maybe it's only necessary to just write a couple of lines about the API. That's great then!
Great. Thank you.
Regarding the “-functions” and “-hook”, I am following the Emacs Lisp convention as described in the manual, so I think “-functions” should be used here:
If the hook variable’s name does not end with ‘-hook’, that indicates it is probably an abnormal hook. These differ from normal hooks in two ways: they can be called with one or more arguments, and their return values can be used in some way. The hook’s documentation says how the functions are called and how their return values are used. Any functions added to an abnormal hook must follow the hook’s calling convention. By convention, abnormal hook names end in ‘-functions’.
https://www.gnu.org/software/emacs/manual/html_node/elisp/Hooks.html
I will try to add a section about APIs (developing an extension in general). Thank you again
oh sure you're right. Adding a couple of documentation line will be absolutely enough.
Hi!
I am coding transclusion support for the rewrite of the emacs plugin for papis in papis.el.
The plugin defines a main org-link type
papis
. I could code a transclusion support for thepapis
link but I wanted to ask if this is the "official" way of doing it or if there is another way,Add the function
papis-org-transclusion-add-papis-id
to theorg-transclusion-add-functions
list did the trick wonderfullyand now one can have a list of transcluded documents like
Is this what you had in mind? I did not find any documentation and I wanted to be sure.
Thanks for the amazing package! Ale