Annotated Bibliography Template

Table of Contents

Introduction

This file describes a template for creating an annotated bibliography document using Org mode. The document is intended to be output as a pdf file and distributed as printed hard copy.

The template is distributed as annotate-biblio-template.org at https://github.com/tsdye/org-bib-template.git.

An example of its use can be found in the files 14c-workshop.org and local.bib, also at https://github.com/tsdye/org-bib-template.git.

The goal was to design a template that makes an annotated bibiliography

  • easy to build,
  • good looking, and
  • organized by topical sections and subsections.

The template relies on a working LaTeX installation that includes several common LaTeX packages, and a database manager for Emacs (table 1).

Table 1: Open source software required by the template
Software Distribution Installation
LaTeX TeX Live (Linux) See distribution instructions
  MacTeX (Mac OS X) See distribution instructions
  proTeXt (Windows) See distribution instructions
LaTeX packages biblatex Typically included with LaTeX distributions
  scrartcl Typically included with LaTeX distributions
  paralist Typically included with LaTeX distributions
  microtype Typically included with LaTeX distributions
  tex-gyre Typically included with LaTeX distributions
Ebib MELPA Path set up by ELPA

In the Org mode file, the first three heading levels are reserved for topics and sub-topics. Bibliographic entries are placed on fourth level headings. The following example shows two fourth level headlines; the first fourth level heading shows what the buffer looks like when Org mode is using descriptive links and the second is when Org mode is using literal links.

* Topic
** Sub-topic
*** Sub-sub-topic
**** ;;Bayliss Revolution
**** [[cite:bayliss09:_rollin_out_revol][;;Bayliss Revolution]]

Workflow

First, you should set the #+TITLE:, #+AUTHOR:, and #+EMAIL: keyword values.

#+TITLE: Your Title
#+AUTHOR: Your Name
#+EMAIL: Your email

I like to organize my annotated bibliographies the same way I've learned to organize projects in Org mode; I make an outline of topics and subtopics using first, second, and third level headings as necessary. Then I write whatever comes to mind for each of the headings. From then on, I insert bibliographic entries, annotate them, and revise topic and sub-topic text accordingly.

Bibliographic entries are inserted as fourth level headings, regardless of the heading level immediately preceding them. Thus, the following example will work just as well as the earlier example:

* Topic
**** ;;Bayliss Revolution

Over the years, my colleagues and I have created a master bibliography with more than 4,000 entries. This is a bit unwieldy to distribute, so I like to make a local bibliography that only contains the entries that appear in the annotated bibliography and that can be easily distributed. One way to do this, and the way that I prefer, is to open the master database and a local database in Ebib and then copy entries from master to local as the annotated bibliography is being written. This is simply achieved by exporting entries from one Ebib database to another.

Adding a bibliographic entry involves creating the fourth level headline and then pressing C-c C-b to insert the citation. Ebib will prompt for the bibliographic key, and then for three strings—one for the post-entry text, another for the pre-entry text, and finally one for the entry's description in the Org mode buffer. Typically, for an annotated bibliography the first two strings are empty.

Once that is done you should have a cite link as a fourth level headline, leaving you ready to annotate.

Options and Keywords

The following example of options and keywords is one that I used recently for an annotated bibliography of radiocarbon dating in Hawai`i. The #+OPTIONS: line lists options in order of descending importance. The option h:4 ensures that headings include LaTeX paragraphs, which are used to typeset the bibliographic entries. The option toc:3 puts all headings above the bibliographic entries into the table of contents. Depending on how much detail you want in the table of contents, this could sensibly be set to toc:2 or toc:1. Or, for a simple bibliography, even toc:nil. The options tags:nil and todo:nil ensure that none of the Org mode metadata attached to headings makes it into the exported document. The last two options are useful for LaTeX export; I like ^:{} because my BibTeX keys are configured to use underscores and I don't want parts of the keys rendered in the Org mode buffer as subscripts.

#+OPTIONS: h:4 toc:3 tags:nil todo:nil ':t ^:{}
#+LATEX_CLASS: koma-article
#+LATEX_CLASS_OPTIONS: [paper=letter,oneside,DIV=8]
#+LATEX_HEADER: \usepackage[style=verbose,backend=bibtex]{biblatex}
#+LATEX_HEADER: \addbibresource{local.bib}
#+STARTUP: entitiespretty

The #+LATEX_CLASS: keyword needs to match the class name defined below.

The #+LATEX_CLASS_OPTIONS: keyword can take any option described in the Koma Script manual. The options shown in the example: set the paper size to letter paper (Europeans might want to use a4 here, or simply get rid of the option to use the default, which is a4); formats for single-sided output, which is good for a bibliography that will be bound with a staple at the top left corner; and uses DIV to calculate the type area of the page. Longer and more complex bibliographies that will be distributed with a binding might want to use the twoside option. The integer value of the DIV option determines the size of the type area; larger integers increase the size of the type area.

The two #+LATEX_HEADER: keywords are included here, rather than in the definition of koma-article, because they are likely to change from one annotated bibliography to the next. In general, the biblatex package will always use the verbose style, but the backend will depend on which of BibTeX or Biber you are accustomed to using. The second #+LATEX_HEADER specifies the name of the bibliographic database that holds entries for the works that appear in the annotated bibliography.

The last line, which starts up Org mode with entitiespretty is just a personal preference for the look of the buffer.

User Entities

The following source code block sets up user entities that are used frequently in my work. I use the various .*macron commands to typeset Hawaiian language words with what is known in Hawaiian as a kahak\omacron{}.

The space entity is useful following a period that doesn't end a sentence. LaTeX sets a space slightly longer than an inter-word space following a sentence ending period. The space entity lets LaTeX know to set an inter-word space.

(setq org-entities-user nil)
(add-to-list 'org-entities-user '("space" "\\ " nil " " " " " " "–"))
(add-to-list 'org-entities-user '("amacron" "\\={a}" nil "&#0257" "a" "a" "ā"))
(add-to-list 'org-entities-user '("emacron" "\\={e}" nil "&#0275" "e" "e" "ē"))
(add-to-list 'org-entities-user '("imacron" "\\={\\i}" nil "&#0299" "i" "i" "ī"))
(add-to-list 'org-entities-user '("omacron" "\\={o}" nil "&#0333" "o" "o" "ō"))
(add-to-list 'org-entities-user '("umacron" "\\={u}" nil "&#0363" "u" "u" "ū"))
(add-to-list 'org-entities-user '("Amacron" "\\={A}" nil "&#0256" "A" "A" "Ā"))
(add-to-list 'org-entities-user '("Emacron" "\\={E}" nil "&#0274" "E" "E" "Ē"))
(add-to-list 'org-entities-user '("Imacron" "\\={I}" nil "&#0298" "I" "I" "Ī"))
(add-to-list 'org-entities-user '("Omacron" "\\={O}" nil "&#0332" "O" "O" "Ō"))
(add-to-list 'org-entities-user '("Umacron" "\\={U}" nil "&#0362" "U" "U" "Ū"))

LaTeX Process

The Org mode variable org-latex-pdf-process holds a list of strings, each of which is run as a shell command. Typically, several commands are needed to process a LaTeX document to produce pdf output. The following two source code blocks use a straightforward approach that should work in most cases. The source code block named set-pdf-process-bibtex uses BibTeX to process the bibliography. BibTeX has been a standard for many years in the LaTeX world. The source code block named set-pdf-process-biber uses a newer bibliography processor named Biber, which is designed to work with BibLaTeX. The choice of which one to use must be reflected in the usepackage command for BibLaTeX at the top of this file; the optional command backend takes either bibtex or biber as its value.

At a practical level, perhaps the main difference between Biber and BibTeX is how they handle special characters. The bibliographic database for BibTeX uses LaTeX commands for special characters while the database for Biber uses UTF-8 characters.

(setq org-latex-pdf-process
      '("pdflatex -interaction nonstopmode -output-directory %o %f"
        "bibtex %b"
        "pdflatex -interaction nonstopmode -output-directory %o %f"
        "pdflatex -interaction nonstopmode -output-directory %o %f"))
(setq org-latex-pdf-process
      '("pdflatex -interaction nonstopmode -output-directory %o %f"
        "biber %b"
        "pdflatex -interaction nonstopmode -output-directory %o %f"
        "pdflatex -interaction nonstopmode -output-directory %o %f"))

Cite Link

There are many ways to manage citations in Org mode. My preference is to manage the bibliography database with Ebib: a BibTeX database manager for Emacs and insert citations using a custom Org mode link. I find the work flow convenient and the look of the Org mode buffer "good enough."

The source code block named ebib-setup defines a cite command that Ebib will use to insert citations in an Org mode buffer. It inserts the BibTeX key as the path part of the link and then offers the user three prompts to enter strings separated by semi-colons as the description part of the link. The first of these typically holds a page number, the second holds a string that appears before the in-text citation (typically, something like "e.g.,"), and the third is the description of the citation visible in the Org mode buffer.

The source code block named define-biblatex-cite-link defines an Org mode link type that parses the link inserted by Ebib and outputs a correctly formatted LaTeX citation. In theory, it is possible also to export correctly formatted citations to other backends, but the link type defined here doesn't do that. The html export simply sandwiches the BibTeX key between <cite> tags and is included here as a placeholder for future development.

(setq ebib-citation-commands
      (quote ((any (("cite" "\\cite%<[%A]%>{%K}")))
              (org-mode (("cite" "[[cite:%K][%A;%A;%A]]"))))))

Koma Article

The following two source code blocks set up a LaTeX class named koma-article that is referenced near the top of the file. The koma-article class is based on the Koma script article class scrartcl, which uses a sans-serif font for headings and a serif font for body text.

The koma-article class uses fonts from the TeX Gyre collection of fonts. As explained in The New Font Project: TeX Gyre, a goal of the project was to produce good quality fonts with diacritical characters sufficient to cover all European languages as well as Vietnamese and Navajo.

The source code block named koma-article-times is based on the Times Roman font. The serif Termes font is a replacement for Times Roman, the sans-serif Heros font is a replacement for Helvetica, and the typewriter Cursor font is a replacement for Courier. The source code block named koma-article-palatino is based on the beautiful Palatino font designed by Hermann Zapf. The Pagella font is the TeX Gyre replacement for Palatino. Typographers often recommend that linespacing be increased slightly with Palatino, and this has been achieved with the addition of the linespacing command.

The Tex Gyre fonts benefit from the microtype package, which provides "subliminal refinements towards typographical perfection," including "character protrusion and font expansion, furthermore the adjustment of inter-word spacing and additional kerning, as well as hyphenatable letter spacing (tracking) and the possibility to disable all or selected ligatures."

In addition, the paralist package is used for its compact versions of the LaTeX list environments.

Finally, the newcommand is provided merely as an illustration of one way to move LaTeX declarations out of the Org file header. This one is useful in my work as an archaeologist and over the years it has crept into my BibTeX database. It shouldn't interfere with your work, but you might want to remove it or replace it with LaTeX commands that you do frequently use.

(require 'ox-latex)
(add-to-list 'org-latex-classes
             '("koma-article"
               "\\documentclass{scrartcl}
                \\usepackage{microtype}
                \\usepackage{tgtermes}
                \\usepackage[scale=.9]{tgheros}
                \\usepackage{tgcursor}
                \\usepackage{paralist}
                \\newcommand{\\rc}{$^{14}C$}"
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
(require 'ox-latex)
(add-to-list 'org-latex-classes
             '("koma-article"
               "\\documentclass{scrartcl}
                \\usepackage{microtype}
                \\usepackage{tgpagella}
                \\linespacing{1.05}
                \\usepackage[scale=.9]{tgheros}
                \\usepackage{tgcursor}
                \\usepackage{paralist}
                \\newcommand{\\rc}{$^{14}C$}"
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

Local variables

The local variables call the source code blocks defined earlier to set up the export environment. When the file annotated-biblio-template.org is opened, Emacs will prompt to allow the local variables to be executed.

The first call creates an alias for the org-sbe function, so that the old name for this function, sbe, will also be recognized.

The second call selects Times New Roman as the serif font. Alternately, this could be replaced by a call to "koma-article-palatino".

The third call sets up user entities.

The fourth call sets up the Org mode pdf process to use BibTeX. If you want to use Biber, instead, you should call "set-pdf-process-biber".

The fifth and sixth calls set up ebib to insert links into the Org mode buffer and instruct Org mode how to use those links to create LaTeX citations.

# eval: (and (fboundp 'org-sbe) (not (fboundp 'sbe)) (fset 'sbe 'org-sbe))
# eval: (sbe "koma-article-times")
# eval: (sbe "user-entities")
# eval: (sbe "set-pdf-process-bibtex")
# eval: (sbe "ebib-setup")
# eval: (sbe "define-biblatex-cite-link")

Author: Thomas S. Dye

Created: 2014-02-02 Sun 07:38

Emacs 24.3.1 (Org mode 8.2.5c)

Validate