Annotated Bibliography Template

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 annotated-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, optionally, a bibliography database manager for Emacs (table 1).

Table 1: Open source software used 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 (optional)	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.

* Topic
** Sub-topic
*** Sub-sub-topic
**** [cite//b: @stuiver86]

First, you should set the #+TITLE:, #+AUTHOR:, #+EMAIL:, and #+EXPORT_FILE_NAME options at the top of the buffer.

#+TITLE: Your Title
#+AUTHOR: Your Name
#+EMAIL: Your email
#+EXPORT_FILE_NAME: Your file name

The other options at the top of the buffer assume the bibliographic database is named local.bib and that it resides somewhere LaTeX can find it, and that the annotated bibliography will be printed single sided on letter paper. These other options are described below, in case you want to change them.

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 as fourth level headings, 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
**** [cite//b: @stuiver86]

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 create a dependent database in Ebib and then add entries to it with M-x ebib-insert-citation as the annotated bibliography is being written. Adding an entry to the annotated bibliography involves creating the fourth level headline and then inserting a citation with the default style and bare variant, [cite//b: ...], which corresponds with the BibLaTeX cite command. I do this with Ebib, as outlined below, but in practice you are free to use whatever method suits you. Once that is done you should have an Org citation as a fourth level headline, leaving you ready to annotate.

When you are finished adding annotated entries, then export the buffer to LaTeX in the usual way.

The following example of options and keywords is one that I used 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 underscores.

#+name: ante-matter
#+begin_example
,#+OPTIONS: h:4 toc:3 tags:nil todo:nil ':t ^:{}
,#+LATEX_CLASS: anno-bib-times
,#+LATEX_CLASS_OPTIONS: [paper=letter,oneside,DIV=8]
,#+LATEX_HEADER: \usepackage[style=verbose,backend=biber]{biblatex}
,#+LATEX_HEADER: \addbibresource{local.bib}
,#+BIBLIOGRAPHY: local.bib
,#+CITE_EXPORT: biblatex verbose
,#+STARTUP: entitiespretty
#+end_example

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 anno-bib-times, 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.

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 source code block uses a straightforward approach that should work in most cases. The source code block named anno-bib-biber uses a bibliography processor named Biber, which is designed to work with BibLaTeX. If you use the BibTeX processor, then this choice 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 can also use UTF-8 characters.

#+name: anno-bib-biber
#+header: :results silent
#+begin_src emacs-lisp
  (setq org-latex-pdf-process
        '("lualatex -interaction nonstopmode -output-directory %o %f"
          "biber %b"
          "lualatex -interaction nonstopmode -output-directory %o %f"
          "lualatex -interaction nonstopmode -output-directory %o %f"))
#+end_src

The LaTeX process also uses the TeX engine, LuaLaTeX, which is UTF-8 aware. An alternative here might be XeLaTeX.

There are many ways to manage citations in Org mode and you are free to use your own way. My preference is to manage the bibliography database with Ebib: a BibTeX database manager for Emacs and use its facilities to insert citations. The source code block named ebib-setup defines a cite command that Ebib will use to insert citations in an Org mode buffer. Note that if you have already set ebib-citation-commands this source code block will override your settings. If you would like to preserve your settings, then remove the corresponding line in the local variables at the bottom of this file.

#+name: ebib-setup
#+header: :results silent :exports none
#+begin_src emacs-lisp
  (setq ebib-citation-commands
        '((any (("cite" "\\cite%<[%A]%>{%K}")))
          (org-mode (("autocite" "[cite: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("autocites" "[cite: %<%A %>%(%<%A %>@%K%< %A%>%< %A%>;%)%< %A%>]")
                     ("autocite*" "[cite/na: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("fullcite" "[cite/full: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("multicite" "%<%A %>@%K%< %A%>%< %A%>;")
                     ("notecite" "[cite/l/b: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("Notecite" "[cite/l/bc: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("Pnotecite" "[cite/l/c: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("pnotecite" "[cite/l: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("textcite" "[cite/t: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("textcites" "[cite/t: %<%A %>%(%<%A %>@%K%< %A%>%< %A%>;%)%< %A%>]")
                     ("Textcite" "[cite/t/c: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("citeauthor" "[cite/a/f: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("citeauthor*" "[cite/a: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("Citeauthor" "[cite/a/cf: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("Citeauthor*" "[cite/a/c: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("citeyear" "[cite/na: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("cite" "[cite//b: %<%A %>@%K%< %A%>%< %A%>;]")
                     ("Cite" "[cite//bc: %<%A %>@%K%< %A%>%< %A%>;]"))))
#+end_src

The following source code block sets up a LaTeX class, anno-bib-times, that can be used to typeset the annotated bibliography. The LaTeX class defined here must be referenced in the #+LATEX_CLASS option near the top of the buffer. The anno-bib-times 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 anno-bib-times 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 anno-bib-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 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.

The several lines devoted to specifying a new Unicode character add a glyph for the glottal stop from Hawaiian orthography.

Finally, the newcommand is provided 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.

#+name: anno-bib-times
#+header: :results silent :exports none
#+begin_src emacs-lisp
  (require 'ox-latex)
  (add-to-list 'org-latex-classes
               '("anno-bib-times"
                 "\\documentclass{scrartcl}
                 [NO-DEFAULT-PACKAGES]
                 [PACKAGES]
                 [EXTRA]
                  \\usepackage{microtype}
                  \\usepackage{fontspec}
                  \\defaultfontfeatures{Ligatures=TeX}
                  \\setmainfont{TeX Gyre Termes}
                  \\setsansfont{TeX Gyre Heros}[Scale=MatchLowercase]
                  \\setmonofont{TeX Gyre Cursor}[Scale=MatchLowercase]
                  \\usepackage{paralist}
                  \\usepackage{graphicx}
                  \\usepackage[x11names]{xcolor}
                  \\usepackage[colorlinks=true,allcolors=Blue4]{hyperref}
                  \\usepackage{newunicodechar}
                  \\DeclareRobustCommand{\\ookina}{%
                  \\raisebox{\\dimexpr\\fontcharht\\font`A-\\height}{%
                  \\scalebox{0.8}{`}%
                         }%
                      }%
                  \\newunicodechar{ʻ}{\\ookina}
                  \\newcommand{\\rc}{$^{14}C$}"
                 ("\\section{%s}" . "\\section*{%s}")
                 ("\\subsection{%s}" . "\\subsection*{%s}")
                 ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
                 ("\\paragraph{%s}" . "\\paragraph*{%s}")
                 ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
#+end_src

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 sets up the Org LaTeX class with Times New Roman as the serif font. The second call sets up the Org mode pdf process to use the LuaLaTeX engine and Biber. The final call sets up Ebib to insert citations into the Org mode buffer. You should remove this final line if you are using another method to work with bibliographies.

# eval: (org-sbe "anno-bib-times")
# eval: (org-sbe "anno-bib-biber")
# eval: (org-sbe "ebib-setup")