org-tutorials/org-latex-export.org

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