Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rougier/org-bib-mode

An Emacs minor mode for literate & annotated bibliography
https://github.com/rougier/org-bib-mode

bibliography bibtex emacs lisp literate-programming orgmode

Last synced: 3 months ago
JSON representation

An Emacs minor mode for literate & annotated bibliography

Awesome Lists containing this project

README 

        
*Literate & annotated bibliography* — Nicolas P. Rougier



[[./bibliography.png]]



*NOTE* This literate and annotated bibliography is an adaptation of the idea 

[[http://cachestocaches.com/2020/3/org-mode-annotated-bibliography/][Managing my Annotated Bibliography with Emacs' Org Mode]] by [[http://gjstein.com/][Gregory J Stein]].



* Introduction



The core idea behind literate bibliography is to have a single structured file where each entry corresponds to a reference. Information concerning an entry is stored as properties and two subsections allow to enter abstract and notes. To ease the manipulation, org-bib-mode provides a sidebar menu that displays the list of bibliograpic entries and provide tools to ease navigation. Under the hood, the org-bib-mode is the union of two  modes:



- [[https://github.com/rougier/pdf-drop-mode][pdf-drop-mode]] that allow to drag and drop a file in order to add it to the bibliography using its doi that is searched automatically.

- [[https://github.com/rougier/org-imenu/][org-imenu]] that allow to easily nagivate among entries and allowing various operations such as filtering entries, moving entries, etc.



org-bib mode is meant to be simple and robust (it is simple but not yet robust). If you need somethign more elaborated, have a look at the

amazing [[https://github.com/jkitchin/org-ref][org-ref]] mode by John Kitchin.



* Installation



org-bib mode depends on [[https://github.com/rougier/pdf-drop-mode][pdf-drop-mode]] and [[https://github.com/rougier/org-imenu/][org-imenu]] that needs to be installed. For example using [[https://github.com/radian-software/straight.el][straight.el]]:



#+begin_src emacs-lisp



(straight-use-package

 '(org-imenu :type git :host github :repo "rougier/org-imenu"))



(straight-use-package

 '(pdf-drop-mode :type git :host github :repo "rougier/pdf-drop-mode"))



#+end_src



* Configuration



The minimal document structure is a document with a single level headline that is used to store new entries. It is configurable via the [[help:org-bib-unsorted-header][org-bib-unsorted-header]] variable (default is "Unsorted").



#+begin_example

  #+LIBRARY-PATH: ~/Documents

  #+LIBRARY-FILE: ~/Documents/my-bibliography.bib

  

  * Unsorted

#+end_example



You need to ensure [[help:pdf-drop-exitftool-path][pdf-drop-exiftool-path]] and [[help:org-drop-pdttotext-path][pdf-drop-pdftotext-path]] points

to relevant binaries (these are needed to extract information from PDF

metadata (exiftool) or PDF content (pdftotext)). Last step is to tell org-bib

where to store PDFs. This is done via the =#+LIBRARY-PATH= keyword that you can

set at the top of your org-file. If you don't, the current directory will be

used. PDF will be copied and renamed automatically if you set the

corresponding options.



* Key bindings



| Key      | Description            | Key        | Description                |

|----------+------------------------+------------+----------------------------|

| =i=        | Show org entry         | =v i=        | Set view mode to org entry |

| =a=        | Show abstract          | =v a=        | Set view mode to abstract  |

| =n=        | Show notes             | =v n=        | Set view mode to notes     |

| ~=~        | Show preview           | =v p=        | Set view mode to preview   |

| =b=        | Show bibtex            | =v b=        | Set view mode to bibtex    |

| =u=        | Show URL               | =v u=        | Set view mode to URL       |

| =p=        | Show PDF               | =v p=        | Set view mode to PDF       |

|          |                        | =v = | Exit view mode             |

| =e=        | Export to bib file     | =f=          | Filter entries             |

| =t=        | Tag entry              | =m=          | Move entry (refile)        |

| =?=        | Mark entry unread      | =!=          | Mark entry read            |

| =M-= | Move entry down        | =M-=     | Move entry up              |

| ==    | Toggle current section | =S-=    | Toggle all sections        |

| =S-= | Next page (PDF view)   | =S-=  | Prev page (PDF view)       |

  



* *Adding an entry*



The simplest way to add a new entry is to drag and drop a PDF file onto the org buffer. The PDF will be parsed to try to identify a DOI and the corresponding bibtex item will be collected from the crossref.org server. The new entry will then be created below the *Unsorted* header (whose name is configurable) and the file will be renamed and copied to the library folder.



If this procedure fails for some reason, you can also enter a new entry manually or using the [[help:org-bib-new-from-pdf][org-bib-from-pdf, ]][[help:org-bib-new-from-doi][org-bib-from-doi]] or [[help:org-bib-new-from-bibtex][org-bib-from-bibtex]] helper functions. In the latter case, no file will be automatically associated but you can later add a file into the library folder and rename it to "year - title.pdf" (replacing year and title with the actual year and title from the entry).



* Edit an entry



An entry is made of a properties block with two sub headlines (Abstract and Notes). You can edit any properties and add or remove them. But be careful to not remove bibliographic properties or else, the conversion to bibtex may fail because of some missing fields that are required.



* *Export the bibliography*



To export the library to a bib file, you can use the [[help:org-bib-export][org-bib-export]] command

(that is bound to the =e= key on the sidebar). The export filename will be deduced from the org filename unless a =#+LIBRARY-FILE:= is defined at the top of the org file.



* Filter view



You can filter the sidebar view (=f=) usin any kind of filtes. Here are some

example searches (note the absence of spaces):



- Articles published in 1984:             YEAR=1984

- Articles published between 2000 & 2010: YEAR>1999+YEAR<2011

- Journal articles:                       TYPE={article}

- Papers by Knuth:                        AUTHOR={Knuth}

- Article published in a journal:         JOURNAL={The Computer Journal}



See also [[https://orgmode.org/worg/org-tutorials/advanced-searching.html][Advanced searching]] from the org [[https://orgmode.org/][website]].