Custom notes source

Citar 1.0 includes a flexibile notes API. Examples of how to use it.

Citar-Org-Roam

This small integration package was developed alongside the API.

https://github.com/emacs-citar/citar-org-roam

Org-Roam-Bibtex

You can also use citar-org-roam to plugin to org-roam-bibtex, like so:

(require 'citar-org-roam)
(citar-register-notes-source
 'orb-citar-source (list :name "Org-Roam Notes"
        :category 'org-roam-node
        :items #'citar-org-roam--get-candidates
        :hasitems #'citar-org-roam-has-notes
        :open #'citar-org-roam-open-note
        :create #'orb-citar-edit-note
        :annotate #'citar-org-roam--annotate))

(setq citar-notes-source 'orb-citar-source)

Org

#+name: bibliographic-entry-template
: #+title: %s
: #+subtitle: Bibliographic Notes
: #+author: %s
: #+email: %s
: #+property: header-args+ :comments link
: #+cite_export: csl apa.csl
:
: * Notes
:
: |
:
: * References
:
: #+begin_src bibtex :tangle %s :exports none
: %s
: #+end_src
:
: #+print_bibliography:

#+begin_src emacs-lisp :var template=bibliographic-entry-template
(defun my-citar-org-open-notes (key entry)
  (let* ((bib (string-join (list my/bibtex-directory key ".bib")))
         (org (string-join (list my/bibtex-directory key ".org")))
         (new (not (file-exists-p org))))
    (funcall citar-file-open-function org)
    (when (and new (eq (buffer-size) 0))
      (insert (format template
                      (assoc-default "title" entry)
                      user-full-name
                      user-mail-address
                      bib
                      (with-temp-buffer
                        (insert-file-contents bib)
                        (buffer-string))))
      (search-backward "|")
      (delete-char 1))))

(setq-default citar-open-note-function 'my-citar-org-open-notes)
#+end_src

Org-noter

The following describes a fix to allow org-noter usage with citar and citar-org-roam.

This is not "full integration", but will allow one to:

• Show org-noter .org notes files for an item in its citar menu entry
• Allow one to create .org notes files from citar that org-noter can read and associate with the .pdf document associated to that citar item.
• Start an org-noter session (i.e. window configuration with notes file and .pdf side-by-side) when viewing the .pdf of an entry in citar, by running M-x org-noter, if the notes file for that entry already exists (and is in the org-noter search path).

Caveat:

The only behaviour that the following instructions can't enable is the ability to create a new note file which automatically has all the citar data filled in (in the file header, title, section headlines or filename) when viewing a .pdf file by running M-x org-noter. Doing so will give you an org-noter prompt for a filename to save your notes to, which you can manually label with the citar key for the item etc. But you can avoid this by doing M-x citar-open, selecting the item in the menu, and then hitting RET on the Create Org-Roam Notes option. And again, if the notes file (as constructed below) already exists, there should be no problem in running an org-noter session.

Instructions

It appears as though the key to connecting a notes file (or even an org-heading) with a .pdf document is that the PROPERTIES drawer for the file contains the NOTER_DOCUMENT property, which is the path to the .pdf file.

Then setting org-noter-notes-search-path and org-noter-default-notes-file-names will allow org-noter to associate the .pdf file and the notes files.

In your citar-org-roam config, make sure that the relevant template expansion keys are defined:

(setq citar-org-roam-template-fields
        '((:citar-citekey "key")
          (:citar-title "title")
          (:citar-author "author" "editor")
          (:citar-date "date" "year" "issued")
          (:citar-pages "pages")
          (:citar-type "=type="))   ) 

Next, define the function citar-add-org-noter-document-property, and advise the function citar-create-note to run it as follows:

(defun citar-add-org-noter-document-property(key &optional entry)
  "Set various properties PROPERTIES drawer when new Citar note is created."
  (interactive)
  (let* ((file-list-temp (list (citar--select-resource key :files t)))
	 (file-path-temp (alist-get 'file file-list-temp)) 
	 (cite-author (cdr (citar-get-field-with-value'(author) key)))
	 (cite-url (cdr (citar-get-field-with-value '(url) key))) )

    (org-set-property "NOTER_DOCUMENT" file-path-temp)
    (org-set-property "Custom_ID" key)
    (org-set-property "AUTHOR" cite-author)
    (org-set-property "URL"    cite-url)
    (org-roam-ref-add (concat "@" key))
    (org-id-get-create) ))

(advice-add 'citar-create-note :after #'citar-add-org-noter-document-property)

You can change citar-add-org-noter-document-property to include more or fewer properties (e.g. you might not want the URL property, so you could just kill the line (org-set-property "URL" cite-url)). The important thing is that the (org-set-property "NOTER_DOCUMENT" file-path-temp) line is present.

Next, create the capture template for the notes file, and make sure that citar-org-roam-capture-template-key is set accordingly:

(add-to-list 'org-roam-capture-templates
	     '("c" "citar literature note" plain "%?"
	       :target (file+head "%(expand-file-name citar-org-roam-subdir org-roam-directory)/${citar-citekey}.org"
				  "#+title: Notes on: ${citar-title}\n#+subtitle: ${citar-author}, ${citar-date}")
	       :unnarrowed t))

(setq citar-org-roam-capture-template-key "c")

Again, this template can be modified -- you don't have to have the ${citar-title}$ as the #+title, it could be a top-level heading (or you don't even have to use it). In this example, the notes file will be in the citar-org-roam-subdir -- which needs to be set, if you haven't already -- or if not, in the org-roam-directory, which you should have set if you use org-roam.

The important thing is that the filename takes the form ${citar-citekey}.org, which is how citar and org-noter can associate the notes file to the item/.pdf.

Finally, make sure to set the org-noter search path, to allow org-noter to find the notes file when you view the .pdf, e.g:

(setq org-noter-notes-search-path '("/path/to/notes" "/path/to/org-roam-directory" "/path/to/citar-org-roam-subdir"))