From 7056dfb26c59b6a39d7a2d6f212c1970d2062c6e Mon Sep 17 00:00:00 2001 From: Bruce D'Arcus Date: Wed, 27 Oct 2021 17:34:14 -0400 Subject: [PATCH] docs(biblio): add readme --- modules/tools/biblio/README.org | 151 ++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 modules/tools/biblio/README.org 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.