1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
* Contributing
:PROPERTIES:
:CUSTOM_ID: contributing
:END:
If you would like to contribute, details:
- For more significant potential changes, file an issue first to get feedback on the basic idea.
- If you do submit a PR, follow the [[https://github.com/bbatsov/emacs-lisp-style-guide][elisp style guide]], and [[https://cbea.ms/git-commit/][these suggestions]] on git commit messages.
- For working on lists and such, we primarily use the =seq= functions, and occassionally ~dolist~.
** Basic Architecture
Citar uses a cache, which stores two hash tables for each bibliography file:
- entries :: as returned by =parsebib-parse=, keys are citekeys, values are alists of entry fields
- pre-formatted :: values are partially-formatted completion strings
The =citar--ref-completion-table= function returns a hash table from the bibliographic cache, and ~citar--get-entry~ and ~-citar--get-value~ provide access to those data.
Most user-accessible citar functions take an argument ~key~ or ~keys~.
Some functions also take an ~entry~ argument, and ~citar--get-value~ takes either.
When using these functions, you should keep in mind that unless you pass an entry alist to ~citar--get-value~, and instead use a key, each call to that function will query the cache.
This, therefore, is a better pattern to use:
#+begin_src emacs-lisp
(let* ((entry (citar--get-entry key))
(title (citar--get-value entry "title")))
(message title))
#+end_src
** Extending citar
You can use ~citar-select-ref~ or ~citar-select-refs~ to write custom commands.
An example:
#+begin_src emacs-lisp
(defun my/citar-insert-annots (keys)
"insert annotations as org text from KEYS-ENTRIES"
(interactive (list (citar-select-refs)))
(let* ((files
(seq-mapcat (lambda (key)
(citar-file--files-for-entry
key (citar--get-entry key)
'("/") '("pdf")))
keys ))
(output (seq-map
(lambda (file)
(pdf-annot-markups-as-org-text ;; you'll still need to write this function!
file)
files)))
(save-excursion
(org-forward-element)
(-each output (lambda (out)
(insert (format "\n%s\n" out))))
output)))
(defun my/independent-insert-annots (key)
"helper function to insert annotations without the bibtex-actins apparatus"
(my/citar-insert-annots (list key)))
#+end_src
Then bind the first function to the appropriate keymap, e.g.,
#+begin_src emacs-lisp
(define-key oc-citar-map (kbd "a") '("insert file annotations" . my/citar-insert-annots))
#+end_src
|
