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 those candidates.

(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. Note that it will 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 (backups will be stored in the ex/citar-library-backup-path).

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

(defun ex/citar-update-pdf-metadata (citekey)
(interactive (list (citar-select-ref)))
  (citar--check-configuration 'citar-library-paths)
  (unless citar-library-paths
    (user-error "Make sure `citar-library-paths' is non-nil"))
  (let* ((files (gethash cite-key (citar-get-files cite-key))))
    (unless files
      (user-error (format "There are no PDF files associated with %s" citekey)))
    (let ((file (or (unless (cdr files) (car files)) (completing-read "Please select a PDF file: " files)))
          (title (citar-get-value 'title citekey))
          (author (cond ((citar-get-value 'author citekey)
                        (citar-get-value 'author citekey))
                        ((citar-get-value 'editor citekey)
                         (concat (citar-get-value 'editor citekey) " (ed.)")))))
      (progn
        (copy-file file ex/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"))))