exporters/anno-bib-template-worg.org

   1 #+OPTIONS: html-link-use-abs-url:nil html-postamble:auto
   2 #+OPTIONS: html-preamble:t html-scripts:t html-style:t
   3 #+OPTIONS: html5-fancy:nil tex:t
   4 #+CREATOR: <a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.3.1 (<a href="https://orgmode.org">Org</a> mode 8.2.5c)
   5 #+HTML_CONTAINER: div
   6 #+HTML_DOCTYPE: xhtml-strict
   7 #+HTML_HEAD:
   8 #+HTML_HEAD_EXTRA:
   9 #+HTML_LINK_HOME:
  10 #+HTML_LINK_UP:
  11 #+HTML_MATHJAX:
  12 #+INFOJS_OPT:
  13 #+TITLE: Annotated Bibliography Template
  14 #+AUTHOR: Thomas S. Dye
  15 #+EMAIL: tsd at tsdye dot com
  16
  17 * Introduction
  18 This file describes a template for creating an annotated bibliography
  19 document using Org mode. The document is intended to be output as a
  20 pdf file and distributed as printed hard copy.
  21
  22 The template is distributed as =annotate-biblio-template.org= at
  23 https://github.com/tsdye/org-bib-template.git.
  24
  25 An example of its use can be found in the files =14c-workshop.org= and
  26 =local.bib=, also at https://github.com/tsdye/org-bib-template.git.
  27
  28 The goal was to design a template that makes an annotated bibiliography
  29   - easy to build,
  30   - good looking, and
  31   - organized by topical sections and subsections.
  32
  33 The template relies on a working LaTeX installation that includes
  34 several common LaTeX packages, and a database manager for Emacs (table
  35 [[software-requirements]]).
  36
  37 #+name: software-requirements
  38 #+caption[Open source software required by the template]: *Open source software required by the template*
  39 | Software       | Distribution      | Installation                                |
  40 |----------------+-------------------+---------------------------------------------|
  41 | LaTeX          | [[http://www.tug.org/texlive][TeX Live (Linux)]]  | See distribution instructions               |
  42 |                | [[http://www.tug.org/mactex/][MacTeX (Mac OS X)]] | See distribution instructions               |
  43 |                | [[http://www.tug.org/protext/][proTeXt (Windows)]] | See distribution instructions               |
  44 | LaTeX packages | [[http://www.ctan.org/pkg/biblatex][biblatex]]          | Typically included with LaTeX distributions |
  45 |                | [[http://www.ctan.org/pkg/koma-script][scrartcl]]          | Typically included with LaTeX distributions |
  46 |                | [[http://www.ctan.org/pkg/paralist][paralist]]          | Typically included with LaTeX distributions |
  47 |                | [[http://ctan.org/tex-archive/macros/latex/contrib/microtype][microtype]]         | Typically included with LaTeX distributions |
  48 |                | [[http://www.ctan.org/pkg/tex-gyre][tex-gyre]]          | Typically included with LaTeX distributions |
  49 | [[http://joostkremers.github.io/ebib/][Ebib]]           | [[http://melpa.milkbox.net/#/][MELPA]]             | Path set up by ELPA                         |
  50
  51 In the Org mode file, the first three heading levels are reserved for
  52 topics and sub-topics. Bibliographic entries are placed on fourth
  53 level headings. The following example shows two fourth level
  54 headlines; the first fourth level heading shows what the buffer looks
  55 like when Org mode is using =descriptive links= and the second is when
  56 Org mode is using =literal links=.
  57
  58 #+name: first-eg
  59 #+begin_example
  60 ,* Topic
  61 ,** Sub-topic
  62 ,*** Sub-sub-topic
  63 ,**** ;;Bayliss Revolution
  64 ,**** [[cite:bayliss09:_rollin_out_revol][;;Bayliss Revolution]]
  65 #+end_example
  66
  67 * Workflow
  68 First, you should set the =#+TITLE:=, =#+AUTHOR:=, and =#+EMAIL:=
  69 keyword values.
  70
  71 #+begin_example
  72 ,#+TITLE: Your Title
  73 ,#+AUTHOR: Your Name
  74 ,#+EMAIL: Your email
  75 #+end_example
  76
  77 I like to organize my annotated bibliographies the same way I've
  78 learned to organize projects in Org mode; I make an outline of topics
  79 and subtopics using first, second, and third level headings as
  80 necessary. Then I write whatever comes to mind for each of the
  81 headings. From then on, I insert bibliographic entries, annotate them,
  82 and revise topic and sub-topic text accordingly.
  83
  84 Bibliographic entries are inserted as fourth level headings,
  85 regardless of the heading level immediately preceding them.  Thus, the
  86 following example will work just as well as the [[first-eg][earlier example]]:
  87
  88 #+name: first-eg
  89 #+begin_example
  90 ,* Topic
  91 ,**** ;;Bayliss Revolution
  92 #+end_example
  93
  94 Over the years, my colleagues and I have created a master bibliography
  95 with more than 4,000 entries. This is a bit unwieldy to distribute, so
  96 I like to make a local bibliography that only contains the entries
  97 that appear in the annotated bibliography and that can be easily
  98 distributed. One way to do this, and the way that I prefer, is to open
  99 the master database and a local database in [[http://joostkremers.github.io/ebib/][Ebib]] and then copy entries
 100 from master to local as the annotated bibliography is being written.
 101 This is simply achieved by [[http://joostkremers.github.io/ebib/ebib-manual.html#exporting-entries][exporting entries from one Ebib database to
 102 another]].
 103
 104 Adding a bibliographic entry involves creating the fourth level
 105 headline and then pressing =C-c C-b= to insert the citation. [[http://joostkremers.github.io/ebib/ebib-manual.html][Ebib]] will
 106 prompt for the bibliographic key, and then for three strings---one for
 107 the post-entry text, another for the pre-entry text, and finally one for
 108 the entry's description in the Org mode buffer. Typically, for an
 109 annotated bibliography the first two strings are empty.
 110
 111 Once that is done you should have a cite link as a fourth level
 112 headline, leaving you ready to annotate.
 113
 114 * Options and Keywords
 115
 116 The following example of options and keywords is one that I used
 117 recently for an annotated bibliography of radiocarbon dating in
 118 Hawai`i. The =#+OPTIONS:= line lists options in order of descending
 119 importance. The option =h:4= ensures that headings include LaTeX
 120 paragraphs, which are used to typeset the bibliographic entries. The
 121 option =toc:3= puts all headings above the bibliographic entries into
 122 the table of contents. Depending on how much detail you want in the
 123 table of contents, this could sensibly be set to =toc:2= or =toc:1=.
 124 Or, for a simple bibliography, even =toc:nil=.  The options =tags:nil=
 125 and =todo:nil= ensure that none of the Org mode metadata attached to
 126 headings makes it into the exported document. The last two options are
 127 useful for LaTeX export; I like =^:{}= because my BibTeX keys are
 128 configured to use underscores and I don't want parts of the keys
 129 rendered in the Org mode buffer as subscripts.
 130
 131 #+name: ante-matter
 132 #+begin_example
 133 ,#+OPTIONS: h:4 toc:3 tags:nil todo:nil ':t ^:{}
 134 ,#+LATEX_CLASS: koma-article
 135 ,#+LATEX_CLASS_OPTIONS: [paper=letter,oneside,DIV=8]
 136 ,#+LATEX_HEADER: \usepackage[style=verbose,backend=bibtex]{biblatex}
 137 ,#+LATEX_HEADER: \addbibresource{local.bib}
 138 ,#+STARTUP: entitiespretty
 139 #+end_example
 140
 141 The =#+LATEX_CLASS:= keyword needs to match the class name defined
 142 [[Koma Article][below]].
 143
 144 The =#+LATEX_CLASS_OPTIONS:= keyword can take any option described in
 145 the [[http://www.ctan.org/pkg/koma-script][Koma Script]] manual. The options shown in [[ante-matter][the example]]: set the paper
 146 size to letter paper (Europeans might want to use =a4= here, or simply
 147 get rid of the option to use the default, which is =a4=); formats for
 148 single-sided output, which is good for a bibliography that will be
 149 bound with a staple at the top left corner; and uses =DIV= to
 150 calculate the type area of the page.  Longer and more complex
 151 bibliographies that will be distributed with a binding might want to
 152 use the =twoside= option. The integer value of the =DIV= option
 153 determines the size of the type area; larger integers increase the
 154 size of the type area.
 155
 156 The two =#+LATEX_HEADER:= keywords are included here, rather than in
 157 the definition of [[Koma%20Article][koma-article]], because they are likely to change from
 158 one annotated bibliography to the next.  In general, the =biblatex=
 159 package will always use the =verbose= style, but the backend will
 160 depend on which of BibTeX or Biber you are accustomed to using.  The
 161 second =#+LATEX_HEADER= specifies the name of the bibliographic
 162 database that holds entries for the works that appear in the annotated
 163 bibliography.
 164
 165 The last line, which starts up Org mode with =entitiespretty= is just
 166 a personal preference for the look of the buffer.
 167
 168 * User Entities
 169 The following source code block sets up user entities that are used frequently
 170 in my work. I use the various =.*macron= commands to typeset Hawaiian
 171 language words with what is known in Hawaiian as a /kahak\omacron{}/.
 172
 173 The =space= entity is useful following a period that doesn't end a
 174 sentence. LaTeX sets a space slightly longer than an inter-word space
 175 following a sentence ending period. The =space= entity lets LaTeX know
 176 to set an inter-word space.
 177
 178 #+name: user-entities
 179 #+begin_src emacs-lisp
 180   (setq org-entities-user nil)
 181   (add-to-list 'org-entities-user '("space" "\\ " nil " " " " " " "–"))
 182   (add-to-list 'org-entities-user '("amacron" "\\={a}" nil "&#0257" "a" "a" "ā"))
 183   (add-to-list 'org-entities-user '("emacron" "\\={e}" nil "&#0275" "e" "e" "ē"))
 184   (add-to-list 'org-entities-user '("imacron" "\\={\\i}" nil "&#0299" "i" "i" "ī"))
 185   (add-to-list 'org-entities-user '("omacron" "\\={o}" nil "&#0333" "o" "o" "ō"))
 186   (add-to-list 'org-entities-user '("umacron" "\\={u}" nil "&#0363" "u" "u" "ū"))
 187   (add-to-list 'org-entities-user '("Amacron" "\\={A}" nil "&#0256" "A" "A" "Ā"))
 188   (add-to-list 'org-entities-user '("Emacron" "\\={E}" nil "&#0274" "E" "E" "Ē"))
 189   (add-to-list 'org-entities-user '("Imacron" "\\={I}" nil "&#0298" "I" "I" "Ī"))
 190   (add-to-list 'org-entities-user '("Omacron" "\\={O}" nil "&#0332" "O" "O" "Ō"))
 191   (add-to-list 'org-entities-user '("Umacron" "\\={U}" nil "&#0362" "U" "U" "Ū"))
 192 #+end_src
 193 * LaTeX Process
 194 The Org mode variable =org-latex-pdf-process= holds a list of strings,
 195 each of which is run as a shell command. Typically, several commands
 196 are needed to process a LaTeX document to produce pdf output. The
 197 following two source code blocks use a straightforward approach that
 198 should work in most cases. The source code block named
 199 [[set-pdf-process-bibtex][set-pdf-process-bibtex]] uses [[http://www.bibtex.org/Using/][BibTeX]] to process the bibliography. BibTeX
 200 has been a standard for many years in the LaTeX world. The source code
 201 block named [[set-pdf-process-biber][set-pdf-process-biber]] uses a newer bibliography processor
 202 named [[http://biblatex-biber.sourceforge.net/][Biber]], which is designed to work with [[http://www.ctan.org/pkg/biblatex][BibLaTeX]].  The choice of
 203 which one to use must be reflected in the =usepackage= command for
 204 BibLaTeX at the top of this file; the optional command =backend= takes
 205 either =bibtex= or =biber= as its value.
 206
 207 At a practical level, perhaps the main difference between Biber and
 208 BibTeX is how they handle special characters. The bibliographic
 209 database for BibTeX uses LaTeX commands for special characters while
 210 the database for Biber uses UTF-8 characters.
 211
 212 #+name: set-pdf-process-bibtex
 213 #+header: :results silent
 214 #+begin_src emacs-lisp
 215   (setq org-latex-pdf-process
 216         '("pdflatex -interaction nonstopmode -output-directory %o %f"
 217           "bibtex %b"
 218           "pdflatex -interaction nonstopmode -output-directory %o %f"
 219           "pdflatex -interaction nonstopmode -output-directory %o %f"))
 220 #+end_src
 221
 222 #+name: set-pdf-process-biber
 223 #+header: :results silent
 224 #+begin_src emacs-lisp
 225   (setq org-latex-pdf-process
 226         '("pdflatex -interaction nonstopmode -output-directory %o %f"
 227           "biber %b"
 228           "pdflatex -interaction nonstopmode -output-directory %o %f"
 229           "pdflatex -interaction nonstopmode -output-directory %o %f"))
 230 #+end_src
 231
 232 * Cite Link
 233 There are many ways to manage citations in Org mode. My preference is
 234 to manage the bibliography database with [[http://joostkremers.github.io/ebib/][Ebib: a BibTeX database
 235 manager for Emacs]] and insert citations using a custom Org mode link. I
 236 find the work flow convenient and the look of the Org mode buffer
 237 "good enough."
 238
 239 The source code block named [[ebib-setup][ebib-setup]] defines a cite command that
 240 [[http://joostkremers.github.io/ebib/][Ebib]] will use to insert citations in an Org mode buffer. It inserts
 241 the BibTeX key as the path part of the link and then offers the user
 242 three prompts to enter strings separated by semi-colons as the
 243 description part of the link. The first of these typically holds a
 244 page number, the second holds a string that appears before the in-text
 245 citation (typically, something like "e.g.,"), and the third is the
 246 description of the citation visible in the Org mode buffer.
 247
 248 The source code block named [[define-biblatex-cite-link][define-biblatex-cite-link]] defines an Org
 249 mode link type that parses the link inserted by [[http://joostkremers.github.io/ebib/][Ebib]] and outputs a
 250 correctly formatted LaTeX citation. In theory, it is possible also to
 251 export correctly formatted citations to other backends, but the link
 252 type defined here doesn't do that. The html export simply sandwiches
 253 the BibTeX key between =<cite>= tags and is included here as a
 254 placeholder for future development.
 255
 256 #+name: ebib-setup
 257 #+begin_src emacs-lisp
 258   (setq ebib-citation-commands
 259         (quote ((any (("cite" "\\cite%<[%A]%>{%K}")))
 260                 (org-mode (("cite" "[[cite:%K][%A;%A;%A]]"))))))
 261 #+end_src
 262
 263 #+name: define-biblatex-cite-link
 264 #+begin_src emacs-lisp :results silent
 265   (org-add-link-type
 266    "cite" 'ebib
 267    (lambda (path desc format)
 268      (cond
 269       ((eq format 'html)
 270        (format "(<cite>%s</cite>)" path))
 271       ((eq format 'latex)
 272        (if (or (not desc) (equal 0 (search "cite:" desc)))
 273            (format "\\cite{%s}" path)
 274          (format "\\cite[%s][%s]{%s}"
 275                  (cadr (split-string desc ";"))
 276                  (car (split-string desc ";"))  path))))))
 277 #+end_src
 278
 279 * Koma Article
 280 The following two source code blocks set up a LaTeX class named
 281 =koma-article= that is referenced near the top of the file. The
 282 =koma-article= class is based on the [[http://www.ctan.org/pkg/koma-script][Koma script]] article class
 283 =scrartcl=, which uses a sans-serif font for headings and a serif font
 284 for body text.
 285
 286 The =koma-article= class uses fonts from the [[http://www.gust.org.pl/projects/e-foundry/tex-gyre/][TeX Gyre collection of
 287 fonts]]. As explained in [[http://www.gust.org.pl/projects/e-foundry/tex-gyre/tb87hagen-gyre.pdf][The New Font Project: TeX Gyre]], a goal of the
 288 project was to produce good quality fonts with diacritical characters
 289 sufficient to cover all European languages as well as Vietnamese and
 290 Navajo.
 291
 292 The source code block named [[koma-article-times][koma-article-times]] is based on the Times
 293 Roman font. The serif Termes font is a replacement for Times Roman,
 294 the sans-serif Heros font is a replacement for Helvetica, and the
 295 typewriter Cursor font is a replacement for Courier. The source code
 296 block named [[koma-article-palatino][koma-article-palatino]] is based on the beautiful Palatino
 297 font designed by Hermann Zapf. The Pagella font is the TeX Gyre
 298 replacement for Palatino. Typographers often recommend that
 299 linespacing be increased slightly with Palatino, and this has been
 300 achieved with the addition of the =linespacing= command.
 301
 302 The Tex Gyre fonts benefit from the [[http://ctan.org/tex-archive/macros/latex/contrib/microtype][microtype package]], which provides
 303 "subliminal refinements towards typographical perfection," including
 304 "character protrusion and font expansion, furthermore the adjustment
 305 of inter-word spacing and additional kerning, as well as hyphenatable
 306 letter spacing (tracking) and the possibility to disable all or
 307 selected ligatures."
 308
 309 In addition, the [[http://www.ctan.org/tex-archive/macros/latex/contrib/paralist/][paralist package]] is used for its compact versions of
 310 the LaTeX list environments.
 311
 312 Finally, the =newcommand= is provided merely as an illustration of one
 313 way to move LaTeX declarations out of the Org file header. This one is
 314 useful in my work as an archaeologist and over the years it has crept
 315 into my BibTeX database. It shouldn't interfere with your work, but
 316 you might want to remove it or replace it with LaTeX commands that you
 317 do frequently use.
 318
 319 #+name: koma-article-times
 320 #+header: :results silent
 321 #+begin_src emacs-lisp
 322    (require 'ox-latex)
 323    (add-to-list 'org-latex-classes
 324                 '("koma-article"
 325                   "\\documentclass{scrartcl}
 326                    \\usepackage{microtype}
 327                    \\usepackage{tgtermes}
 328                    \\usepackage[scale=.9]{tgheros}
 329                    \\usepackage{tgcursor}
 330                    \\usepackage{paralist}
 331                    \\newcommand{\\rc}{$^{14}C$}"
 332                   ("\\section{%s}" . "\\section*{%s}")
 333                   ("\\subsection{%s}" . "\\subsection*{%s}")
 334                   ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
 335                   ("\\paragraph{%s}" . "\\paragraph*{%s}")
 336                   ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
 337 #+end_src
 338
 339 #+name: koma-article-palatino
 340 #+header: :results silent
 341 #+begin_src emacs-lisp
 342    (require 'ox-latex)
 343    (add-to-list 'org-latex-classes
 344                 '("koma-article"
 345                   "\\documentclass{scrartcl}
 346                    \\usepackage{microtype}
 347                    \\usepackage{tgpagella}
 348                    \\linespacing{1.05}
 349                    \\usepackage[scale=.9]{tgheros}
 350                    \\usepackage{tgcursor}
 351                    \\usepackage{paralist}
 352                    \\newcommand{\\rc}{$^{14}C$}"
 353                   ("\\section{%s}" . "\\section*{%s}")
 354                   ("\\subsection{%s}" . "\\subsection*{%s}")
 355                   ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
 356                   ("\\paragraph{%s}" . "\\paragraph*{%s}")
 357                   ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
 358 #+end_src
 359
 360 * Local variables
 361
 362 The [[local-vars-eg][local variables]] call the source code blocks defined earlier to set
 363 up the export environment. When the file
 364 =annotated-biblio-template.org= is opened, Emacs will prompt to allow
 365 the local variables to be executed.
 366
 367 The first call creates an alias for the =org-sbe= function, so that
 368 the old name for this function, =sbe=, will also be recognized.
 369
 370 The second call selects Times New Roman as the serif font.
 371 Alternately, this could be replaced by a call to
 372 "koma-article-palatino".
 373
 374 The third call sets up user entities.
 375
 376 The fourth call sets up the Org mode pdf process to use BibTeX. If you
 377 want to use Biber, instead, you should call "set-pdf-process-biber".
 378
 379 The fifth and sixth calls set up ebib to insert links into the Org
 380 mode buffer and instruct Org mode how to use those links to create
 381 LaTeX citations.
 382
 383 #+name: local-vars-eg
 384 #+begin_example
 385 # eval: (and (fboundp 'org-sbe) (not (fboundp 'sbe)) (fset 'sbe 'org-sbe))
 386 # eval: (sbe "koma-article-times")
 387 # eval: (sbe "user-entities")
 388 # eval: (sbe "set-pdf-process-bibtex")
 389 # eval: (sbe "ebib-setup")
 390 # eval: (sbe "define-biblatex-cite-link")
 391 #+end_example
 392