Support via Liberapay

LaTeX Export for Org Mode < 8.0

1. Start up

Org-mode LaTeX export is easy. Place the following code in your .emacs and you're ready to go.

(require 'ox-latex)
(unless (boundp 'org-latex-classes)
  (setq org-latex-classes nil))
(add-to-list 'org-latex-classes
             '("article"
               "\\documentclass{article}"
               ("\\section{%s}" . "\\section*{%s}")))

This tells the Org-mode LaTeX exporter to use the standard LaTeX article document class by default and to map Org-mode headlines and lists to LaTeX sectioning and list commands, as follows:

* section
** itemize
*** itemize, etc.
,    - itemize

Now you can pick a LaTeX export command from the export menu, C-c C-e, and expect to find a well-formed LaTeX document with the same base name as your org-mode buffer.

It could hardly be easier!

2. Why LaTeX Export?

As the manual says, "Org is a mode for keeping notes, maintaining TODO lists, and doing project planning with a fast and effective plain-text system." LaTeX is a convenient interface to TeX, a typesetting system that its author "intended for the creation of beautiful books — and especially for books that contain a lot of mathematics." Where do these two activities–keeping notes and making beautiful books–overlap?

Org-mode is well supplied with a variety of other exporters. The Org ASCII exporter produces a readable and simple version of an Org file for printing and sharing of notes. The HTML exporter does such a good job of preparing notes for the web that many people use it to create entire web sites. The XOXO exporter makes notes accessible to other software applications and the DocBook exporter starts the journey to many other formats, including LaTeX, using DocBook tools.

The niche for the LaTeX exporter is producing a version of an Org file for printing and sharing notes that looks better than an ASCII printout but that can be produced without the overhead required to support DocBook. All that is needed is a working LaTeX installation. LaTeX distributions for all major platforms are today well-developed and easy to use and maintain.

3. More Highly-Structured Documents

You can prepare more highly structured LaTeX documents by adding a few lines to org-latex-classes in .emacs.

(add-to-list 'org-latex-classes
             '("article"
               "\\documentclass{article}"
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

This setup produces the following document structure:

* section
** subsection
*** subsubsection
**** paragraph
***** subparagraph
****** itemize, etc.
,       - itemize

4. Exporting Other LaTeX Document Classes

The LaTeX exporter can be configured to produce LaTeX output for books, reports, letters or any other document class, including custom classes. These can be useful if notes need to be formatted to a certain specification, such as a company technical manual, or if the notes are quite long, as might be the case when Org-mode is used as a laboratory or project notebook.

Here is a standard setup for export to a LaTeX book class:

(add-to-list 'org-latex-classes
             '("book"
               "\\documentclass{book}"
               ("\\part{%s}" . "\\part*{%s}")
               ("\\chapter{%s}" . "\\chapter*{%s}")
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
             )

Then, in the Org file with a book-full of notes, add this line:

#+LaTeX_CLASS: book

A useful set of alternatives is the KOMA script classes. These have a somewhat more modern design than the standard LaTeX classes.

For example, the KOMA script article class can be configured in .emacs:

(add-to-list 'org-latex-classes
          '("koma-article"
             "\\documentclass{scrartcl}"
             ("\\section{%s}" . "\\section*{%s}")
             ("\\subsection{%s}" . "\\subsection*{%s}")
             ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
             ("\\paragraph{%s}" . "\\paragraph*{%s}")
             ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

Then, this class can be used by including the following line in the Org-mode file.

#+LaTeX_CLASS: koma-article

5. Passing Options to Document Classes

The standard LaTeX document classes, article, report, book, slides, and letter take options that, where applicable, select the type size, paper size, orientation, whether to print one- or two-sided, and a variety of formatting specifications. Custom LaTeX document classes can define their own options, as needed.

You can pass options to the LaTeX \documentclass macro by putting a line like this in your Org-mode file:

#+LaTeX_CLASS_OPTIONS: [a4paper,twoside,twocolumn]

A useful option with the KOMA script classes typesets table captions properly. The standard LaTeX classes will incorrectly typeset table captions exported by Org-mode above the table. The following option to the KOMA script classes accomplishes this.

#+LaTeX_CLASS_OPTIONS: [captions=tableheading]

6. Using Custom Classes

If the user has custom LaTeX document classes that conflict with the default packages or that only require a few of the default packages to support all features of the LaTeX exporter, then this can be handled in .emacs using [DEFAULT-PACKAGES], [NO-DEFAULT-PACKAGES], [PACKAGES], [NO-PACKAGES], [EXTRA], [NO-EXTRA].

Here is a simple example that uses an experimental LaTeX class1 that supports the Org-mode requirements and leaves open the possibility of adding file specific packages:

(add-to-list 'org-latex-classes
      '("org-article"
         "\\documentclass{org-article}
         [NO-DEFAULT-PACKAGES]
         [PACKAGES]
         [EXTRA]"
         ("\\section{%s}" . "\\section*{%s}")
         ("\\subsection{%s}" . "\\subsection*{%s}")
         ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
         ("\\paragraph{%s}" . "\\paragraph*{%s}")
         ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

The Org-mode LaTeX exporter uses several packages to support special characters used by org-entities. One of these, amssymb, conflicts with several LaTeX fonts. If you want finer control over which packages are loaded, then it makes sense to define an export class like this in .emacs:

(add-to-list 'org-latex-classes
          '("koma-article"
             "\\documentclass{scrartcl}
             [NO-DEFAULT-PACKAGES]
             [EXTRA]"
             ("\\section{%s}" . "\\section*{%s}")
             ("\\subsection{%s}" . "\\subsection*{%s}")
             ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
             ("\\paragraph{%s}" . "\\paragraph*{%s}")
             ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

Alternatively, export classes can be defined on a per-file basis in a source code block that is evaluated prior to LaTeX export. This is perhaps the most flexible way to set up LaTeX export. Since the add-to-list is a globally side-effecting action, this example only calls it if it would add a LaTeX class that isn't already on the org-latex-classes list:

 #+name: setup
 #+begin_src emacs-lisp :results silent :exports none
(unless (find "per-file-class" org-latex-classes :key 'car
          :test 'equal)
  (add-to-list 'org-latex-classes
           '("per-file-class"
              "\\documentclass{scrartcl}
              [NO-DEFAULT-PACKAGES]
              [EXTRA]"
              ("\\section{%s}" . "\\section*{%s}")
              ("\\subsection{%s}" . "\\subsection*{%s}")
              ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
              ("\\paragraph{%s}" . "\\paragraph*{%s}")
              ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
 #+end_src

Then, add this line to the Org-mode file:

#+LaTeX_CLASS: per-file-class

7. Specifying LaTeX Packages

According to its author, the LaTeX macro package "represents a balance between functionality and ease of use." The LaTeX user who adds functionality through the addition of packages necessarily makes the software more difficult to use. Like LaTeX itself, the Org-mode LaTeX exporter has struck its own balance between functionality and ease of use with the addition of several LaTeX packages. These are written out in the LaTeX header as LaTeX \usepackage commands.

Org-mode keeps the names of the LaTeX packages it uses in a data structure designed for ease of maintenance as additional features are added to the LaTeX exporter. Packages in the default packages list, org-latex-default-packages-alist, are required to support all features of the LaTeX exporter. This list is typically specified in the Org-mode source code and its documentation contains a warning not to modify it. Packages not included on the default packages list that the user needs consistently can be added to org-latex-packages-alist.

If you want to specify particular packages, either in addition to or in place of those used by Org-mode, then you can either place them in a custom class definition, where they can be used by any Org-mode document, or you can add them to the Org-mode document directly so their effect is local to the Org-mode buffer.

An example custom class definition that adds the graphicx package might look like this in .emacs:

(add-to-list 'org-latex-classes
             '("per-file-class"
               "\\documentclass{scrartcl}
                 \\usepackage{graphicx}
            [NO-DEFAULT-PACKAGES]
            [NO-PACKAGES]"
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

Packages needed for a particular file can be specified by inserting a line like this in the Org-mode buffer:

#+LATEX_HEADER: \usepackage{xyz}

One reason for specifying LaTeX packages in the Org-mode buffer is that highly configurable packages can be tailored for a particular use. Perhaps the best example among the packages in org-latex-default-packages-alist is hyperref, which has an elaborate list of keyval options. PDF output destined for interactive use might load hyperref with options to distinguish links with attractive colors, for instance. This might be achieved with following lines, which load the xcolor package2 and then use named colors to distinguish external blue links from internal red links:

#+LATEX_HEADER: \usepackage[hyperref,x11names]{xcolor}
#+LATEX_HEADER: \usepackage[colorlinks=true,urlcolor=SteelBlue4,linkcolor=Firebrick4]{hyperref}

In addition, you can pick up the encoding used in the Org-mode buffer and pass this information on to LaTeX by loading the inputenc package as follows:

#+LATEX_HEADER: \usepackage[AUTO]{inputenc}

8. Creating PDF Output

The LaTeX exporter by default produces code ready for processing by pdflatex. pdflatex calls the pdfTeX program, a modern extension of TeX that produces PDF output directly, using the standard LaTeX macros. pdfTeX is tightly integrated with PDF features such as hypertext links and tables of contents, using LaTeX packages such as hyperref, which is included in the default packages list.

Org-mode offers a command to produce a PDF file from the LaTeX export. This is bound to C-c C-e p. The command C-c C-e d does all this and opens the PDF file in the default reader.

If you use a different TeX typesetting engine or would like to customize how Org-mode produces the pdf file, then you will want to modify the variable org-latex-to-pdf-process. This is a list of strings, each of which contains a call to one of the TeX typesetting engines or to an auxiliary program, such as BibTeX, makeindex, etc.

For example, the shell script texi2dvi will run pdflatex as many times as needed to build a pdf file successfully. The following code in .emacs will instruct Org-mode to use texi2dvi when making a pdf file. Note that you should check that texi2dvi is installed on your system and that it works correctly before adding this code to your .emacs.

(setq org-latex-to-pdf-process '("texi2dvi --pdf --clean --verbose --batch %f"))

Note that makeindex and bibtex require a bit more effort to work in this way because of path name issues. Nick Dokos suggested this fix, which specifies a path to one or more BibTeX .bib files:

#+begin_src sh :exports none
  BIBINPUTS=/path/to/bib/:$BIBINPUTS
  export BIBINPUTS
#+end_src

If you have system-wide bibliography and index files, then it might be useful to modify BIBINPUTS in .profile or similar. The code example above uses Babel to set the variable on a per-file basis.

An alternative to the default TeX engine is XeTeX, which merges TeX with Unicode and modern font technologies. The Emacs-Fu blog has an example XeTeX setup for Org-mode. There is also an entry in the Org-Mode FAQ entitled How can I use XeLaTeX for LaTeX export instead of pdfLaTeX?

9. Exporting Parts of an Org-mode Buffer

Tags can be used to select which parts of an Org-mode buffer are sent to the LaTeX exporter. In the typical case, the Org-mode buffer contains material for a single export file along with material that shouldn't appear in the export; tags distinguish the export parts from the non-export parts. This is the single export case. It is also possible to use tags to specify multiple export targets in a single Org-mode buffer. In the multiple export case, tags are resolved by a publishing management system.

9.1. The Single Export Case

The tags used for the single export case are held in two variables: org-export-select-tags is a list of tags, initially set to export, that select a tree or sub-tree for export; org-export-exclude-tags is a list of tags, initially set to noexport, that exclude a tree or subtree for export. The effect they have on export is logical, but the logic isn't necessarily what one might expect. In particular, if both select tags and exclude tags are to be used in the same buffer, then their use must follow certain rules. Also, the handling of unmarked trees and subtrees changes depending on which tags are used and how they are used.

If neither select tags nor exclude tags are used, then all of the trees and their subtrees are sent to the LaTeX exporter. If, however, a select tag is added to a tree as in the example below, then unmarked trees will not be sent to the exporter. Thus, the effect of a select tag is not restricted to its tree; its effect extends to the entire buffer.

* Tree 1                                                             :export:
,   This is exported
** Subtree 1
,   This is also exported
* Tree 2
,  This is not exported
** Subtree 2
,  This is not exported, either

Once the scope of the tag's effect is grasped, the primary rule of using select and exclude tags is obvious: only one type of tag may be used for the trees of a buffer. If both types of tags are used for trees, how can Org-mode decide what to do with the unmarked trees?

A corollary of this rule is that the other type of tag can only be used in a subtree of the tagged tree in order to reverse the effect of the tree-level tag, as in the following example.

* Tree 1                                                             :export:
,   This is exported
** Subtree 1                                                       :noexport:
,   This is not exported
* Tree 2
,  This is not exported
** Subtree 2
,  This is not exported, either

9.2. The Multiple Export Case

In the multiple export case, tags used to select a tree or subtree for export are defined in .emacs as part of the configuration needed to specify the many properties of a publication project. A tutorial illustrates the flexibility of the publishing mechanism using an HTML example. The intricacies of the publishing mechanism are beyond the scope of of this LaTeX export tutorial. Here, a working example3 is described.

In the example, the file index.org holds material for two export targets, one related to work items and the other related to home. The variable org-publish-project-alist has two entries, one for a project named work and the other for a project named home. Both projects are based on the file index.org located in ~/notes/org.

Both projects will create output files named index.tex, based on the name of the Org-mode file used for import. The two index.tex files are kept separate by writing them to different directories, as indicated by the keyword argument :publishing-directory.

(setq org-publish-project-alist
      '(
        ("work"
         :base-directory "~/notes/org/"
         :base-extension "org"
         :publishing-directory "~/notes/export/work/"
         :publishing-function org-publish-org-to-latex
         :select-tags     ("@WORK")
         :title "Work Notes"
         :include ("index.org")
         :exclude "\\.org$"
         )
        ("home"
         :base-directory "~/notes/org/"
         :base-extension "org"
         :publishing-directory "~/notes/export/home/"
         :publishing-function org-publish-org-to-latex
         :select-tags     ("@HOME")
         :title "Home Phone"
         :include ("index.org")
         :exclude "\\.org$"
         )
        ))

The parts of index.org tagged @WORK can now be exported to ~/notes/export/work/index.tex with C-c C-e X and selecting the work project.

Similarly, the parts of index.org tagged @HOME can now be exported to ~/notes/export/home/index.tex with C-c C-e X and selecting the home project.

10. Markup

Org-mode provides wiki-like markup for various display characteristics. This is often handy and it translates directly into LaTeX, but the design philosophy of LaTeX is centered around semantic markup, "what you say is what you mean" rather than "what you see is what you get" (lampooned by zealous LaTeX users as "what you see is all you get"). In practice, LaTeX users define common semantic elements in a LaTeX class or style file and these are marked up in text with commands often peculiar to the class or style file. Clearly, there is no way that Org-mode can anticipate commands peculiar to arbitrary class or style files. Fortunately, Org-mode provides facilities to define special characters and to specify inline and block-level markup.

10.1. Special Characters

The variable org-entities-user holds the information needed to define special characters. In response to a question posed by Rasmus Pank Roulund, Lawrence Mitchell described how to use this variable to define an escaped space, which is used in LaTeX to insert a single space, instead of a double space, after a period that doesn't end a sentence.

With this definition:

(setq org-entities-user '(("space" "\\ " nil " " " " " " " ")))

then

this is some text, e.g.\space foo bar

is exported as

this is some text, e.g.\  foo bar

10.2. Block-level Markup

For simple block-level arbitrary markup, you can use the contributed package org-special-blocks, which turns #+begin_foo into \begin{foo} upon LaTeX export. You can use ordinary Org markup inside the block. For example, you can wrap an abstract in

#+BEGIN_ABSTRACT
This is an *abstract* with ordinary =Org-mode= /markup/.
#+END_ABSTRACT

For more complex cases, where you need to pass parameters or process block contents, but don't want to use literal LaTeX, you may want to explore the possibilities of the contributed org-exp-blocks package.

An example of block-level markup for a results block that will be typeset with a shaded background:

#+LaTeX_HEADER: \usepackage{framed}
#+LaTeX_HEADER: \usepackage{xcolor}
#+LaTeX_HEADER: \definecolor{shadecolor}{gray}{.95}
#+LaTeX_HEADER: \newenvironment{results}{\begin{shaded}}{\end{shaded}}

10.3. Inline Markup

Inline arbitrary semantic markup can be implemented by defining a new link type in .emacs.4 The following code block defines a new link type, latex, whose path argument can hold the name of any LaTeX command. This one defines export markup for HTML and LaTeX. A link such as [latex:proglang][Org-mode] will export \proglang{Org-mode} to the LaTeX file. In this way, it is possible to make the Org-mode LaTeX exporter conform to the semantic markup defined in arbitrary style files. Org-mode will even complete your new link type!

(org-add-link-type
 "latex" nil
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "<span class=\"%s\">%s</span>" path desc))
    ((eq format 'latex)
     (format "\\%s{%s}" path desc)))))

Two examples of LaTeX commands for inline semantic markup:

#+LaTeX_HEADER: \let\progstruct=\texttt
#+LaTeX_HEADER: \newcommand{\progexample}[1]{{\ttfamily\small #1}}

10.4. Captions

The LaTeX caption command is typically passed two arguments: the required argument, which is typeset with the figure or table; and the optional argument, which appears in the List of Figures or List of Tables. It is common nowadays, especially in the sciences, to have long captions (actually captions plus legends) with figures and much abbreviated versions, typically less than a line long, in the List of Figures. In addition, many styles require that figure captions end with a period; the caption passed to the List of Figures should not end in a period.

The Org-mode #+CAPTION: macro handles an optional argument.

This construct:

#+CAPTION[Short caption]: Long caption.

exports:

\caption[Short caption]{Long caption.}

11. Styling the Frontmatter

The Org-mode LaTeX exporter requires configuration to gain full access to the LaTeX frontmatter formatting capacity.

11.1. Abstract, contents, and lists of figures and tables

In the default configuration, the Org-mode LaTeX exporter includes a function that sandwiches the LaTeX \tableofcontents command between a command that sets the depth of the headings that appear in the table of contents (based on the number of headline levels that will be exported as headings, rather than lists) and a command to add some vertical space. Neither of these additions to the \tableofcontents command is especially desireable. It is often the case that one wants the table of contents depth to differ from the depth to which sections are numbered. Also, in the LaTeX world, the space between the end of one element and the start of another is something that is specified within a class or style file, rather than within the document itself. Formatting with the class or style file exclusively can give the finished document a pleasing stylistic uniformity that is difficult to achieve in an ad hoc way. Also, hardwiring the table of contents in this way always puts it directly following the output of the LaTeX maketitle command. In practice, however, it is often useful to print an abstract or executive summary between the title and the table of contents. Fortunately, the LaTeX exporter is coded in such a way that it is possible for the user to alter this behavior relatively easily.

(defun org-export-latex-no-toc (depth)
    (when depth
      (format "%% Org-mode is exporting headings to %s levels.\n"
              depth)))
  (setq org-export-latex-format-toc-function 'org-export-latex-no-toc)

With this setup, place the abstract and #+LATEX: commands for frontmatter before the first exported headline, e.g.,

#+BEGIN_abstract
  [Abstract here]
#+END_abstract
#+LATEX: \tableofcontents
#+LATEX: \listoftables
#+LATEX: \listoffigures
* First Exported Headline

11.2. Titles and Title Page Layout

The default title created by the LaTeX exporter is often just fine, but in cases where you would like to include specific information in the title, or create a custom title page, then perhaps the best way to do this was posted to the Org-mode list by Nick Dokos:

#+LATEX_HEADER: \input{mytitle}

* Foo
 foo

* Bar
 bar

where the file mytitle.tex looks like this:

\renewcommand\maketitle{\begin{titlepage}%
FOO
\end{titlepage}%
}

12. Exporting Listings

12.1. Exporting Pseudo-Code

The LaTeX exporter will fontify exported code blocks written in any language that has an associated Emacs mode for editing. If you want to export pseudo-code, for which there is no corresponding Emacs mode, then one approach is to use #+begin_latex ... #+end_latex and write the pseudo-code directly in LaTeX. This depends on the LaTeX listings package, which is one of the default packages used by Org-mode.

Dan Davison provided this example on the Org-mode list:

#+begin_latex
\begin{algorithm}
 \caption{An algorithm}
 \label{alg:myalg}
 \begin{lstlisting}[mathescape,escapeinside='']
   '\foreach individual $i$'
       '\foreach group $k$'
           $\gamma_{ik} \getsp Q_{k}\prod_{l}\prod_{a=1}^{2}P_{lkX_{ila}}$
 \end{lstlisting}
\end{algorithm}
#+end_latex

12.2. Typesetting and Fontifying Source Code

Org-mode supports two LaTeX packages for typesetting and fontifying source code; listings and minted. The listings package is a pure LaTeX implementation that works reasonably well, but the package appears to be orphaned and the latest documentation was written in 2007. In contrast, the minted package is not a pure LaTeX solution and relies on an external Python script, pygmentize, to typeset and fontify source code. This package appears to be actively maintained. Both packages are included in the TeXLive and MacTeX LaTeX distributions. If your distribution lacks one or the other, then you'll need to check the documentation for instructions how to install them.

The two packages are structured somewhat differently, but it is possible to configure Org-mode so that these differences are mostly smoothed over, making it possible to generate LaTeX code that will work with either package. The two main differences have to do with the minted package's generation of language names by appending code to the language name; this convention is not followed by the listings package. In addition, the minted package defines styles, by which it means colorizing semantic elements of the programming language. This facility is not implemented in the listings package.

The following sections show the basics of listings and minted setups which, when exported to LaTeX, illustrate the ability of each package to typeset and fontify source code on a per-language basis.

12.3. Example minted setup

In this example, the minted package is specified in the #+LaTeX_HEADER:. This is followed by a command to use the minted style emacs, which colors source code in a way familiar to emacs users. The final #+LaTeX_HEADER: line uses the newminted macro to set the font size for code blocks of common-lisp.

The source code block setup-minted includes emacs-lisp code that might typically appear in .emacs, but can be useful in a source code block where it can be used to configure LaTeX export for an individual document. In the source code block, the variables that control LaTeX export using the minted package are configured. First, org-latex-listings is set to use the minted package. Then, the variable org-latex-custom-lang-environments is used to associate the emacs-lisp code of an Org-mode source code block with the common-lisp language that the minted package knows how to parse. Note that this is given as common-lispcode here, but as common-lisp in the call to the newminted macro. The minted package appends code to language names by default. The variable org-latex-minted-options sets typesetting options that will apply to all programming languages. See the minted package documentation for the very many options that can be set with key/val pairs. The three entries in the association list call for source code blocks to be framed with lines, set in a very small font, and identified with line numbers. In relation to these settings, the emacs-lisp code will be set at a slightly larger font size. Finally, the variable org-latex-to-pdf-process is set using the -shell-escape option so the external pygmentize program can be called and its results incorporated into the pdf document. Note that using the -shell-escape option creates security holes.

A Python source code block at the end illustrates how the default emacs-style code differs from the specially formatted emacs-lisp source code.

#+LATEX_CLASS: article
#+LaTeX_HEADER: \usepackage{minted}
#+LaTeX_HEADER: \usemintedstyle{emacs}
#+LaTeX_HEADER: \newminted{common-lisp}{fontsize=\footnotesize}

#+name: setup-minted
#+begin_src emacs-lisp :exports both :results silent
     (setq org-latex-listings 'minted)
     (setq org-latex-custom-lang-environments
           '(
            (emacs-lisp "common-lispcode")
             ))
     (setq org-latex-minted-options
           '(("frame" "lines")
             ("fontsize" "\\scriptsize")
             ("linenos" "")))
     (setq org-latex-to-pdf-process
           '("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
             "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
             "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))
#+end_src

#+name: another-listing
#+begin_src python :exports code
   x = str(y)
#+end_src

When this example is exported (C-c C-e d) the resulting pdf file contains two source code blocks nicely typeset and colored in a way common to many emacs setups.

12.4. Example listings setup

In this example, the listings package is specified in the #+LaTeX_HEADER:. It is followed by three #+LaTeX_HEADER: lines that construct a call to the lstnewenvironment command that associates the language identifier common-lispcode with the Lisp language that the listings package knows how to parse, and configures typesetting options that will apply to code identified as common-lispcode. Note that common-lispcode is used here simply to conform with the setup used by the minted package for typesetting emacs-lisp code. The final #+LaTeX_HEADER: line defines a new LaTeX command that configures typesetting Python code inline.

The source code block setup-listings instructs Org-mode to use the listings package. It sets the variable org-latex-custom-lang-environments to associate emacs-lisp source code in Org-mode with common-lispcode, as defined by lstnewenvironment. Then it configures default options in the variable org-latex-listings-options that place a frame around source code blocks, set code in a fairly small font, and number lines at the left with tiny numbers. The variable org-latex-to-pdf-process doesn't need to use the -shell-escape option in the call to pdflatex because the listings package is pure LaTeX and doesn't rely on the output of external programs. A new link type, latex, is defined. This can be used to markup inline code snippets. This is followed by a short Python source code block that illustrates the difference between the default typesetting options and the options specified for emacs-lisp source code blocks. Finally, the latex link type is used to call the new python command to typeset an inline code snippet.

#+LATEX_CLASS: article
#+LaTeX_HEADER: \usepackage{listings}
#+LaTeX_HEADER: \lstnewenvironment{common-lispcode}
#+LaTeX_HEADER: {\lstset{language={Lisp},basicstyle={\ttfamily\footnotesize},frame=single,breaklines=true}}
#+LaTeX_HEADER: {}
#+LaTeX_HEADER: \newcommand{\python}[1]{\lstset{language={Python},basicstyle={\ttfamily\small}}\lstinline{#1}}

#+name: setup-listings
#+begin_src emacs-lisp :exports both :results silent
  (setq org-latex-listings 'listings)
  (setq org-latex-custom-lang-environments
        '((emacs-lisp "common-lispcode")))
  (setq org-latex-listings-options
        '(("frame" "lines")
          ("basicstyle" "\\footnotesize")
          ("numbers" "left")
          ("numberstyle" "\\tiny")))
  (setq org-latex-to-pdf-process
        '("pdflatex -interaction nonstopmode -output-directory %o %f"
        "pdflatex -interaction nonstopmode -output-directory %o %f"
        "pdflatex -interaction nonstopmode -output-directory %o %f"))
  (org-add-link-type
   "latex" nil
   (lambda (path desc format)
     (cond
      ((eq format 'html)
       (format "<span class=\"%s\">%s</span>" path desc))
      ((eq format 'latex)
       (format "\\%s{%s}" path desc)))))
#+end_src

#+name: another-listing
#+begin_src python :exports code
  x = str(y)
#+end_src

This is an inline snippet of Python: [[latex:python][x = str(y)]].

When this example is exported, both source code blocks are typeset without any semantic markup, which would be specified by element, rather than with a style as with the minted package.

13. Exporting Tables

There are several ways to prepare a table in Org-mode for export to LaTeX. Perhaps the easiest is to supply the Org-mode table with a caption and a label:

#+CAPTION: [Short caption]{Long caption}
#+LABEL: tab:my-table

This has the great advantage of exporting cleanly to HTML, ASCII, and other backends, but the amount of control over the results is somewhat limited.

At the other extreme, you can create an arbitrarily complex LaTeX table and wrap it in #+BEGIN_LATEX:#+END_LATEX:. This will give you complete control over the LaTeX export, but leave you high and dry for export to other backends and deprive you of the pleasure of building a table with the facilities provided by Org-mode.

A middle ground passes one or more Org-mode tables to a Babel source block, which uses orgtbl-to-generic to set the table. Currently, the entries in the Library of Babel convert only to LaTeX. This approach lets you compose tables in Org-mode but currently requires entries in the table to be marked up with LaTeX, rather than Org-mode conventions.

13.1. How LaTeX typesets tables

LaTeX divides table handling into two parts: typesetting the actual table, and placing the table on the page along with a caption and cross-reference information.

LaTeX provides several environments for typesetting tables. The LaTeX exporter currently supports a well-rounded subset of these:

tabular
table doesn't break across pages, user responsible for determining column widths
tabularx
table doesn't break across pages, width of table specified by user, automatic calculation of column widths
tabulary
like tabularx, but tries harder to calculate optimal column widths
longtable
table breaks across pages, can't be used in a multicolumn page layout

Because the various tabular envionments don't break across pages, they are typically "floated" by wrapping them in a table environment, or for a table that spans columns in a multi-column page layout, a table* environment. LaTeX will "float" the typeset table to an appropriate place in the output, ensuring that the table doesn't run off the end of the page (unless it is taller than the text height). Note that the LaTeX environments responsible for handling the information specified by #+CAPTION: and #+LABEL: are table, table*, and longtable. If tabular, tabularx, and tabulary are used by themselves, then they won't support captions and cross-references.

13.2. Table Rules

The tables in many high-quality publications use rules of different widths for the different "lines" in a table. The horizontal rules at the top and bottom of a table are heavier than the rule separating the column heads from the table body. In general, good table design discourages the use of vertical rules; they are superfluous in an otherwise well-designed table.

The LaTeX exporter currently uses rules of the same width everywhere in a table. It is possible to get book quality tables.

The following steps assume that the org-babel-load-languages variable has an entry (latex . t) and that functions in the Library of Babel are available. I have this in .emacs so that Org-mode knows where to find the Library of Babel (but don't know if it is strictly necessary):

(org-babel-lob-ingest "/path/to/library-of-babel.org")

First, load the booktabs package:

#+LATEX_HEADER: \usepackage{booktabs}

Then, give your table a name, e.g., #+tblname: test-table and put it somewhere the LaTeX exporter won't see, perhaps in a sub-tree tagged with :noexport:.

Finally, create a LaTeX source block something like this:

#+name: tabularx-export
#+begin_src latex :exports results :results latex :noweb yes
  \begin{table}[htb!]
  \centering
  \footnotesize
  \caption{A table to test booktabs}
  \label{tab:test-table}
  <<booktabs(table=test-table,align="lrX",env="tabularx",width="\\textwidth")>>
  \end{table}
 #+end_src

When you export the file to LaTeX, this code block is expanded in a #+results: block and wrapped in #+BEGIN_LaTeX#+END_LaTeX. If the table has column heads, then the rule beneath them should be finer than the rules at the top and bottom of the table.

13.3. Notes in tables

In a better world, the LaTeX footnote command would work inside a tabular environment, setting the notes at the end of the table. The current situation is described in the TeX FAQ. A manual solution is possible, and can be implemented in Org-mode as follows.

First, define a counter that uses table note marks (asterisk, dagger, pilcrow, etc.) and a command to use it. Here is an example:

#+LaTeX_HEADER: \newcounter{my@fn}
#+LaTeX_HEADER: \newcommand{\fn}[1]{\setcounter{my@fn}{#1}\textsuperscript{\fnsymbol{my@fn}}}

Then use a LaTeX source block that calls booktabs-notes from the Library of Babel.

#+begin_src latex :exports results :results latex
  \begin{table}[htb!]
    \centering
    \footnotesize
    \caption{The table caption without Org-mode markup}
    \label{tab:dates}
    <<booktabs-notes(table=dates,notes=dates-fn,lspace=t,align="rcr",env="tabular")>>
  \end{table}
#+end_src

This works like booktabs (see Table Rules), except it accepts a second Org-mode table that contains the table notes. Remember that both of these Org-mode tables are sent to orgtbl-to-generic so Org-mode markup within them won't give the results you might expect. Instead, the table entries use LaTeX markup.

#+tblname: dates
| One\fn{1} | Two\fn{2} | Three\fn{3} |
|-----------+------------+-------------|
| A         | B          | C           |
| D         | E          | F           |
#+tblname: dates-fn
| \multicolumn{3}{l}{\fn{1} A table note.}               |
| \multicolumn{3}{l}{\fn{2} Another table note.}         |
| \multicolumn{3}{l}{\fn{3} The \emph{last} table note.} |

There is also a switch, lspace, which if set non-nil calls the addlinespace command from the booktabs package after the bottomrule that separates the table body from the notes.

13.4. Changing font size

Tables often benefit from a smaller font size than the body text of a document. However, Org-mode doesn't offer a way to change the font size in a table. A discussion on the Org-mode list yielded two solutions, one of which makes a setting for all the tables in the Org-mode document and another that is used on individual tables.

The first solution, offered by Nick Dokos, uses a LaTeX style file, illustrated here with scripttab.sty. This style file sets all the tables in the document with the same size font. The command \scriptsize yields a very small font; the particular size is determined in LaTeX by the font size of \normalsize. Note that \scriptsize can be replaced by another legal LaTeX font size, such as \footnotesize or \small.

\makeatletter
\def \@floatboxreset {%
        \reset@font
        \scriptsize %\footnotesize %\small
        \@setminipage
}
\makeatother

Put scriptab.sty where LaTeX can find it and then add this line to the Org-mode file:

#+LaTeX_HEADER: \usepackage{scripttab}

A second approach, which sets the font size for an individual table with the #+ATTR_LaTeX line, was proposed by Suvayu Ali. This solution is documented on Org ad hoc code, quick hacks and workarounds. Any LaTeX command that works inside the table environment can be passed in this way.

14. Exporting Lists

LaTeX typically sets lists as displayed material, outside of normal paragraphs. The three LaTeX list environments — itemize, enumerate, and description — are all supported by Org-mode. Additionally, Org-mode includes code to typeset its checkboxes.

14.1. Vertical White Space

In standard LaTeX, lists are set with a lot of vertical white space and it is sometimes nicer to set them more compactly. This can be accomplished with the paralist package.

#+LaTeX_HEADER: \usepackage{paralist}

You can redefine the standard LaTeX list environments with their compact paralist equivalents:

#+LaTeX_HEADER: \let\itemize\compactitem
#+LaTeX_HEADER: \let\description\compactdesc
#+LaTeX_HEADER: \let\enumerate\compactenum

With these settings, all the lists in the Org-mode document will be exported in compact form.

14.2. Set Enumerated Lists in a Paragraph

The paralist package has a facility for setting lists in paragraphs, rather than displayed separately. Typically the lists in a paragraph are enumerated and it is possible to set Org-mode's enumerated lists in paragraph, while displaying itemized and description lists.

#+LaTeX_HEADER: \let\itemize\compactitem
#+LaTeX_HEADER: \let\description\compactdesc
#+LaTeX_HEADER: \let\enumerate\inparaenum

14.3. Specify the Enumerator

With the paralist package you can also specify how to enumerate the list. These two examples use lowercase Roman numerals in parentheses and lowercase letters in parentheses, either of which might be used when an enumerated list is set in a paragraph.

#+LaTeX_HEADER: \renewenvironment{enumerate}{\begin{inparaenum}[(i)]}{\end{inparaenum}}
#+LaTeX_HEADER: \renewenvironment{enumerate}{\begin{inparaenum}[(a)]}{\end{inparaenum}}

14.4. Checkboxes

Checkboxes aren't supported natively in LaTeX, so Org-mode rolls its own. The variable org-export-latex-list-parameters controls how this is done. Skip Collins and Nick Dokos discussed how to modify these parameters. Their discussion resulted in a proposal for better looking checkboxes.

#LATEX_HEADER: \setbox0=\hbox{\large$\square$}
#+BIND: org-export-latex-list-parameters (:cbon "[{\\parbox[][][c]{\\wd0}{\\large$\\boxtimes$}}]" :cboff "[{\\parbox[][][c]{\\wd0}{\\large$\\square$}}]")

15. Fonts

The default LaTeX font is Computer Modern, which was designed by Donald Knuth. Computer Modern is perfectly serviceable, but not as nice as other fonts available for LaTeX. Alternative font sets are suggested below.

There are many choices and your choice of which ones to use will be guided, in part, by whether or not your document uses math. If so, then you'll want to choose a font with math support.

Another consideration will be whether or not the font clashes with the amssymb package that Org-mode loads by default.

LaTeX documents might need three text fonts, one for the serif typeface used for text, the sans-serif typeface often used for heads and sub-heads, and the monospace typewriter typeface typically used to set code examples and the like. Choosing fonts that look good with one another is part of the typesetter's art; some care has been taken to match fonts in each set.

15.1. Bera

Bera is the LaTeX version of the Bitstream's Vera family of fonts. The family includes serif, sans-serif, and monospace fonts designed to work well with one another.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage[scaled]{beraserif}
#+LaTeX_HEADER: \usepackage[scaled]{berasans}
#+LaTeX_HEADER: \usepackage[scaled]{beramono}

15.2. Charter

Charter was designed to reproduce well on low-resolution 300 dpi printers. It is paired here with Helvetica and Courier, like Times, for which it is an alternative. Helvetica is set a bit smaller to match the shape of the Charter font. These fonts conflict with the amssymb= package.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage[bitstream-charter]{mathdesign}
#+LaTeX_HEADER: \usepackage[scaled=.9]{helvet}
#+LaTeX_HEADER: \usepackage{courier} % tt

15.3. Garamond

Garamond refers to a group of old-style serif typefaces and is named after the sixteenth-century type designer, Claude Garamond. It is an elegant typeface. Garamond requires a bit more leading than normal. The sans-serif font is Latin Modern and the typewriter font is Courier. Both were chosen to match the shape and stroke weight of Garamond.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage[urw-garamond]{mathdesign}
#+LaTeX_HEADER: \usepackage{lmodern}
#+LaTeX_HEADER: \usepackage{courier}
#+LaTeX_HEADER: \linespread{1.0609}

15.4. KP family

The KP font family is produced by Christophe Caignaert for the Johannes Kepler project. The family supports math.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage{kpfonts}

15.5. Libertine

The Linux Libertine Project produces OpenSource fonts. Libertine is a replacement for Times New Roman and includes a companion sans-serif font. It was used to typeset the Wikipedia logo. The monospace typewriter font is Latin Modern.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage{libertine}
#+LaTeX_HEADER: \renewcommand*\oldstylenums[1]{{\fontfamily{fxlj}\selectfont #1}}
#+LaTeX_HEADER: \usepackage{lmodern}

15.6. Nimbus

The Nimbus font set uses fonts from the Tex-Gyre distribution, which provides a rich collection of diacritical characters in the attempt to cover as many Latin-based scripts as possible. The serif font is Termes, which is a replacement for Times Roman. The sans-serif font is Heros, which is a replacement for Helvetica. The monospace font is Cursor, which is a Courier replacement.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage{tgtermes}
#+LaTeX_HEADER: \usepackage[scale=.85]{tgheros}
#+LaTeX_HEADER: \usepackage{tgcursor}

15.7. Palatino

The beautiful, old-style serif font, Palatino, was designed by Herman Zapf. It is somewhat heavier and easier to read than Garamond. Palatino gets a bit more leading than normal. It is paired here with Helvetica and Courier, as is Times, for which it is an alternative.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage{mathpazo}
#+LaTeX_HEADER: \linespread{1.05}
#+LaTeX_HEADER: \usepackage[scaled]{helvet}
#+LaTeX_HEADER: \usepackage{courier}

15.8. Times

The times option uses URW Nimbus Roman, a Times clone, for the serif font, URW Nimbus Sans, a Helvetica clone, for the sans-serif font, and URW Nimbus Mono, a Courier clone, for the typewriter font. This is a standard set of common typefaces typically used in scientific publications. All of the fonts should be included in a typical LaTeX distribution.

Times New Roman was designed by Stanley Morison for The Times of London during a redesign of the newspaper prompted, in part, by Morison's criticism of its typography in 1929. Helvetica was developed in 1957 by Max Miedinger. Helvetica looks better with Times if it is set slightly smaller than the serif font. Courier was designed by Howard Kettler in 1955 for use in IBM typewriters.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage{mathptmx}
#+LaTeX_HEADER: \usepackage[scaled=.90]{helvet}
#+LaTeX_HEADER: \usepackage{courier}

15.9. Utopia

Utopia is a transitional serif font designed by Robert Slimbach for Adobe in 1989. It became free software in 2006. It is paired here with the Bera sans serif and monospaced fonts. Note that the Utopia font clashes with the amssymb package.

#+LaTeX_HEADER: \usepackage[T1]{fontenc}
#+LaTeX_HEADER: \usepackage[adobe-utopia]{mathdesign}
#+LaTeX_HEADER: \usepackage[scaled]{berasans}
#+LaTeX_HEADER: \usepackage[scaled]{beramono}

16. Cross-references

The Org-mode LaTeX exporter assigns its own labels to section headings. In response to a question from Rasmus Pank Roulund on how to resolve a label when cross-referencing a section heading, Lawrence Mitchell pointed out that with the following setting:

(setq org-export-latex-hyperref-format "\\ref{%s}")

a link to a headline will cross reference properly during LaTeX export.

For example,

* My Headline
In section [[My Headline]] we discuss ...

exports to LaTeX correctly. Note that the link must match the headline exactly for this to work.

17. Bibliography

LaTeX has its own bibliography management system based on the BibTeX software. The BibTeX software uses an external database of bibliographic entries identified by keys. The user passes the bibliographic key to any one of several citation commands at an appropriate place in the text and BibTeX replaces it in the output with a formatted in-text citation. It also compiles and typesets a list of cited works, ensuring that every work cited in the text appears in the list, and that every work that appears in the list is cited in the text.

In its standard configuration Org-mode uses the BibTeX software. Citation commands can be inserted directly into the Org-mode file, e.g.,

\cite{dominick_10}

and the list of cited works inserted at an appropriate place, e.g.,

\bibliographystyle{plain}
\bibliography{my-bib-db}

where my-bib-db is the name of an external bibliographic database, and plain is a BibTeX style.

In-text citations can be entered by hand, but in practice it quickly becomes cumbersome to remember bibliographic keys and to type them correctly. Authors writing in LaTeX typically use the RefTeX software, originally written by Carsten Dominick, to select the bibliographic key from the external database and to insert it into the text with a citation command. RefTeX can also be used to insert citations into the Org-mode document, as detailed in this FAQ. A more detailed setup that associates reading notes with BibTeX bibliographic entries is described in this post to the Org-mode list.

The natbib package extends BibTeX with several convenient in-text citation commands. The commands all start with cite and end with one or more letters that indicate a style. The most commonly used commands are:

  1. \citep for parenthetical citations, e.g., (Jones, 1958);
  2. \citet for textual citations, e.g., Jones (1958);
  3. \citealt for textual citations without parentheses, e.g. Jones 1958.

There are starred versions of most commands that will output the full author lists rather than use the abbreviation et. al.

To use natbib place this line in the Org-mode file:

LATEX_HEADER: \usepackage{natbib}

17.1. Biblatex

The biblatex package, which recently emerged from beta status, offers support for the full range of citation styles, including the numeric styles favored by scientists, the author-date styles used by social scientists, and the footnote styles popular in the humanities.

You'll need two additions to the LaTeX preamble, one to load biblatex and the other to specify the *.bib files that hold the BibTeX database. Loading biblatex without options defaults to a numeric citation style typical in the sciences.

#+LaTeX_HEADER: \usepackage{biblatex}
#+LaTeX_HEADER: \bibliography{my-bib,my-other-bib}

There are a number of citation and bibliography styles that ship with biblatex and there is a growing body of contributed styles. These can be selected by passing options to biblatex. The author/date style used in the social sciences can be selected:

#+LaTeX_HEADER: \usepackage[style=authordate]{biblatex}

Or a footnote style used in the humanities:

#+LaTeX_HEADER: \usepackage[style=verbose]{biblatex}

Biblatex supports the various citation commands implemented by natbib.

#+LaTeX_HEADER: \usepackage[natbib]{biblatex}

The list of cited works can be placed in the document by adding this line to the appropriate place in the Org-mode file:

\printbibliography

17.2. Using Ebib and Extended Link Syntax

Thanks to work by Ali Tofigh and Joost Kremers, it is possible to manage citations using the ebib program for managing BibTeX databases. Using ebib with Org-mode was the idea of Ali Tofigh, who sent this message to the Org-mode list:

A while ago I asked on this list about connecting org-mode with ebib, which is a bibtex database manager for emacs. Thanks to Joost Kremers, there is now a solution.

I asked the developer of ebib, Joost Kremers, if he could write a function that would start ebib on a given bibtex entry. He kindly added this functionality to the 'ebib' function (which starts ebib in emacs) and it is now available in the ebib git repository (see http://ebib.sourceforge.net). If you are using ebib and would like to get org-mode to open bibtex entries do the following:

  1. Install the latest development version of ebib.
  2. make sure ebib-preload-bib-files is set properly so that your .bib file is loaded by ebib when ebib starts
  3. add the following line to your .emacs:
(org-add-link-type "ebib" 'ebib)

Now you can insert ebib links in your documents like this: [ebib:Jones1998][some paper title]. Opening this link should now result in ebib starting, loading your default bibtex database, and highlighting the bibtex entry Jones1998. Alternatively, if you have already started ebib, then opening the link will get you to the bibtex entry in your opened ebib database.

17.2.1. Natbib citation commands

The link types defined for use with ebib can also format output for the LaTeX exporter. The following link types insert the natbib citation commands, using an optional command if the citation link includes a description.

  (org-add-link-type
   "citep" 'ebib
   (lambda (path desc format)
     (cond
      ((eq format 'latex)
       (if (or (not desc) (equal 0 (search "citep:" desc)))
             (format "\\citep{%s}" path)
             (format "\\citep[%s]{%s}" desc path)
)))))
  (org-add-link-type
   "citet" 'ebib
   (lambda (path desc format)
     (cond
      ((eq format 'latex)
       (if (or (not desc) (equal 0 (search "citet:" desc)))
             (format "\\citet{%s}" path)
             (format "\\citet[%s]{%s}" desc path)
)))))
  (org-add-link-type
   "citealt" 'ebib
   (lambda (path desc format)
     (cond
      ((eq format 'latex)
       (if (or (not desc) (equal 0 (search "citealt:" desc)))
             (format "\\citealt{%s}" path)
             (format "\\citealt[%s]{%s}" desc path)
)))))
(org-add-link-type
 "citealp" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "citealp:" desc)))
         (format "\\citealp{%s}" path)
       (format "\\citealp[%s]{%s}" desc path)
       )))))
(org-add-link-type
 "citealt*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "citealt*:" desc)))
         (format "\\citealt*{%s}" path)
       (format "\\citealt*[%s]{%s}" desc path)
       )))))
(org-add-link-type
 "citealp*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "citealp*:" desc)))
         (format "\\citealp*{%s}" path)
       (format "\\citealp*[%s]{%s}" desc path)
       )))))
(org-add-link-type
 "citep*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "citep*:" desc)))
         (format "\\citep*{%s}" path)
       (format "\\citep*[%s]{%s}" desc path)
       )))))
  (org-add-link-type
   "citet*" 'ebib
   (lambda (path desc format)
     (cond
      ((eq format 'latex)
       (if (or (not desc) (equal 0 (search "citet*:" desc)))
             (format "\\citet*{%s}" path)
             (format "\\citet*[%s]{%s}" desc path)
)))))

17.2.2. Standard biblatex citation commands

The standard biblatex citation commands have the following syntax: \command[⟨prenote⟩][⟨postnote⟩]{⟨keys⟩}

They have been implemented by parsing the description part of the link on a semicolon, so that, e.g., [[cite:foo][postnote;prenote]] becomes \cite[prenote][postnote]{foo}. Note that [[cite:foo]] and [[cite:foo][;]] are functionally equivalent.

(org-add-link-type
 "cite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "cite:" desc)))
         (format "\\cite{%s}" path)
       (format "\\cite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Cite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Cite:" desc)))
         (format "\\Cite{%s}" path)
       (format "\\Cite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "parencite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "parencite:" desc)))
         (format "\\parencite{%s}" path)
       (format "\\parencite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Parencite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Parencite:" desc)))
         (format "\\Parencite{%s}" path)
       (format "\\Parencite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "footcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "footcite:" desc)))
         (format "\\footcite{%s}" path)
       (format "\\footcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "footcitetext" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "footcitetext:" desc)))
         (format "\\footcitetext{%s}" path)
       (format "\\footcitetext[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))

(org-add-link-type
 "cite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "cite:" desc)))
         (format "\\cite{%s}" path)
       (format "\\cite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Cite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Cite:" desc)))
         (format "\\Cite{%s}" path)
       (format "\\Cite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "parencite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "parencite:" desc)))
         (format "\\parencite{%s}" path)
       (format "\\parencite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Parencite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Parencite:" desc)))
         (format "\\Parencite{%s}" path)
       (format "\\Parencite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "footcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "footcite:" desc)))
         (format "\\footcite{%s}" path)
       (format "\\footcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "footcitetext" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "footcitetext:" desc)))
         (format "\\footcitetext{%s}" path)
       (format "\\footcitetext[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))

17.2.3. Style-specific biblatex commands

These commands can only be used by some of the citation styles that ship with biblatex.

(org-add-link-type
 "textcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "textcite:" desc)))
         (format "\\textcite{%s}" path)
       (format "\\textcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Textcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Textcite:" desc)))
         (format "\\Textcite{%s}" path)
       (format "\\Textcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "smartcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "smartcite:" desc)))
         (format "\\smartcite{%s}" path)
       (format "\\smartcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Smartcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Smartcite:" desc)))
         (format "\\Smartcite{%s}" path)
       (format "\\Smartcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "cite*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "cite*:" desc)))
         (format "\\cite*{%s}" path)
       (format "\\cite*[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "parencite*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "parencite*:" desc)))
         (format "\\parencite*{%s}" path)
       (format "\\parencite*[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "supercite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (format "\\cite*{%s}" path)))))
(org-add-link-type
 "textcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "textcite:" desc)))
         (format "\\textcite{%s}" path)
       (format "\\textcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Textcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Textcite:" desc)))
         (format "\\Textcite{%s}" path)
       (format "\\Textcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "smartcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "smartcite:" desc)))
         (format "\\smartcite{%s}" path)
       (format "\\smartcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "Smartcite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "Smartcite:" desc)))
         (format "\\Smartcite{%s}" path)
       (format "\\Smartcite[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "cite*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "cite*:" desc)))
         (format "\\cite*{%s}" path)
       (format "\\cite*[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "parencite*" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (if (or (not desc) (equal 0 (search "parencite*:" desc)))
         (format "\\parencite*{%s}" path)
       (format "\\parencite*[%s][%s]{%s}"
               (cadr (split-string desc ";"))
               (car (split-string desc ";"))  path))))))
(org-add-link-type
 "supercite" 'ebib
 (lambda (path desc format)
   (cond
    ((eq format 'html)
     (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (format "\\cite*{%s}" path)))))

Footnotes:

1

The results of this experiment are now included in this document.

2

The xcolor manual is an education in color management and is highly recommended reading.

3

Based on posts to the mailing list by Karl Marino and Carsten Dominik. Thanks to Bernt Hansen and Nick Dokos for help debugging a problem implementing the publishing project.

4

This non-obvious use of the Org-mode link syntax appeared on the Org-mode mailing list under the heading text color + highlight (!). There was a lively discussion there, to which the ideas of Samuel Wales, Christian Moe and Eric Schulte contributed directly to this implementation.

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.