[API Question] Add more link types (use case in papis.el)

[alejandrogallo]

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 the papis 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 the org-transclusion-add-functions list did the trick wonderfully

    (defun papis-org-transclusion-add-papis-id (link plist)
      (when (string= "papis" (org-element-property :type link))
        (let* ((id (org-element-property :path link))
               (doc (papis--from-id id))
               (notes-path (papis--ensured-notes-path doc))
               (new-link (with-temp-buffer
                           (insert "file:")
                           (insert notes-path)
                           (beginning-of-buffer)
                           (org-element-link-parser))))
          (org-transclusion-add-org-file new-link plist))))
    (cl-pushnew 'papis-org-transclusion-add-papis-id
                org-transclusion-add-functions)

and now one can have a list of transcluded documents like

#+transclude: [[papis:d27eac97f9dab8e63d1ceeddc41bb8ff][The Mu'allaqa of Tarafa]]  :expand-links
#+transclude: [[papis:0858c8b2885089446f1647ad9bb80a41][A fifth-order perturbation comparison of electron correlation theories]] :expand-links 

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

[nobiot]

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

[nobiot]

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.

[alejandrogallo]

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.

[nobiot]

Yes, that’s exactly what is done (?): https://github.com/nobiot/org-transclusion/blob/main/org-transclusion.el#L425

[nobiot]

Let me know if I have misunderstood what you are saying. Happy to discuss a PR further with you.

[alejandrogallo]

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!

[nobiot]

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

[nobiot]

I will try to add a section about APIs (developing an extension in general). Thank you again

[alejandrogallo]

oh sure you're right. Adding a couple of documentation line will be absolutely enough.