HaTeX-1.0.0: Text/LaTeX.hs

module Text.LaTeX 
     ( -- * How to use HaTeX
       -- ** Introduction
       -- $guide1

       -- ** LaTeX file structure
       -- $guide2

       -- ** A simple example
       -- $guide3

       -- ** Enriching your text
       -- $guide4

       -- ** Performing IO actions
       -- $guide5

       -- * HaTeX related functions
       hatex
     , hatexVersion
       -- * Exporting to /.tex/
     , export
       -- * Re-exports
     , module Text.LaTeX.Result
     , module Text.LaTeX.Monad
     , module Text.LaTeX.Define
     , module Text.LaTeX.Arguments
     , module Text.LaTeX.Packages
     , module Text.LaTeX.Commands
     , module Text.LaTeX.IO
     , module Text.LaTeX.Macro
     ) where

import Text.LaTeX.Monad
import Text.LaTeX.Commands
import Text.LaTeX.Arguments
import Text.LaTeX.Define
import Text.LaTeX.Packages
import Text.LaTeX.IO
import Text.LaTeX.Result
import Text.LaTeX.Macro
--
import System.FilePath (takeExtension)

-- | HaTeX nice word.
hatex :: LaTeX
hatex = makebox [] [] $ do "H"
                           raisebox (ex (-0.55)) [] [] $
                             makebox [0.5 >> width] [] "A"
                           tex

-- | Your HaTeX version.
hatexVersion :: LaTeX
hatexVersion = do textbf "1" ; ".0.0"

-- | Export the 'Result' of a 'LaTeX' sequence in a /.tex/ file.
export ::
     LaTeX    -- ^ 'LaTeX' to export.
  -> FilePath -- ^ Path of export.
  -> IO ()
export x fp = do y <- nlx x
                 let z = fromResult y
                 if takeExtension fp == ".tex" then writeFile fp z
                                               else writeFile (fp ++ ".tex") z

-----------------------------------------------------------------------------------------------------------

-- Introduction

{- $guide1
If you know how to use LaTeX, you will easily understand how to use HaTeX.
Otherwise, you will need to read well the documentation.

A first step may be to know the LaTeX file structure.
-}

-- LaTeX file structure

{- $guide2
A LaTeX file has two parts:

- A header where you define general settings (document class, page style, use of extern packages, ...) of your document.

- The document's content.
-}

-- A simple example

{- $guide3
We're going to write an example, the best for understanding.

* Function 'documentclass' is used for determining if our document is an 'article', a 'book', a 'report', etc.

* Function 'author' is used for specify document's authory.

* Function 'title' for document's title.

Then, with this three functions, we will define a header in the 'LaTeX' monad.
'LaTeX' is a writer monad that concatenates the text generated by the programmer.
Usually, the text is generated simply writing it, or by functions.

> example = do documentclass [] article
>              author "Daniel Diaz"
>              title "Example"

The first argument of 'documentclass' is used for change certain settings of the class.
For example, you can set the document's main font size to 12pt, writing:

> documentclass [pt 12] article

Or set paper size to A4:

> documentclass [pt 12,a4paper] article

Now, I will write a content:

> hello = "Hello, world!"

To insert the content into the document, we have the function 'document'. Completing our first example:

> example = do documentclass [] article
>              author "Daniel Diaz"
>              title "Example"
>              document hello

At first glance, it seems that 'author', 'title' or 'document' receive a @String@ as argument.
Really, they require a 'LaTeX' argument. 'LaTeX' is the type that represents texts in HaTeX.
So, I recommend to use /Overloaded Strings/
(See <http://www.haskell.org/ghc/docs/6.12.2/html/users_guide/type-class-extensions.html#overloaded-strings>).
-}

-- Enriching your text

{- $guide4
There are numerous functions to enrich your document.
One feature is change your font format with the functions shown here: "Text.LaTeX.Commands#Fonts".

For example, in:

> texttt "Hello!"

'texttt' sets as monospaced font his content. Or composing:

> texttt $ textbf "Hello!"

'textbf' sets as bold font the monospaced font of @\"Hello!\"@.

If you only want @\"ll\"@ with bold format:

> texttt $ do "He"
>             textbf "ll"
>             "o!"

Applying the function to only part of the text, we achieve modify just that part.
-}

{- $guide5
To includes an 'IO' computation in 'LaTeX' monad, use 'iolx'.

> gtime = do t <- iolx getClockTime
>            ...

Some 'IO' computations are predefined in "Text.LaTeX.IO".
-}