doomemacs/modules/tools/biblio/README.org

#+TITLE:   tools/biblio
#+DATE:    April 11, 2020
#+SINCE:   21.12.0 (#5290)
#+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.
docs(biblio): add readme 2021-10-27 17:34:14 -04:00			`#+TITLE: tools/biblio`
			`#+DATE: April 11, 2020`
refactor(biblio): reformat module - Defer citar-org, since citar autoloads it. - Add introducing PR to #+SINCE and use new calver scheme. - Move <localleader> @ keybind to :lang org Ref: #5810 2021-11-22 14:21:19 +01:00			`#+SINCE: 21.12.0 (#5290)`
docs(biblio): add readme 2021-10-27 17:34:14 -04:00			`#+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.`