[![Build Status](](

Document generation from Elixir, using LaTeX.

## Highlighted Features

* Generate professional-quality typeset `.pdf` (and `.dvi`) documents using
  [LaTeX](, and support defining your own
  TeX processors for different formats.
* Built-in support for EEx templating with automatic escaping and a custom helpers
* Preprocessing support (multiple runs for bibliographies, etc)

## Prerequisites

While features are on the roadmap to ease authorship of `.tex` documents,
at the current time knowledge of LaTeX is assumed (or at least a basic
willingness to wade into that very deep topic).

We recommend you start your knowledge quest at the
[LaTeX homepage](

## Installation

Add as a dependency to your `mix.exs`:

def deps do
    iona: "~> 0.2"

Install it with `mix deps.get` and don't forget to add it to your applications list:

def application do
  [applications: [:iona]]

## LaTeX

Of course you need a TeX system installed, including `latex`, `pdflatex`,
or any other variants you'd like to use to process your `.tex` source into final
documents. (The default configuration assumes `pdflatex` is installed for PDF
generation and `latex` is installed for DVI generation. See "Configuration," below.)

You can download and install a TeX system at the
[LaTeX Project website]( -- or using the
the package management system of your choice.

## Examples

### From TeX source

Generate a PDF from an existing `.tex` source:

Iona.source(path: "simple.tex")
|> Iona.write!("/path/to/document.pdf")

You can also use a binary string:

Iona.source("\documentclass[12pt]{article} ...")
|> Iona.write!("/path/to/simple.pdf")

More complex preprocessing needs for citations and bibliographies?
Define the prepocessing pipeline:

Iona.source(path: "academic.tex")
|> Iona.write!("/path/to/academic.pdf",
               preprocess: ~w(latex bibtex latex))

Want to get the raw document content as a binary? Use `to`:

Iona.source(path: "fancy.tex")
|> MyModule.do_something_with_pdf_string

## From an EEx TeX template

%{title: "My Document"}
|> Iona.template(path: "/path/to/template.tex.eex")
|> Iona.write("/path/to/my_document.pdf")

Values are inserted into EEx with, eg, `<%= @title %>` after being automatically
escaped by `Iona.Template.Helper.escape/1`.

If you're confident values are safe for raw insertion into your LaTeX documents
(or you'd like to support insertion of LaTeX commands), use `raw/1`, made
available by default as part of `Iona.Template.Helper`:

For instance, if you wanted to style `@title` as boldface, you could pass it
as `"{\bf My Document}"` and insert it as a raw string:

<%= raw @title %>

### With Custom Helpers

You can import additional helper modules for use in your templates by two methods.

The first (and preferred) method is by overriding the `:helpers` application
configuration setting (see "Configuration," below).

You can also pass a `:helpers` option to `Iona.template/1` with a list of
additional helpers:

%{title: "My Document"}
|> Iona.template(path: "/path/to/template.tex.eex",
                 helpers: [My.Custom.HelperModule])
|> Iona.write("/path/to/my_document.pdf")

Note in this case the setting is additive; the list is concatenated with the
`:helpers` defined in the application configuration.

## Configuration

The default, out-of-the-box settings for Iona are equivalent to the
following Mix config:

config :iona,
  helpers: [Iona.Template.Helper],
  preprocess: [],
  processors: [pdf: "pdflatex", dvi: "latex"]

Note you can also pass a `:preprocess` and `:processor` options to define a preprocessing pipeline
on a case-by-case basis. See the examples above or the documentation for `` and `Iona.write/3`.

## License


### LaTeX

LaTeX is free software, and is not distributed with this (unaffiliated) project.
Please see the [LaTeX homepage]( for more information.