Org mode is well known for its powerful taking notes and task management capabilities, but for me it is always (or at least now) the document preparation mechanism that truly attracts me. Just imagine how amazing that we can just write content in org mode and then convert it to either PDF through LaTeX or HTML. Actually since Org mode is so good at these LaTeX tasks, I am even using the Org Beamer rather than the original LaTeX Beamer to prepare presentations. Another strong point of Org mode is Babel, which enables the execution of source code in Org file. This makes Org mode a good tool for literature programming.

There are different ways to include graphics in a Org originated document. For example, we can draw figures using TikZ directly, or we can use other programming languages or tools, such as python and ditaa embedded in Org mode’s source code block to generate figure. Following are some examples to include graphics in Org mode.

Source code in org-mode

Source code can be embedded and evaluated in org file through `src' block. To start with source code evaluation, we first need to enable interested languages in .emacs configuration file (by default only emacs-lisp is enabled):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (python . t)
   (ditaa . t)
   (dot . t)
   (plantuml . t)
   (gnuplot . t)
   (sh . t)
   (org . t)
   (latex . t)))

The source code block can be exported either as the code block it self or the evaluation results of it depending on the value of :exports. The values could be code (the default), results, both or none. Which kind of results are generated after evaluation depending on the header argument :results.

:exports code

If the following python code block is included in the org file:

1
2
3

#+begin_src python
print "Hello, Python!"
#+end_src

the HTML output is like this:

1

print "Hello, Python!"

:exports results

If the :exports is specified as results and :results has value of output:

1
2
3

#+begin_src python :exports results :results output
print "Hello, Python!"
#+end_src

after evaluation of the source code block (C-c C-c) the HTML output is

1

Hello, Python!

If the results of a source code block needs to be exported, chances are we already evaluated the code to check its results. So when export, it is better to used the pre-evaluated results directly and avoid repeated evaluation again. By setting the following variable, when export, only inline code blocks will be evaluated. Non-inline code blocks are assumed to have their results already inserted in the buffer. An extra advantage of using =‘inline-only= is potential hazardous code may be avoided when export org file from unknown sources.

1

(setq org-export-babel-evaluate 'inline-only)

Using ‘ditta’ to draw diagrams

ditaa can convert diagrams drawn using ascii art into bitmap graphics. Example of using ditaa is shown below:

1
2
3
4
5
6
7
8
9

#+begin_src ditaa :file images/blue.png :cmdline -r
+---------+
| cBLU    |
|         |
|    +----+
|    |cPNK|
|    |    |
+----+----+
#+end_src

Include ‘tikz’ figures

pgf/tikz is another great software to draw professional graphics in LaTeX document, and it’s also easy to be included in a LaTeX environment in org file. Although tikz code can be put in a #+BEGIN_LaTeX ... #+END_LaTeX directly, but then the figure can only be viewed when export the whole org file to pdf. The second method is to put the tikz code of each figure in an individual TeX file, and include figures generated by the code. The downside of this method is then we have to keep all of those files and it may mess up easily.

The magic way to include, to me, is to put tikz in a LaTex source code block, and when execute this code block, figures can be generated and kept in a seperate ‘images’ folder without worrying about where to store the TeX code. Since tikz generates pdf format figure, imagemagic needs to be used if we want to preview the figure in org mode (though we will use pdf later when export to html or pdf file).

1
2

;; use imagemagick to preview latex
(setq org-latex-create-formula-image-program 'imagemagick)

The following emacs configuration code included several useful packages so we do not need to specify them for each latex source code block.

1
2
3
4
5
6

;; set up tikz as one of the default packages for LaTeX
(setq org-latex-packages-alist
      (quote (("" "color" t)
          ("" "minted" t)
          ("" "parskip" t)
          ("" "tikz" t))))

An source code block example for tikz

Simply using the following code, when evaluation the results will be wrapped to a BEGIN_LaTeX ... END_LaTeX environment.

1
2
3
4
5
6
7
8

#+NAME: example-tikz
#+begin_src latex :exports results :results output :file images/pic.pdf
\begin{tikzpicture}
\node[red!40!black] (a) {A};
\node (b) [right of=a] {B};
\draw[->] (a) -- (b);
\end{tikzpicture}
#+end_src

1
2
3
4

#+results: example-tikz
#+BEGIN_LaTeX
[[file:../images/2015-10-23-pic.png]]
#+END_LaTeX

The workaround is to specify :results to use raw instead of the default latex format.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#+begin_src latex :exports results :results output raw :file images/fsa.png
% Define block styles
\usetikzlibrary{shapes,arrows}
\tikzstyle{astate} = [circle, draw, text centered, font=\footnotesize, fill=blue!25]
\tikzstyle{rstate} = [circle, draw, text centered, font=\footnotesize, fill=red!25]

\begin{tikzpicture}[->,>=stealth', shorten >=1pt, auto, node distance=2.8cm, semithick]
\node [astate] (1) at (0,0) {1};
\node [astate] (2) at (1,0) {2};
\node [rstate] (3) at (2,0) {3};
\path (1) edge [bend left] node {b} (2)
(2) edge node {b} (3)
(2) edge [bend left] node {a} (1)
(3) edge [loop above] node {(a, b)} (3);
\end{tikzpicture}
#+end_src

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

% Define block styles
\usetikzlibrary{shapes,arrows}
\tikzstyle{astate} = [circle, draw, text centered, font=\footnotesize, fill=blue!25]
\tikzstyle{rstate} = [circle, draw, text centered, font=\footnotesize, fill=red!25]

\begin{tikzpicture}[->,>=stealth', shorten >=1pt, auto, node distance=2.8cm, semithick]
  \node [astate] (1) at (0,0) {1};
  \node [astate] (2) at (1,0) {2};
  \node [rstate] (3) at (2,0) {3};
  \path (1) edge [bend left] node {b} (2)
  (2) edge node {b} (3)
  (2) edge [bend left] node {a} (1)
  (3) edge [loop above] node {(a, b)} (3);
\end{tikzpicture}