Introduction: Org to LaTeX to PDF
There are two types of Emacs users: those who give up and go back to vscode, and those who get full citizenship and move permanently to Emacs town. This article is for those masochists who don't care if Google provides an easier tool for writing pretty texts and code notebooks.
Org-mode is an awesome tool for writing multi-purpose text in Emacs. It can be used for literate programming (like Jupyter Notebooks) in any languages we want, for todo-lists and schedules, for articles and much more.
We have been using Org files for our own notetaking for a few months now, but until yesterday we didn't really explore the export and publish functionalities, which allow us to transform org texts into formats used in the world outside of Emacs, and package a collection of texts into a cohesive unit. (we will not explore publish in this article, as we have not yet used it).
We want to configure Emacs to export an Org text to a pretty PDF. Let's use this article, which we are currently writing in org-mode (inception!) as an example. Our objective is to use org-export-dispatch (C-c C-e) to export to LaTeX as PDF file and open.
LaTeX: what is it, installation, exporting PDF
The first step in our pipeline from Emacs Org to PDF is exporting our document to LaTeX. Emacs can't do that if the program is not installed. So, before we try to export our Org file, let us make sure that we can correctly produce a PDF from LaTeX code.
What is LaTeX?
From the LaTeX documentation:
LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is the de facto standard for the communication and publication of scientific documents.
In this sense, LaTeX is a hierarchical text definition language, like markup or html, which allow us to describe the role of each section in the context of the whole text. This is an example of LaTeX code, taken from the docs.
\documentclass{article}
\title{Cartesian closed categories and the price of eggs}
\author{Jane Doe}
\date{September 1994}
\begin{document}
\maketitle
Hello world!
\end{document}
The documentclass section describes the template for the output document; in other words, the style, which is defined in the LaTeX document template.
In summary, LaTeX is a language and a program for:
- hierarchical text definition language (like markup, html)
- format and style definition language (like css)
- text processing program
Installation
If we open the LaTeX Project GET page, we will find the recommended distributions for the most popular operating systems. We are configuring this on our MacBook Air, so we should get MacTeX. However, the complete MacTeX bundle is 5GB, which is absurdly huge for our humble project. Rather, let us go for the much smaller 90MB BasicTeX.
The BasicTeX .pkg file is very much plug and play, as it installs the binaries to folders already supported in the terminal PATH. For generating a PDF from LaTeX code, will use XeLaTeX, an improved version of LaTeX with support for unicode and special fonts.
Fixing problems and exporting the PDF
Even the minimal BasicTeX comes with the necessary tools to generate a PDF. Therefore, we should be ready to export our PDF after the installation. Let's save the the LaTeX code example provided earlier as article.tex and try exporting it to PDF by using the xelatex article.tex command.
In our machine we have encountered some problems, registered in a .log file. Let us see what they are and how to solve them.
$ xelatex article.tex
...
(/usr/local/texlive/2023basic/texmf-dist/tex/latex/amsmath/amsopn.sty))
(/usr/local/texlive/2023basic/texmf-dist/tex/latex/amsfonts/amssymb.sty
(/usr/local/texlive/2023basic/texmf-dist/tex/latex/amsfonts/amsfonts.sty))
! LaTeX Error: File 'wrapfig.sty' not found.
The error is very clear. LaTeX cannot find the wrapfig package. Our distribution must have come without it. The good thing is that the error message even shows us where to put it. The fix is easy, we just download the file and store it where the error pointed us, maybe in the graphics/ folder:
$ wget http://mirrors.ctan.org/macros/latex/contrib/wrapfig/wrapfig.sty
$ sudo mv wrapfig.sty /usr/local/texlive/2023basic/texmf-dist/tex/latex/graphics/wrapfig.sty
If we run xelatex article.tex again, we get a different error, and that is progress; it means the first problem
was solved. Here is the second error:
$ xelatex article.tex
...
(/usr/local/texlive/2023basic/texmf-dist/tex/latex/amsmath/amsopn.sty))
(/usr/local/texlive/2023basic/texmf-dist/tex/latex/amsfonts/amssymb.sty
(/usr/local/texlive/2023basic/texmf-dist/tex/latex/amsfonts/amsfonts.sty))
! LaTeX Error: File 'capt-of.sty' not found.
This is almost the same error as before. LaTeX cannot find the capt-of package. The solution here is a bit more challenging, because the source does not provide the .sty file (don't ask us why). We have to compile it ourselves.
$ wget http://mirrors.ctan.org/macros/latex/contrib/capt-of/capt-of.dtx
$ wget http://mirrors.ctan.org/macros/latex/contrib/capt-of/capt-of.ins
$ xelatex capt-of.ins
$ sudo mv capt-of.sty /usr/local/texlive/2023basic/texmf-dist/tex/latex/caption/capt-of.sty
Now, if we run xelatex article.tex, we get a beautiful article.pdf exported by LaTeX. Awesome.
Running on Emacs
The essential part is basically done. All we have to do now in order to export our org files to PDF is telling Emacs what LaTeX compiler and command to use. For that, just add to the elisp configuration file (e.g. init.el):
(setq org-latex-compiler "xelatex")
(setq org-latex-pdf-process '("xelatex %f"))
We can now run M-x org-export-dispatch (C-c C-e) to export to LaTeX as PDF file and open (options l-o), just like we wanted. In fact, we have done it in just the org file for this article, and it worked beautifully.
This concludes our explanation of how to export an Org text to a pretty PDF. One thing to add is that we are not academics who produce papers frequently, so our knowledge of LaTeX is very limited. Feel free to leave any suggestions and corrections in the commentaries.
Top comments (0)