diff --git a/init.example.el b/init.example.el index 4d42f7fcf..dc4e6ea9a 100644 --- a/init.example.el +++ b/init.example.el @@ -85,6 +85,7 @@ :tools ;;ansible + ;;biblio ; Writes a PhD for you (citation needed) ;;debugger ; FIXME stepping through code, to help you add bugs ;;direnv ;;docker diff --git a/modules/tools/biblio/README.org b/modules/tools/biblio/README.org new file mode 100644 index 000000000..838319bc8 --- /dev/null +++ b/modules/tools/biblio/README.org @@ -0,0 +1,151 @@ +#+TITLE: tools/biblio +#+DATE: April 11, 2020 +#+SINCE: 3.0 +#+STARTUP: inlineimages + +* Table of Contents :TOC_3:noexport: +- [[#description][Description]] + - [[#maintainers][Maintainers]] + - [[#module-flags][Module Flags]] + - [[#plugins][Plugins]] +- [[#prerequisites][Prerequisites]] + - [[#pdf-viewing][PDF viewing]] + - [[#bibtex-completion][Bibtex completion]] +- [[#features][Features]] +- [[#configuration][Configuration]] + - [[#org-cite][Org-cite]] + - [[#processor-configuration][Processor configuration]] + - [[#other-configuration-options][Other configuration options]] + - [[#path-configuration][Path configuration]] + - [[#templates][Templates]] +- [[#troubleshooting][Troubleshooting]] + +* Description +This module adds tools to help when working with bibliographies and citations. +Minimal modifications have been made to the packages and the configuration +details are listed in [[*Configuration][Configuration]] below. Some sensible defaults have been +selected so it should be possible to use without modifications. + +** Maintainers ++ [[https://github.com/bdarcus][bdarcus]] ++ [[https://github.com/brianmcgillion][bmg]] + +** Module Flags +This module provides no flags. + +** Plugins ++ [[https://github.com/tmalsburg/helm-bibtex][bibtex-completion]] ++ ~:completion vertico~ + + [[https://github.com/bdarcus/citar][citar]] ++ ~:completion helm~ + + [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] ++ ~:completion ivy~ + + [[https://github.com/tmalsburg/helm-bibtex][ivy-bibtex]] + +* Prerequisites +There are no hard dependencies for this module. + +** PDF viewing +An application for opening PDF files is required. By default =DocView= is used +though it is highly recommended to enable =:tools pdf= in your personal ~init.el~ +file to enable [[https://github.com/politza/pdf-tools][pdf-tools]]. + +** Bibtex completion +For vertico, helm, or ivy bibtex completion you should enable =:completion vertico=, =:completion helm=, or +=:completion ivy= respectively. + +* Features +Both [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] (includes helm-bibtex, ivy-bibtex and bibtex-completion code) +and [[https://github.com/bdarcus/bibtex-actions][citar]] provide an extensive range of features so it is best to check their +respective sites for a full list of features. + +On a high-level you can expect: ++ bibliography management ++ Notes per reference ++ citation support ++ citation lookup ++ org integration for writing literate latex (org-roam) ++ fast indexing and searching of references. + +To understand the interaction of these packages this [[https://www.reddit.com/r/emacs/comments/cxu0qg/emacs_org_and_bibtex_as_alternative_to_zotero_and/eyqe4vq/][reddit]] thread will explain +the unique features and the overlapping functionality if any. + +In addition, this module provides support for native Org-mode citations: =org-cite=. + +* Configuration + +For all these packages it is advisable to use ~(after! package)~ in your +~config.el~ to override any default settings and tune the packages to your +needs. + +** Org-cite + +*** Processor configuration + +=Org-cite= provides rich features and flexible configuration options via its "processor" capabilities. + +1. /insert/ provides =org-cite-insert= integration for inserting and editing citations. +2. /activate/ provides fontification, previews, etc. +3. /follow/ integrates contextual citation actions with =org-open-at-point=. +4. /export/ for different output targets. + +This module makes available the following processors: + +1. The core =oc-basic=, =oc-natbib=, =oc-biblatex=, and =oc-csl=. +2. [[https://github.com/bdarcus/bibtex-actions][citar]] for integration with =vertico= completion. + +For user-interface, the module configures these processors as follows for the different completion modules: + +| Feature | Vertico | Ivy | Helm | +|----------+---------+----------+----------| +| Insert | citar | oc-basic | oc-basic | +| Activate | citar | oc-basic | oc-basic | +| Follow | citar | oc-basic | oc-basic | + + +*** Other configuration options + +If you like, you can also set the =oc-csl= processor to look in a specific +directory for your CSL styles: + +#+BEGIN_SRC emacs-lisp +(setq org-cite-csl-styles-dir "~/Zotero/styles") +#+END_SRC + +** Path configuration + +You must set the path variable for either =citar= (if using =vertico= +completion) or =bibtex-completion= (if using =ivy= or =helm=); this module will +in turn set the =org-cite-global-bibliography= path variable to this: + +#+BEGIN_src emacs-lisp +(setq! bibtex-completion-bibliography '("/path/to/references.bib")) +#+END_src + +#+BEGIN_src emacs-lisp +(setq! citar-bibliography '("/path/to/references.bib")) +#+END_src + +You may also set the respective note and library path variables as well for +enhanced functionality: + +#+BEGIN_src emacs-lisp +(setq! bibtex-completion-library-path '("/path/to/library/path/") + bibtex-completion-notes-path "/path/to/your/notes/") +#+END_src + +#+BEGIN_src emacs-lisp +(setq! citar-library-paths '("/path/to/library/files/") + citar-notes-paths '("/path/to/your/notes/")) +#+END_src + +** Templates + +This module provides reasonable default templates for the packages. However, if +you wish to change these refer to the respective packages for in-depth +instructions. + +* Troubleshooting +# Common issues and their solution, or places to look for help. + +Look to the respective package repositories. diff --git a/modules/tools/biblio/config.el b/modules/tools/biblio/config.el index 46fef46e9..6d0cd390f 100644 --- a/modules/tools/biblio/config.el +++ b/modules/tools/biblio/config.el @@ -1,11 +1,12 @@ ;;; tools/biblio/config.el -*- lexical-binding: t; -*- (use-package! bibtex-completion + :when (or (featurep! :completion ivy) + (featurep! :completion helm)) :defer t :config (setq bibtex-completion-additional-search-fields '(keywords) - bibtex-completion-pdf-field "file"));; This tell bibtex-completion to look at the File field of the bibtex to figure out which pdf to open - + bibtex-completion-pdf-field "file"));; This tells bibtex-completion to look at the File field of the bibtex to figure out which pdf to open (use-package! ivy-bibtex :when (featurep! :completion ivy) @@ -14,7 +15,46 @@ (add-to-list 'ivy-re-builders-alist '(ivy-bibtex . ivy--regex-plus))) -(use-package! citar - :when (featurep! :completion vertico) - :after embark - :defer t) +;;; Org-Cite configuration + +(use-package! oc + :after org + :config + (map! :map org-mode-map + :localleader + :desc "Insert citation" "@" #'org-cite-insert) + (setq org-cite-global-bibliography + (let ((paths + (cond + ((boundp 'citar-bibliography) citar-bibliography) + ((boundp 'bibtex-completion-bibliography) bibtex-completion-bibliography)))) + ;; Always return bibliography paths as list for org-cite. + (if (stringp paths) (list paths) paths)) + ;; setup export processor; default csl/citeproc-el, with biblatex for + ;; latex + org-cite-export-processors + '((latex biblatex) + (t csl)) + org-cite-insert-processor 'citar + org-cite-follow-processor 'citar + org-cite-activate-processor 'citar + org-support-shift-select t)) + + + ;;; Org-cite processors +(use-package! oc-biblatex + :after oc) + +(use-package! oc-csl + :after oc) + +(use-package! oc-natbib + :after oc) + +;;;; Third-party + +(use-package! citar-org + :when (featurep! :lang org +roam2) + :config + ;; Include property drawer metadata for 'org-roam' v2. + (setq citar-org-note-include '(org-id org-roam-ref))) diff --git a/modules/tools/biblio/packages.el b/modules/tools/biblio/packages.el index d9a2adc8c..7c442ebf4 100644 --- a/modules/tools/biblio/packages.el +++ b/modules/tools/biblio/packages.el @@ -1,10 +1,13 @@ ;; -*- no-byte-compile: t; -*- ;;; tools/biblio/packages.el -(package! bibtex-completion :pin "b85662081de98077f13f1a9fac03764702325d28") (when (featurep! :completion ivy) - (package! ivy-bibtex :pin "b85662081de98077f13f1a9fac03764702325d28")) + (package! bibtex-completion :pin "bb47f355b0da8518aa3fb516019120c14c8747c9") + (package! ivy-bibtex :pin "bb47f355b0da8518aa3fb516019120c14c8747c9")) (when (featurep! :completion helm) - (package! helm-bibtex :pin "b85662081de98077f13f1a9fac03764702325d28")) + (package! bibtex-completion :pin "bb47f355b0da8518aa3fb516019120c14c8747c9") + (package! helm-bibtex :pin "bb47f355b0da8518aa3fb516019120c14c8747c9")) (when (featurep! :completion vertico) - (package! citar :pin "fd33f5c4f7981036a969b5ca8aaf42380848ab32")) + (package! citar :pin "41ec5d4d5d625f7d784b4de20d14b7bceaf1730c")) + +(package! citeproc :pin "c8ff95862823cdff067e8cc9bb7f5ef537e8f1d9")