# HaTeX User's Guide

### From HaskellWiki

Daniel Díaz (Talk | contribs) (Update) |
Daniel Díaz (Talk | contribs) |
||

Line 58: | Line 58: | ||

mappend :: m -> m -> m |
mappend :: m -> m -> m |
||

mconcat :: [m] -> m |
mconcat :: [m] -> m |
||

− | </haskell>See that <hask>mappend</hask> corresponds to the monoid operation and <hask>mempty</hask> to its neutral element. |
+ | </haskell> |

+ | |||

+ | See that <hask>mappend</hask> corresponds to the monoid operation and <hask>mempty</hask> to its neutral element. |
||

The names of the methods may seem insuitable, but they correspond to an example of monoid: |
The names of the methods may seem insuitable, but they correspond to an example of monoid: |
||

the lists with the appending <hask>(++)</hask> operation. Who is the neutral element here? The empty list: |
the lists with the appending <hask>(++)</hask> operation. Who is the neutral element here? The empty list: |
||

Line 64: | Line 64: | ||

<haskell> |
<haskell> |
||

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

− | </haskell>This class plays a significant role in HaTeX. Keep reading. |
+ | </haskell> |

+ | |||

+ | This class plays a significant role in HaTeX. Keep reading. |
||

===LaTeX blocks=== |
===LaTeX blocks=== |
||

Line 98: | Line 98: | ||

<haskell> |
<haskell> |
||

linespread :: Float -> LaTeX |
linespread :: Float -> LaTeX |
||

− | </haskell>As you may know, a title in LaTeX can contain itself LaTeX code. So the type for the Haskell |
+ | </haskell> |

+ | |||

+ | As you may know, a title in LaTeX can contain itself LaTeX code. So the type for the Haskell |
||

function <hask>title</hask> is: |
function <hask>title</hask> is: |
||

<haskell> |
<haskell> |
||

title :: LaTeX -> LaTeX |
title :: LaTeX -> LaTeX |
||

− | </haskell>And this is, essentialy, the way to work with HaTeX: '''to create blocks and combine them'''. |
+ | </haskell> |

+ | |||

+ | And this is, essentialy, the way to work with HaTeX: '''to create blocks and combine them'''. |
||

Once you have your final block ready, you will be able to create its corresponding LaTeX code |
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 |
(we will see how later). Note that for every block there is a LaTeX code, but not for every code |
||

Line 118: | Line 118: | ||

class IsString a where |
class IsString a where |
||

fromString :: String -> a |
fromString :: String -> a |
||

− | </haskell>Since there is a set of characters reserved to create commands or another constructions, |
+ | </haskell> |

+ | |||

+ | Since there is a set of characters reserved to create commands or another constructions, |
||

HaTeX takes care and avoids them replacing each reserved character with a command which |
HaTeX takes care and avoids them replacing each reserved character with a command which |
||

output looks like the original character. For example, the backslash <hask>\</hask> is replaced with |
output looks like the original character. For example, the backslash <hask>\</hask> is replaced with |
||

Line 155: | Line 155: | ||

mconcat [ "I can see a " , textbf "rainbow" |
mconcat [ "I can see a " , textbf "rainbow" |
||

, " in the blue " , textit "sky" , "." ] |
, " in the blue " , textit "sky" , "." ] |
||

− | </haskell>===Rendering=== |
+ | </haskell> |

+ | |||

+ | ===Rendering=== |
||

This is the last step in our LaTeX document creation. When we have our final |
This is the last step in our LaTeX document creation. When we have our final |
||

Line 169: | Line 169: | ||

<> author "John Short" |
<> author "John Short" |
||

<> document (maketitle <> "This is all.") |
<> document (maketitle <> "This is all.") |
||

− | </haskell>Then, after calling <hask>renderFile "short.tex" short</hask>, the following file appears |
+ | </haskell> |

+ | |||

+ | Then, after calling <hask>renderFile "short.tex" short</hask>, the following file appears |
||

in the current working directory (line breaks added for easier visualization): |
in the current working directory (line breaks added for easier visualization): |
||

Line 180: | Line 180: | ||

This is all |
This is all |
||

\end{document} |
\end{document} |
||

− | </haskell>Finally, you may use commands like <hask>latex</hask> or <hask>pdflatex</hask> to compile the LaTeX |
+ | </haskell> |

+ | |||

+ | Finally, you may use commands like <hask>latex</hask> or <hask>pdflatex</hask> to compile the LaTeX |
||

output to dvi or pdf. |
output to dvi or pdf. |
||

Line 187: | Line 187: | ||

<haskell> |
<haskell> |
||

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

− | </haskell>The <hask>Render</hask> class that appears in the context is defined: |
+ | </haskell> |

+ | |||

+ | The <hask>Render</hask> class that appears in the context is defined: |
||

<haskell> |
<haskell> |
||

class Render a where |
class Render a where |
||

render :: a -> Text |
render :: a -> Text |
||

− | </haskell>So, it is the class of types that can be rendered to a <hask>Text</hask> value. The |
+ | </haskell> |

+ | |||

+ | So, it is the class of types that can be rendered to a <hask>Text</hask> value. The |
||

type <hask>LaTeX</hask> is an instance, but other types, like <hask>Int</hask> or <hask>Float</hask>, so are too. |
type <hask>LaTeX</hask> is an instance, but other types, like <hask>Int</hask> or <hask>Float</hask>, so are too. |
||

These instances are useful for creating blocks from other values. With the function |
These instances are useful for creating blocks from other values. With the function |
||

Line 221: | Line 221: | ||

<haskell> |
<haskell> |
||

data W m a = W m a |
data W m a = W m a |
||

− | </haskell>Note that to get the monad we need to fix the type <hask>m</hask> (kind of monads is <hask>* -> *</hask>). To inject |
+ | </haskell> |

+ | |||

+ | Note that to get the monad we need to fix the type <hask>m</hask> (kind of monads is <hask>* -> *</hask>). To inject |
||

an arbitrary value into the monad (the Haskell <hask>return</hask> function) we use the neutral element (<hask>mempty</hask>) |
an arbitrary value into the monad (the Haskell <hask>return</hask> function) we use the neutral element (<hask>mempty</hask>) |
||

of the monoid. |
of the monoid. |
||

Line 228: | Line 228: | ||

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

inject a = W mempty a |
inject a = W mempty a |
||

− | </haskell>Think that no other element of <hask>m</hask> is possible to think: it is the only element we know of it! |
+ | </haskell> |

+ | |||

+ | Think that no other element of <hask>m</hask> is possible to think: it is the only element we know of it! |
||

Like any other monad, <hask>W m</hask> is also a <hask>Functor</hask>. We just apply the function to the value. |
Like any other monad, <hask>W m</hask> is also a <hask>Functor</hask>. We just apply the function to the value. |
||

Line 234: | Line 234: | ||

instance Functor (W m) where |
instance Functor (W m) where |
||

fmap f (W m a) = W m (f a) |
fmap f (W m a) = W m (f a) |
||

− | </haskell>Every <hask>Monad</hask> instance can be given by the two monad operations <hask>inject</hask> and <hask>join</hask>. We already |
+ | </haskell> |

+ | |||

+ | Every <hask>Monad</hask> instance can be given by the two monad operations <hask>inject</hask> and <hask>join</hask>. We already |
||

defined the <hask>inject</hask> function. The other one deletes one monad type constructor. |
defined the <hask>inject</hask> function. The other one deletes one monad type constructor. |
||

Line 240: | Line 240: | ||

join :: Monoid m => W m (W m a) -> W m a |
join :: Monoid m => W m (W m a) -> W m a |
||

join (W m (W m' a)) = W (mappend m m') a |
join (W m (W m' a)) = W (mappend m m') a |
||

− | </haskell>In this function we use the other <hask>Monoid</hask> method to combine both values. It is important to |
+ | </haskell> |

+ | |||

+ | In this function we use the other <hask>Monoid</hask> method to combine both values. It is important to |
||

note that in both monad operations <hask>inject</hask> and <hask>join</hask> we used <hask>mempty</hask> and <hask>mappend</hask> |
note that in both monad operations <hask>inject</hask> and <hask>join</hask> we used <hask>mempty</hask> and <hask>mappend</hask> |
||

respectively. In practice, this is because they act equal. Indeed, they are equal if we forget the |
respectively. In practice, this is because they act equal. Indeed, they are equal if we forget the |
||

Line 249: | Line 249: | ||

return = inject |
return = inject |
||

w >>= f = join (fmap f w) |
w >>= f = join (fmap f w) |
||

− | </haskell>There is nothing to say about this instance. It is and standard definition valid to any monad. |
+ | </haskell> |

+ | |||

+ | There is nothing to say about this instance. It is and standard definition valid to any monad. |
||

What we have done here is to hide in a monad a monoid with all its operations. We have created a |
What we have done here is to hide in a monad a monoid with all its operations. We have created a |
||

Line 258: | Line 258: | ||

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

tell m = W m () |
tell m = W m () |
||

− | </haskell>When we execute the machine, it returns to us the result of operate all the values we have put on it. |
+ | </haskell> |

+ | |||

+ | When we execute the machine, it returns to us the result of operate all the values we have put on it. |
||

<haskell> |
<haskell> |
||

execute :: W m a -> m |
execute :: W m a -> m |
||

execute (W m a) = m |
execute (W m a) = m |
||

− | </haskell>Let's see the machine working. For example, the <hask>Int</hask> type with addition forms a <hask>Monoid</hask>. |
+ | </haskell> |

+ | |||

+ | Let's see the machine working. For example, the <hask>Int</hask> type with addition forms a <hask>Monoid</hask>. |
||

<haskell> |
<haskell> |
||

Line 276: | Line 276: | ||

tell 3 |
tell 3 |
||

tell 4 |
tell 4 |
||

− | </haskell>When we evaluate <hask>example</hask> we get <hask>10</hask>, as expected. Using <hask>mapM_</hask> we can rewrite <hask>example</hask>. |
+ | </haskell> |

+ | |||

+ | When we evaluate <hask>example</hask> we get <hask>10</hask>, as expected. Using <hask>mapM_</hask> we can rewrite <hask>example</hask>. |
||

<haskell> |
<haskell> |
||

example :: Int |
example :: Int |
||

example = execute $ mapM_ tell [ 1 .. 4 ] |
example = execute $ mapM_ tell [ 1 .. 4 ] |
||

− | </haskell>===The LaTeX Monad=== |
+ | </haskell> |

+ | |||

+ | ===The LaTeX Monad=== |
||

Let's go back to the <hask>LaTeX</hask> type. Since <hask>LaTeX</hask> is an instance of <hask>Monoid</hask> we can construct |
Let's go back to the <hask>LaTeX</hask> type. Since <hask>LaTeX</hask> is an instance of <hask>Monoid</hask> we can construct |
||

Line 288: | Line 288: | ||

<haskell> |
<haskell> |
||

type LaTeXW = W LaTeX |
type LaTeXW = W LaTeX |
||

− | </haskell>The <hask>W</hask> machine is waiting now for <hask>LaTeX</hask> values. |
+ | </haskell> |

+ | |||

+ | The <hask>W</hask> machine is waiting now for <hask>LaTeX</hask> values. |
||

<haskell> |
<haskell> |
||

Line 296: | Line 296: | ||

tell $ author "Monads lover" |
tell $ author "Monads lover" |
||

tell $ title "LaTeX and the Writer Monad" |
tell $ title "LaTeX and the Writer Monad" |
||

− | </haskell>We put all that blocks in the machine, and it returns the concatenated block. We saved a lot of |
+ | </haskell> |

+ | |||

+ | We put all that blocks in the machine, and it returns the concatenated block. We saved a lot of |
||

<hask>mappend</hask>'s, but we now have a lot of <hask>tell</hask>'s. No problem. Just redefine each function of |
<hask>mappend</hask>'s, but we now have a lot of <hask>tell</hask>'s. No problem. Just redefine each function of |
||

blocks with <hask>tell</hask> and <hask>execute</hask>. |
blocks with <hask>tell</hask> and <hask>execute</hask>. |
||

Line 303: | Line 303: | ||

author' :: LaTeXW a -> LaTeXW () |
author' :: LaTeXW a -> LaTeXW () |
||

author' = tell . author . execute |
author' = tell . author . execute |
||

− | </haskell>If it is done in a similar way with <hask>documentclass</hask> and <hask>title</hask>, every <hask>tell</hask> in <hask>example</hask> |
+ | </haskell> |

+ | |||

+ | If it is done in a similar way with <hask>documentclass</hask> and <hask>title</hask>, every <hask>tell</hask> in <hask>example</hask> |
||

disappears. |
disappears. |
||

Line 312: | Line 312: | ||

author' "Monads lover" |
author' "Monads lover" |
||

title' "LaTeX and the Writer Monad" |
title' "LaTeX and the Writer Monad" |
||

− | </haskell>And we can now use the <hask>LaTeX</hask> machine more comfortably. However, we have all functions duplicated. |
+ | </haskell> |

+ | |||

+ | And we can now use the <hask>LaTeX</hask> machine more comfortably. However, we have all functions duplicated. |
||

This is why the <hask>LaTeXC</hask> class exists. We are going to talk about it later. |
This is why the <hask>LaTeXC</hask> class exists. We are going to talk about it later. |
||

Line 324: | Line 324: | ||

<haskell> |
<haskell> |
||

foo :: Monad m => LaTeXT m a |
foo :: Monad m => LaTeXT m a |
||

− | </haskell>However, in practice, we can avoid it. Say we going to use an specific monad <hask>M</hask>. |
+ | </haskell> |

+ | |||

+ | However, in practice, we can avoid it. Say we going to use an specific monad <hask>M</hask>. |
||

<haskell> |
<haskell> |
||

Line 330: | Line 330: | ||

foo :: LaTeXW a |
foo :: LaTeXW a |
||

− | </haskell>Now, type signatures remain unchanged. |
+ | </haskell> |

+ | |||

+ | Now, type signatures remain unchanged. |
||

The other change is a new feature: the <hask>lift</hask> function. With it we can do any computation |
The other change is a new feature: the <hask>lift</hask> function. With it we can do any computation |
||

Line 348: | Line 348: | ||

readCode "foo.hs" |
readCode "foo.hs" |
||

"It was a funny exercise." |
"It was a funny exercise." |
||

− | </haskell>Different monads will give different features. In the case we are not interested in any of |
+ | </haskell> |

+ | |||

+ | Different monads will give different features. In the case we are not interested in any of |
||

these features, it is enough to use the Identity monad. |
these features, it is enough to use the Identity monad. |
||

Line 354: | Line 354: | ||

type LaTeXW = LaTeXT Identity |
type LaTeXW = LaTeXT Identity |
||

</haskell> |
</haskell> |
||

+ | |||

+ | |||

==The LaTeXC class== |
==The LaTeXC class== |
||

Line 373: | Line 375: | ||

LaTeX, in addition to its predefined commands, has a big number of 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 |
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 |
+ | in separated modules, with one or more modules per package. This way, you can import only those |

functions you actually need. Some of these modules are below explained. |
functions you actually need. Some of these modules are below explained. |
||

Line 392: | Line 394: | ||

<> author "Ángela" |
<> author "Ángela" |
||

<> title "Issues with non-ASCII characters" |
<> title "Issues with non-ASCII characters" |
||

− | </haskell>Don't forget to set to UTF-8 encoding your Haskell source too. |
+ | </haskell> |

+ | |||

+ | Don't forget to set to UTF-8 encoding your Haskell source too. |
||

===Graphicx=== |
===Graphicx=== |
||

Line 402: | Line 404: | ||

<haskell> |
<haskell> |
||

includegraphics :: LaTeXC l => [IGOption] -> FilePath -> l |
includegraphics :: LaTeXC l => [IGOption] -> FilePath -> l |
||

− | </haskell>The list of <hask>IGOption</hask>'s allows you to set some properties of the image, like width, |
+ | </haskell> |

+ | |||

+ | The list of <hask>IGOption</hask>'s allows you to set some properties of the image, like width, |
||

height, scaling or rotation. See the API documentation for details. |
height, scaling or rotation. See the API documentation for details. |
||

## Latest revision as of 09:52, 14 May 2014

## Contents |

## [edit] 1 Preface

### [edit] 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 their LaTeX 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!

### [edit] 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.

## [edit] 2 Basics

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

### [edit] 2.1 The Monoid class

If you are already familiar with theA *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.

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

The names of the methods may seem insuitable, but they correspond to an example of monoid:

the lists with the appendingxs ++ [] = [] ++ xs = xs

This class plays a significant role in HaTeX. Keep reading.

### [edit] 2.2 LaTeX blocks

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

*a*can be seen as a Haskell expression

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

a totally empty code is a well-formed piece of LaTeX code, we can speak about the empty block.

And, as the reader may notice, these blocks with its appending form a monoid. Namely,to collapse them all in a single block.

### [edit] 2.3 Creating blocks

We have now a 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

this value will generate the desired block.

Other LaTeX expressions depend on a given argument. For examplea number. How we deal with this? As you expect, with functions. We can create blocks that depend on values with functions that take these values as arguments, where these arguments can be

blocks as well. For instance, we have the functionlinespread :: Float -> LaTeX

As you may know, a title in LaTeX can contain itself LaTeX code. So the type for the Haskell

functiontitle :: LaTeX -> LaTeX

And this is, essentialy, the way to work with HaTeX: **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!*

#### [edit] 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

Since there is a set of characters reserved to create commands or another constructions, HaTeX takes care and avoids them replacing each reserved character with a command which

output looks like the original character. For example, the backslash*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

#### [edit] 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### [edit] 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

as follows:

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

### [edit] 2.5 Rendering

This is the last step in our LaTeX document creation. When we have our final

LaTeX blockthe form of its correspondent LaTeX code.

Say we have the next definition:

short = documentclass [] article <> title "A short message" <> author "John Short" <> document (maketitle <> "This is all.")

in the current working directory (line breaks added for easier visualization):

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

output to dvi or pdf.

The functionrenderFile :: Render a => FilePath -> a -> IO ()

class Render a where render :: a -> Text

These instances are useful for creating blocks from other values. With the function

**be careful!**Because

**not**escape reserved characters.

### [edit] 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.

## [edit] 3 LaTeX blocks and the Writer monad

### [edit] 3.1 The Writer Monad

Fixed a monoidand elements from other types. Thus, the Haskell declaration is as follows^{4}:

data W m a = W m a

of the monoid.

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

respectively. In practice, this is because they act equal. Indeed, they are equal if we forget the

instance Monoid m => Monad (W m) where return = inject w >>= f = join (fmap f w)

There is nothing to say about this instance. It is and standard definition valid to any monad.

What we have done here is to hide in a monad a monoid with all its operations. We have created a

machine that operates monoid values. To insert a value into the machine we need thefunction:

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

When we execute the machine, it returns to us the result of operate all the values we have put on it.

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

instance Monoid Int where mempty = 0 mappend = (+) example :: Int example = execute $ do tell 1 tell 2 tell 3 tell 4

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

### [edit] 3.2 The LaTeX Monad

Let's go back to thetype LaTeXW = W LaTeX

example :: LaTeX example = execute $ do tell $ documentclass [] article tell $ author "Monads lover" tell $ title "LaTeX and the Writer Monad"

We put all that blocks in the machine, and it returns the concatenated block. We saved a lot of

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

disappears.

example :: LaTeX example = execute $ do documentclass' [] article author' "Monads lover" title' "LaTeX and the Writer Monad"

### [edit] 3.3 Composing monads

To add flexibility to HaTeX, the writer monad explained above is defined as a monad transformer,

namedThe first change is in type signatures. We need to carry an inner monad in every type.

foo :: Monad m => LaTeXT m a

type LaTeXW = LaTeXT M foo :: LaTeXW a

Now, type signatures remain unchanged.

The other change is a new feature: theof our inner monad at any time. For example, suppose we want to output some code we have in
the file *foo.hs*. Instead of copy all its content, or read and carry it as an argument along the code,

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."

Different monads will give different features. In the case we are not interested in any of these features, it is enough to use the Identity monad.

type LaTeXW = LaTeXT Identity

## [edit] 4 The LaTeXC class

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

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

typeclass. This way, we have both interfaces with a single import, without being worry about maintaining duplicated code. The cost is to have class constraints in type signatures. But these constraints are only required in the package. At the user level, you choose your interface and write type signatures in consequence.

## [edit] 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, with one or more modules per package. This way, you can import only those functions you actually need. Some of these modules are below explained.

### [edit] 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

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"

Don't forget to set to UTF-8 encoding your Haskell source too.

### [edit] 5.2 Graphicx

With thefunction.

includegraphics :: LaTeXC l => [IGOption] -> FilePath -> l

height, scaling or rotation. See the API documentation for details.

## [edit] 6 Epilogue

### [edit] 6.1 Notes about this guide

**This guide is not static**. It will certainly be changed with the time.
Any reader can participate as a writer since the guide is itself open source (and
written in Haskell!). The source repository can be reached at:
https://github.com/Daniel-Diaz/hatex-guide. Read more detailed instructions in the
README file.

If you think there is something unclear, something hard to understand, please, report it.

### [edit] 6.2 Notes from the author

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

## [edit] 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.