How to actually use these functions? #156

kronikpillow · 2022-11-05T12:37:00Z

kronikpillow
Nov 5, 2022

Hi there, excuse me if I'm being a noob, but i'm relatively new to Emacs, and I'v been using org-roam v2 since i started using to build a "wiki" / "guide" for a video game I'v been playing ... and I'v been looking on how to improve the notes and links and everything, and i stumbled up upon this project in my searches on Brave search, Task management with org-roam Vol. 5: Dynamic and fast agenda ... but i am completely unaware how to get them working, I'v been going trough the docs for the last 4 days, and i'm unsuccessful at setting things up ...

~~I use Doom Emacs and this is in my config so far:~~

(use-package! vulpea
  :hook ((org-roam-db-autosync-mode . vulpea-db-autosync-enable)))

~~and I'v configured the agenda with~~

(add-to-list 'org-tags-exclude-from-inheritance "project")

(defun vulpea-project-p ()
  "Return non-nil if current buffer has any todo entry.

TODO entries marked as done are ignored, meaning the this
function returns nil if current buffer contains only completed
tasks."
  (seq-find                                 ; (3)
   (lambda (type)
     (eq type 'todo))
   (org-element-map                         ; (2)
       (org-element-parse-buffer 'headline) ; (1)
       'headline
     (lambda (h)
       (org-element-property :todo-type h)))))

(defun vulpea-project-update-tag ()
    "Update PROJECT tag in the current buffer."
    (when (and (not (active-minibuffer-window))
               (vulpea-buffer-p))
      (save-excursion
        (goto-char (point-min))
        (let* ((tags (vulpea-buffer-tags-get))
               (original-tags tags))
          (if (vulpea-project-p)
              (setq tags (cons "project" tags))
            (setq tags (remove "project" tags)))

          ;; cleanup duplicates
          (setq tags (seq-uniq tags))

          ;; update tags if changed
          (when (or (seq-difference tags original-tags)
                    (seq-difference original-tags tags))
            (apply #'vulpea-buffer-tags-set tags))))))

(defun vulpea-buffer-p ()
  "Return non-nil if the currently visited buffer is a note."
  (and buffer-file-name
       (string-prefix-p
        (expand-file-name (file-name-as-directory org-roam-directory))
        (file-name-directory buffer-file-name))))

(defun vulpea-project-files ()
    "Return a list of note files containing 'project' tag." ;
    (seq-uniq
     (seq-map
      #'car
      (org-roam-db-query
       [:select [nodes:file]
        :from tags
        :left-join nodes
        :on (= tags:node-id nodes:id)
        :where (like tag (quote "%\"project\"%"))]))))

(defun vulpea-agenda-files-update (&rest _)
  "Update the value of `org-agenda-files'."
  (setq org-agenda-files (vulpea-project-files)))

(add-hook 'find-file-hook #'vulpea-project-update-tag)
(add-hook 'before-save-hook #'vulpea-project-update-tag)

(advice-add 'org-agenda :before #'vulpea-agenda-files-update)
(advice-add 'org-todo-list :before #'vulpea-agenda-files-update)

~~I get this error:~~
~~Error caused by user's config or system: /home/kronikpillow/.config/doom/config.el, (void-variable org-tags-exclude-from-inheritance)~~

~~when i invoke vulpea-find to create a new note, then when i try to invoke vulpea-meta-add it tells me that the current file is not a note?~~

also, I'm confused as to how to actually invoke the non interactive functions, when I run M-x: i only have vulpea-find vulpea-db-autosync-mode vulpea-insert vulpea-find-backlinks ~~and i can't find any of the other functions?

sorry if im not explaining this right, please have patience with me :) appreciate any help

kronikpillow · 2022-11-05T13:14:06Z

kronikpillow
Nov 5, 2022
Author

like, how am i actually supposed to invoke vulpea-create? if i add your examples to my config.org, what happens is that the notes from the examples get automatically created ... o.O

I'm not sure how to incorporate this in to my work flow, and i'm totally lost :(

1 reply

d12frosted Nov 6, 2022
Maintainer

like, how am i actually supposed to invoke vulpea-create? if i add your examples to my config.org, what happens is that the notes from the examples get automatically created ... o.O

That makes sense. Your configuration file is evaluated every time you start Emacs. You can find more information in Init file documentation.

kronikpillow · 2022-11-05T17:32:11Z

kronikpillow
Nov 5, 2022
Author

SOLVED on my own :) boy was this a headache, I'll come back to you to give you a suggestion how to improve your blog post in VOL 2 section, as it's the only one i couldn't get to work, I need to take a break, this was a 48h journey in trying to clean up org agenda 😃😃

0 replies

kronikpillow · 2022-11-05T18:19:08Z

kronikpillow
Nov 5, 2022
Author

OK so ... to a person who is not knowledgeable in Emacs-lisp, and how syntax looks like, and works, when reading trough your blog post, the background white color doesn't help distinguish between what a reader should place in the config, and what a paragraph of the blog post is, so I'v taken steps to screenshot and illustrate what I was doing, and what a reader should do

the red outline represents what I was placing in my config

the blue outline is what a reader should place in his config to get it working

the blue arrow ... add a : instead of a . so that it's clear that this is where the example starts

the issue is the white background on the blog, the entire time i was reading trough the blog post i was thinking that the following is part of the paragraph between examples:

 "Get category of item at point for agenda.

Category is defined by one of the following items:

- CATEGORY property
- TITLE keyword
- TITLE property
- filename without directory and extension

Usage example:

and that the code a reader is supposed to place in his config is:

(setq org-agenda-prefix-format
      '((agenda . " %i %-12(vulpea-agenda-category)%?-12t% s")
        (todo . " %i %-12(vulpea-agenda-category) ")
        (tags . " %i %-12(vulpea-agenda-category) ")
        (search . " %i %-12(vulpea-agenda-category) ")))

(defun vulpea-agenda-category ()

and

  (setq org-agenda-prefix-format
        '((agenda . \" %(vulpea-agenda-category) %?-12t %12s\")))

Refer to `org-agenda-prefix-format' for more information."
  (let* ((file-name (when buffer-file-name
                      (file-name-sans-extension
                       (file-name-nondirectory buffer-file-name))))
         (title (vulpea-buffer-prop-get "title"))
         (category (org-get-category)))
    (or (if (and
             title
             (string-equal category file-name))
            title
          category)
        "")))

or

  (setq org-agenda-prefix-format
        '((agenda . \" %(vulpea-agenda-category) %?-12t %12s\")))

Refer to `org-agenda-prefix-format' for more information."
  (let* ((file-name (when buffer-file-name
                      (file-name-sans-extension
                       (file-name-nondirectory buffer-file-name))))
         (title (vulpea-buffer-prop-get "title"))
         (category (org-get-category))
         (result
          (or (if (and
                   title
                   (string-equal category file-name))
                  title
                category)
              "")))
    (if (numberp len)
        (s-truncate len (s-pad-right len " " result))
      result)))

maybe change the background? and add a : instead of a . at the arrow point, or somehow wrap the full example in a different color to make it more clear, where a paragraph starts & ends, and where the actual code starts & ends, or include syntax highlighting in the examples :)

apart from that, could you show me a example of how to invoke the programmable function to create a note and how i could put it to good use instead of having to constantly use vulpea-find and capture to create notes? like, I'm confused, if i set a programmable function in my config as per your examples on the repository, when i launch my emacs, what happens is that it creates that 1 note by default, how does that help me create different notes with the same function?

2 replies

d12frosted Nov 6, 2022
Maintainer

Thanks for the feedback. At some point of time the syntax highlighting got broken. I need to fix that.

But you really need to learn Emacs Lisp. What you outlined in red is partially documentation and implementation of vulpea-agenda-category. The idea was to put whole snippet. The following code sets the value of org-agenda-prefix-format

(setq org-agenda-prefix-format
      '((agenda . " %i %-12(vulpea-agenda-category)%?-12t% s")
        (todo . " %i %-12(vulpea-agenda-category) ")
        (tags . " %i %-12(vulpea-agenda-category) ")
        (search . " %i %-12(vulpea-agenda-category) ")))

Since it uses vulpea-agenda-category function, you need to define it as well:

(defun vulpea-agenda-category ()
  "Get category of item at point for agenda.

Category is defined by one of the following items:

- CATEGORY property
- TITLE keyword
- TITLE property
- filename without directory and extension

Usage example:

  (setq org-agenda-prefix-format
        '((agenda . \" %(vulpea-agenda-category) %?-12t %12s\")))

Refer to `org-agenda-prefix-format' for more information."
  (let* ((file-name (when buffer-file-name
                      (file-name-sans-extension
                       (file-name-nondirectory buffer-file-name))))
         (title (vulpea-buffer-prop-get "title"))
         (category (org-get-category)))
    (or (if (and
             title
             (string-equal category file-name))
            title
          category)
        "")))

Here "Refer to `org-agenda-prefix-format' for more information." is the last line of documentation.

d12frosted Nov 6, 2022
Maintainer

apart from that, could you show me a example of how to invoke the programmable function to create a note and how i could put it to good use instead of having to constantly use vulpea-find and capture to create notes? like, I'm confused, if i set a programmable function in my config as per your examples on the repository, when i launch my emacs, what happens is that it creates that 1 note by default, how does that help me create different notes with the same function?

I don't understand your question. Your init.el file is evaluated every time you start Emacs. Then you can evaluate code by different means: running an interactive function, starting a REPL (for example, ielm) or using eval-expression (bound to M-: by default).

For example, vulpea-find is an interactive function that executes org-roam-capture- if the note you typed is not found. This way you can create new notes. If you need an interactive function that only creates a note - use org-roam-capture. Vulpea is built on top of org-roam and you can use them together.

d12frosted · 2022-11-05T19:17:45Z

d12frosted
Nov 5, 2022
Maintainer

@kronikpillow Oh bummer. It saddens me to hear you have troubles with this library. I can't read all your questions thoughtfully at the moment, but I will try to address your questions tomorrow. After briefly reading your messages I want to make few remarks to help you while I am offline.

First and foremost, vulpea is a library. It's main goal is to provide API for writing your own applications/scripts/automations. Yes, it exposes few interactive functions, but as a library it targets people familiar with Emacs Lisp. I would advice going over built-in Emacs tutorial (C-h i) to learn more. It's really easier once you have basic knowledge of Emacs Lisp.

Secondly, can you please elaborate what exactly you want to achieve? I mean, you state that you are using Org as a wiki and then you mention my task management series. So I am little bit puzzled.

Anyways, I will answer all your questions. Thank you for taking your time to share your troubles.

1 reply

d12frosted Nov 6, 2022
Maintainer

@kronikpillow

also, I'm confused as to how to actually invoke the non interactive functions, when I run M-x: i only have vulpea-find vulpea-db-autosync-mode vulpea-insert vulpea-find-backlinks ~~and i can't find any of the other functions?

Well, that's the point of distinction between interactive and non-interactive functions. The first group can be called interactively either through M-x or via key binding. All others must be called non-interactively, e.g. through the code or via special means of code evaluation (e.g. ielm or eval-expression).

As I said before, vulpea is a library that provides some interactive functions, but it's primary goal is to provide API that one can use programmatically. One example would be using these functions in your init.el (e.g. configuration files).

I know that Emacs is not the easiest editor out in the wild, but at least it comes with tons of built-in documentation and tutorials you can access via C-h i. Some topics you might be interested in:

kronikpillow · 2022-11-05T21:29:10Z

kronikpillow
Nov 5, 2022
Author

what i'm trying to achieve is incorporate Org-Roam in to my GTD workflow, while keeping a personal Zettle knowledge base as well...kinda exactly what your talking about in that blog post. the Guide/wiki about the game, is just 1 category i will have in the Zettle, it's just something im currently actively working on and using to master the workflow

lets think of the wiki as a project ...
the project has various topics which is it's own note
the topics are connected between each other, regularly reference each other and provide links to specific notes, or headers in notes
each note has it's own TODO's, which i wan't loaded in the Org Agenda, so that i can get things done, while processing each note as i write about the topic.

i also want a capture template, where i can quickly write a create a new note for a different topic in that same project, when, or a inbox file like you described in VOL.7 where i can write new notes and TODO's related to that entire project, which i can then later refile in to new notes as i work on them ... and as i work on the wiki ... then later to build my knowledgebase regarding other stuff and utilize the power of vulpea :)

the issue im now having is with VOL.7, the defined vulpea-capture-task is creating a inbox file in my /doom folder instead of the org/roam folder, and it's not being picked up by the agenda :D

2 replies

d12frosted Nov 6, 2022
Maintainer

what i'm trying to achieve is incorporate Org-Roam in to my GTD workflow, while keeping a personal Zettle knowledge base as well...kinda exactly what your talking about in that blog post. the Guide/wiki about the game, is just 1 category i will have in the Zettle, it's just something im currently actively working on and using to master the workflow

Ah I see. Well yeah, than the blog series you linked might be helpful. They assume basic knowledge of Emacs configuration, Emacs Lisp and Org mode. Without that I guess it might be really hard to use all that, cause many things are implicit there.

the issue im now having is with VOL.7, the defined vulpea-capture-task is creating a inbox file in my /doom folder instead of the org/roam folder, and it's not being picked up by the agenda :D

Do you have a repository where I can look at your configurations? There are plenty things that might go astray. For example, what is the value of vulpea-capture-inbox-file? Do you have the following configuration:

(setq org-capture-templates
      '(("t" "todo" plain (file vulpea-capture-inbox-file)
         "* TODO %?\n%U\n" :clock-in t :clock-resume t)))

?

Besides, you are using Doom and it has plenty of custom configurations for Org, so that might be also relevant. You should consult with Doom documentation on how to extend and configure its modules.

d12frosted Nov 28, 2022
Maintainer

the issue im now having is with VOL.7, the defined vulpea-capture-task is creating a inbox file in my /doom folder instead of the org/roam folder, and it's not being picked up by the agenda :D

I think there is a mistake in my article. You should set the value of vulpea-capture-inbox-file to absolute file. E.g. (expand-file-name (format "inbox-%s.org" (system-name)) org-directory).

Regarding second issue, I see the following stuff in your configs:

(defun vulpea-project-files ()
    "Return a list of note files containing 'project' tag." ;
    (seq-uniq
     (seq-map
      #'car
      (org-roam-db-query
       [:select [nodes:file]
        :from tags
        :left-join nodes
        :on (= tags:node-id nodes:id)
        :where (like tag (quote "%\"project\"%"))]))))

(defun vulpea-agenda-files-update (&rest _)
  "Update the value of `org-agenda-files'."
  (setq org-agenda-files (vulpea-project-files)))

That means that your agenda contains only files that are part of your roam system (e.g. notes picked by roam) and that are tagged as project. Since the file is created outside roam directory, you agenda can't find it.

kronikpillow · 2022-11-09T10:42:27Z

kronikpillow
Nov 9, 2022
Author

back, sorry for the late reply, been busy ... here is my repo

one question, why org-capture instead of org-roam-capture?

1 reply

d12frosted Nov 28, 2022
Maintainer

@kronikpillow sorry, haven't got a chance to look into your configurations yet. Hopefully will do soon.

one question, why org-capture instead of org-roam-capture?

🤔 I don't know how to answer this question beside by asking a reversed version of it :) Why org-roam-capture instead of org-capture?

And I asked about org-capture-templates because this is what I use in the article :)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

How to actually use these functions? #156

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 6 comments 7 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

Select a reply

How to actually use these functions? #156

kronikpillow Nov 5, 2022

Replies: 6 comments · 7 replies

kronikpillow Nov 5, 2022 Author

d12frosted Nov 6, 2022 Maintainer

kronikpillow Nov 5, 2022 Author

kronikpillow Nov 5, 2022 Author

d12frosted Nov 6, 2022 Maintainer

d12frosted Nov 6, 2022 Maintainer

d12frosted Nov 5, 2022 Maintainer

d12frosted Nov 6, 2022 Maintainer

kronikpillow Nov 5, 2022 Author

d12frosted Nov 6, 2022 Maintainer

d12frosted Nov 28, 2022 Maintainer

kronikpillow Nov 9, 2022 Author

d12frosted Nov 28, 2022 Maintainer

kronikpillow
Nov 5, 2022

Replies: 6 comments 7 replies

kronikpillow
Nov 5, 2022
Author

d12frosted Nov 6, 2022
Maintainer

kronikpillow
Nov 5, 2022
Author

kronikpillow
Nov 5, 2022
Author

d12frosted Nov 6, 2022
Maintainer

d12frosted Nov 6, 2022
Maintainer

d12frosted
Nov 5, 2022
Maintainer

d12frosted Nov 6, 2022
Maintainer

kronikpillow
Nov 5, 2022
Author

d12frosted Nov 6, 2022
Maintainer

d12frosted Nov 28, 2022
Maintainer

kronikpillow
Nov 9, 2022
Author

d12frosted Nov 28, 2022
Maintainer