1ead7e0c43f24300a88ec5148bb29d44757ab8b7
[worg.git] / org-tutorials / org-latex-export.org
1 * Settings                                                         :noexport:
2 #+TITLE:   LaTeX Export
3 #+AUTHOR:    Tom Dye
4 #+EMAIL:     tsd@tsdye2.com
5 #+DATE:      2010-04-24 Sat
6 #+DESCRIPTION: 
7 #+KEYWORDS: 
8 #+LANGUAGE:  en
9 #+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
10 #+OPTIONS:   TeX:t LaTeX:nil skip:nil d:nil todo:t pri:nil tags:not-in-toc
11 #+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
12 #+EXPORT_SELECT_TAGS: export
13 #+EXPORT_EXCLUDE_TAGS: noexport
14 #+LINK_UP:   
15 #+LINK_HOME: 
16
17 * Start up
18 Org-mode LaTeX export is easy.  Place the following code in your
19 .emacs and you're ready to go.
20
21 #+begin_src emacs-lisp
22   (require 'org-latex)
23   (unless (boundp 'org-export-latex-classes)
24     (setq org-export-latex-classes nil))
25   (add-to-list 'org-export-latex-classes
26                '("article"
27                  "\\documentclass{article}"
28                  ("\\section{%s}" . "\\section*{%s}")))  
29 #+end_src
30
31 This tells the Org-mode LaTeX exporter to use the standard LaTeX
32 =article= document class by default and to map Org-mode headlines and
33 lists to LaTeX sectioning and list commands, as follows:
34
35 #+begin_src org
36   ,* section
37   ,** itemize
38   ,*** itemize, etc.
39   ,    - itemize
40 #+end_src
41
42 Now you can pick a LaTeX export command from the export menu, =C-c
43 C-e=, and expect to find a well-formed LaTeX document with the same
44 base name as your org-mode buffer.
45
46 It could hardly be easier!
47
48 * Why LaTeX Export?
49
50 As the manual says, "Org is a mode for keeping notes, maintaining TODO
51 lists, and doing project planning with a fast and effective plain-text
52 system."  LaTeX is a convenient interface to TeX, a typesetting system
53 that its author "intended for the creation of beautiful books — and
54 especially for books that contain a lot of mathematics."  Where do
55 these two activities--keeping notes and making beautiful books--overlap?
56
57 Org-mode is well supplied with a variety of other exporters.  The Org
58 ASCII exporter produces a readable and simple version of an Org file
59 for printing and sharing of notes.  The HTML exporter does such a good
60 job of preparing notes for the web that many people use it to create
61 entire web sites.  The XOXO exporter makes notes accessible to other
62 software applications and the DocBook exporter starts the journey to
63 many other formats, including LaTeX, using DocBook tools.
64
65 The niche for the LaTeX exporter is producing a version of an Org file
66 for printing and sharing notes that looks better than an ASCII
67 printout but that can be produced without the overhead required to
68 support DocBook.  All that is needed is a working LaTeX installation.
69 LaTeX distributions for all major platforms are today well-developed
70 and easy to use and maintain.
71
72 * More Highly-Structured Documents
73
74 You can prepare more highly structured LaTeX documents by adding a few
75 lines to =org-export-latex-classes= in =.emacs=.
76
77 #+begin_src emacs-lisp
78   (add-to-list 'org-export-latex-classes
79                '("article"
80                  "\\documentclass{article}"
81                  ("\\section{%s}" . "\\section*{%s}")
82                  ("\\subsection{%s}" . "\\subsection*{%s}")
83                  ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
84                  ("\\paragraph{%s}" . "\\paragraph*{%s}")
85                  ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
86 #+end_src
87
88 This setup produces the following document structure:
89
90 #+begin_src org
91   ,* section
92   ,** subsection
93   ,*** subsubsection
94   ,**** paragraph
95   ,***** subparagraph
96   ,****** itemize, etc.
97   ,       - itemize
98 #+end_src
99
100 * Exporting Other LaTeX Document Classes
101
102 The LaTeX exporter can be configured to produce LaTeX output for
103 books, reports, letters or any other document class, including custom
104 classes.  These can be useful if notes need to be formatted to a
105 certain specification, such as a company technical manual, or if the
106 notes are quite long, as might be the case when Org-mode is used as a
107 laboratory or project notebook.
108
109 Here is a standard setup for export to a LaTeX book class:
110
111 #+begin_src emacs-lisp
112   (add-to-list 'org-export-latex-classes
113                `("book"
114                  "\\documentclass{book}"
115                  ("\\part{%s}" . "\\part*{%s}")
116                  ("\\chapter{%s}" . "\\chapter*{%s}")
117                  ("\\section{%s}" . "\\section*{%s}")
118                  ("\\subsection{%s}" . "\\subsection*{%s}")
119                  ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
120                )
121 #+end_src
122
123 Then, in the Org file with a book-full of notes, add this line:
124
125 #+begin_src org
126   #+LaTeX_CLASS: book 
127 #+end_src
128
129 # <<koma-script>>
130 A useful set of alternatives is the [[http://www.komascript.de/][KOMA script]] classes.  These have a
131 somewhat more modern design than the standard LaTeX classes.  
132
133 For example, the KOMA script article class can be configured in =.emacs=.
134
135 #+begin_src emacs-lisp :
136   (add-to-list 'org-export-latex-classes
137             '("koma-article"
138                "\\documentclass{scrartcl}"
139                ("\\section{%s}" . "\\section*{%s}")
140                ("\\subsection{%s}" . "\\subsection*{%s}")
141                ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
142                ("\\paragraph{%s}" . "\\paragraph*{%s}")
143                ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
144 #+end_src
145
146 Then, this class can be used by including the following line in the
147 Org-mode file.
148
149 #+begin_src org :exports code
150   #+LaTeX_CLASS: koma-article
151 #+end_src
152
153 * Passing Options to Document Classes
154 The standard LaTeX document classes, =article=, =report=, =book=,
155 =slides=, and =letter= take options that, where applicable, select the
156 type size, paper size, orientation, whether to print one- or
157 two-sided, and a variety of formatting specifications.  Custom LaTeX
158 document classes can define their own options, as needed.
159
160 You can pass options to the LaTeX =\documentclass= macro by putting a
161 line like this in your Org-mode file:
162
163 #+begin_src org :exports code
164   #+LaTeX_CLASS_OPTIONS: [a4paper,twoside,twocolumn] 
165 #+end_src
166
167 A useful option with the [[koma-script][KOMA script]] classes typesets table captions
168 properly.  The standard LaTeX classes will incorrectly typeset table captions
169 exported by Org-mode above the table.  The following option to the
170 [[koma-script][KOMA script]] classes accomplishes this.
171
172 #+begin_src org
173   #+LaTeX_CLASS_OPTIONS: [captions=tableheading] 
174 #+end_src
175
176 * Using Custom Classes
177 If the user has custom LaTeX document classes that conflict with the
178 default packages or that only require a few of the default packages to
179 support all features of the LaTeX exporter, then this can be handled
180 in =.emacs= using [DEFAULT-PACKAGES], [NO-DEFAULT-PACKAGES],
181 [PACKAGES], [NO-PACKAGES], [EXTRA], [NO-EXTRA].    
182
183 Here is a simple example that uses an experimental [[http://orgmode.org/worg/org-contrib/babel/examples/article-class.html][LaTeX class]][fn:3] that
184 supports the Org-mode requirements and leaves open the possibility of
185 adding file specific packages:
186   
187 #+begin_src emacs-lisp
188   (add-to-list 'org-export-latex-classes
189         '("org-article"
190            "\\documentclass{org-article}
191            [NO-DEFAULT-PACKAGES]
192            [PACKAGES]
193            [EXTRA]"
194            ("\\section{%s}" . "\\section*{%s}")
195            ("\\subsection{%s}" . "\\subsection*{%s}")
196            ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
197            ("\\paragraph{%s}" . "\\paragraph*{%s}")
198            ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
199 #+end_src
200
201 The Org-mode LaTeX exporter uses several packages to support special
202 characters used by =org-entities=.  One of these, =amssymb=, conflicts
203 with several [[font-section][LaTeX fonts]].  If you want finer control over which
204 packages are loaded, then it makes sense to define an export class
205 like this in =.emacs=:
206
207 #+begin_src emacs-lisp :tangle no
208   (add-to-list 'org-export-latex-classes
209             '("koma-article"
210                "\\documentclass{scrartcl}
211                [NO-DEFAULT-PACKAGES]
212                [EXTRA]"
213                ("\\section{%s}" . "\\section*{%s}")
214                ("\\subsection{%s}" . "\\subsection*{%s}")
215                ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
216                ("\\paragraph{%s}" . "\\paragraph*{%s}")
217                ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
218 #+end_src
219
220 Alternatively, export classes can be defined on a per-file basis in a
221 source code block that is evaluated prior to LaTeX export.  This is
222 perhaps the most flexible way to set up LaTeX export.  Since the
223 =add-to-list= is a globally side-effecting action, this
224 example only calls it if it would add a LaTeX class that isn't
225 already on the =org-export-latex-classes= list:
226
227 #+begin_example 
228   #+name: setup
229   #+begin_src emacs-lisp :results silent :exports none
230  (unless (find "per-file-class" org-export-latex-classes :key 'car
231            :test 'equal)
232    (add-to-list 'org-export-latex-classes
233             '("per-file-class"
234                "\\documentclass{scrartcl}
235                [NO-DEFAULT-PACKAGES]
236                [EXTRA]"
237                ("\\section{%s}" . "\\section*{%s}")
238                ("\\subsection{%s}" . "\\subsection*{%s}")
239                ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
240                ("\\paragraph{%s}" . "\\paragraph*{%s}")
241                ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
242   #+end_src
243 #+end_example
244
245 Then, add this line to the Org-mode file:
246
247 #+begin_src org :exports code
248   #+LaTeX_CLASS: per-file-class
249 #+end_src
250
251 * Specifying LaTeX Packages
252 According to its author, the LaTeX macro package "represents a balance
253 between functionality and ease of use."  The LaTeX user who adds
254 functionality through the addition of packages necessarily makes the
255 software more difficult to use.  Like LaTeX itself, the Org-mode LaTeX
256 exporter has struck its own balance between functionality and ease of
257 use with the addition of several LaTeX packages.  These are written
258 out in the LaTeX header as LaTeX =\usepackage= commands.
259
260 Org-mode keeps the names of the LaTeX packages it uses in a data
261 structure designed for ease of maintenance as additional features are
262 added to the LaTeX exporter.  Packages in the default packages list,
263 =org-export-latex-default-packages-alist=, are required to support all
264 features of the LaTeX exporter.  This list is typically specified in
265 the Org-mode source code and its documentation contains a warning not
266 to modify it.  Packages not included on the default packages list that
267 the user needs consistently can be added to
268 =org-export-latex-packages-alist=.
269
270 If you want to specify particular packages, either in addition to
271 or in place of those used by Org-mode, then you can either place them
272 in a custom class definition, where they can be used by any Org-mode
273 document, or you can add them to the Org-mode document directly so
274 their effect is local to the Org-mode buffer.
275
276 An example custom class definition that adds the =graphicx= package
277 might look like this in =.emacs=:
278
279 #+name: custom-class-definition
280 #+begin_src emacs-lisp :exports code
281   (add-to-list 'org-export-latex-classes
282                '("per-file-class"
283                  "\\documentclass{scrartcl}
284                    \\usepackage{graphicx} 
285               [NO-DEFAULT-PACKAGES]
286               [NO-PACKAGES]"
287                  ("\\section{%s}" . "\\section*{%s}")
288                  ("\\subsection{%s}" . "\\subsection*{%s}")
289                  ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
290                  ("\\paragraph{%s}" . "\\paragraph*{%s}")
291                  ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
292 #+end_src
293
294 Packages needed for a particular file can be specified by inserting a
295 line like this in the Org-mode buffer:
296 #+begin_src org :exports code
297   ,#+LATEX_HEADER: \usepackage{xyz}
298 #+end_src
299
300 One reason for specifying LaTeX packages in the Org-mode buffer is
301 that highly configurable packages can be tailored for a particular
302 use.  Perhaps the best example among the packages in
303 =org-export-latex-default-packages-alist= is =hyperref=, which has an
304 elaborate list of keyval options.  PDF output destined for interactive
305 use might load =hyperref= with options to distinguish links with
306 attractive colors, for instance.  This might be achieved with
307 following lines, which load the =xcolor= package[fn:4] and then use
308 named colors to distinguish external blue links from internal red
309 links:
310
311 #+name: hyperref-header
312 #+begin_src org :exports code
313   ,  #+LATEX_HEADER: \usepackage[hyperref,x11names]{xcolor}
314   ,  #+LATEX_HEADER: \usepackage[colorlinks=true,urlcolor=SteelBlue4,linkcolor=Firebrick4]{hyperref}
315 #+end_src
316
317 In addition, you can pick up the encoding used in the Org-mode buffer and pass
318 this information on to LaTeX by loading the =inputenc= package as
319 follows:
320
321 #+name: inputenc
322 #+begin_src org :exports code
323   #+LATEX_HEADER: \usepackage[AUTO]{inputenc}
324 #+end_src
325
326 * Creating PDF Output
327 The LaTeX exporter by default produces code ready for processing by
328 pdflatex.  pdflatex calls the pdfTeX program, a modern extension of
329 TeX that produces PDF output directly, using the standard LaTeX
330 macros.  pdfTeX is tightly integrated with PDF features such as
331 hypertext links and tables of contents, using LaTeX packages such as
332 hyperref, which is included in the default packages list.
333
334 Org-mode offers a command to produce a PDF file from the LaTeX export.
335 This is bound to =C-c C-e p=.  The command =C-c C-e d= does all this
336 *and* opens the PDF file in the default reader.
337
338 If you use a different TeX typesetting engine or would like to
339 customize how Org-mode produces the pdf file, then you will want to
340 modify the variable =org-latex-to-pdf-process=.  This is a list of
341 strings, each of which contains a call to one of the TeX typesetting
342 engines or to an auxiliary program, such as BibTeX, makeindex, etc.  
343
344 For example, the shell script =texi2dvi= will run =pdflatex= as many
345 times as needed to build a pdf file successfully.  The following code
346 in =.emacs= will instruct Org-mode to use =texi2dvi= when making a pdf
347 file.  Note that you should check that =texi2dvi= is installed on your
348 system and that it works correctly before adding this code to your
349 =.emacs=. 
350  
351 #+name: texi2dvi
352 #+begin_src emacs-lisp :exports code
353 (setq org-latex-to-pdf-process '("texi2dvi --pdf --clean --verbose --batch %f"))
354 #+end_src
355
356 Note that =makeindex= and =bibtex= require a bit more effort to work
357 in this way because of path name issues.  Nick Dokos suggested
358 this fix, which specifies a path to one or more BibTeX =.bib= files: 
359
360 #+begin_example 
361   ,#+begin_src sh :exports none
362     BIBINPUTS=/path/to/bib/:$BIBINPUTS
363     export BIBINPUTS
364   ,#+end_src
365 #+end_example
366
367 If you have system-wide bibliography and index files, then it might be
368 useful to modify =BIBINPUTS= in =.profile= or similar.  The code
369 example above uses Babel to set the variable on a per-file basis.
370
371 An alternative to the default TeX engine is [[http://scripts.sil.org/cms/scripts/page.php?site_id%3Dnrsi&id%3Dxetex][XeTeX]], which merges TeX
372 with Unicode and modern font technologies.  The Emacs-Fu blog has an
373 [[http://emacs-fu.blogspot.com/2011/04/nice-looking-pdfs-with-org-mode-and.html][example XeTeX setup for Org-mode]].  There is also an entry in the
374 Org-Mode FAQ entitled [[http://orgmode.org/worg/org-faq.html#using-xelatex-for-pdf-export][How can I use XeLaTeX for LaTeX export instead
375 of pdfLaTeX?]]
376
377 * Exporting Parts of an Org-mode Buffer
378 Tags can be used to select which parts of an Org-mode buffer are sent
379 to the LaTeX exporter.  In the typical case, the
380 Org-mode buffer contains material for a single export file along with
381 material that shouldn't appear in the export; tags distinguish the
382 export parts from the non-export parts.  This is the single
383 export case.  It is also possible to use tags to specify multiple
384 export targets in a single Org-mode buffer.  In the multiple export
385 case, tags are resolved by a [[http://orgmode.org/org.html#Publishing][publishing management system]].  
386
387 ** The Single Export Case
388 The tags used for the single export case are held in
389 two variables: =org-export-select-tags= is a list of tags, initially set
390 to =export=, that select a tree or sub-tree for export;
391 =org-export-exclude-tags= is a list of tags, initially set to
392 =noexport=, that exclude a tree or subtree for export.  The effect
393 they have on export is logical, but the logic isn't necessarily what
394 one might expect.  In particular, if both select tags and exclude tags
395 are to be used in the same buffer, then their use must follow certain
396 rules.  Also, the handling of unmarked trees and subtrees changes
397 depending on which tags are used and how they are used.
398
399 If neither select tags nor exclude tags are used, then all of the trees
400 and their subtrees are sent to the LaTeX exporter.  If, however, a
401 select tag is added to a tree as in the example below, then unmarked
402 trees will *not* be sent to the exporter.  Thus, the effect of a
403 select tag is not restricted to its tree; its effect extends to the
404 entire buffer.
405
406 #+begin_src org
407   ,* Tree 1                                                             :export:
408   ,   This is exported
409   ,** Subtree 1
410   ,   This is also exported
411   ,* Tree 2
412   ,  This is not exported
413   ,** Subtree 2
414   ,  This is not exported, either
415 #+end_src
416
417 Once the scope of the tag's effect is grasped, the primary rule of using
418 select and exclude tags is obvious: only one type of tag may be used
419 for the trees of a buffer.  If both types of tags are used for trees,
420 how can Org-mode decide what to do with the unmarked trees?  
421
422 A corollary of this rule is that the other type of tag can only be
423 used in a subtree of the tagged tree in order to reverse the effect of
424 the tree-level tag, as in the following example.
425
426 #+begin_src org
427   ,* Tree 1                                                             :export:
428   ,   This is exported
429   ,** Subtree 1                                                       :noexport:
430   ,   This is not exported
431   ,* Tree 2
432   ,  This is not exported
433   ,** Subtree 2
434   ,  This is not exported, either
435 #+end_src
436
437
438 ** The Multiple Export Case
439 In the multiple export case, tags used to select a tree or subtree for
440 export are defined in =.emacs= as part of the configuration needed to
441 specify the many properties of a publication project.  A tutorial
442 illustrates [[http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html][the flexibility of the publishing mechanism]] using an HTML
443 example.  The intricacies of the publishing mechanism are beyond the
444 scope of of this LaTeX export tutorial.  Here, a working example[fn:1]
445 is described.
446
447 In the example, the file =index.org= holds material for two export
448 targets, one related to work items and the other related to home.  The
449 variable =org-publish-project-alist= has two entries, one for a
450 project named =work= and the other for a project named =home=.  Both
451 projects are based on the file =index.org= located in =~/notes/org=.
452
453 Both projects will create output files named =index.tex=, based on the
454 name of the Org-mode file used for import.  The two =index.tex= files
455 are kept separate by writing them to different directories, as
456 indicated by the keyword argument =:publishing-directory=.
457 #+begin_src emacs-lisp
458   (setq org-publish-project-alist
459         '(
460           ("work"
461            :base-directory "~/notes/org/"
462            :base-extension "org"
463            :publishing-directory "~/notes/export/work/"
464            :publishing-function org-publish-org-to-latex
465            :select-tags     ("@WORK")
466            :title "Work Notes"
467            :include ("index.org")
468            :exclude "\\.org$"
469            )
470           ("home"
471            :base-directory "~/notes/org/"
472            :base-extension "org"
473            :publishing-directory "~/notes/export/home/"
474            :publishing-function org-publish-org-to-latex
475            :select-tags     ("@HOME")
476            :title "Home Phone"
477            :include ("index.org")
478            :exclude "\\.org$"
479            )
480           ))
481 #+end_src
482
483 The parts of =index.org= tagged =@WORK= can now be exported to
484 =~/notes/export/work/index.tex= with =C-c C-e X= and selecting the
485 =work= project.
486
487 Similarly, the parts of =index.org= tagged =@HOME= can now be exported to
488 =~/notes/export/home/index.tex= with =C-c C-e X= and selecting the
489 =home= project.
490
491 * Markup
492 Org-mode provides wiki-like markup for various display
493 characteristics.  This is often handy and it translates directly into
494 LaTeX, but the design philosophy of LaTeX is centered around semantic
495 markup, "what you say is what you mean" rather than "what you see is
496 what you get" (lampooned by zealous LaTeX users as "what you see is
497 all you get").  In practice, LaTeX users define common semantic
498 elements in a LaTeX class or style file and these are marked up in
499 text with commands often peculiar to the class or style file.
500 Clearly, there is no way that Org-mode can anticipate commands
501 peculiar to arbitrary class or style files.  Fortunately, Org-mode
502 provides facilities to define special characters and to specify inline
503 and block-level markup.
504
505 ** Special Characters
506 The variable =org-entities-user= holds the information needed to
507 define special characters.  In response to a question posed by Rasmus
508 Pank Roulund, Lawrence Mitchell described how to use this variable to
509 define an escaped space, which is used in LaTeX to insert a single
510 space, instead of a double space, after a period that doesn't end a
511 sentence.
512
513 With this definition:
514
515 : (setq org-entities-user '(("space" "\\ " nil " " " " " " " ")))
516
517 then
518
519 : this is some text, e.g.\space foo bar
520
521 is exported as
522
523 : this is some text, e.g.\  foo bar
524
525 ** Block-level Markup
526 For simple /block-level/ arbitrary markup, you can use the contributed
527 package [[file:../org-contrib/org-special-blocks.org][org-special-blocks]], which turns ~#+begin_foo~ into
528 ~\begin{foo}~ upon LaTeX export. You can use ordinary Org markup
529 inside the block. For example, you can wrap an abstract in
530
531 : #+BEGIN_ABSTRACT
532 : This is an *abstract* with ordinary =Org-mode= /markup/. 
533 : #+END_ABSTRACT
534
535 For more complex cases, where you need to pass parameters or process
536 block contents, but don't want to use literal LaTeX, you may want to
537 explore the possibilities of the contributed [[file:../contrib/org-exp-blocks][org-exp-blocks]] package.
538
539 An example of block-level markup for a results block that will be
540 typeset with a shaded background:
541
542 : #+LaTeX_HEADER: \usepackage{framed}
543 : #+LaTeX_HEADER: \usepackage{xcolor}
544 : #+LaTeX_HEADER: \definecolor{shadecolor}{gray}{.95}
545 : #+LaTeX_HEADER: \newenvironment{results}{\begin{shaded}}{\end{shaded}}
546
547
548 ** Inline Markup
549 /Inline/ arbitrary semantic markup can be implemented by defining a new link type
550 in =.emacs=.[fn:2]   The following code block defines a new link type,
551 =latex=, whose =path= argument can hold the name of any LaTeX
552 command.  This one defines export markup for HTML and LaTeX.  A link
553 such as =[latex:proglang][Org-mode]= will export
554 =\proglang{Org-mode}= to the LaTeX file.  In this way, it is possible
555 to make the Org-mode LaTeX exporter conform to the semantic markup
556 defined in arbitrary style files.  Org-mode will even complete your
557 new link type!
558
559 #+name: semantic-markup
560 #+begin_src emacs-lisp :exports code
561   (org-add-link-type
562    "latex" nil
563    (lambda (path desc format)
564      (cond
565       ((eq format 'html)
566        (format "<span class=\"%s\">%s</span>" path desc))
567       ((eq format 'latex)
568        (format "\\%s{%s}" path desc)))))
569 #+end_src
570
571 Two examples of LaTeX commands for inline semantic markup:
572
573 : #+LaTeX_HEADER: \let\progstruct=\texttt
574 : #+LaTeX_HEADER: \newcommand{\progexample}[1]{{\ttfamily\small #1}}
575
576 ** Captions
577 The LaTeX caption command is typically passed two arguments: the
578 required argument, which is typeset with the figure or table; and the
579 optional argument, which appears in the List of Figures or List of
580 Tables.  It is common nowadays, especially in the sciences, to have
581 long captions (actually captions plus legends) with figures and much
582 abbreviated versions, typically less than a line long, in the List of
583 Figures.  In addition, many styles require that figure captions end
584 with a period; the caption passed to the List of Figures should not
585 end in a period.
586  
587 The Org-mode =#+CAPTION:= macro handles an optional argument.
588
589 This construct:
590
591 : #+CAPTION: [Short caption]{Long caption.}
592
593 exports: 
594
595 : \caption[Short caption]{Long caption.}
596
597 * Styling the Frontmatter
598 The Org-mode LaTeX exporter requires configuration to gain full access
599 to the LaTeX frontmatter formatting capacity.
600  
601 ** Abstract, contents, and lists of figures and tables
602 In the default configuration, the Org-mode LaTeX exporter includes a
603 function that sandwiches the LaTeX =\tableofcontents= command between
604 a command that sets the depth of the headings that appear in the table
605 of contents (based on the number of headline levels that will be
606 exported as headings, rather than lists) and a command to add some
607 vertical space.  Neither of these additions to the =\tableofcontents=
608 command is especially desireable.  It is often the case that one wants
609 the table of contents depth to differ from the depth to which sections
610 are numbered.  Also, in the LaTeX world, the space between the end of one
611 element and the start of another is something that is specified within
612 a class or style file, rather than within the document itself.  Formatting with
613 the class or style file exclusively can give the finished document a pleasing
614 stylistic uniformity that is difficult to achieve in an ad hoc way.
615 Also, hardwiring the table of contents in this way always puts it
616 directly following the output of the LaTeX =maketitle= command.  In
617 practice, however, it is often useful to print an abstract or
618 executive summary between the title and the table of contents.
619 Fortunately, the LaTeX exporter is coded in such a way that it is
620 possible for the user to alter this behavior relatively easily.
621
622 #+name: format-no-toc
623 #+begin_src emacs-lisp :exports code
624 (defun org-export-latex-no-toc (depth)  
625     (when depth
626       (format "%% Org-mode is exporting headings to %s levels.\n"
627               depth)))
628   (setq org-export-latex-format-toc-function 'org-export-latex-no-toc)
629 #+end_src
630
631 With this setup, place the abstract and =#+LATEX:= commands for
632 frontmatter before the first exported headline, e.g.,
633
634 : #+BEGIN_abstract
635 :   [Abstract here]
636 : #+END_abstract
637 : #+LATEX: \tableofcontents
638 : #+LATEX: \listoftables
639 : #+LATEX: \listoffigures
640 : * First Exported Headline
641
642
643 ** Titles and Title Page Layout
644 The default title created by the LaTeX exporter is often just fine,
645 but in cases where you would like to include specific information in
646 the title, or create a custom title page, then perhaps the best way to
647 do this was posted to the Org-mode list by Nick Dokos:
648
649 #+begin_example
650 #+LATEX_HEADER: \input{mytitle}
651  
652  * Foo
653  foo
654  
655  * Bar
656  bar
657 #+end_example
658
659 where the file mytitle.tex looks like this:
660
661 #+begin_example
662 \renewcommand\maketitle{\begin{titlepage}%
663 FOO
664 \end{titlepage}%
665 }
666 #+end_example
667
668 * Exporting Listings
669 ** Exporting Pseudo-Code
670   The LaTeX exporter will fontify exported code blocks written in any
671   language that has an associated Emacs mode for editing.  If you want
672   to export pseudo-code, for which there is no corresponding Emacs
673   mode, then one approach is to use =#+begin_latex ... #+end_latex=
674   and write the pseudo-code directly in LaTeX.  This depends on the
675   LaTeX [[http://www.ctan.org/tex-archive/macros/latex/contrib/listings/][listings package]], which is one of the default packages used by
676   Org-mode. 
677
678   Dan Davison provided this example on the Org-mode list:
679
680 : #+begin_latex
681 : \begin{algorithm}
682 :  \caption{An algorithm}
683 :  \label{alg:myalg}
684 :  \begin{lstlisting}[mathescape,escapeinside='']
685 :    '\foreach individual $i$'
686 :        '\foreach group $k$'
687 :            $\gamma_{ik} \getsp Q_{k}\prod_{l}\prod_{a=1}^{2}P_{lkX_{ila}}$
688 :  \end{lstlisting}
689 : \end{algorithm}
690 : #+end_latex
691 ** Typesetting and Fontifying Source Code
692 Org-mode supports two LaTeX packages for typesetting and fontifying
693 source code; listings and minted.  The listings package is a pure
694 LaTeX implementation that works reasonably well, but the package
695 appears to be orphaned and the latest documentation was written
696 in 2007.  In contrast, the minted package is not a pure LaTeX solution
697 and relies on an external Python script, pygmentize, to typeset and
698 fontify source code.  This package appears to be actively maintained.
699 Both packages are included in the TeXLive and MacTeX LaTeX
700 distributions.  If your distribution lacks one or the other, then
701 you'll need to check the documentation for instructions how to install
702 them. 
703
704 The two packages are structured somewhat differently, but it is
705 possible to configure Org-mode so that these differences are mostly
706 smoothed over, making it possible to generate LaTeX code that will
707 work with either package.  The two main differences have to do with
708 the minted package's generation of language names by appending =code=
709 to the language name; this convention is not followed by the listings
710 package.  In addition, the minted package defines /styles/, by which
711 it means colorizing semantic elements of the programming language.
712 This facility is not implemented in the listings package.
713
714 The following sections show the basics of listings and minted setups
715 which, when exported to LaTeX, illustrate the ability of each package
716 to typeset and fontify source code on a per-language basis.
717
718 ** Example minted setup
719
720 In this example, the minted package is specified in the
721 =#+LaTeX_HEADER:=.  This is followed by a command to use the minted
722 style =emacs=, which colors source code in a way familiar to emacs
723 users.  The final =#+LaTeX_HEADER:= line uses the =newminted= macro to
724 set the font size for code blocks of =common-lisp=. 
725
726 The source code block =setup-minted= includes emacs-lisp code that
727 might typically appear in .emacs, but can be useful in a source code
728 block where it can be used to configure LaTeX export for an individual
729 document.  In the source code block, the variables that control LaTeX
730 export using the minted package are configured.  First,
731 =org-export-latex-listings= is set to use the minted package.  Then,
732 the variable =org-export-latex-custom-lang-environments= is used to
733 associate the emacs-lisp code of an Org-mode source code block with
734 the common-lisp language that the minted package knows how to parse.
735 Note that this is given as =common-lispcode= here, but as
736 =common-lisp= in the call to the =newminted= macro.  The minted
737 package appends =code= to language names by default.  The variable
738 =org-export-latex-minted-options= sets typesetting options that will
739 apply to all programming languages.  See the minted package
740 documentation for the very many options that can be set with key/val
741 pairs. The three entries in the association list call for source code
742 blocks to be framed with lines, set in a very small font, and
743 identified with line numbers.  In relation to these settings, the
744 emacs-lisp code will be set at a slightly larger font size.  Finally,
745 the variable =org-latex-to-pdf-process= is set using the
746 =-shell-escape= option so the external pygmentize program can be
747 called and its results incorporated into the pdf document.  Note that
748 using the =-shell-escape= option creates security holes.
749
750 A Python source code block at the end illustrates how the default
751 emacs-style code differs from the specially formatted emacs-lisp
752 source code.
753
754 #+begin_example 
755 , #+LATEX_CLASS: article
756 , #+LaTeX_HEADER: \usepackage{minted}
757 , #+LaTeX_HEADER: \usemintedstyle{emacs}
758 , #+LaTeX_HEADER: \newminted{common-lisp}{fontsize=\footnotesize}
759
760 , #+name: setup-minted
761 , #+begin_src emacs-lisp :exports both :results silent
762      (setq org-export-latex-listings 'minted)
763      (setq org-export-latex-custom-lang-environments
764            '(
765             (emacs-lisp "common-lispcode")
766              ))
767      (setq org-export-latex-minted-options
768            '(("frame" "lines")
769              ("fontsize" "\\scriptsize")
770              ("linenos" "")))
771      (setq org-latex-to-pdf-process
772            '("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
773              "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
774              "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))
775 , #+end_src
776
777 , #+name: another-listing
778 , #+begin_src python :exports code
779    x = str(y)
780 , #+end_src
781 #+end_example
782  
783 When this example is exported (=C-c C-e d=) the resulting pdf file
784 contains two source code blocks nicely typeset and colored in a way
785 common to many emacs setups.
786
787 ** Example listings setup
788
789 In this example, the listings package is specified in the
790 =#+LaTeX_HEADER:=.  It is followed by three =#+LaTeX_HEADER:= lines
791 that construct a call to the =lstnewenvironment= command that
792 associates the language identifier =common-lispcode= with the =Lisp=
793 language that the listings package knows how to parse, and configures
794 typesetting options that will apply to code identified as
795 =common-lispcode=.  Note that =common-lispcode= is used here simply to
796 conform with the setup used by the minted package for typesetting
797 emacs-lisp code.  The final =#+LaTeX_HEADER:= line defines a new LaTeX
798 command that configures typesetting Python code inline.
799
800 The source code block =setup-listings= instructs Org-mode to use the
801 listings package.  It sets the variable
802 =org-export-latex-custom-lang-environments= to associate =emacs-lisp=
803 source code in Org-mode with =common-lispcode=, as defined by
804 =lstnewenvironment=.  Then it configures default options in the
805 variable =org-export-latex-listings-options= that place a frame around
806 source code blocks, set code in a fairly small font, and number lines
807 at the left with tiny numbers.  The variable
808 =org-latex-to-pdf-process= doesn't need to use the =-shell-escape=
809 option in the call to pdflatex because the listings package is pure
810 LaTeX and doesn't rely on the output of external programs.  A new link
811 type, =latex=, is defined.  This can be used to markup inline code
812 snippets.  This is followed by a short Python source code block that
813 illustrates the difference between the default typesetting options and
814 the options specified for =emacs-lisp= source code blocks.  Finally,
815 the =latex= link type is used to call the new =python= command to
816 typeset an inline code snippet.
817
818 #+begin_example 
819 , #+LATEX_CLASS: article
820 , #+LaTeX_HEADER: \usepackage{listings}
821 , #+LaTeX_HEADER: \lstnewenvironment{common-lispcode}
822 , #+LaTeX_HEADER: {\lstset{language={Lisp},basicstyle={\ttfamily\footnotesize},frame=single,breaklines=true}}
823 , #+LaTeX_HEADER: {}
824 , #+LaTeX_HEADER: \newcommand{\python}[1]{\lstset{language={Python},basicstyle={\ttfamily\small}}\lstinline{#1}}
825
826 , #+name: setup-listings
827 , #+begin_src emacs-lisp :exports both :results silent
828   (setq org-export-latex-listings 'listings)
829   (setq org-export-latex-custom-lang-environments
830         '((emacs-lisp "common-lispcode")))
831   (setq org-export-latex-listings-options
832         '(("frame" "lines")
833           ("basicstyle" "\\footnotesize")
834           ("numbers" "left")
835           ("numberstyle" "\\tiny")))
836   (setq org-latex-to-pdf-process
837         '("pdflatex -interaction nonstopmode -output-directory %o %f"
838         "pdflatex -interaction nonstopmode -output-directory %o %f"
839         "pdflatex -interaction nonstopmode -output-directory %o %f"))
840   (org-add-link-type
841    "latex" nil
842    (lambda (path desc format)
843      (cond
844       ((eq format 'html)
845        (format "<span class=\"%s\">%s</span>" path desc))
846       ((eq format 'latex)
847        (format "\\%s{%s}" path desc)))))
848 , #+end_src
849
850 , #+name: another-listing
851 , #+begin_src python :exports code
852   x = str(y)
853 , #+end_src
854
855 , This is an inline snippet of Python: [[latex:python][x = str(y)]].
856 #+end_example
857
858 When this example is exported, both source code blocks are typeset
859 without any semantic markup, which would be specified by element,
860 rather than with a style as with the minted package.
861 * Exporting Tables
862 There are several ways to prepare a table in Org-mode for export to
863 LaTeX.  Perhaps the easiest is to supply the Org-mode table with a
864 caption and a label:
865
866 : #+CAPTION: [Short caption]{Long caption}
867 : #+LABEL: tab:my-table
868
869 This has the great advantage of exporting cleanly to HTML, ASCII, and
870 other backends, but the amount of control over the results is somewhat
871 limited. 
872
873 At the other extreme, you can create an arbitrarily complex LaTeX
874 table and wrap it in =#+BEGIN_LATEX:= ... =#+END_LATEX:=.  This will
875 give you complete control over the LaTeX export, but leave you high
876 and dry for export to other backends and deprive you of the pleasure
877 of building a table with the facilities provided by Org-mode.
878
879 A middle ground passes one or more Org-mode tables to a Babel source
880 block, which uses =orgtbl-to-generic= to set the table.  Currently,
881 the entries in the Library of Babel convert only to LaTeX.  This
882 approach lets you compose tables in Org-mode but currently requires
883 entries in the table to be marked up with LaTeX, rather than Org-mode
884 conventions.
885
886 ** How LaTeX typesets tables
887 LaTeX divides table handling into two parts: typesetting the actual
888 table, and placing the table on the page along with a caption and
889 cross-reference information.
890
891 LaTeX provides several environments for typesetting tables.  The LaTeX
892 exporter currently supports a well-rounded subset of these:
893
894   - tabular :: table doesn't break across pages, user responsible for
895                determining column widths
896   - tabularx :: table doesn't break across pages, width of table
897                 specified by user, automatic calculation of column widths
898   - tabulary :: like tabularx, but tries harder to calculate optimal
899                 column widths
900   - longtable :: table breaks across pages, can't be used in a
901                  multicolumn page layout
902
903 Because the various tabular envionments don't break across pages, they
904 are typically "floated" by wrapping them in a =table= environment, or
905 for a table that spans columns in a multi-column page layout, a
906 =table*= environment.  LaTeX will "float" the typeset table to an
907 appropriate place in the output, ensuring that the table doesn't run
908 off the end of the page (unless it is taller than the text height).
909 Note that the LaTeX environments responsible for handling the
910 information specified by =#+CAPTION:= and =#+LABEL:= are =table=,
911 =table*=, and =longtable=.  If =tabular=, =tabularx=, and =tabulary=
912 are used by themselves, then they won't support captions and
913 cross-references. 
914
915 ** Table Rules
916 The tables in many high-quality publications use rules of different
917 widths for the different "lines" in a table.  The horizontal rules at
918 the top and bottom of a table are heavier than the rule separating the
919 column heads from the table body.  In general, good table design
920 discourages the use of vertical rules; they are superfluous in an
921 otherwise well-designed table.
922
923 The LaTeX exporter currently uses rules of the same width everywhere
924 in a table.  It is possible to get book quality tables.
925
926 The following steps assume that the =org-babel-load-languages=
927 variable has an entry =(latex . t)= and that functions in the Library
928 of Babel are available.  I have this in =.emacs= so that Org-mode
929 knows where to find the Library of Babel (but don't know if it
930 is strictly necessary):
931 :  (org-babel-lob-ingest "/path/to/library-of-babel.org")
932
933
934 First, load the =booktabs= package:
935
936 : #+LATEX_HEADER: \usepackage{booktabs}
937
938 Then, give your table a name, e.g., =#+tblname: test-table= and put it
939 somewhere the LaTeX exporter won't see, perhaps in a sub-tree tagged with
940 =:noexport:=.
941
942 Finally, create a LaTeX source block something like this:
943
944 : #+name: tabularx-export
945 : #+begin_src latex :exports results :results latex :noweb yes
946 :   \begin{table}[htb!]
947 :   \centering
948 :   \footnotesize
949 :   \caption{A table to test booktabs}
950 :   \label{tab:test-table}
951 :   <<booktabs(table=test-table,align="lrX",env="tabularx",width="\\textwidth")>>  
952 :   \end{table}
953 :  #+end_src
954
955 When you export the file to LaTeX, this code block is expanded in a
956 =#+results:= block and wrapped in =#+BEGIN_LaTeX= ... =#+END_LaTeX=.
957 If the table has column heads, then the rule beneath them should be
958 finer than the rules at the top and bottom of the table.
959
960 ** Notes in tables
961
962 In a better world, the LaTeX =footnote= command would work inside a
963 =tabular= environment, setting the notes at the end of the table. The
964 current situation is described in the
965 [[http://www.tex.ac.uk/cgi-bin/texfaq2html?label%3Dfootintab][TeX
966 FAQ]].  A manual solution is possible, and can be implemented in
967 Org-mode as follows.
968
969 First, define a counter that uses table note marks (asterisk, dagger,
970 pilcrow, etc.) and a command to use it.  Here is an example:
971
972 : #+LaTeX_HEADER: \newcounter{my@fn}
973 : #+LaTeX_HEADER: \newcommand{\fn}[1]{\setcounter{my@fn}{#1}\textsuperscript{\fnsymbol{my@fn}}}
974
975 Then use a LaTeX source block that calls =booktabs-notes= from the
976 Library of Babel.
977
978 : #+begin_src latex :exports results :results latex
979 :   \begin{table}[htb!]
980 :     \centering
981 :     \footnotesize
982 :     \caption{The table caption without Org-mode markup}
983 :     \label{tab:dates}
984 :     <<booktabs-notes(table=dates,notes=dates-fn,lspace=t,align="rcr",env="tabular")>>  
985 :   \end{table}
986 : #+end_src
987
988 This works like =booktabs= (see [[Table%20Rules][Table Rules]]),
989 except it accepts a second Org-mode table that contains the table
990 notes.  Remember that both of these Org-mode tables are sent to
991 =orgtbl-to-generic= so Org-mode markup within them won't give the
992 results you might expect.  Instead, the table entries use LaTeX
993 markup. 
994
995 : #+tblname: dates
996 : | One\fn{1} | Two\fn{2} | Three\fn{3} |
997 : |-----------+------------+-------------|
998 : | A         | B          | C           |
999 : | D         | E          | F           |
1000
1001 : #+tblname: dates-fn
1002 : | \multicolumn{3}{l}{\fn{1} A table note.}               |
1003 : | \multicolumn{3}{l}{\fn{2} Another table note.}         |
1004 : | \multicolumn{3}{l}{\fn{3} The \emph{last} table note.} |
1005
1006
1007 There is also a switch, =lspace=, which if set non-nil calls the
1008 =addlinespace= command from the =booktabs= package after the
1009 =bottomrule= that separates the table body from the notes.
1010
1011 ** Changing font size
1012 Tables often benefit from a smaller font size than the body text of a
1013 document.  However, Org-mode doesn't offer a way to change the font
1014 size in a table.  A discussion on the Org-mode list yielded two solutions,
1015 one of which makes a setting for all the tables in the Org-mode
1016 document and another that is used on individual tables.
1017
1018 The first solution, offered by Nick Dokos, uses a LaTeX style file,
1019 illustrated here with =scripttab.sty=.  This style file sets all the
1020 tables in the document with the same size font.  The command
1021 =\scriptsize= yields a very small font; the particular size is
1022 determined in LaTeX by the font size of =\normalsize=.  Note that
1023 =\scriptsize= can be replaced by another legal LaTeX font size, such
1024 as =\footnotesize= or =\small=.
1025
1026 #+name: scripttab
1027 #+begin_src latex :exports code
1028 \makeatletter
1029 \def \@floatboxreset {%
1030         \reset@font
1031         \scriptsize %\footnotesize %\small
1032         \@setminipage
1033 }
1034 \makeatother
1035 #+end_src
1036
1037 Put =scriptab.sty= where LaTeX can find it and then add this line to
1038 the Org-mode file:
1039
1040 : #+LaTeX_HEADER: \usepackage{scripttab}
1041
1042 A second approach, which sets the font size for an individual table
1043 with the =#+ATTR_LaTeX= line, was proposed by Suvayu Ali. This
1044 solution is documented on
1045 [[http://orgmode.org/worg/org-hacks.html#latex-command-for-floats][Org
1046 ad hoc code, quick hacks and workarounds]]. Any LaTeX command that
1047 works inside the table environment can be passed in this way.
1048
1049 * Exporting Lists
1050 LaTeX typically sets lists as displayed material, outside of normal
1051 paragraphs.  The three LaTeX list environments --- =itemize=,
1052 =enumerate=, and =description= --- are all supported by Org-mode.
1053 Additionally, Org-mode includes code to typeset its checkboxes.
1054
1055 ** Vertical White Space
1056 In standard LaTeX, lists are set with a lot of vertical white space
1057 and it is sometimes nicer to set them more compactly.  This can be
1058 accomplished with the =paralist= package.
1059
1060 : #+LaTeX_HEADER: \usepackage{paralist}
1061
1062 You can redefine the standard LaTeX list environments with their
1063 compact =paralist= equivalents:
1064
1065 : #+LaTeX_HEADER: \let\itemize\compactitem
1066 : #+LaTeX_HEADER: \let\description\compactdesc
1067 : #+LaTeX_HEADER: \let\enumerate\compactenum  
1068
1069 With these settings, all the lists in the Org-mode document will be
1070 exported in compact form.
1071
1072 ** Set Enumerated Lists in a Paragraph
1073
1074 The =paralist= package has a facility for setting lists in paragraphs,
1075 rather than displayed separately.  Typically the lists in a paragraph
1076 are enumerated and it is possible to set Org-mode's enumerated lists
1077 in paragraph, while displaying itemized and description lists.
1078
1079 : #+LaTeX_HEADER: \let\itemize\compactitem
1080 : #+LaTeX_HEADER: \let\description\compactdesc
1081 : #+LaTeX_HEADER: \let\enumerate\inparaenum
1082
1083
1084 ** Specify the Enumerator
1085 With the =paralist= package you can also specify how to enumerate the
1086 list.  These two examples use lowercase Roman numerals in parentheses
1087 and lowercase letters in parentheses, either of which might be used
1088 when an enumerated list is set in a paragraph.
1089
1090 : #+LaTeX_HEADER: \renewenvironment{enumerate}{\begin{inparaenum}[(i)]}{\end{inparaenum}}
1091 : #+LaTeX_HEADER: \renewenvironment{enumerate}{\begin{inparaenum}[(a)]}{\end{inparaenum}}
1092
1093 ** Checkboxes
1094 Checkboxes aren't supported natively in LaTeX, so Org-mode rolls its
1095 own.  The variable =org-export-latex-list-parameters= controls how
1096 this is done.  Skip Collins and Nick Dokos discussed how to modify
1097 these parameters.  Their discussion resulted in a proposal for better
1098 looking checkboxes.
1099
1100 : #LATEX_HEADER: \setbox0=\hbox{\large$\square$}
1101
1102 : #+BIND: org-export-latex-list-parameters (:cbon "[{\\parbox[][][c]{\\wd0}{\\large$\\boxtimes$}}]" :cboff "[{\\parbox[][][c]{\\wd0}{\\large$\\square$}}]")
1103
1104 * Fonts
1105 # <<font-section>>
1106 The default LaTeX font is Computer Modern, which was designed by
1107 Donald Knuth.  Computer Modern is perfectly serviceable, but not as
1108 nice as other fonts available for LaTeX.  Alternative font sets are
1109 suggested below.
1110
1111 There are many choices and your choice of which ones to use will be
1112 guided, in part, by whether or not your document uses math.  If so,
1113 then you'll want to choose a font with math support.
1114
1115 Another consideration will be whether or not the font clashes with the
1116 =amssymb= package that Org-mode loads by default.
1117
1118 LaTeX documents might need three text fonts, one for the serif
1119 typeface used for text, the sans-serif typeface often used for heads
1120 and sub-heads, and the monospace typewriter typeface typically used to
1121 set code examples and the like.  Choosing fonts that look good with
1122 one another is part of the typesetter's art; some care has been taken
1123 to match fonts in each set.
1124
1125 ** Bera
1126 # <<bera-font>>
1127
1128 Bera is the LaTeX version of the Bitstream's Vera family of fonts.
1129 The family includes serif, sans-serif, and monospace fonts designed to
1130 work well with one another. 
1131
1132 : #+LaTeX_HEADER: \usepackage[T1]{fontenc} 
1133 : #+LaTeX_HEADER: \usepackage[scaled]{beraserif}
1134 : #+LaTeX_HEADER: \usepackage[scaled]{berasans} 
1135 : #+LaTeX_HEADER: \usepackage[scaled]{beramono}
1136
1137 ** Charter
1138 # <<charter-font>>
1139
1140 [[http://en.wikipedia.org/wiki/Bitstream_Charter][Charter]] was designed to reproduce well on low-resolution 300 dpi
1141 printers.  It is paired here with Helvetica and Courier, like [[times-font][Times]],
1142 for which it is an alternative.  Helvetica is set a bit smaller to
1143 match the shape of the Charter font.  These fonts conflict with the
1144 [[latex:package][amssymb]] package.
1145
1146 : #+LaTeX_HEADER: \usepackage[T1]{fontenc} 
1147 : #+LaTeX_HEADER: \usepackage[bitstream-charter]{mathdesign}
1148 : #+LaTeX_HEADER: \usepackage[scaled=.9]{helvet} 
1149 : #+LaTeX_HEADER: \usepackage{courier} % tt
1150
1151 ** Garamond
1152 # <<garamond-font>>
1153
1154 [[http://en.wikipedia.org/wiki/Garamond][Garamond]] refers to a group of old-style serif typefaces and is named
1155 after the sixteenth-century type designer, Claude Garamond.  It is an
1156 elegant typeface.  Garamond requires a bit more leading than normal.
1157 The sans-serif font is Latin Modern and the typewriter font is
1158 Courier.  Both were chosen to match the shape and stroke weight of
1159 Garamond.
1160
1161 : #+LaTeX_HEADER: \usepackage[T1]{fontenc} 
1162 : #+LaTeX_HEADER: \usepackage[urw-garamond]{mathdesign}
1163 : #+LaTeX_HEADER: \usepackage{lmodern} 
1164 : #+LaTeX_HEADER: \usepackage{courier}
1165 : #+LaTeX_HEADER: \linespread{1.0609}
1166
1167 ** KP family
1168 # <<kp-font>>
1169
1170 The [[http://tug.ctan.org/pkg/kpfonts][KP font family]] is produced by Christophe Caignaert for the
1171 Johannes Kepler project.  The family supports math.
1172
1173 : #+LaTeX_HEADER: \usepackage[T1]{fontenc} 
1174 : #+LaTeX_HEADER: \usepackage{kpfonts}
1175
1176 ** Libertine
1177 # <<libertine-font>>
1178
1179 The [[http://www.linuxlibertine.org/][Linux Libertine Project]] produces OpenSource fonts.  Libertine is a
1180 replacement for Times New Roman and includes a companion sans-serif
1181 font.  It was used to typeset the Wikipedia logo.  The monospace
1182 typewriter font is Latin Modern.
1183
1184 : #+LaTeX_HEADER: \usepackage[T1]{fontenc} 
1185 : #+LaTeX_HEADER: \usepackage{libertine}
1186 : #+LaTeX_HEADER: \renewcommand*\oldstylenums[1]{{\fontfamily{fxlj}\selectfont #1}}
1187 : #+LaTeX_HEADER: \usepackage{lmodern}
1188 ** Nimbus                                                     
1189 # <<nimbus-font>>
1190
1191 The Nimbus font set uses fonts from the [[http://www.gust.org.pl/projects/e-foundry/tex-gyre/][Tex-Gyre]] distribution, which
1192 provides a rich collection of diacritical characters in the attempt to
1193 cover as many Latin-based scripts as possible.  The serif font is
1194 Termes, which is a replacement for Times Roman.  The sans-serif font
1195 is Heros, which is a replacement for Helvetica.  The monospace font is
1196 Cursor, which is a Courier replacement.
1197
1198 : #+LaTeX_HEADER: \usepackage[T1]{fontenc}
1199 : #+LaTeX_HEADER: \usepackage{tgtermes}
1200 : #+LaTeX_HEADER: \usepackage[scale=.85]{tgheros}
1201 : #+LaTeX_HEADER: \usepackage{tgcursor}
1202
1203 ** Palatino
1204 # <<palatino-font>>
1205
1206 The beautiful, old-style serif font, [[http://en.wikipedia.org/wiki/Palatino][Palatino]], was designed by [[http://en.wikipedia.org/wiki/Herman_Zapf][Herman
1207 Zapf]].  It is somewhat heavier and easier to read than [[garamond-font][Garamond]].
1208 Palatino gets a bit more leading than normal.  It is paired here with
1209 Helvetica and Courier, as is [[times-font][Times]], for which it is an alternative.
1210
1211 : #+LaTeX_HEADER: \usepackage[T1]{fontenc}
1212 : #+LaTeX_HEADER: \usepackage{mathpazo}
1213 : #+LaTeX_HEADER: \linespread{1.05}
1214 : #+LaTeX_HEADER: \usepackage[scaled]{helvet}
1215 : #+LaTeX_HEADER: \usepackage{courier}
1216
1217 ** Times
1218 # <<times-font>>
1219
1220 The =times= option uses URW Nimbus Roman, a Times clone, for the serif
1221 font, URW Nimbus Sans, a Helvetica clone, for the sans-serif font,
1222 and URW Nimbus Mono, a Courier clone, for the typewriter font.  This
1223 is a standard set of common typefaces typically used in scientific
1224 publications.  All of the fonts should be included in a typical LaTeX
1225 distribution. 
1226
1227 [[http://en.wikipedia.org/wiki/Times_Roman][Times New Roman]] was designed by [[http://en.wikipedia.org/wiki/Stanley_Morison][Stanley Morison]] for /The Times/ of
1228 London during a redesign of the newspaper prompted, in part, by
1229 Morison's criticism of its typography in 1929.  [[http://en.wikipedia.org/wiki/Helvetica][Helvetica]] was
1230 developed in 1957 by [[http://en.wikipedia.org/wiki/Max_Miedinger][Max Miedinger]].  Helvetica looks better with Times
1231 if it is set slightly smaller than the serif font.  [[http://en.wikipedia.org/wiki/Courier_(typeface)][Courier]] was
1232 designed by Howard Kettler in 1955 for use in IBM typewriters.
1233
1234 : #+LaTeX_HEADER: \usepackage[T1]{fontenc}
1235 : #+LaTeX_HEADER: \usepackage{mathptmx} 
1236 : #+LaTeX_HEADER: \usepackage[scaled=.90]{helvet} 
1237 : #+LaTeX_HEADER: \usepackage{courier}
1238
1239 ** Utopia
1240 # <<utopia-font>>
1241
1242 [[http://en.wikipedia.org/wiki/Utopia_(typeface)][Utopia]] is a transitional serif font designed by [[http://en.wikipedia.org/wiki/Robert_Slimbach][Robert Slimbach]] for
1243 Adobe in 1989.  It became free software in 2006.  It is paired here
1244 with the Bera sans serif and monospaced fonts.  Note that the Utopia
1245 font clashes with the [[latex:package][amssymb]] package.
1246
1247 : #+LaTeX_HEADER: \usepackage[T1]{fontenc} 
1248 : #+LaTeX_HEADER: \usepackage[adobe-utopia]{mathdesign}
1249 : #+LaTeX_HEADER: \usepackage[scaled]{berasans} 
1250 : #+LaTeX_HEADER: \usepackage[scaled]{beramono}
1251
1252 * Cross-references
1253 The Org-mode LaTeX exporter assigns its own labels to section
1254 headings.  In response to a question from Rasmus Pank Roulund on how
1255 to resolve a label when cross-referencing a section heading, Lawrence
1256 Mitchell pointed out that with the following setting:
1257
1258 : (setq org-export-latex-hyperref-format "\\ref{%s}")
1259
1260 a link to a headline will cross reference properly during LaTeX
1261 export.
1262
1263 For example,
1264
1265 : * My Headline
1266 : In section [[My Headline]] we discuss ...
1267
1268 exports to LaTeX correctly.  Note that the link must match the
1269 headline exactly for this to work.
1270
1271 * Bibliography
1272 # <<bibliography section>>
1273
1274 LaTeX has its own bibliography management system based on the BibTeX
1275 software.  The BibTeX software uses an external database of
1276 bibliographic entries identified by keys.  The user passes the
1277 bibliographic key to any one of several citation commands at an
1278 appropriate place in the text and BibTeX replaces it in the output
1279 with a formatted in-text citation.  It also compiles and typesets a
1280 list of cited works, ensuring that every work cited in the text
1281 appears in the list, and that every work that appears in the list is
1282 cited in the text.
1283
1284 In its standard configuration Org-mode uses the BibTeX software.
1285 Citation commands can be inserted directly into the Org-mode file,
1286 e.g.,
1287
1288 : \cite{dominick_10}
1289
1290 and the list of cited works inserted at an appropriate place, e.g.,
1291
1292 : \bibliographystyle{plain}
1293 : \bibliography{my-bib-db}
1294
1295 where =my-bib-db= is the name of an external bibliographic database,
1296 and =plain= is a BibTeX style.
1297
1298 In-text citations can be entered by hand, but in practice it quickly
1299 becomes cumbersome to remember bibliographic keys and to type them
1300 correctly.  Authors writing in LaTeX typically use the RefTeX
1301 software, originally written by Carsten Dominick, to select the
1302 bibliographic key from the external database and to insert it into the
1303 text with a citation command.  RefTeX can also be used to insert
1304 citations into the Org-mode document, as detailed in [[http://orgmode.org/worg/org-faq.html#using-reftex-in-org-mode][this FAQ.]]  A more
1305 detailed setup that associates reading notes with BibTeX
1306 bibliographic entries is described in this [[http://article.gmane.org/gmane.emacs.orgmode/2406/match%3Dbibliography][post to the Org-mode list.]]
1307
1308 The =natbib= package extends BibTeX with several convenient in-text
1309 citation commands.  The commands all start with =cite= and end with
1310 one or more letters that indicate a style.  The most commonly used
1311 commands are:
1312   1. =\citep= for parenthetical citations, e.g., (Jones, 1958);
1313   2. =\citet= for textual citations, e.g., Jones (1958);
1314   3. =\citealt= for textual citations without parentheses, e.g. Jones 1958.
1315 There are starred versions of most commands that will output the full
1316 author lists rather than use the abbreviation =et. al.=
1317
1318 To use =natbib= place this line in the Org-mode file:
1319
1320 : LATEX_HEADER: \usepackage{natbib}
1321
1322 ** Biblatex
1323
1324 The [[latex:package][biblatex]] package, which recently emerged from beta status, offers
1325 support for the full range of citation styles, including the numeric
1326 styles favored by scientists, the author-date styles used by social
1327 scientists, and the footnote styles popular in the humanities.
1328
1329 You'll need two additions to the LaTeX preamble, one to load biblatex
1330 and the other to specify the =*.bib= files that hold the BibTeX
1331 database.  Loading biblatex without options defaults to a numeric
1332 citation style typical in the sciences.
1333
1334 : #+LaTeX_HEADER: \usepackage{biblatex}
1335 : #+LaTeX_HEADER: \bibliography{my-bib,my-other-bib}
1336
1337 There are a number of citation and bibliography styles that ship with
1338 biblatex and there is a growing body of contributed styles.  These can
1339 be selected by passing options to biblatex.  The author/date style
1340 used in the social sciences can be selected:
1341
1342 : #+LaTeX_HEADER: \usepackage[style=authordate]{biblatex}
1343
1344 Or a footnote style used in the humanities:
1345
1346 : #+LaTeX_HEADER: \usepackage[style=verbose]{biblatex}
1347
1348
1349 Biblatex supports the various citation commands implemented by
1350 [[latex:package][natbib]].
1351
1352 : #+LaTeX_HEADER: \usepackage[natbib]{biblatex}
1353
1354 The list of cited works can be placed in the document by adding this
1355 line to the appropriate place in the Org-mode file:
1356
1357 : \printbibliography
1358
1359 ** Using Ebib and Extended Link Syntax
1360
1361 Thanks to work by Ali Tofigh and Joost Kremers, it is possible to
1362 manage citations using the [[http://ebib.sourceforge.net/][ebib]] program for managing BibTeX databases.
1363 Using ebib with Org-mode was the idea of Ali Tofigh, who sent this
1364 message to the Org-mode list:
1365
1366 A while ago I asked on this list about connecting org-mode with ebib,
1367 which is a bibtex database manager for emacs. Thanks to Joost Kremers,
1368 there is now a solution.
1369
1370 I asked the developer of ebib, Joost Kremers, if he could write a
1371 function that would start ebib on a given bibtex entry. He kindly
1372 added this functionality to the 'ebib' function (which starts ebib in
1373 emacs) and it is now available in the ebib git repository (see
1374 http://ebib.sourceforge.net). If you are using ebib and would like to
1375 get org-mode to open bibtex entries do the following:
1376
1377 1) Install the latest development version of ebib.
1378
1379 2) make sure =ebib-preload-bib-files= is set properly so that your =.bib= file is loaded by ebib when ebib starts
1380
1381 3) add the following line to your =.emacs=:
1382 : (org-add-link-type "ebib" 'ebib)
1383
1384 Now you can insert ebib links in your documents like this:
1385 =[ebib:Jones1998][some paper title]=. Opening this link should now
1386 result in ebib starting, loading your default bibtex database, and
1387 highlighting the bibtex entry Jones1998. Alternatively, if you have
1388 already started ebib, then opening the link will get you to the bibtex
1389 entry in your opened ebib database.
1390
1391 *** Natbib citation commands
1392 The link types defined for use with ebib can also format output for
1393 the LaTeX exporter.  The following link types insert the natbib
1394 citation commands, using an optional command if the citation link
1395 includes a description.
1396
1397 #+name: define-citep-link
1398 #+begin_src emacs-lisp :results silent
1399   (org-add-link-type 
1400    "citep" 'ebib
1401    (lambda (path desc format)
1402      (cond
1403       ((eq format 'latex)
1404        (if (or (not desc) (equal 0 (search "citep:" desc)))
1405              (format "\\citep{%s}" path)
1406              (format "\\citep[%s]{%s}" desc path)
1407 )))))
1408 #+end_src
1409
1410 #+name: define-citet-link
1411 #+begin_src emacs-lisp :results silent
1412   (org-add-link-type 
1413    "citet" 'ebib
1414    (lambda (path desc format)
1415      (cond
1416       ((eq format 'latex)
1417        (if (or (not desc) (equal 0 (search "citet:" desc)))
1418              (format "\\citet{%s}" path)
1419              (format "\\citet[%s]{%s}" desc path)
1420 )))))
1421 #+end_src
1422
1423 #+name: define-citealt-link
1424 #+begin_src emacs-lisp :results silent
1425   (org-add-link-type 
1426    "citealt" 'ebib
1427    (lambda (path desc format)
1428      (cond
1429       ((eq format 'latex)
1430        (if (or (not desc) (equal 0 (search "citealt:" desc)))
1431              (format "\\citealt{%s}" path)
1432              (format "\\citealt[%s]{%s}" desc path)
1433 )))))
1434 #+end_src
1435
1436 #+name: define-citealp-link
1437 #+begin_src emacs-lisp 
1438   (org-add-link-type 
1439    "citealp" 'ebib
1440    (lambda (path desc format)
1441      (cond
1442       ((eq format 'latex)
1443        (if (or (not desc) (equal 0 (search "citealp:" desc)))
1444            (format "\\citealp{%s}" path)
1445          (format "\\citealp[%s]{%s}" desc path)
1446          )))))
1447 #+end_src
1448
1449 #+name: define-citealtstar-link
1450 #+begin_src emacs-lisp 
1451   (org-add-link-type 
1452    "citealt*" 'ebib
1453    (lambda (path desc format)
1454      (cond
1455       ((eq format 'latex)
1456        (if (or (not desc) (equal 0 (search "citealt*:" desc)))
1457            (format "\\citealt*{%s}" path)
1458          (format "\\citealt*[%s]{%s}" desc path)
1459          )))))
1460 #+end_src
1461
1462 #+name: define-citealpstar-link
1463 #+begin_src emacs-lisp 
1464   (org-add-link-type 
1465    "citealp*" 'ebib
1466    (lambda (path desc format)
1467      (cond
1468       ((eq format 'latex)
1469        (if (or (not desc) (equal 0 (search "citealp*:" desc)))
1470            (format "\\citealp*{%s}" path)
1471          (format "\\citealp*[%s]{%s}" desc path)
1472          )))))
1473 #+end_src
1474
1475 #+name: define-citepstar-link
1476 #+begin_src emacs-lisp 
1477   (org-add-link-type 
1478    "citep*" 'ebib
1479    (lambda (path desc format)
1480      (cond
1481       ((eq format 'latex)
1482        (if (or (not desc) (equal 0 (search "citep*:" desc)))
1483            (format "\\citep*{%s}" path)
1484          (format "\\citep*[%s]{%s}" desc path)
1485          )))))
1486 #+end_src
1487
1488 #+name: define-citetstar-link
1489 #+begin_src emacs-lisp 
1490   (org-add-link-type 
1491    "citet*" 'ebib
1492    (lambda (path desc format)
1493      (cond
1494       ((eq format 'latex)
1495        (if (or (not desc) (equal 0 (search "citet*:" desc)))
1496              (format "\\citet*{%s}" path)
1497              (format "\\citet*[%s]{%s}" desc path)
1498 )))))
1499 #+end_src
1500
1501
1502 *** Standard biblatex citation commands
1503
1504 The standard biblatex citation commands have the following syntax: 
1505 \command[⟨prenote⟩][⟨postnote⟩]{⟨keys⟩}
1506
1507 They have been implemented by parsing the description part of the link
1508 on a semicolon, so that, e.g.,
1509 =[[cite:foo][postnote;prenote]]= becomes
1510 =\cite[prenote][postnote]{foo}=.  Note that =[[cite:foo]]= and
1511 =[[cite:foo][;]]= are functionally equivalent.  
1512  
1513 #+name: define-standard-biblatex-commands
1514 #+begin_src emacs-lisp :noweb yes :results silent :exports code
1515   <<define-biblatex-cite-link>>
1516   <<define-biblatex-cap-cite-link>>
1517   <<define-biblatex-parencite-link>>
1518   <<define-biblatex-cap-parencite-link>>
1519   <<define-biblatex-footcite-link>>
1520   <<define-biblatex-footcitetext-link>>
1521
1522 #+end_src
1523
1524 #+name: define-biblatex-cite-link
1525 #+begin_src emacs-lisp :results silent :exports code
1526   (org-add-link-type 
1527    "cite" 'ebib
1528    (lambda (path desc format)
1529      (cond
1530       ((eq format 'html)
1531        (format "(<cite>%s</cite>)" path))
1532       ((eq format 'latex)
1533        (if (or (not desc) (equal 0 (search "cite:" desc)))
1534            (format "\\cite{%s}" path)
1535          (format "\\cite[%s][%s]{%s}"
1536                  (cadr (split-string desc ";"))
1537                  (car (split-string desc ";"))  path))))))
1538 #+end_src
1539
1540 #+name: define-biblatex-cap-cite-link
1541 #+begin_src emacs-lisp :results silent :exports code
1542   (org-add-link-type 
1543    "Cite" 'ebib
1544    (lambda (path desc format)
1545      (cond
1546       ((eq format 'html)
1547        (format "(<cite>%s</cite>)" path))
1548       ((eq format 'latex)
1549        (if (or (not desc) (equal 0 (search "Cite:" desc)))
1550            (format "\\Cite{%s}" path)
1551          (format "\\Cite[%s][%s]{%s}"
1552                  (cadr (split-string desc ";"))
1553                  (car (split-string desc ";"))  path))))))
1554 #+end_src
1555
1556 #+name: define-biblatex-parencite-link
1557 #+begin_src emacs-lisp :results silent :exports code
1558   (org-add-link-type 
1559    "parencite" 'ebib
1560    (lambda (path desc format)
1561      (cond
1562       ((eq format 'html)
1563        (format "(<cite>%s</cite>)" path))
1564       ((eq format 'latex)
1565        (if (or (not desc) (equal 0 (search "parencite:" desc)))
1566            (format "\\parencite{%s}" path)
1567          (format "\\parencite[%s][%s]{%s}"
1568                  (cadr (split-string desc ";"))
1569                  (car (split-string desc ";"))  path))))))
1570 #+end_src
1571
1572 #+name: define-biblatex-cap-parencite-link
1573 #+begin_src emacs-lisp :results silent :exports code
1574   (org-add-link-type 
1575    "Parencite" 'ebib
1576    (lambda (path desc format)
1577      (cond
1578       ((eq format 'html)
1579        (format "(<cite>%s</cite>)" path))
1580       ((eq format 'latex)
1581        (if (or (not desc) (equal 0 (search "Parencite:" desc)))
1582            (format "\\Parencite{%s}" path)
1583          (format "\\Parencite[%s][%s]{%s}"
1584                  (cadr (split-string desc ";"))
1585                  (car (split-string desc ";"))  path))))))
1586 #+end_src
1587
1588 #+name: define-biblatex-footcite-link
1589 #+begin_src emacs-lisp :results silent :exports code
1590   (org-add-link-type 
1591    "footcite" 'ebib
1592    (lambda (path desc format)
1593      (cond
1594       ((eq format 'html)
1595        (format "(<cite>%s</cite>)" path))
1596       ((eq format 'latex)
1597        (if (or (not desc) (equal 0 (search "footcite:" desc)))
1598            (format "\\footcite{%s}" path)
1599          (format "\\footcite[%s][%s]{%s}"
1600                  (cadr (split-string desc ";"))
1601                  (car (split-string desc ";"))  path))))))
1602 #+end_src
1603
1604 #+name: define-biblatex-footcitetext-link
1605 #+begin_src emacs-lisp :results silent :exports code
1606   (org-add-link-type 
1607    "footcitetext" 'ebib
1608    (lambda (path desc format)
1609      (cond
1610       ((eq format 'html)
1611        (format "(<cite>%s</cite>)" path))
1612       ((eq format 'latex)
1613        (if (or (not desc) (equal 0 (search "footcitetext:" desc)))
1614            (format "\\footcitetext{%s}" path)
1615          (format "\\footcitetext[%s][%s]{%s}"
1616                  (cadr (split-string desc ";"))
1617                  (car (split-string desc ";"))  path))))))
1618 #+end_src
1619
1620 *** Style-specific biblatex commands
1621
1622 These commands can only be used by some of the citation styles that
1623 ship with biblatex.
1624
1625 #+name: define-style-specific-biblatex-commands
1626 #+begin_src emacs-lisp :noweb yes :results silent :exports code
1627   <<define-biblatex-textcite-link>>
1628   <<define-biblatex-cap-textcite-link>>
1629   <<define-biblatex-smartcite-link>>
1630   <<define-biblatex-cap-smartcite-link>>
1631   <<define-biblatex-citestar-link>>
1632   <<define-biblatex-parencitestar-link>>
1633   <<define-biblatex-supercite-link>>
1634 #+end_src
1635
1636 #+name: define-biblatex-textcite-link
1637 #+begin_src emacs-lisp :results silent :exports code
1638   (org-add-link-type 
1639    "textcite" 'ebib
1640    (lambda (path desc format)
1641      (cond
1642       ((eq format 'html)
1643        (format "(<cite>%s</cite>)" path))
1644       ((eq format 'latex)
1645        (if (or (not desc) (equal 0 (search "textcite:" desc)))
1646            (format "\\textcite{%s}" path)
1647          (format "\\textcite[%s][%s]{%s}"
1648                  (cadr (split-string desc ";"))
1649                  (car (split-string desc ";"))  path))))))
1650 #+end_src
1651
1652 #+name: define-biblatex-cap-textcite-link
1653 #+begin_src emacs-lisp :results silent :exports code
1654   (org-add-link-type 
1655    "Textcite" 'ebib
1656    (lambda (path desc format)
1657      (cond
1658       ((eq format 'html)
1659        (format "(<cite>%s</cite>)" path))
1660       ((eq format 'latex)
1661        (if (or (not desc) (equal 0 (search "Textcite:" desc)))
1662            (format "\\Textcite{%s}" path)
1663          (format "\\Textcite[%s][%s]{%s}"
1664                  (cadr (split-string desc ";"))
1665                  (car (split-string desc ";"))  path))))))
1666 #+end_src
1667
1668 #+name: define-biblatex-smartcite-link
1669 #+begin_src emacs-lisp :results silent :exports code
1670   (org-add-link-type 
1671    "smartcite" 'ebib
1672    (lambda (path desc format)
1673      (cond
1674       ((eq format 'html)
1675        (format "(<cite>%s</cite>)" path))
1676       ((eq format 'latex)
1677        (if (or (not desc) (equal 0 (search "smartcite:" desc)))
1678            (format "\\smartcite{%s}" path)
1679          (format "\\smartcite[%s][%s]{%s}"
1680                  (cadr (split-string desc ";"))
1681                  (car (split-string desc ";"))  path))))))
1682 #+end_src
1683
1684 #+name: define-biblatex-cap-smartcite-link
1685 #+begin_src emacs-lisp :results silent :exports code
1686   (org-add-link-type 
1687    "Smartcite" 'ebib
1688    (lambda (path desc format)
1689      (cond
1690       ((eq format 'html)
1691        (format "(<cite>%s</cite>)" path))
1692       ((eq format 'latex)
1693        (if (or (not desc) (equal 0 (search "Smartcite:" desc)))
1694            (format "\\Smartcite{%s}" path)
1695          (format "\\Smartcite[%s][%s]{%s}"
1696                  (cadr (split-string desc ";"))
1697                  (car (split-string desc ";"))  path))))))
1698 #+end_src
1699
1700 #+name: define-biblatex-citestar-link
1701 #+begin_src emacs-lisp :results silent :exports code
1702   (org-add-link-type 
1703    "cite*" 'ebib
1704    (lambda (path desc format)
1705      (cond
1706       ((eq format 'html)
1707        (format "(<cite>%s</cite>)" path))
1708       ((eq format 'latex)
1709        (if (or (not desc) (equal 0 (search "cite*:" desc)))
1710            (format "\\cite*{%s}" path)
1711          (format "\\cite*[%s][%s]{%s}"
1712                  (cadr (split-string desc ";"))
1713                  (car (split-string desc ";"))  path))))))
1714 #+end_src
1715
1716 #+name: define-biblatex-parencitestar-link
1717 #+begin_src emacs-lisp :results silent :exports code
1718   (org-add-link-type 
1719    "parencite*" 'ebib
1720    (lambda (path desc format)
1721      (cond
1722       ((eq format 'html)
1723        (format "(<cite>%s</cite>)" path))
1724       ((eq format 'latex)
1725        (if (or (not desc) (equal 0 (search "parencite*:" desc)))
1726            (format "\\parencite*{%s}" path)
1727          (format "\\parencite*[%s][%s]{%s}"
1728                  (cadr (split-string desc ";"))
1729                  (car (split-string desc ";"))  path))))))
1730 #+end_src
1731
1732 #+name: define-biblatex-supercite-link
1733 #+begin_src emacs-lisp :results silent :exports code
1734   (org-add-link-type 
1735    "supercite" 'ebib
1736    (lambda (path desc format)
1737      (cond
1738       ((eq format 'html)
1739        (format "(<cite>%s</cite>)" path))
1740       ((eq format 'latex)
1741        (format "\\cite*{%s}" path)))))
1742 #+end_src
1743
1744 * Footnotes
1745
1746 [fn:1] Based on posts to the mailing list by Karl Marino and Carsten
1747 Dominik.  Thanks to Bernt Hansen and Nick Dokos for help debugging a
1748 problem implementing the publishing project.
1749 [fn:2] This non-obvious use of the Org-mode link syntax appeared on the
1750 Org-mode mailing list under the heading =text color + highlight= (!).
1751 There was a lively discussion there, to which the ideas of
1752 Samuel Wales, Christian Moe and Eric Schulte contributed directly to
1753 this implementation.    
1754 [fn:3] The results of this experiment are now included in this
1755 document.  
1756 [fn:4] The =xcolor= manual is an education in color management and is
1757 highly recommended reading.
1758
1759