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
\\setromanfont [BoldFont={Gentium Basic Bold},
                ItalicFont={Gentium Basic Italic}]{Gentium Basic}
\\setsansfont{Charis SIL}
\\setmonofont[Scale=0.8]{DejaVu Sans Mono}
\\geometry{a4paper, textwidth=6.5in, textheight=10in,
            marginparsep=7pt, marginparwidth=.6in}
     ("\\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!


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.


Philipp said...

Awesome advice, thank you.

Brad said...

The linux libertine produce the best looking pdfs from LaTex that I've seen so far.

Andi Albrecht said...

Thanks for this advice! On Ubuntu I've had to install ttf-sil-gentium-basic in addition to ttf-sil-gentium. Otherwise the resulting document was empty except for the formula.

Anonymous said...

The Linux Libertine is a very, very nice font indeed! However, I find Minion Pro (which can be borrowed from the Adobe Reader distribution) a lot nicer, especially with the package "microtype" using pdftex.

Fernand said...

I think the math mode part of the example document is still using Computer Modern, which is butt ugly.

Coquelicot said...

Thanks for good article. I managed to get it working after upgrading the org-mode package on Ubuntu to 7.4 (default is 6.63 and not everything works out of the box).

Unknown said...

Might be a version mismatch with org mode: I had to
(require 'org-latex)
before the org-export-latex-classes variables was known.


Great fu anyway. Thanks!

mwnnlin said...

Thanks a ton!

Avdi Grimm said...

This is so so so timely for me. Thank you!

Anonymous said...

Isn't this just re-inventing the wheel? You've not convinced me that emacs+org+latex=pdf is any better than emacs+latex=pdf.

djcb said...

@Anonymous: well, it's about balancing ease of editing with flexibility. I find typing org much more convenient than typeing LaTeX. But if I hadn't work with LaTex before, maybe it would feel a bit too 'magic'.

Lex Fridman said...

@tom111 Great point. I also had to include (require 'org-latex) instead of (require 'org). Otherwise, Emacs was giving a warning that org-export-latex-classes is a void variable.

Marcelo de Moraes Serpa said...

Thanks for this gem man, your blog is so freaking useful, keep up the good work!

Anonymous said...

You know you could just write your own documentclass file? Then all you'll need is begin your document with \documentclass{yourclass}, and you can also have customisations to it, like the \author and \maketitle in the article-class.

Anonymous said...

Great blog and nice tutorial.

One issue is that the PDF would not compile for me due to a missing font. I googled around and found out I needed the following package as well (I'm a LaTeX neophyte). Hope this helps:

apt-get install texlive-latex-recommended

Peter said...

Thank you! I used your setup, and everything works nicely, except that the first page of the resulting PDF is blank except for: "pdfkeywords=, pdfsubject=, pdfcreator=Emacs Org-mode version 7.8.03"

Any thoughts?

Anonymous said...

@Peter Hyperref is missing add
to the djcb-org-article class

Anonymous said...

Thanks for the code.

John J. Camilleri said...

Nice post! Unfortunately I keep getting the error "PDF file was not produced". Here is the contents of my texput.log, any ideas?

This is XeTeX, Version 3.1415926-2.4-0.9998 (TeX Live 2012/Debian) (format=xelatex 2012.10.23) 18 FEB 2013 11:28
entering extended mode
restricted \write18 enabled.
%&-line parsing enabled.
! Emergency stop.
<*> %f

*** (job aborted, no legal \end found)

IgnorantWookie said...

I am having the same error as John J. Camilleri. Previously I've been using this to format my pdfs for schoolwork, and it really makes beautiful pdfs. I haven't updated my system just to insure this continued to work. Recently I had to install a fresh version of Linux Mint 15.

What should be done to fix this error? I would really love to have this working again.

Wild Pottok said...

Thanks a lot for this article.

Funnily, just as I managed to integrate your config, it seems to have stopped working, along with Emacs 24.4 ?