#Basics# Through this section you will learn the basics of \hatex. Essentially, /how/ it works. ##The Monoid class## If you are already familiar with the \{Monoid\} class, jump to the next point. The \{Monoid\} class is something that you must get used to in Haskell. But don't worry, it is quite simple (despite having a similar name to the \{Monad\} class). A /monoid/ in Mathematics is an algebraic structure consisting of a set of objects, an /associative/ operation and 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 one that does not change other values when operated with, because it means nothing with respect to the operation! 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, in which case the /neutral element/ would be the number one. Now that you know the math basics behind the \{Monoid\} class, let's see its definition: \[ class Monoid m where mempty :: m mappend :: m -> m -> m mconcat :: [m] -> m \] See that \{mappend\} corresponds to the monoid operation and \{mempty\} to its neutral element. The names of the methods may seem unsuitable, but they correspond to a particular case of monoid: the lists with the appending \{(++)\} operation. What is the neutral element here? The empty list: \[ xs ++ [] = [] ++ xs = xs \] This class plays a significant role in \hatex. Keep reading. ##LaTeX blocks## Suppose we have a well-formed\f By /well-formed/ we mean all braces, environments, math expressions, ... are closed. \f piece of \latex code, call it $a$. Now, let \{LaTeX\} be a Haskell type in which each element represents a well-formed piece of \latex code. Then, $a$ can be seen as a Haskell expression \{a\} of type \{LaTeX\}. We can say that \{a\} is a \{LaTeX\} *block*. What happens if we append, by juxtaposition, two \{LaTeX\} blocks? As both are well-formed, so is the result. Thus, two blocks appended form another block. This way, we can define an operation over the \{LaTeX\} blocks. If we consider that 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 the append operation form a monoid. Namely, \{LaTeX\} is an instance of the \{Monoid\} class. Of course, our objective when using \hatex is to create a \{LaTeX\} block that fits our purpose. The way to achieve this is to create a multitude of \{LaTeX\} blocks and use the \{Monoid\} operation to collapse them into a single block. ##Creating blocks## We now have a universe of blocks that form a monoid. What we need is a way to create these blocks. As we said, a block is the representation of a well-formed piece of \latex code. Let \{a\} be the block of the \latex expression \{\delta{}\}\f Please, note that the \{LaTeX\} block is *not* the same that the \latex expression. The former is a Haskell value, not the \latex code itself. \f. Since this is a constant expression, it has a constant value in Haskell, named \{delta\}. Calling this value will generate the desired block. Other \latex expressions depend on a given argument. For example \{\linespread{x}\}, where \{x\} is a number. How do we use these? As you would 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 function \{linespread\} with type: \[ linespread :: Float -> LaTeX \] As you may know, a title in \latex can itself contain \latex code. So the type for the Haskell function \{title\} is: \[ title :: LaTeX -> LaTeX \] And this is essentialy the way we work with \hatex: *to create blocks and combine them*. Once you have your final block ready, you will be able to create the \latex code that corresponds to it (we will see how later). Note that there is \latex code for every block, but not every piece of \latex has a block, because a malformed (in the sense of the negation of our well-formed concept) code does *not* have a corresponding block. This fact has a practical consequence: *we cannot create malformed \latex code* using \hatex. /And that's a good thing!/ ###From strings### Inserting text in a \latex document is a constant task. You can create a block with text given an arbitrary \{String\} with the \{fromString\} function, method of the \{IsString\} class: \[ class IsString a where fromString :: String -> a \] Since there is a set of characters reserved to create commands or another constructions, \hatex takes care to avoid using them, replacing each with a command whose output looks like the originally intended character. For example, the backslash \{\\} is replaced with the \{\backslash{}\} command. The function that avoids reserved characters is exported with the name \{protectString\}. Also, there is a variant for \{Text\} values called \{protectText\}. The use of the \{IsString\} class is because the /Overloaded Strings/ extension. This is similar to the /Overloaded Numbers/ Haskell feature, which translates the number \{4\} to \{fromInteger 4\}. In a similar way, with \{OverloadedStrings\} enabled, the string \{"foo"\} is translated to \{fromString "foo"\}. If we now apply this to our blocks, the string \{"foo"\} will be automatically translated to a \{latex\} block with /foo/ as content. Quite handy! We will assume that the \{OverloadedStrings\} extension is enabled from now on. ###More blocks### There are a lot of functions to create blocks. In fact, we can say this is the primary purpose of the library. \latex has a lot of commands: they can set font attributes, create tables, insert graphics, include mathematical symbols, etc. So \hatex has 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 - you can either build it locally or find it on Hackage: . You will find the class constraint \{LaTeXC l\} in every entity. \{LaTeX\} is an instance of this class, so you can think of \{l\} as the \{LaTeX\} datatype without any problem. There is more about this in the section about the \{LaTeXC\} class. ##Putting blocks together## Once you have your blocks, as we said before, you need to join them. The \{mappend\} method of the \{Monoid\} class will do this. If \{a\} and \{b\} are two blocks, \{mappend a b\}, or \{a `mappend` b\}, or even \{a <> b\}\f From *GHC 7.4*, \{(<>)\} is defined as a synonym for \{mappend\}. For previous versions of GHC, \hatex exports the synonym. \f, return the juxtaposition of \{a\} and \{b\}. For lists of blocks, you can use \{mconcat\} instead as follows: \[ mconcat [ "I can see a " , textbf "rainbow" , " in the blue " , textit "sky" , "." ] \] ##Rendering## This is the last step in our \latex document creation. When we have our final \latex block \{a\}, the function \{renderFile\} can output it to a file, in the form of its correspondent \latex code. Say we have this definition: \[ short = documentclass [] article <> title "A short message" <> author "John Short" <> document (maketitle <> "This is all.") \] Then, after calling \{renderFile "short.tex" short\}, the following file will appear 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} \] Finally, you may use commands like \{latex\} or \{pdflatex\} in your command line environment to compile the \latex output to dvi or pdf. The function \{renderFile\} is not only for \{LaTeX\} values. Let's see its type: \[ renderFile :: Render a => FilePath -> a -> IO () \] The \{Render\} class that appears in the context is defined as: \[ class Render a where render :: a -> Text \] So, it is the class of types that can be rendered to a \{Text\} value. The type \{LaTeX\} is an instance, but other types, like \{Int\} or \{Float\}, are too. These instances are useful for creating blocks from other values. With the function \{rendertex\}, any value in the \{Render\} class can be transformed to a block. First, the value is converted to \{Text\}, and then to \{LaTeX\} in the same way as we did with strings. But, *be careful* because \{rendertex\} does *not* escape reserved characters. ##Try it yourself## As always, the best way to learn something well is to try it for yourself. Since looking at code examples can help you greatly, \hatex comes with several examples at [] so you can see for yourself how to accomplish various tasks. The API reference is also a good reference to keep in mind. Descriptions of functions allow you to know exactly how they work. Even when these are not present, just the function names and their type signatures can be very helpful and descriptive.