How to create notes linking to files on the system

[jayrajput]

Similar to how one can link url in the ekg, I would like to link the files on the system. Further I would like to browse the files. File like org files shall open in emacs whereas other files like pptx shall open with system viewer.

Any pointers on how one can build such functionality in EKG?

[ahyatt]

I think that's a good idea, but it isn't implemented yet, and probably will not be until the next version. If you are interested in trying to build it, you can look at how the URL resources happen and add functionality so that it dispatches to find-file if it is detected to be a file. Understanding what should happen when the file doesn't exist is an interesting design point. I'm happy to review any pull request you send.

[jayrajput]

Sure. Let me try to code something on the suggested lines. I will be looking for guidance and will use this discussion for the same.

Understanding what should happen when the file doesn't exist is an interesting design point.

Will not find-file create it as a new file which seems to me an acceptable and not-confusing behavior. Quoting from Visiting (GNU Emacs Manual)

To create a new file, just visit it using the same command, C-x C-f. Emacs displays ‘(New file)’ in the echo area, but in other respects behaves as if you had visited an existing empty file.

[jayrajput]

I found that if I replace browse-url in ekg-notes-browse with org-link-open-from-string, then it is able to browse http URLs, pdf files, org files on the system fine. Here is the test code which articulates the same.

  ; this adds an ekg-note which works with ekg-notes-browse
  (ekg-capture-url
   "https://github.com/ahyatt/ekg"
   "ahyaat/ekg: The emacs knowledge graph")

  ; this adds an ekg-note which works with ekg-notes-browse
  (ekg-capture-url
   "file:c:/Users/jayra/Downloads/BVS2023-2024.pdf"
   "file:c:/Users/jayra/Downloads/BVS2023-2024.pdf")

  ; this adds an ekg-note which works with ekg-notes-browse
  (ekg-capture-url
   "file:c:/Users/jayra/AppData/Roaming/org/roam/20220108204433-portfolio.org"
   "file:c:/Users/jayra/AppData/Roaming/org/roam/20220108204433-portfolio.org")

  ; this add an ekg-notes which works with ekg-notes-browse
  (ekg-capture-url
   "file:c:/Users/jayra/AppData/Roaming/org/roam/20230506T120007__ekg_emacs_lisp.org"
   "file:c:/Users/jayra/AppData/Roaming/org/roam/20230506T120007__ekg_emacs_lisp.org")

  (org-link-open-from-string "[[file:c:/Users/jayra/Downloads/BVS2023-2024.pdf]]")

Updated function ekg-notes-browse using org-link-open-from-string in place of browse-url

(defun ekg-notes-browse ()
  "If the note is about a browseable resource, browse to it.
For URLs, this will use `browse-url'."
  (interactive nil ekg-notes-mode)
  (let ((note (ekg--current-note-or-error)))
    (cond ((ffap-url-p (ekg-note-id note))
           (org-link-open-from-string (ekg-note-id note))))))

[ahyatt]

This is a nice solution, but I'm trying to not have a hard dependency on org-mode. Perhaps what you could do is to use this function if it exists (using fboundp), and if not, you can use a less powerful version that you write yourself.

[jayrajput]

Sure. I will work as suggested. One question though out of curiosity, is not Org part of Emacs, so it will never happens that org-link-open-from-string is not available?

If the fear is that Emacs org may remove the function in future and breaking ekg, will it be better to add a test case to check for presence of this dependency?

Also I see that ekg.el is already requiring ol. Is not that creating a hard dependency on org-mode? Ol is the package which also has org-link-open-from-string

(require 'ol)

Looking for more guidance and trying to understand ekg better.

[jayrajput]

Based on your feedback of not adding a dependency on org function. I am thinking of adding a configuration to let the end user choose the function to browse these browsable notes. See code with new configuration ekg-notes-browse-func and the usage of the same in the existing ekg-notes-browse function.

(defcustom ekg-notes-browse-func 'browse-url
  "Function to browse the browseable resource."
  :type '(set function)
  :group 'ekg)

(defun ekg-notes-browse ()
  "If the note is about a browseable resource, browse to it.
For URLs, this will use function provided by ekg-notes-browse-func."
  (interactive nil ekg-notes-mode)
  (let ((note (ekg--current-note-or-error)))
    (cond ((ffap-url-p (ekg-note-id note))
           (funcall ekg-notes-browse-func (ekg-note-id note))))))

[ahyatt]

As to why not require org-mode, yes, it's now (in the last 2 releases IIRC) in emacs, but I think it's nice if ekg pulls in as few libraries as possible. Org is a pretty big library that I'd prefer not to pull in unless we have to. I've tried to keep ekg's dependencies lean to the extent possible. I should maybe even make the dependency on ol dependent on just using org linking, which not everyone is going to want to do.

For ekg-notes-browse-func, it seems this is just for urls? If so, it might be good to have one variable handle everything, perhaps via an alist of types to handlers. Actually, there must be something like this already, but I haven't been able to find it at the moment. It'd be nice to not have to have new variables for new types - maybe a single function, which for users of org could perhaps be org-link-open-from-string? I haven't played around with this, so maybe this wouldn't work.

[jayrajput]

Thanks for the reply.

Your design philosophy of keeping ekg lean and not dependent on ol make sense to me. Thanks for explaining the same. Probably some design/philosophy notes be added to the documentation.

You are right that ekg-notes-browse-func by default will only work for URLs as the default being browse-url. I can easily add file: scheme of the paths to be opened by find-file. Let me know if you want that. You will have to let me know the schemes supported by default by ekg.

The reasons I left it to browse-url is that I was worried about the test repercussion (the code I had was not easy to test). I did looked into the ekg-test and did not found any inspirations for my testing. And the test combinations were too many. So I thought of punting the configuration/testing to the end user and let the base package handle the URLs by default. This again goes into the philosophy/design on how we want ekg to evolve. The base ekg with extensions written by end user. This is where I have been even thought/argued about ekg-capture-url also to be an extension and probably not kept in the base package.

Further since ekg is evolving to support browsable resources other than url, does it warrants rename/aliasing of ekg-capture-url?

[jayrajput]

Here is the code based on the association list. I am struggling with the type in defcustom. Still working on verifying if the defcustom syntax is right or not.

Please see if it make sense and I can go ahead and submit a PR. We can review this again during the PR review.

  (defcustom ekg-notes-browse-funcs
    (list (cons (rx "http" (1+ anything))  #'browse-url)
          (cons (rx (1+ anything))  #'find-file))
    "Functions for browsing notes. The entries in this list are cons
  cells where the car identifies regular expression matching the note
  id and the cdr the corresponding function."
    :group 'ekg
    :type '(repeat
            (cons (choice :value ""
                          (string :tag "File Regular Expression"))
                  (choice :value ""
                          (function :tag "Function")))))

  (defun ekg-notes-browse ()
    "If the note is about a browseable resource, browse it using the function 
corresponding to the note id in `ekg-notes-browse-funcs'"    
    (interactive nil ekg-notes-mode)
    (let ((note-id (ekg-note-id (ekg--current-note-or-error))))
      (cond ((ffap-url-p note-id)
             (funcall
              (cdr (assoc note-id ekg-notes-browse-funcs 'string-match))
              note-id)))))

[ahyatt]

Sorry for the slow replies here, it's just been a busy time. For your initial question, I think it's probably best to have many functions, one for each type of thing to capture. That way you can get a more tailored experience (via different interactive invocations per function).

I think what you wrote is reasonable, but I'd like to take a bit to think about this. For example, should we have a regex-based approached you did here, or perhaps delegate this to a function that may not be as easily configurable, but it would be more powerful. Also, should file have a prefix? Should all resources basically be URLs? Let me know if you have thoughts about this, but it might be helpful to think about the various things that could be resources.

I think, though, 90% chance that what you've written is going to the correct thing to do. Let's aim to make a decision in a week's time.

Also, I'd like this to release the next version of ekg in the next few days, so this would be in the version after that. That will also give us some leeway to rethink things if necessary.

[jayrajput]

Thanks for bringing these questions. I was also struggling with the same. I was cheating a little bit though. I was thinking of using org-link-open-from-string for my personal use, but then the struggle was should file have a prefix? I do wanted to make some incremental progress though and so the updated code. The org-link-open-from-string does require prefixes, but then ekg-capture is all flexible to store any URL, provided the function to browse works fine with it.

There is a definitely a beauty in the ekg base package. This whole functionality of browsing links either be http or other schemes like file is just a mere extension of ekg-capture, Does it make sense to build the link inserting/browsing separately like ekg-org-roam as a separate file and keep the base ekg lean. Although you can say that ekg.el is just 1K lines, and is already very lean :-). Keep ekg.el lean will also help new users to understand the code better.

On your question on regexes, I was thinking of adding capability of auto-mode and system default similar to org-file-apps. Mostly I have been reading on the org-file-apps and org-open-file and adapt to our needs. But then those can be incrementally added as well. One of my use case is to link pdf/pptx file which I want to open with system default and not emacs.

Other point is all this is database so I can update and fix things really fast and programmatically if need be and that was another reasons to not worry about things. I am all for incremental progress and not get stuck at things. But we need to balance and take some time to decide on things.

[jayrajput]

I got curious and tried to look how markdown-mode is handling links. The code kind of confirms to your initial idea of using either browse-url or find-file. This will not work for opening pptx/pdf in system viewer.

Further reading the code, I realized that the link should be URI and so have prefixes. This answers the question if the file should have a prefix. It is actually a link represent by a URI and so compliancy with RFC 3986 mandates file: prefix for local files.

(defun markdown--browse-url (url)
  (let* ((struct (url-generic-parse-url url))
         (full (url-fullness struct))
         (file url))
    ;; Parse URL, determine fullness, strip query string
    (setq file (car (url-path-and-query struct)))
    ;; Open full URLs in browser, files in Emacs
    (if full
        (browse-url url)
      (when (and file (> (length file) 0))
        (let ((link-file (funcall markdown-translate-filename-function file)))
          (if (and markdown-open-image-command (string-match-p (image-file-name-regexp) link-file))
              (if (functionp markdown-open-image-command)
                  (funcall markdown-open-image-command link-file)
                (process-file markdown-open-image-command nil nil nil link-file))
            (find-file link-file)))))))

So I am thinking of adapting this code for ekg and making this function as end user configurable to handle the use case of opening pptx/pdf files.

Updated Code

  (defcustom ekg-notes-browse-func 'ekg--browse-url
    "Function to browse the notes"
    :type '(set function)
    :group 'ekg)

  (defun ekg--browse-url (url)
    (let* ((struct (url-generic-parse-url url))
           (full (url-fullness struct))
           (file (car (url-path-and-query struct))))
      ;; Open full URLs in browser, files in Emacs
      (if full
          (browse-url url)
        (when (and file (> (length file) 0))
          (find-file file)))))

  (defun ekg-notes-browse ()`
    "If the note is about a browseable resource, browse to it.
  For URLs, this will use function provided by ekg-notes-browse-func."
    (interactive nil ekg-notes-mode)
    (let ((note (ekg--current-note-or-error)))
      (cond ((ffap-url-p (ekg-note-id note))
             (funcall ekg-notes-browse-func (ekg-note-id note))))))

[jayrajput]

Shall I send a PR for this one? @ahyatt

[ahyatt]

Yes, that would be good, although I think it will take some thought and some iterations before we settle on something. So, no rush, but once you are ready to move this along, please go ahead.

[jayrajput]

Thanks. I will send a PR.