Example functions

pdf-tools integration

Search contents of PDFs

If you run this and select candidates, this will pass the list of any associated PDF files to pdf-tools to search across all of them. If you run embark-act-all on a filtered candidate list, it will pass the files associated with all of them.

(defun ex/search-pdf-contents (keys-entries &optional str)
  "Search pdfs."
  (interactive (list (citar-select-refs)))
  (let ((files (citar-file--files-for-multiple-entries
                (citar--ensure-entries keys-entries)
                citar-library-paths
                '("pdf")))
        (search-str (or str (read-string "Search string: "))))
    (pdf-occur-search files search-str t)))

;; with this, you can exploit embark's multitarget actions, so that you can run `embark-act-all`
(add-to-list 'embark-multitarget-actions #'ex/search-pdf-contents)

Add metadata to PDF files

This function will use the metadata from the entry and update the PDF file metadata.

(defun ex/update-pdf-metadata (key-entry)
  "Add/update metadata of PDF for KEY-ENTRY."
  (interactive (list (citar-select-ref)))
  (let* ((entry (cdr key-entry))
         (key (car key-entry))
         (file (car (citar-file--files-for-entry
                     key
                     entry
                     citar-library-paths
                     '("pdf"))))
         (title (citar-clean-string (citar-get-value 'title entry)))
         (author (citar-get-value 'author entry)))
    (call-process-shell-command
     (concat "exiftool -Title='" title "' -Author='" author "' " file))))

Alternatively, in order to make use of the 'editor' field when the 'author' field is empty while also keeping your library free of the backup files that exiftool creates by default, the following may be of use:

(defvar ex/citar-library-backup-path "/path/to/library/backup")

(defun ex/update-pdf-metadata-alt (key-entry)
  "Add/update metadata of PDF for KEY-ENTRY."
(interactive (list (citar-select-ref)))
  (let* ((entry (cdr key-entry))
         (key (car key-entry))
         (file (car (citar-file--files-for-entry
                     key
                     entry
                     citar-library-paths
                     '("pdf"))))
         (nofile nil)
         (title (citar-clean-string (citar-get-value 'title entry)))
         (author (cond ((citar-has-a-value '(author) entry)
                        (citar-get-value 'author entry))
                        ((citar-has-a-value '(editor) entry)
                         (concat (citar-get-value 'editor entry) " (ed.)")))))
    (if (not file)
        (print (format "I could not find an PDF file associated with \'%s\'" key))
      (progn
        (copy-file file my/bib-library-backup-path 1)
        (call-process-shell-command
         (concat "exiftool -overwrite_original_in_place -Title='" title "' -Author='" author "' " file))))))

org-roam-bibtex integration

If you are using org-roam-bibtex you can use the following function to open the PDF associated with the current heading.

(defun my-citar-open-current-pdf ()
    "Open REFs of the node at point."
    (interactive)
    (let ((keys (when-let* ((prop (org-entry-get (point) "ROAM_REFS" t))
                            (refs (when prop (split-string-and-unquote prop)))
                            (oc-cites
                             (seq-map (lambda (ref) (substring ref 7 (- (length ref) 1))) refs)))
                  oc-cites)))
      (if keys
          (citar-open (car keys)) 
        (user-error "No ROAM_REFS found"))))