2011-04-12

nice-looking pdfs with org-mode and xetex

I've discussed the wonderful org-mode here a number of times already. It has become a pretty important part of my overall workflow. One thing I am using org-mode for, is to produce all kinds of PDF-documents that I can share with other people.

org-mode & LaTeX

In the past, I often used straight LaTeX for such things; I wrote my thesis with it, but also many other documents. There are many things I like about LaTeX, one of them being that I can use emacs for writing. Still, there are also a few things I do not particularly like. First, I think LaTeX is quite heavy with formatting directives, which hinder my writing flow (e.g., when I want to include an image, a table or a source code snippet). Another thing is that I find the default LaTeX styles a bit boring. Nothing wrong with it, but there just too many documents with the exact same lay-out.

Now, back to org-mode. One way to use org-mode is as a friendly way to generate LaTeX (and, consequently, PDFs). This is a big improvement! Much more than LaTeX itself, org-mode allows to focus on the contents of the document, rather than instructing LaTeX what to do. This comes at the price of small bit of flexibility, but, if needed org-mode allows you include straight LaTeX when needed – so while keeping easy things easy, hard things are still possible. The latter does require a bit of experience with LaTeX a though.

setting up XeTeX

Now, for the second issue, the way documents look, there are other solutions, and they live on the LaTeX side of things. I'm sure many have seen The Beauty of LaTeX. Using the XeTeX implementation of LaTeX and the fontspec package, you can create LaTeX documents with a bit 'refreshed' look.

So, the steps to get this working with org-mode:

  • install the texlive-xetex packages on Ubuntu and Debian (this installs a huge set of packages)
  • install the SIL fonts (I'm using ttf-sil-gentium and ttf-sil-charis, but there are more)
  • I'm also using DejaVu Mono (ttf-dejavu)

teaching org-mode about the new XeTeX stuff

We now need to define some LaTeX document class for org-mode that uses XeTeX and some of these new fonts. Let's call the document class djcb-org-article (as I often use the djcb- prefix for my own stuff), it could be something like the following (add to your org-setup – e.g., in your .emacs, make sure there is a (require 'org) before this:

;; 'djcb-org-article' for export org documents to the LaTex 'article', using
;; XeTeX and some fancy fonts; requires XeTeX (see org-latex-to-pdf-process)
(add-to-list 'org-export-latex-classes
  '("djcb-org-article"
"\\documentclass[11pt,a4paper]{article}
\\usepackage[T1]{fontenc}
\\usepackage{fontspec}
\\usepackage{graphicx} 
\\defaultfontfeatures{Mapping=tex-text}
\\setromanfont{Gentium}
\\setromanfont [BoldFont={Gentium Basic Bold},
                ItalicFont={Gentium Basic Italic}]{Gentium Basic}
\\setsansfont{Charis SIL}
\\setmonofont[Scale=0.8]{DejaVu Sans Mono}
\\usepackage{geometry}
\\geometry{a4paper, textwidth=6.5in, textheight=10in,
            marginparsep=7pt, marginparwidth=.6in}
\\pagestyle{empty}
\\title{}
      [NO-DEFAULT-PACKAGES]
      [NO-PACKAGES]"
     ("\\section{%s}" . "\\section*{%s}")
     ("\\subsection{%s}" . "\\subsection*{%s}")
     ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
     ("\\paragraph{%s}" . "\\paragraph*{%s}")
     ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

Of course, this can be customized to your own preference; e.g., North-Americans may not be using A4-paper.

org-mode takes care of the export from its own format to LaTeX, but we need to tell it to use xelatex to process the LaTeX to PDF:

(setq org-latex-to-pdf-process 
  '("xelatex -interaction nonstopmode %f"
     "xelatex -interaction nonstopmode %f")) ;; for multiple passes

That's all that's needed on the setup-side.

creating a document

Now, let's create a little test document, test.org, to show how it works:

#+LaTeX_CLASS: djcb-org-article
#+TITLE: My little document

* Introduction
  
  This is my document. There are many like it, but this is mine. It's easy to
  write without *too* _many_ /distractions/.
  
** Normal distribution

   Probability density of the normal distribution, using familiar TeX notation
   for formulae:
 
   $$\frac{1}{\sqrt{2\pi\sigma^2}}e^{ -\frac{(x-\mu)^2}{2\sigma^2} }$$

** Some table

| *Greek God* | *Roman God* | *Element*      |
|-------------+-------------+----------------|
| Zeus        | Jupiter     | Sky and clouds |
| Hera        | Juno        | Family         |
| Poseidon    | Neptune     | Sea            |
| Hades       | Pluto       | Underworld     |

We can export this to a PDF using C-c C-e p (or C-c C-e d to automatically open the PDF in a PDF-viewer). This should all work nicely; if it doesn't, note that when exporting, say, test.org, org-mode will create a file called test.tex, and visit in a buffer. There's also a buffer with the output from various commands, but sometimes it can be useful to run LaTeX (xelatex in this case) on the file by hand, to find any problems. The wonderful org-documentation about exporting to LaTeX has more information.

I think the result is pretty nice – it stays true to the class LaTeX article class, but freshens it up a bit with some news font. If you can make something better – which is not unlikely – you are of course invited to contribute your own!

Concluding

org-mode is a pretty convenient way to write nice-looking PDFs. Combined with xelatex, they don't have to look too plain :). However, I'm aware of my limitations when it comes to the coolness/aesthetic aspects, but I hope others can show the way here.

Maybe org-mode could ship with a number of ready-made templates to make it easy to make nice-looking documents, resumes, reference cards, reports, meeting notes and so on.