README.md

Iona
====
[![Build Status](https://travis-ci.org/CargoSense/iona.svg?branch=master)](https://travis-ci.org/CargoSense/iona)

Document generation from Elixir, using LaTeX.

## Highlighted Features

* Generate professional-quality typeset `.pdf` (and `.dvi`) documents using
  [LaTeX](http://www.latex-project.org/), 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](http://www.latex-project.org/).

## Installation

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

```elixir
def deps do
  [
    iona: "~> 0.2"
  ]
end
```

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

```elixir
def application do
  [applications: [:iona]]
end
```

## 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](https://latex-project.org/ftp.html) -- or using the
the package management system of your choice.

## Examples

### From TeX source

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

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

You can also use a binary string:

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

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

```elixir
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`:

```elixir
Iona.source(path: "fancy.tex")
|> Iona.to(:pdf)
|> MyModule.do_something_with_pdf_string
```

## From an EEx TeX template

```elixir
%{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:

```elixir
%{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:

```elixir
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 `Iona.to/3` and `Iona.write/3`.

## License

See [LICENSE](./LICENSE).

### LaTeX

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