# HaTeX User's Guide

### From HaskellWiki

## Contents |

## 1 Preface

### 1.1 Introduction

If you are here because you want to learn more about HaTeX, or just feel curious, you are in the right place. First of all, note that this guide is addressed to that people that already knows the basics of both Haskell and LaTeX. Otherwise, try to learn first a bit of these languages (both are quite useful learnings). To learn Haskell, though I guess you already learned it since you are reading these lines, go to the Haskell web [1] and search for some tutorials or books. To learn LaTeX, you can start with*The not so short introduction to LaTeX* [2].

The HaTeX library aspires to be the tool that Haskellers could want to make theirLaTeX things without exit of their language (we understand that is difficult to leave Haskell after the first date), trying to be the most comprehensive and well done as possible. Do you think, anyway, that something could be done better? Perhaps something is lacked? Go then to the HaTeX mailing list [3] and leave your complain without mercy! Or, in the case you are a GitHub user, say your word in the issue list [4] or, to be awesome, make yourself a patch and send a pull request. This is the great thing about open source projects!

### 1.2 What is HaTeX?

Before we explain *how* HaTeX works, it is convenient to say *what* actually HaTeX is.

*HaTeX is a Haskell library that provides functions to create, manipulate and parse LaTeX code.*

People often says that *HaTeX is a LaTeX DSL*. With it you can enjoy all the advantages you already have in Haskell while creating LaTeX documents. A common purpose is to automatize the creation of such documents, perhaps from a source data in Haskell. A more exotic one is to render chess tables. Possibilities are in a wide range. The idea is the following: if you can do it with LaTeX, you can do it with HaTeX, but adding all the Haskell features.

## 2 Basics

Through this section you will learn the basics of HaTeX. Essentially, *how* it works.

### 2.1 The Monoid class

If you are already familiar with the*monoid*in Mathematics is an algebraic structure consisting of a set of objects with an operation between them, being this operation

*associative*and with a

*neutral element*. Phew! But what is the meaning of this? By

*associative*we mean that, if you have three elements

*a*,

*b*and

*c*, then

*a** (

*b**

*c*) = (

*a**

*b*) *

*c*. A

*neutral element*is the one that does not worth to operate with, because it does nothing! To say,

*e*is a

*neutral element*if

*e**

*a*=

*a**

*e*=

*a*, given any object

*a*. As an example, you may take the

*real numbers*as objects and the ordinary multiplication as operation. Now that you know the math basics behind the

class Monoid m where mempty :: m mappend :: m -> m -> m mconcat :: [m] -> m

xs ++ [] = [] ++ xs = xs

### 2.2 LaTeX blocks

Suppose we have a well-formed^{1}piece of LaTeX code, call it

*a*. Now, let

*a*can be seen as a Haskell expression

**block**. What happens if we append, by juxtaposition, two

### 2.3 Creating blocks

We have now an universe of blocks forming a monoid. What we need now is a way to create these blocks. As we said, a block is the representation of a well-formed piece of LaTeX code. Let^{2}. Since this is a constant expression, it has a constant value in Haskell, named

linespread :: Float -> LaTeX

title :: LaTeX -> LaTeX

**to create blocks and combine them**. Once you have your final block ready, you will be able to create its corresponding LaTeX code (we will see how later). Note that for every block there is a LaTeX code, but not for every code there is a block, because a malformed (in the sense of the negation of our well-formed concept) code has

**not**a block in correspondence. This fact has a practical consequence:

**we cannot create malformed LaTeX code**.

*And that's a good deal!*

#### 2.3.1 From strings

Inserting text in a LaTeX document is a constant task. You can create a block with text given an arbitraryclass IsString a where fromString :: String -> a

*Overloaded Strings*extension. This one is similar to the

*Overloaded Numbers*Haskell feature, which translates the number

*foo*as content. Quite handy! We will assume the

#### 2.3.2 More blocks

There is a lot of functions for create blocks. In fact, we can say that this is the main purpose of the library. LaTeX has a lot of commands, in order to set font attributes, create tables, insert graphics, include mathematical symbols, etc. So HaTeX have a function for each command defined in LaTeX (to tell the truth, only for a small subset). Please, go to the API documentation to read about particular functions. Build it locally or find it in Hackage: http://hackage.haskell.org/package/HaTeX. You will find the class constraint### 2.4 Putting blocks together

Once you have the blocks, as we said before, you need to append them. The^{3}, is the block with

mconcat [ "I can see a " , textbf "rainbow" , " in the blue " , textit "sky" , "." ]

### 2.5 Rendering

This is the last step in our LaTeX document creation. When we have our finalLaTeX blockshort = documentclass [] article <> title "A short message" <> author "John Short" <> document (maketitle <> "This is all.")

\documentclass{article}\title{A short message} \author{John Short} \begin{document} \maketitle{} This is all

\end{document}

renderFile :: Render a => FilePath -> a -> IO ()

class Render a where render :: a -> Text

**be careful!**Because

**not**escape reserved characters.

### 2.6 Try yourself

As always, the best way to learn something well is to try it by yourself. Since to see code examples can give you a great help, HaTeX comes with several examples where you can see by yourself how to get the work done.

The API reference is also a good point to keep in mind. Descriptions of functions make you know how exactly they works. And, when they are not present, function names with type signatures may be very helpful and descriptive.

## 3 LaTeX blocks and the Writer monad

===The Writer Monad=== Fixed a monoid^{4}:

data W m a = W m a

inject :: Monoid m => a -> W m a inject a = W mempty a

instance Functor (W m) where fmap f (W m a) = W m (f a)

join :: Monoid m => W m (W m a) -> W m a join (W m (W m' a)) = W (mappend m m') a

instance Monoid m => Monad (W m) wherereturn = injectw >>= f = join (fmap f w)

tell :: m -> W m () tell m = W m ()

execute :: W m a -> m execute (W m a) = m

instance Monoid Int wheremempty = 0 mappend = (+)example :: Int example = execute $ do

tell 1 tell 2 tell 3tell 4

example :: Int example = execute $ mapM_ tell [ 1 .. 4 ]

### 3.1 The LaTeX Monad

Let's go back to thetype LaTeXW = W LaTeX

example :: LaTeXexample = execute $ do

tell $ documentclass [] article tell $ author "Monads lover"tell $ title "LaTeX and the Writer Monad"

author' :: LaTeXW a -> LaTeXW () author' = tell . author . execute

example :: LaTeXexample = execute $ do

documentclass' [] article author' "Monads lover"title' "LaTeX and the Writer Monad"

### 3.2 Composing monads

To add flexibility to HaTeX, the writer monad explained above is defined as a monad transformer, namedfoo :: Monad m => LaTeXT m a

type LaTeXW = LaTeXT Mfoo :: LaTeXW a

*foo.hs*. Instead of copy all its content, or read and carry it as an argument along the code, you can simply read that file using

type LaTeXIO = LaTeXT IO readCode :: FilePath -> LaTeXIO () readCode fp = lift (readFileTex fp) >>= verbatim . raw example :: LaTeXIO () example = do "This is the code I wrote this morning:" readCode "foo.hs" "It was a funny exercise."

type LaTeXW = LaTeXT Identity

## 4 The LaTeXC class

HaTeX has two different interfaces. One uses blocks as^{5}or to have a typeclass which unifies both interfaces. Since duplicate definitions is a hard work and can arise problems

^{6}, we took the second alternative and defined the

## 5 Packages

LaTeX, in addition to its predefined commands, has a big number of packages that increase its power. HaTeX functions for some of these packages are defined in separated modules, one module per package. This way, you can import only those functions you actually need. Some of these modules are below explained.

### 5.1 Inputenc

This package is of vital importance if you use non-ASCII characters in your document. For example, if my name is*Ángela*, the

*Á*character will not appear correctly in the output. To solve this problem, use the

import Text.LaTeX.Base import Text.LaTeX.Packages.Inputenc thePreamble :: LaTeX thePreamble = documentclass [] article <> usepackage [utf8] inputenc <> author "Ángela" <> title "Issues with non-ASCII characters"

### 5.2 Graphicx

With theincludegraphics :: LaTeXC l => [IGOption] -> FilePath -> l

## 6 Epilogue

### 6.1 Notes about this guide

**This guide is not static**. It will be changed, extended and improved with the time. If you think there is something unclear, something hard to understand, please, report it.

### 6.2 Notes from the author

It has been a long time since I started with the HaTeX project. But it was not until version 3.3 that I feel like it is taking the right way. This is why I did not write this guide before.

I learned a lot during its creation, beginning with a little project that would help myself to write LaTeX documents, and then becoming in my first contact with the Haskell Community. And all the time it was funny.

I would like to end this guide saying thanks to all people that has been interested in HaTeX some way, specially to those that contributed to it with patches, opinions or bug reports. **Thanks**.

## 7 Footnotes

^{1}: With *well-formed* we mean that all braces, environments, math expressions, ... are closed.

^{2}: Please, note that the

**not**the same that the LaTeX expression. The former

is a Haskell value, not the LaTeX code itself.

^{3}: From

**GHC 7.4**,

versions of GHC, HaTeX exports the synonym.

^{4}: Some authors write it using tuples, like this:

^{5}: This was the approach taken in HaTeX 3 until the version 3.3, where the

^{6}: In fact, we had a problem with HaTeX-meta, the program that automatically generated the duplicated functions.
The problem was described in a blog post: http://deltadiaz.blogspot.com.es/2012/04/hatex-trees-and-problems.html.