README.md.xtpl

% xtpl(1) templating utitiliy
% Felix Leipold
% May 2012

Description
===========

xtpl is a templating mechnism in the spirit of unix.
It was developed to help with document preparation,
but could also be used in other circumstances,
where text needs to be enriched with output from other utilities.

xtpl takes a template text and substitutes special expressions with
the output from external tools. It also allows to filter parts
of the document through an external filter.

Including output from a utility
===============================

The most basic usecase for xtpl is to simply include the output from a
utility into the document.
Consider the following example document (`readme.txt.xtpl`):

~~~~~ {.tpl}
<<<<
cat examples/output_from_utility.xtpl
>>>>
~~~~~

When invoked like this:


~~~~ {.bash}
xtpl < readme.txt.xtpl
~~~~

we will get the following output:

~~~~ {.tpl}
<<<<
./xtpl < examples/output_from_utility.xtpl
>>>>

~~~~

Filtering parts of the document
===============================


Now we do not only want to get the output from an external utility, we also want to pipe input into that
process. Like the following example:

~~~~ {.tpl}
<<<<
cat examples/filtering.xtpl
>>>>
~~~~

Piping this through xtpl will yield:

~~~~~ {.tpl}
<<<<
./xtpl < examples/filtering.xtpl
>>>>

~~~~~

Redirecting the output of a utility into a separate file - e.g. Images
======================================================================

Sometimes we also might want to include only a link to a resource into our text.
A classical example would be a graph generated by _dot_:

~~~~~~ {.example}
<<<<
cat examples/redirecting_utility_output_to_file.xtpl
>>>>
~~~~~~~

Now this yields the following output:

~~~~~~ {.html}
<<<<
./xtpl < examples/redirecting_utility_output_to_file.xtpl
>>>>

~~~~~~

Also there is now a file called graph.png, so that when we look at the file with the browser
we will see the graph.