content_processor.tikz

Description

This content processor provides support for automatically generating graphics via the fantastic PGF/TikZ library for LaTeX.

Prerequisites

You will need to have a current LaTeX distribution with the PGF/TikZ library and ImageMagick or GraphicsMagick installed for this to work. You will also need Ghostscript if you want support for transparent PNG images and pdf2svg for SVG output support.

More exactly, you will need to have the following programs available in the binary search path:

pdflatex

This program is usually included in the LaTeX distribution. It is used for generating a PDF from the LaTeX document that describes the PGF/TikZ graphic.

convert

This program is provided by ImageMagick or GraphicsMagick. It is used to convert the generated PDF document to an image file and to optionally resize it.

identify

This program is provided by ImageMagick or GraphicsMagick. It is used to determine the exact size of the generated image file.

gs

This program is provided by the Ghostscript package. It is used for generating transparent PNG images.

pdf2svg

This program converts the generated PDF to an SVG file.

If you are using Ubuntu Linux you can install everything that is needed by running the following command:

$ sudo aptitude install texlive pgf ghostscript imagemagick pdf2svg

Usage

This content processor is normally used in one of the following ways:

• Either with the tag tikz which provides an easy way to insert an image tag and generate a TikZ picture at the same time.

• Or in combination with the path handler copy. An easy way to do this is by creating a file with the tikz extension. This file is automatically handled by the path handler copy which changes its extension to png and processes it with this processor.

The content needs to contain just the PGF/TikZ image commands because the content processor itself automatically wraps it with the approriate LaTeX commands to create a full LaTeX document which is then converted to an image.

There are some configuration options for configuring the behaviour of this processor:

• If the generated image should be partly transparent, use the  content_processor.tikz.transparent option.

• The render quality of the image can be adjusted with the  content_processor.tikz.resolution option.

• Use the  content_processor.tikz.libraries option to specify TikZ library names that should be loaded.

• The  content_processor.tikz.opts option provides a way for specifying arbitrary options for the tikzpicture environment.

• Finally, the LaTeX document template that is wrapped around the PGF/TikZ commands can be customized by creating a template file and referencing it by using the  content_processor.tikz.template option.

Custom LaTeX Templates

If you want to use a custom LaTeX template, the following special objects are available:

context['data']

Contains the PGF/TikZ commands for the image.

context[OPTION_NAME]

The value for the configuration option OPTION_NAME. This should be used instead of context.website.config[OPTION_NAME] since the value may have been changed.

Here is an example for such a LaTeX template:

--- name:content pipeline:erb
\documentclass{standalone}
\usepackage{tikz}

<% if context['content_processor.tikz.libraries'] %>
\usetikzlibrary{<%= context['content_processor.tikz.libraries'].join(',') %>}
<% end %>

\begin{document}
\begin{tikzpicture}[<%= context['content_processor.tikz.opts'] %>]
<%= context['data'] %>
\end{tikzpicture}
\end{document}

Examples

Have a look at the tag tikz to see example input and the generated images.