iona v1.0.0-alpha.3 Iona View Source

Iona

Build Status Hex.pm Hex.pm Hex.pm

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)
  • Optionally generating a prepared directory with a build.sh script for final processing.

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

The package can be installed by adding iona to your list of dependencies in mix.exs:

def deps do
  [
    {:iona, "~> 0.4"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. The docs can be found at https://hexdocs.pm/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))

To generate a directory with a build script that can be run to finalize the build, use prepare:

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

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

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

Complex preprocessors

You can provide functions in the preprocessing pipeline too. The function will be invoked, given the temporary directory processing is occuring and the basename of the original file (eg, "source.tex"):

Iona.source(path: "source.tex")
|> Iona.write!("/path/to/source.pdf",
               preprocess: [fn (directory, filename) -> :ok end])

Function preprocessors should return:

  • :ok if processing should continue
  • {:shell, command} to indicate a command should be run as a preprocessor (see example below)
  • {:error, reason} if processing should halt

If given {:shell, command}, Iona will execute that command as a preprocessor. This is especially useful for interpolation, eg:

knitr = fn (_, filename) ->
  {:shell, "R -e 'library(knitr);knitr(\"#{filename}\");'" }
end

Iona.source(path: "graphs.Rnw")
|> Iona.write!("/path/to/graphs.pdf",
               preprocess: [knitr])

Important: As always, only interpolate trusted input into shell commands.

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

License

See LICENSE.

LaTeX

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

Link to this section Summary

Functions

Generate a directory with a build script that can be run to finalize the build.

The same as prepare/4 but raises Iona.ProcessingError if it fails.

Define the document source, either as a raw TeX binary or the path to a .tex file.

Fill in a template with assignments, with TeX escaping support

The same as template/2, but raises Iona.ProcessingError if it fails. Returns the template otherwise.

Generate a formatted document as a string.

The same as to/3, but raises Iona.ProcessingError if it fails. Returns the document content otherwise.

Generate a formatted document to a file path.

The same as write/3 but raises Iona.ProcessingError if it fails.

Link to this section Types

Link to this type

eex_tex_t()

View Source
eex_tex_t() :: binary()
Link to this type

executable_t()

View Source
executable_t() :: binary()
Link to this type

processing_opts()

View Source
processing_opts() :: [preprocess: [executable_t()], processor: executable_t()]
Link to this type

source_opts()

View Source
source_opts() :: [path: Path.t(), include: [Path.t()]]
Link to this type

supported_format_t()

View Source
supported_format_t() :: atom()
Link to this type

template_opts()

View Source
template_opts() :: [{:path, Path.t()}]

Link to this section Functions

Link to this function

prepare(input, output, format, opts \\ [])

View Source
prepare(
  input :: Iona.Input.t(),
  output :: Path.t(),
  format :: Iona.supported_format_t(),
  opts :: processing_opts()
) :: :ok | {:error, term()}

Generate a directory with a build script that can be run to finalize the build.

Examples

iex> Iona.source(path: "academic.tex")
iex> |> Iona.prepare!("/path/to/build/directory", :pdf, preprocess: ~w(latex bibtex latex))
:ok
Link to this function

prepare!(input, output, format, opts \\ [])

View Source
prepare!(
  input :: Iona.Input.t(),
  output :: Path.t(),
  format :: Iona.supported_format_t(),
  opts :: processing_opts()
) :: :ok

The same as prepare/4 but raises Iona.ProcessingError if it fails.

Link to this function

source(criteria)

View Source
source(criteria :: binary()) :: Iona.Source.t()
source(criteria :: source_opts()) :: Iona.Source.t()

Define the document source, either as a raw TeX binary or the path to a .tex file.

As raw TeX:

Iona.source("\documentclass[12pt]{article} ...")

From a file:

Iona.source(path: "/path/to/document.tex")

When providing a file path, you can also define additional files needed for processing. They will be copied to the temporary directory where processing will take place.

Iona.source(path: "/path/to/document.tex",
            include: ["/path/to/document.bib",
                      "/path/to/documentclass.sty"])

However, when possible, files should be placed in the search path of your TeX installation.

Link to this function

template(assigns, criteria)

View Source
template(assigns :: Keyword.t() | map(), criteria :: eex_tex_t()) ::
  {:ok, Iona.Template.t()} | {:error, term()}
template(assigns :: Keyword.t() | map(), criteria :: template_opts()) ::
  {:ok, Iona.Template.t()} | {:error, term()}

Fill in a template with assignments, with TeX escaping support

{:ok, template} = [title: "An Article", author: "Bruce Williams"]
|> Iona.template(path: "/path/to/article.tex")

Iona.write(template, "/path/to/article.pdf")
Link to this function

template!(assigns, criteria)

View Source
template!(
  assigns :: Keyword.t() | map(),
  criteria :: eex_tex_t() | template_opts()
) :: Iona.Template.t()

The same as template/2, but raises Iona.ProcessingError if it fails. Returns the template otherwise.

[title: "An Article", author: "Bruce Williams"]
|> Iona.template!(path: "/path/to/article.tex")
|> Iona.write("/path/to/article.pdf")
Link to this function

to(input, format, opts \\ [])

View Source
to(
  input :: Iona.Input.t(),
  format :: supported_format_t(),
  opts :: processing_opts()
) :: {:ok, binary()} | {:error, binary()}

Generate a formatted document as a string.

Without processing options:

{:ok, pdf_string} = Iona.source(path: "/path/to/document.tex")
|> Iona.to(:pdf)

With processing options:

{:ok, pdf_string} = Iona.source(path: "/path/to/document.tex")
|> Iona.to(:pdf, processor: "xetex")
Link to this function

to!(input, format, opts \\ [])

View Source
to!(
  input :: Iona.Input.t(),
  format :: supported_format_t(),
  opts :: processing_opts()
) :: binary()

The same as to/3, but raises Iona.ProcessingError if it fails. Returns the document content otherwise.

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

If writing to a file, see write/3 and write/4, as they are both shorter to type and have better performance characteristics.

Link to this function

write(input, path, opts \\ [])

View Source
write(input :: Iona.Input.t(), path :: Path.t(), opts :: processing_opts()) ::
  :ok | {:error, term()}

Generate a formatted document to a file path.

Without processing options:

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

With processing options:

:ok = Iona.source(path: "/path/to/document.tex")
|> Iona.write("/path/to/document.pdf",
processor: "xetex")
Link to this function

write!(input, path, opts \\ [])

View Source
write!(input :: Iona.Input.t(), path :: Path.t(), opts :: processing_opts()) ::
  :ok

The same as write/3 but raises Iona.ProcessingError if it fails.

Without processing options:

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

With processing options:

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