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   (add-to-list 'org-export-latex-classes
  23                '("article"
  24                  "\\documentclass{article}"
  25                  ("\\section{%s}" . "\\section*{%s}")))
  26 #+end_src
  27
  28 This tells the Org-mode LaTeX exporter to use the standard LaTeX
  29 =article= document class by default and to map Org-mode headlines and
  30 lists to LaTeX sectioning and list commands, as follows:
  31
  32 #+begin_src org
  33   ,* section
  34   ,** itemize
  35   ,*** itemize, etc.
  36   ,    - itemize
  37 #+end_src
  38
  39 Now you can pick a LaTeX export command from the export menu, =C-c
  40 C-e=, and expect to find a well-formed LaTeX document with the same
  41 base name as your org-mode buffer.
  42
  43 It could hardly be easier!
  44
  45 * Why LaTeX Export?
  46
  47 As the manual says, "Org is a mode for keeping notes, maintaining TODO
  48 lists, and doing project planning with a fast and effective plain-text
  49 system."  LaTeX is a convenient interface to TeX, a typesetting system
  50 that its author "intended for the creation of beautiful books — and
  51 especially for books that contain a lot of mathematics."  Where do
  52 these two activities--keeping notes and making beautiful books--overlap?
  53
  54 Org-mode is well supplied with a variety of other exporters.  The Org
  55 ASCII exporter produces a readable and simple version of an Org file
  56 for printing and sharing of notes.  The HTML exporter does such a good
  57 job of preparing notes for the web that many people use it to create
  58 entire web sites.  The XOXO exporter makes notes accessible to other
  59 software applications and the DocBook exporter starts the journey to
  60 many other formats, including LaTeX, using DocBook tools.
  61
  62 The niche for the LaTeX exporter is producing a version of an Org file
  63 for printing and sharing notes that looks better than an ASCII
  64 printout but that can be produced without the overhead required to
  65 support DocBook.  All that is needed is a working LaTeX installation.
  66 LaTeX distributions for all major platforms are today well-developed
  67 and easy to use and maintain.
  68
  69 * More Highly-Structured Documents
  70
  71 You can prepare more highly structured LaTeX documents by adding a few
  72 lines to =org-export-latex-classes= in the .emacs.
  73
  74 #+begin_src emacs-lisp
  75   (add-to-list 'org-export-latex-classes
  76                '("article"
  77                  "\\documentclass{article}"
  78                  ("\\section{%s}" . "\\section*{%s}")
  79                  ("\\subsection{%s}" . "\\subsection*{%s}")
  80                  ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
  81                  ("\\paragraph{%s}" . "\\paragraph*{%s}")
  82                  ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
  83 #+end_src
  84
  85 This setup produces the following document structure:
  86
  87 #+begin_src org
  88   ,* section
  89   ,** subsection
  90   ,*** subsubsection
  91   ,**** paragraph
  92   ,***** subparagraph
  93   ,****** itemize, etc.
  94   ,       - itemize
  95 #+end_src
  96
  97 * Exporting Other LaTeX Document Classes
  98
  99 The LaTeX exporter can be configured to produce LaTeX output for
 100 books, reports, letters or any other document class, including custom
 101 classes.  These can be useful if notes need to be formatted to a
 102 certain specification, such as a company technical manual, or if the
 103 notes are quite long, as might be the case when Org-mode is used as a
 104 laboratory or project notebook.
 105
 106 Here is a standard setup for export to a LaTeX book class:
 107
 108 #+begin_src emacs-lisp
 109   (add-to-list 'org-export-latex-classes
 110                `("book"
 111                  "\\documentclass[11pt,letter]{book}"
 112                  ("\\part{%s}" . "\\part*{%s}")
 113                  ("\\chapter{%s}" . "\\chapter*{%s}")
 114                  ("\\section{%s}" . "\\section*{%s}")
 115                  ("\\subsection{%s}" . "\\subsection*{%s}")
 116                  ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
 117                )
 118 #+end_src
 119
 120 Then, in the Org file with a book-full of notes, add this line:
 121
 122 #+begin_src org
 123   #+LaTeX_CLASS: book
 124 #+end_src
 125
 126 * Passing Options to Document Classes
 127 The standard LaTeX document classes, =article=, =report=, =book=,
 128 =slides=, and =letter= take options that, where applicable, select the
 129 type size, paper size, orientation, whether to print one- or
 130 two-sided, and a variety of formatting specifications.  Custom LaTeX
 131 document classes can define their own options, as needed.
 132
 133 You can pass options to the LaTeX =\documentclass= macro by putting a
 134 line like this in your Org-mode file:
 135
 136 #+begin_src org
 137   #+LaTeX_CLASS_OPTIONS: [a4paper,twoside,twocolumn]
 138 #+end_src
 139
 140 * Specifying LaTeX Packages
 141 According to its author, the LaTeX macro package "represents a balance
 142 between functionality and ease of use."  The LaTeX user who adds
 143 functionality through the addition of packages necessarily makes the
 144 software more difficult to use.  Like LaTeX itself, the Org-mode LaTeX
 145 exporter has struck its own balance between functionality and ease of
 146 use with the addition of several LaTeX packages.  These are written
 147 out in the LaTeX header as LaTeX \usepackage{} commands.
 148
 149 The names of the LaTeX packages are kept in a data structure designed
 150 for ease of maintenance as additional features are added to the LaTeX
 151 exporter.  Packages in the default packages list,
 152 =org-export-latex-default-packages-alist=, are required to support all
 153 features of the LaTeX exporter.  This list is typically specified in
 154 the Org-mode source code and its documentation contains a warning not
 155 to modify it.  Packages not included on the default packages list that
 156 the user needs consistently can be added to
 157 =org-export-latex-packages-alist=.  Packages needed for a particular
 158 file can be specified by inserting a line like this in the Org-mode
 159 buffer:
 160 #+begin_src org
 161   ,#+LATEX_HEADER: \usepackage{xyz}
 162 #+end_src
 163 * Using Custom Classes
 164 If the user has custom LaTeX document classes that conflict with the
 165 default packages or that only require a few of the default packages to
 166 support all features of the LaTeX exporter, then this can be handled
 167 in the .emacs using [DEFAULT-PACKAGES], [NO-DEFAULT-PACKAGES],
 168 [PACKAGES], [NO-PACKAGES], [EXTRA], [NO-EXTRA].
 169
 170 Here is a simple example that uses a LaTeX class that supports the
 171 Org-mode requirements and leaves open the possibility of adding file
 172 specific packages:
 173
 174 #+begin_src emacs-lisp
 175     (add-to-list 'org-export-latex-classes
 176           '("article"
 177              "\\documentclass{org-ready}
 178              [NO-DEFAULT-PACKAGES]
 179              [EXTRA]"
 180              ("\\section{%s}" . "\\section*{%s}")
 181              ("\\subsection{%s}" . "\\subsection*{%s}")
 182              ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
 183              ("\\paragraph{%s}" . "\\paragraph*{%s}")
 184              ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
 185 #+end_src
 186 * Creating PDF Output
 187 The LaTeX exporter by default produces code ready for processing by
 188 pdflatex.  pdflatex calls the pdfTeX program, a modern extension of
 189 TeX that produces PDF output directly, using the standard LaTeX
 190 macros.  pdfTeX is tightly integrated with PDF features such as
 191 hypertext links and tables of contents, using LaTeX packages such as
 192 hyperref, which is included in the default packages list.
 193
 194 Org-mode offers a command to produce a PDF file from the LaTeX export.
 195 This is bound to =C-c C-e p=.  The command =C-c C-e d= does all this
 196 *and* opens the PDF file in the default reader.
 197
 198 If you use a different TeX typesetting engine, then you will want to
 199 modify the variable =org-latex-to-pdf-process=.  This is a list of
 200 strings, each of which contains a call to one of the TeX typesetting
 201 engines or to an auxiliary program, such as BibTeX, makeindex, etc.
 202
 203 * Exporting Parts of an Org-mode Buffer
 204 Tags can be used to select which parts of an Org-mode buffer are sent
 205 to the LaTeX exporter.  In the typical case, the
 206 Org-mode buffer contains material for a single export file along with
 207 material that shouldn't appear in the export; tags distinguish the
 208 export parts from the non-export parts.  This is the single
 209 export case.  It is also possible to use tags to specify multiple
 210 export targets in a single Org-mode buffer.  In the multiple export
 211 case, tags are resolved by a [[http://orgmode.org/org.html#Publishing][publishing management system]].
 212
 213 ** The Single Export Case
 214 The tags used for the single export case are held in
 215 two variables: =org-export-select-tags= is a list of tags, initially set
 216 to =export=, that select a tree or sub-tree for export;
 217 =org-export-exclude-tags= is a list of tags, initially set to
 218 =noexport=, that exclude a tree or subtree for export.  The effect
 219 they have on export is logical, but the logic isn't necessarily what
 220 one might expect.  In particular, if both select tags and exclude tags
 221 are to be used in the same buffer, then their use must follow certain
 222 rules.  Also, the handling of unmarked trees and subtrees changes
 223 depending on which tags are used and how they are used.
 224
 225 If neither select tags nor exclude tags are used, then all of the trees
 226 and their subtrees are sent to the LaTeX exporter.  If, however, a
 227 select tag is added to a tree as in the example below, then unmarked
 228 trees will *not* be sent to the exporter.  Thus, the effect of a
 229 select tag is not restricted to its tree; its effect extends to the
 230 entire buffer.
 231
 232 #+begin_src org
 233   ,* Tree 1                                                             :export:
 234   ,   This is exported
 235   ,** Subtree 1
 236   ,   This is also exported
 237   ,* Tree 2
 238   ,  This is not exported
 239   ,** Subtree 2
 240   ,  This is not exported, either
 241 #+end_src
 242
 243 Once the scope of the tag's effect is grasped, the primary rule of using
 244 select and exclude tags is obvious: only one type of tag may be used
 245 for the trees of a buffer.  If both types of tags are used for trees,
 246 how can Org-mode decide what to do with the unmarked trees?
 247
 248 A corollary of this rule is that the other type of tag can only be
 249 used in a subtree of the tagged tree in order to reverse the effect of
 250 the tree-level tag, as in the following example.
 251
 252 #+begin_src org
 253   ,* Tree 1                                                             :export:
 254   ,   This is exported
 255   ,** Subtree 1                                                       :noexport:
 256   ,   This is not exported
 257   ,* Tree 2
 258   ,  This is not exported
 259   ,** Subtree 2
 260   ,  This is not exported, either
 261 #+end_src
 262
 263
 264 ** The Multiple Export Case
 265 In the multiple export case, tags used to select a tree or subtree for
 266 export are defined in =.emacs= as part of the configuration needed to
 267 specify the many properties of a publication project.  A tutorial
 268 illustrates [[http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.php][the flexibility of the publishing mechanism]] using an HTML
 269 example.  The intricacies of the publishing mechanism are beyond the
 270 scope of of this LaTeX export tutorial.  Here, a working example[fn:1]
 271 is described.
 272
 273 In the example, the file =index.org= holds material for two export
 274 targets, one related to work items and the other related to home.  The
 275 variable =org-publish-project-alist= has two entries, one for a
 276 project named =work= and the other for a project named =home=.  Both
 277 projects are based on the file =index.org= located in =~/notes/org=.
 278
 279 Both projects will create output files named =index.tex=, based on the
 280 name of the Org-mode file used for import.  The two =index.tex= files
 281 are kept separate by writing them to different directories, as
 282 indicated by the keyword argument =:publishing-directory=.
 283 #+begin_src emacs-lisp
 284   (setq org-publish-project-alist
 285         '(
 286           ("work"
 287            :base-directory "~/notes/org/"
 288            :base-extension "org"
 289            :publishing-directory "~/notes/export/work/"
 290            :publishing-function org-publish-org-to-latex
 291            :select-tags     ("@WORK")
 292            :title "Work Notes"
 293            :include ("index.org")
 294            :exclude "\\.org$"
 295            )
 296           ("home"
 297            :base-directory "~/notes/org/"
 298            :base-extension "org"
 299            :publishing-directory "~/notes/export/home/"
 300            :publishing-function org-publish-org-to-latex
 301            :select-tags     ("@HOME")
 302            :title "Home Phone"
 303            :include ("index.org")
 304            :exclude "\\.org$"
 305            )
 306           ))
 307 #+end_src
 308
 309 The parts of =index.org= tagged =@WORK= can now be exported to
 310 =~/notes/export/work/index.tex= with =C-c C-e X= and selecting the
 311 =work= project.
 312
 313 Similarly, the parts of =index.org= tagged =@HOME= can now be exported to
 314 =~/notes/export/home/index.tex= with =C-c C-e X= and selecting the
 315 =home= project.
 316
 317 * Exporting Pseudo-Code
 318   The LaTeX exporter will fontify exported code blocks written in any
 319   language that has an associated Emacs mode for editing.  If you want
 320   to export pseudo-code, for which there is no corresponding Emacs
 321   mode, then one approach is to use =#+begin_latex ... #+end_latex=
 322   and write the pseudo-code directly in LaTeX.  This depends on the
 323   LaTeX [[http://www.ctan.org/tex-archive/macros/latex/contrib/listings/][listings package]], which is one of the default packages used by
 324   Org-mode.
 325
 326   Dan Davison provided this example on the Org-mode list:
 327
 328 : #+begin_latex
 329 : \begin{algorithm}
 330 :  \caption{An algorithm}
 331 :  \label{alg:myalg}
 332 :  \begin{lstlisting}[mathescape,escapeinside='']
 333 :    '\foreach individual $i$'
 334 :        '\foreach group $k$'
 335 :            $\gamma_{ik} \getsp Q_{k}\prod_{l}\prod_{a=1}^{2}P_{lkX_{ila}}$
 336 :  \end{lstlisting}
 337 : \end{algorithm}
 338 : #+end_latex
 339
 340
 341
 342 * Footnotes
 343
 344 [fn:1] Based on posts to the mailing list by Karl Marino and Carsten
 345 Dominik.  Thanks to Bernt Hansen and Nick Dokos for help debugging a
 346 problem implementing the publishing project.