1.3.1. DONE Standard classes: article, book, report, beamer

1.3.2. STARTED Code blocks

1. Listings package
   

   On Ubuntu, listings.sty is part of the texlive-latex-recommended package. If you want to use color names, you will need color.sty, part of the texlive-latex-base Ubuntu package.

   The setup is straightforward - add this to your .emacs (or equivalent):

   (require 'ox-latex)
   
   (setq org-latex-listings t)
   (add-to-list 'org-latex-packages-alist '("" "listings"))
   (add-to-list 'org-latex-packages-alist '("" "color"))
   

2. Minted package
   

   Minted is an externally provided package. It consists of a couple of pieces: minted.sty provides the latex interface. It calls on an external python program called ``pygmentize'' to do the heavy lifting. See the Special note about TeX and external programs.

   The minted.sty package can be downloaded from CTAN:

   http://mirror.ctan.org/macros/latex/contrib/minted.zip

   See Where to get packages for instructions.

   The pygmentize library can be downloaded from

   http://pygments.org

   and there is documentation about installation as well.

   To use minted with org, there is no setup involved other than setting org-latex-listings to minted:

   (setq org-latex-listings 'minted)
   

   The minted.sty package is automatically added to the output .tex file.

3. Special note about TeX and external programs
   

   Some packages (e.g. minted.sty) try to execute an external program in order to accomplish their goal, by using the so-called \textbackslash write18 construct. This is normally prohibited for security reasons. There are various ways to allow it, some more convenient or more secure than others.

   If you use e.g. pdflatex from the command line, then in order to allow such external program execution, you just add the command-line option –shell-escape:

   pdflatex --shell-escape myfile.tex
   

   If you are exporting from org to latex and processing directly to pdf, then this mechanism can be implemented by customizing org-latex-to-pdf-process, which is a list of commands to execute. By default, this list consists of three repetitions of a basic pdflatex command, so you need to modify each of the three instances to add the –shell-escape option. NB: the three repetitions are supposed to ensure that all the references in a basic tex file will be resolved. This heuristic works most of the time, but not all the time.

   A more flexible approach consists of using the texi2dvi program, which analyzes logs in order to figure out what it needs to do: if the log contains complaints about undefined references, then texi2dvi will call pdflatex (or whatever) again in order to resolve them. In addition, texi2dvi is smart enough to invoke bibtex and texindex/makeindex if necessary, something that you would have to specify explicitly if you don't use texi2dvi. So why not use texi2dvi by default?

   One problem is that the currently [2012-02-21 Tue] available version on most OSes suffers from an obscure egrep bug, one that causes mysterious failures (unless you've seen the error before).

   If you want to take matters into your own hands, by all means fix texi2dvi in your setup and use it. The bug is on line 1713 - change it from

   echo "$command_line_filename" | $EGREP '^(/|[A-z]:/)' >&6 \
   

   to

   echo "$command_line_filename" | $EGREP '^(/|[A-Za-z]:/)' >&6 \
   

   The observant reader will note that the regexps are not equivalent, but in practice that does not matter unless you have DOS drives named with one of the characters in the ASCII charset that falls between ``Z'' and ``a''. If you do have drives named like this, you have more immediate problems than getting org to work on your machine.

   OK, let's assume you fixed your version of texi2dvi. How do you use it? Just set

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

   Wait a minute: where do I put the –shell-escape option? That's the second problem with texi2dvi. The best way I know to have texi2dvi call pdflatex with the –shell-escape option is to define the env variable

   PDFLATEX="pdflatex --shell-escape"
   export PDFLATEX
   

   in your .profile, .bash_profile, .login or whatever init file your login shell uses. Emacs will inherit this env variable and its value and when org invokes texi2dvi (which used $PDFLATEX internally), everything will work out. Another method (which is probably preferred by the security-conscious) is to leave it undefined. If pdflatex does not end up executing external programs, there is no problem. If it does, you'll get an error, so you say

   (setenv "PDFLATEX" "pdflatex --shell-escape")
   

   to your emacs and everything will work as before. The only problem is that the error is usually well hidden, so you'll have to dig to find it. For example, trying to export this file to PDF with PDFLATEX undefined, gives me the following error:

   PDF file /home/nick/src/emacs/org/Worg/org-dependencies.pdf was not produced
   

   But if I export to latex and try it from the command line:

   pdflatex org-dependencies.tex
   

   the error is clear:

   ! Package minted Error: You must invoke LaTeX with the -shell-escape flag.
   

   Achim Gratz suggested a different, less intrusive method on the mailing list:

   > 2) put this in ~/.profile: > PDFLATEX="pdflatex –shell-escape" > export PDFLATEX

   You might not want to do this either. The canonical way to set the environment for a single command is to define it right there with the invocation of the command.

   (setq org-latex-to-pdf-process '("PDFLATEX=\"pdflatex –shell-escape\" texi2dvi -p %f"))

   Or if your system still had the locale bug even

   (setq org-latex-to-pdf-process '("LC_ALL=C PDFLATEX=\"pdflatex –shell-escape\" texi2dvi -p %f"))

1.3.3. STARTED Symbols

1.6.1. STARTED Exporting LaTeX fragments as images.