#+TITLE: BibTeX layer

#+TAGS: dsl|layer|markup|programming

[[file:img/logo.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#configuration][Configuration]]
- [[#key-bindings][Key bindings]]

* Description
BibTeX and BibLaTeX files are a common way to manage bibliographies. The format
was original designed to work with LaTeX files and subsequently has been adopted
by other markup formats such as MarkDown and Org mode.

This layer adds support to manipulate BibTeX and BibLaTeX files in Spacemacs.

** Features:
- Syntax highlighting for BibTeX and BibLaTeX files.
- Utilities for automatically adding entries from different data sources.
- Support for inserting citations in various other modes.

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =bibtex= to the existing =dotspacemacs-configuration-layers= list in this
file.

* Configuration
This layer also supports having a global BibTeX file. For a basic
configuration, add this to your =~/.spacemacs= inside
=dotspacemacs/user-config=:

#+BEGIN_SRC emacs-lisp
  (setq org-ref-default-bibliography '("~/Papers/references.bib")
        org-ref-pdf-directory "~/Papers/"
        org-ref-bibliography-notes "~/Papers/notes.org")
#+END_SRC

Certain modes, such as =latex-mode= with AucTeX, will automatically lookup
references in a document if any of the recognized bibliography commands are
used. Other modes may have a similar feature, or one could always set
file-local variables (through ~SPC f v f~).

You can also customize which program is used to display the PDFs. For example,
to use Zathura:

#+BEGIN_SRC emacs-lisp
  (setq org-ref-open-pdf-function
    (lambda (fpath)
      (start-process "zathura" "*helm-bibtex-zathura*" "/usr/bin/zathura" fpath)))
#+END_SRC

More configuration options are available and are detailed in the =org-ref= and
=helm-bibtex= package documentations.

* Key bindings
In a Bib(La)TeX file, the following key bindings are added:

| Key binding               | Description                                |
|---------------------------+--------------------------------------------|
| ~SPC m j~ / ~g j~ / ~C-j~ | Next entry                                 |
| ~SPC m k~ / ~g k~ / ~C-k~ | Previous entry                             |
| ~SPC m p~                 | Open PDF                                   |
| ~SPC m n~                 | Open notes                                 |
| ~SPC m b~                 | Open browser                               |
| ~SPC m i~                 | Insert new entry                           |
| ~SPC m s~                 | Sort entry                                 |
| ~SPC m h~                 | Various actions on entry                   |
| ~SPC m l a~               | Lookup and add arXiv paper (don't get PDF) |
| ~SPC m l A~               | Lookup and add arXiv paper (download PDF)  |
| ~SPC m l d~               | Lookup and add paper by DOI                |
| ~SPC m l i~               | Lookup and add book by ISBN                |
| ~SPC m l p~               | Lookup and add paper by PMID               |

In addition, =org-mode=, =latex-mode= and =markdown-mode= all have the following
key binding added:

| Key binding | Description     |
|-------------+-----------------|
| ~SPC m i c~ | Insert citation |