Generate LaTeX Documents From Org Mode

LaTeX Logo

Introduction

I needed to generate PDF documents including mathematical formulae and graphics drawings. As I already use Org mode for documentation, I decided to employ Org mode for this task as well, rather than dealing with LaTeX directly, like I used to do a long time ago.

Summary

This page contains

what software components are needed
which Org mode customisations are needed
how to set various LaTeX preferences

You might want to download the file ./org2latex.zip to see my test and configuration files.

Prerequisites

I use the "texlive" TeX/LaTeX software. I installed the following Debian packages:

texlive: This is not the full TeX/LaTeX set, but sufficient, except for the next item
texlive-latex-extra: is needed because of wrapfig.sty, which is required by the Org mode exporter (Emacs v28.2 Org mode v9.5.5)
cm-super: makes sure you get decent looking "type 1" fonts included in the output PDF document. By default you get "type 3" bit-mapped fonts which do not look smooth
texlive-lang-german: because I write in german and english
texlive-latex-recommended-doc: to have documentation available locally
inkscape: TeX/LaTeX cannot directly deal with scalable vector graphics (SVG) but it calls inkscape automatically to support SVG

Approach

I wanted to do as few tweaking on the LaTeX set-up as possible and hence tried to fulfil as many of my requirements on the Org mode side.

The Org mode exporter UI (C-c C-e) gives you the choice to generate a *.tex or *.pdf file (with *.tex as an intermediate step). If you choose the latter, the pdflatex program will be invoked by Org mode by default.

In-Buffer Settings

Instead of putting Org mode settings in Emacs' init.el file, I put them in a file mysetup.org, which I include in a main.org document file like this:

#+SETUPFILE: ~/mysetup.org

as the first line. This allows for easy central maintenance.

And: If you needed a special setting for a particular document, you could still put this setting after the #+SETUPFILE... line and it will take precedence.

LaTeX Settings

Not all settings can be put in the set-up file. I needed to have LaTeX import a file with symbol definitions, to have additional UTF-8 special characters available in LaTeX. Only the LaTeX import statement could go in the Org mode set-up file. The LaTeX definitions went in a file called myAddUTF8.tex. I store this file in directory ~/texmf/

Manifest

I share those files in file ./org2latex.zip, which contains:

README.txt	txt version of this web-page
test.org	Test Org mode source file
test.pdf	Resulting output PDF file
test.tex	Resulting intermediate LaTeX file
mysetup.org	Org set-up file
myAddUTF8.tex	LaTeX symbol definitions
redetho-logo1.svg	Test logo
blind_*.svg	Test vector graphics file
blind_*.jpg	Test image files
lit.bib	Test BibTeX file for citations

The files are provided as is. I do not take any responsibility nor provide any warranty.

Installation

Unzip ./org2latex.zip to any convenient location
You might want to copy mysetup.org to your home directory. If you choose a different location, please amend the path in the first line of test.org
You might want to copy myAddUTF8.tex to ~/texmf/. If you choose a different location, please amend the line
```
#+LATEX_HEADER: \input{~/texmf/myAddUTF8}
```
in file mysetup.org

Test Usage to Generate a LaTeX-PDF-File

Open test.org in Emacs
Export to a LaTeX PDF file by pressing C-c C-e l p, which runs the command org-latex-export-to-pdf
View the resulting file test.pdf using your favourite PDF-viewer. Please note that the ZIP archive also contains a result file test.pdf and the intermediate file test.tex for your reference. You might want to rename those two beforehand

While the C-c C-e standard Org mode exporter is fine for tests and occasional exports, I use a Makefile for more complex projects. That Makefile would typically contain (covers both Windows and Linux):

ifeq ($(OS),Windows_NT)
	EMACSCL=$(MYPROGPATH)/emacs-27.2/bin/emacsclientw.exe
else
	EMACSCL=emacsclient
endif

test.pdf:	test.org $(HOME)/mysetup.org
	$(EMACSCL) --eval "(find-file \"test.org\")" \
	 "(org-latex-export-to-pdf)"

Description of My LaTeX Preferences

Below text has some narrative about the LaTeX settings in file mysetup.org. Of course your requirements may be different.

#+LATEX_CLASS_OPTIONS: [fleqn, a4paper,11pt]

I prefer left aligned equations. You might have different paper or font size requirements.

#+LATEX_HEADER: \usepackage[a4paper,margin=1in,left=1.5in]{geometry}

The default LaTeX page layout use quite a lot of margin, which I adjust here.

#   #+LATEX_HEADER: \usepackage{helvet}

Normally, I am fine with Computer Modern fonts for article type write-ups, but in case…

#+LATEX_HEADER: \usepackage[shorthands=off,AUTO]{babel}

The babel package allows to use other languages rather than english. This construct does two things:

A language specification in your Org mode file like #+LANGUAGE: xx will replace the AUTO literal by an approriate language string. This is done by the Org mode exporter. If you omit the #+LANGUAGE: xx construct then english will be the default language
babel allows special escaping for non ASCII characters. shorthands=off switches this escape mechanism off. Because today this escaping is much less needed as you can enter such characters directly as UTF-8.

#+LATEX_HEADER: \usepackage{eurosym}

The currency I use most often.

#+LATEX_HEADER: \usepackage{parskip}

I prefer to separate paragraphs by empty space rather than by indenting the first line.

#+LATEX_HEADER: \usepackage{svg}

I use scalable vector graphics (SVG).

#+OPTIONS: tex:dvisvgm

That part of mysetup.org is related to SVG processing. It makes sure that SVG files stay scalable rather than being converted to bit mapped graphics.

#+LATEX_HEADER: \svgsetup{inkscapelatex=false, inkscapearea=page}

By default, LaTeX processes text elements in the included SVG files. This can produce unexpected results. inkscapelatex=false leaves the SVG text elements alone.

By default, the "bounding box" of all graphics elements in the SVG file determines what is being projected/scaled into the resulting LaTeX/PDF. inkscapearea=page rather makes shure that the full size of the SVG is considered instead, either using the viewBox attribute or the width and height attributes in the SVG file.

#  UTF-8 input is fine, but for output LaTeX needs some definitions
#+LATEX_HEADER: \input{~/texmf/myAddUTF8}

While you can use UTF-8 to input quite some special characters, LaTeX needs further definitions on the output side.

#  Customise title
#+LATEX_HEADER: \makeatletter
#+LATEX_HEADER: \renewcommand{\maketitle}{%
#+LATEX_HEADER:   \begingroup\parindent0pt
#+LATEX_HEADER:   \sffamily
#+LATEX_HEADER:   \Huge{\bfseries\@title}\par\bigskip
#+LATEX_HEADER:   \LARGE{\bfseries\@author}\par\medskip
#+LATEX_HEADER:   \normalsize\@date\par\bigskip
#+LATEX_HEADER:   \endgroup\@afterindentfalse\@afterheading}
#+LATEX_HEADER: \makeatother

These statements define a custom title page, where things are left aligned rather than centered.

Supporting Special Characters

Greek Characters

I you need to use greek character, not those from math mode, but upright characters possibly with diacritics, the most easy solution is to use the textalpha LaTeX package. You would hence add

#+LATEX_HEADER: \usepackage{textalpha}

to your Org mode document, to write e.g. τέχνη. Please see the documentation

Box Graphics Characters

For simple graphics you might want to use the good old box graphics characters with a fixed width font. The LaTeX pmboxdraw package supports this:

#+LATEX_HEADER: \usepackage{pmboxdraw}

Example Org Mode block using box graphics characters:

:  Protocol
: ┌───┴──┐
: https://cc-alzenau.de/news/
:         └─────┬─────┘└─┬──┘
:            Domain     Sub-
:                       Directory

Please see https://ctan.org/pkg/pmboxdraw.

Other Export Target Formats

I trust you noticed that the file mysetup.org also contains Org mode in-buffer customisations for HTML export and text export. I have written about HTML export here.

You might also be interested in beamer slide generation from Org mode or using pandoc together with Org mode.