Documentation for beamer export with new exporter
[worg.git] / org-dependencies.org
1 #+TODO: TODO STARTED | DONE
2 #+OPTIONS: toc:t
3
4 * Dependencies
5
6 #+index: Dependencies
7
8 Certain parts of org-mode have dependencies on external packages. This
9 file documents these dependencies. Many sections are placeholders,
10 waiting for input. If you can, please contribute. If you think that
11 another section should be added, please add it and fill it out. Also,
12 if you spot any mistakes, omissions or superfluities, please fix
13 them. If you have an account, you can clone the Worg tree and make the
14 additions/fixes (see [[http://orgmode.org/worg/worg-git.html]] for more
15 information), but if you don't or don't want to do it yourself, that's
16 fine too: a note to the [[mailto:emacs-orgmode@gnu.org][orgmode mailing list]] will also do
17 the job. Thanks!
18
19 Version: Org-mode version 7.8.03 (release_7.8.03.346.g1915.dirty)
20
21 ** TODO Exporting in general.
22
23 Anything here?
24
25 ** STARTED LaTeX export.
26
27 The LaTeX class is selected using the construct
28
29 : #+LaTeX_CLASS: <class>
30
31 org-latex predefines the treatment of the following LaTeX classes article,
32 report, book, beamer - or you can roll your own. And you can, of course,
33 customize the treatment to your heart's content.  This assumes a standard
34 LaTeX install.
35
36 On Linux/Mac OSX/BSD, the TeXlive distribution is recommended.  On Windows,
37 most people prefer MikTeX.
38
39 ** Where to get packages
40
41 The best way to get these packages is by using the package manager that
42 comes with your operating system. These generally contain many useful LaTeX
43 packages.
44
45 If that is not possible, then you can get individual LaTeX packages from
46 the CTAN sites (see [[http://www.tex.ac.uk/cgi-bin/texfaq2html?label=archives][CTAN archives]] for more information), but the
47 installation process is less straightforward (but more portable): generally
48 speaking, a LaTeX package comes in two files: a .ins file and a .dtx file
49 (usually packed in a zip or tgz archive). Processing the .ins file through
50 latex separates out the code from the .dtx file and produces the pieces
51 that need to be installed on your system, but then it is up to you to
52 figure out where to copy these files on your system for TeX and friends to
53 find them. The command ``kpsewhich'' is useful here: learn to use it well.
54
55 Processing the .dtx file directly through latex produces the
56 documentation of the package:
57
58     - latex foo.ins -> foo.sty, etc.
59     - pdflatex foo.dtx -> foo.pdf
60
61 Those too can be installed in standard places, so that the command ``texdoc''
62 can find and display them.
63
64 Many questions are answered by the [[http://www.tex.ac.uk/cgi-bin/texfaq2html?introduction=yes][TeX FAQ]] site, although the search
65 capability is fairly primitive by today's standards: you will have to
66 search a bit more diligently.
67
68 *** DONE Standard classes: article, book, report, beamer
69
70 The LaTeX packages included by default are as follows:
71
72 | LaTeX package | Ubuntu container package  | Options | Comments                          |
73 |---------------+---------------------------+---------+-----------------------------------|
74 | inputenc      | texlive-latex-base        | utf8    |                                   |
75 | fontenc       | texlive-latex-base        | T1      |                                   |
76 | fixltx2e      | texlive-latex-base        |         | Various LaTeX fixes - fix-cm too? |
77 | graphicx      | texlive-latex-base        |         |                                   |
78 | longtable     | texlive-latex-base        |         |                                   |
79 | float         | texlive-latex-recommended |         | floating environments             |
80 | wrapfig       | texlive-latex-extra       |         | text wrapping around figures      |
81 | soul          | texlive-latex-extra       |         | Underline/strike through          |
82 | textcomp      | texlive-latex-base        |         | Misc text symbols                 |
83 | marvosym      | texlive-fonts-recommended |         | Euro symbol                       |
84 | wasysym       | texlive-fonts-recommended |         | Misc symbols                      |
85 | latexsym      | texlive-latex-base        |         | Math symbols                      |
86 | amssymb       | texlive-base              |         | Math symbols                      |
87 | hyperref      | texlive-latex-base        |         |                                   |
88
89 *** STARTED Code blocks
90 By default, code blocks are rendered as verbatim blocks on export -
91 this setting does not have any additional dependencies.  However,
92 LaTeX provides a couple of packages that produce output that most
93 people prefer: one is the ``listings'' package and the other is the
94 ``minted'' package.  Which package is used is determined by the value
95 of the variable org-export-latex-listings: nil means the default
96 verbatim block export, 'minted means the minted package and any
97 non-nil value other than 'minted means the listings package.
98
99
100 **** Listings package
101
102 On Ubuntu, listings.sty is part of the texlive-latex-recommended package.
103 If you want to use color names, you will need color.sty, part of the
104 texlive-latex-base Ubuntu package.
105
106 The setup is straightforward - add this to your .emacs (or equivalent):
107
108 #+BEGIN_SRC emacs-lisp :exports code :results none
109    (require 'org-latex)
110
111    (setq org-export-latex-listings t)
112    (add-to-list 'org-export-latex-packages-alist '("" "listings"))
113    (add-to-list 'org-export-latex-packages-alist '("" "color"))
114 #+END_SRC
115
116 **** Minted package
117
118 Minted is an externally provided package. It consists of a couple of
119 pieces: minted.sty provides the latex interface. It calls on an
120 external python program called ``pygmentize'' to do the heavy
121 lifting. See the [[*Special%20note%20about%20TeX%20and%20external%20programs][Special note about TeX and external programs]].
122
123 The minted.sty package can be downloaded from CTAN:
124
125   http://mirror.ctan.org/macros/latex/contrib/minted.zip
126
127 See [[*Where%20to%20get%20packages][Where to get packages]] for instructions.
128
129 The pygmentize library can be downloaded from
130
131   http://pygments.org
132
133 and there is documentation about installation as well.
134
135 To use minted with org, there is no setup involved other than
136 setting org-export-latex-listings to minted:
137
138 #+BEGIN_SRC emacs-lisp
139    (setq org-export-latex-listings 'minted)
140 #+END_SRC
141
142 The minted.sty package is automatically added to the output .tex
143 file.
144
145 **** Special note about TeX and external programs
146
147 Some packages (e.g. minted.sty) try to execute an external program in
148 order to accomplish their goal, by using the so-called \textbackslash =write18=
149 construct. This is normally *prohibited* for security reasons. There
150 are various ways to allow it, some more convenient or more secure than
151 others.
152
153 If you use e.g. pdflatex from the command line, then in order to allow
154 such external program execution, you just add the command-line option
155 --shell-escape:
156
157 #+BEGIN_SRC sh
158   pdflatex --shell-escape myfile.tex
159 #+END_SRC
160
161 If you are exporting from org to latex and processing directly to pdf,
162 then this mechanism can be implemented by customizing
163 org-latex-to-pdf-process, which is a list of commands to execute.  By
164 default, this list consists of three repetitions of a basic pdflatex
165 command, so you need to modify each of the three instances to add the
166 --shell-escape option. NB: the three repetitions are supposed to
167 ensure that all the references in a basic tex file will be
168 resolved. This heuristic works most of the time, but not all the time.
169
170 A more flexible approach consists of using the texi2dvi program, which
171 analyzes logs in order to figure out what it needs to do: if the log
172 contains complaints about undefined references, then texi2dvi will
173 call pdflatex (or whatever) again in order to resolve them. In
174 addition, texi2dvi is smart enough to invoke bibtex and
175 texindex/makeindex if necessary, something that you would have to
176 specify explicitly if you don't use texi2dvi. So why not use texi2dvi
177 by default?
178
179 One problem is that the currently [2012-02-21 Tue] available version
180 on most OSes suffers from an obscure egrep bug, one that causes
181 mysterious failures (unless you've seen the error before).
182
183 If you want to take matters into your own hands, by all means fix
184 texi2dvi in your setup and use it. The bug is on line 1713 - change
185 it from 
186
187 #+BEGIN_SRC sh
188   echo "$command_line_filename" | $EGREP '^(/|[A-z]:/)' >&6 \
189 #+END_SRC
190
191 to
192
193 #+BEGIN_SRC sh
194   echo "$command_line_filename" | $EGREP '^(/|[A-Za-z]:/)' >&6 \
195 #+END_SRC
196
197 The observant reader will note that the regexps are *not* equivalent,
198 but in practice that does not matter unless you have DOS drives named
199 with one of the characters in the ASCII charset that falls between
200 ``Z'' and ``a''. If you do have drives named like this, you have more
201 immediate problems than getting org to work on your machine.
202
203 OK, let's assume you fixed your version of texi2dvi. How do you use
204 it? Just set
205
206 #+BEGIN_SRC emacs-lisp
207   (setq org-latex-to-pdf-process '("texi2dvi --pdf %f" ))
208 #+END_SRC
209
210 Wait a minute: where do I put the --shell-escape option? That's the
211 second problem with texi2dvi. The best way I know to have texi2dvi
212 call pdflatex with the --shell-escape option is to define the env
213 variable
214
215 #+BEGIN_SRC sh
216   PDFLATEX="pdflatex --shell-escape"
217   export PDFLATEX
218 #+END_SRC
219
220 in your .profile, .bash_profile, .login or whatever init file your
221 login shell uses. Emacs will inherit this env variable and its value
222 and when org invokes texi2dvi (which used $PDFLATEX internally),
223 everything will work out. Another method (which is probably preferred
224 by the security-conscious) is to leave it undefined. If pdflatex does
225 not end up executing external programs, there is no problem. If it does,
226 you'll get an error, so you say
227
228 #+BEGIN_SRC emacs-lisp
229   (setenv "PDFLATEX" "pdflatex --shell-escape")
230 #+END_SRC
231
232 to your emacs and everything will work as before. The only problem is
233 that the error is usually well hidden, so you'll have to dig to find it.
234 For example, trying to export this file to PDF with PDFLATEX undefined,
235 gives me the following error:
236
237   =PDF file /home/nick/src/emacs/org/Worg/org-dependencies.pdf was not produced=
238
239 But if I export to latex and try it from the command line:
240
241 #+BEGIN_SRC sh
242 pdflatex org-dependencies.tex
243 #+END_SRC
244
245 the error is clear:
246
247   =! Package minted Error: You must invoke LaTeX with the -shell-escape flag.=
248
249 Achim Gratz suggested a different, less intrusive method on the mailing list:
250 #+BEGIN_QUOTE
251 > 2) put this in ~/.profile:
252 >    PDFLATEX="pdflatex --shell-escape"
253 >    export PDFLATEX
254
255 You might not want to do this either.  The canonical way to set the
256 environment for a single command is to define it right there with the
257 invocation of the command.
258
259  (setq org-latex-to-pdf-process '("PDFLATEX=\"pdflatex --shell-escape\" texi2dvi -p %f"))
260
261 Or if your system still had the locale bug even
262
263  (setq org-latex-to-pdf-process '("LC_ALL=C PDFLATEX=\"pdflatex --shell-escape\" texi2dvi -p %f"))
264
265 #+END_QUOTE
266
267 *** STARTED Symbols
268
269 LaTeX syntax can be used to introduce many special symbols into a
270 document (e.g. mathematical symbols). Most of these symbols are
271 defined by basic LaTeX, but some require the presence of extra
272 packages.
273
274 | LaTeX macro | Rendered Symbol (approx) | LaTeX package | Ubuntu container package  |
275 |-------------+--------------------------+---------------+---------------------------|
276 | =\EUR=      | \EUR                     | marvosym      | texlive-fonts-recommended |
277 | =\euro=     | \euro                    | eurosym       | texlive-fonts-recommended |
278
279 Note that marvosym is now included as part of the default setup so you do
280 not need to include the package explicitly.
281
282 ** STARTED PDF export.
283
284 PDF export goes through LaTeX export first, so all the LaTeX dependencies
285 apply here as well.
286
287 Certain PDF viewers have been reported to produce more or less unreadable
288 files if Adobe Type3 fonts are used in the document.  Evince has been
289 identified as one of those. One way around this problem is to not use Type3
290 fonts. Another is to use a viewer that does not mistreat Type 3 fonts.
291
292 You can find more information about this problem in the TeX FAQ:
293
294 To find out whether a document uses Type3 fonts, open it with Acrobat
295 Reader/Evince, select Properties from the File menu and then select the
296 Fonts tab; alternatively, use the pdffonts program (part of the xpdf-reader
297 package) from the command line.
298
299 It is probably impossible to get rid of Type3 fonts completely
300 (particularly if you are using special symbols or languages that don't use
301 the Latin alphabet: in such cases, font availability is more limited and
302 you just might not be able to find Type1 fonts to do the job).
303
304 For standard latin-alphabet languages that use the Computer Modern fonts
305 (including small variations e.g. Polish and Czech), you *can* find Type1
306 versions: (XXX-needs fixing) the texlive-fonts-extra package (on
307 Ubuntu/Debian) e.g. includes the AMS CM fonts which work well.  Similar
308 packages exist for other Linux distributions and probably for other
309 operating systems as well.
310
311 | Type1 font      | LaTeX package | Ubuntu container package |
312 |-----------------+---------------+--------------------------|
313 | Computer Modern | amsfonts      | texlive-base             |
314 | Euler           |               |                          |
315
316 (/XXX-needs fixing)
317
318 ** TODO DocBook export.
319
320 ** STARTED HTML export.
321
322 *** STARTED Exporting LaTeX fragments as images.
323
324 LaTeX fragments can be exported as images for inclusion into HTML
325 documents. For example, complicated mathematical expressions can be
326 dealt with this way. This is done by creating a LaTeX file that
327 contains the fragment, processing it through LaTeX to produce a DVI
328 file and then processing it through dvipng. So, in addition to LaTeX,
329 you will need dvipng: on Ubuntu, this is available in the "dvipng"
330 package.
331
332 The LaTeX file contains a somewhat different list of LaTeX packages.  Note
333 that this is the default list, determined by the value of the variable
334 ``org-format-latex-header''.
335
336 | LaTeX package | Ubuntu container package | Options  |
337 |---------------+--------------------------+----------|
338 | amssymb       | texlive-base             |          |
339 | color         | texlive-latex-base       | usenames |
340 | amsmath       | texlive-latex-base       |          |
341 | latexsym      | texlive-latex-base       |          |
342 | eucal         | texlive-base             | mathscr  |
343
344 ** TODO org-plot
345
346 ** STARTED org-babel
347
348 For evaluating code blocks in some language, you need at the very
349 least, the interpreter for the language.