NAME¶
Template::Plugin::Latex - Template Toolkit plugin for Latex
VERSION¶
This documentation refers to "Template::Plugin::Latex" version 3.02.
SYNOPSIS¶
Sample Template Toolkit code:
[%- USE Latex;
mystr = "a, b & c" | latex_encode;
FILTER latex("pdf"); -%]
\documentclass{article}
\begin{document}
This is a PDF document generated by
LaTeX and the Template Toolkit, with some
interpolated data: [% mystr %]
\end{document}
[% END; -%]
DESCRIPTION¶
The "Latex" Template Toolkit plugin provides a "latex"
filter that allows the use of LaTeX to generate PDF, PostScript and DVI output
files from the Template Toolkit. The plugin uses LaTeX::Driver to run the
various LaTeX programs.
Processing of the LaTeX document takes place in a temporary directory that is
deleted once processing is complete. The standard LaTeX programs
("latex" or "pdflatex", "bibtex" and
"makeindex") are run and re-run as necessary until all references,
indexes, bibliographies, table of contents, and lists of figures and tables
are stable or it is apparent that they will not stabilize. The format
converters "dvips", "dvipdf", "ps2pdf" and
"pdf2ps" are run as necessary to convert the output document to the
requested format. The "TEXINPUTS" environment variable is set up to
include the template directory and the "INCLUDES" directories, so
that LaTeX file inclusion commands should find the intended files.
The output of the filter is binary data (although PDF and PostScript are not
stictly binary). You should be careful not to prepend or append any extraneous
characters (even space characters) or text outside the FILTER block as this
text will be included in the file output. Notice in the example below how we
use the post-chomp flags ('-') at the end of the "USE" and
"END" directives to remove the trailing newline characters:
[% USE Latex(format='pdf') -%]
[% FILTER latex %]
...LaTeX document...
[% END -%]
If you're redirecting the output to a file via the third argument of the
Template module's "process()" method then you should also pass the
"binmode" parameter, set to a true value to indicate that it is a
binary file.
use Template;
my $tt = Template->new({
INCLUDE_PATH => '/path/to/templates',
OUTPUT_PATH => '/path/to/pdf/output',
});
my $vars = {
title => 'Hello World',
}
$tt->process('example.tt2', $vars, 'example.pdf', binmode => 1)
|| die $tt->error();
If you want to capture the output to a template variable, you can do so like
this:
[% output = FILTER latex %]
...LaTeX document...
[% END %]
You can pass additional arguments when you invoke the filter, for example to
specify the output format.
[% FILTER latex(format='pdf') -%]
...LaTeX document...
[% END %]
If you want to write the output to a file then you can specify an
"output" parameter.
[% FILTER latex(output='example.pdf') %]
...LaTeX document...
[% END %]
If you don't explicity specify an output format then the filename extension
(e.g. 'pdf' in the above example) will be used to determine the correct
format.
You can specify a different filter name using the "filter" parameter.
[% USE Latex(filter='pdf') -%]
[% FILTER pdf %]
...LaTeX document...
[% END %]
You can also specify the default output format. This value can be
"latex", "pdf" or "dvi".
[% USE Latex(format='pdf') %]
Note: the "LaTeX::Driver" distribution includes three filter programs
("latex2dvi", "latex2pdf" and "latex2ps") that
use the "LaTeX::Driver" package to process LaTeX source data into
DVI, PDF or PostScript file respectively. These programs have a
"-tt2" option to run their input through the Template Toolkit before
processing as LaTeX source. The programs do not use the "Latex"
plugin unless the template requests it, but they may provide an alternative
way of processing Template Toolkit templates to generate typeset output.
SUBROUTINES/METHODS¶
"USE Latex(options)"¶
This statement loads the plugin (note that prior to version 2.15 the filter was
built in to Template Toolkit so this statement was unnecessary; it is now
required).
The "latex" Filter¶
The "latex" filter accepts a number of options, which may be specified
on the USE statement or on the filter invocation.
- "format"
- specifies the format of the output; one of "dvi"
(TeX device independent format), "ps" (PostScript) or
"pdf" (Adobe Portable Document Format). The follow special
values are also accepted: "pdf(ps)" (generates PDF via
PostScript, using "dvips" and "ps2pdf"),
"pdf(dvi)" (generates PDF via dvi, using
"dvipdfm")
- "output"
- the name of the output file, or just the output format
- "indexstyle"
- the name of the "makeindex" style file to use
(this is passed with the "-s" option to
"makeindex")
- "indexoptions"
- options to be passed to "makeindex". Useful
options are "-l" for letter ordering of index terms (rather than
the default word ordering), "-r" to disable implicit page range
formation, and "-c" to compress intermediate blanks in index
keys. Refer to makeindex(1) for full details.
- "maxruns"
- The maximum number of runs of the formatter program
(defaults to 10).
- "extraruns"
- The number of additional runs of the formatter program
after it seems that the formatting of the document has stabilized (default
0). Note that the setting of "maxruns" takes precedence, so if
"maxruns" is set to 10 and "extraruns" is set to 3,
and formatting stabilizes after 8 runs then only 2 extra runs will be
performed.
The "latex_encode" filter¶
The "latex_encode" filter encodes LaTeX special characters in its
input into their LaTeX encoded representations. It also encodes other
characters that have
The special characters are: "\" (command character), "{"
(open group), "}" (end group), "&" (table column
separator), "#" (parameter specifier), "%" (comment
character), "_" (subscript), "^" (superscript),
"~" (non-breakable space), "$" (mathematics mode).
- "except"
- Lists the characters that should be excluded from encoding.
By default no special characters are excluded, but it may be useful to
specify "except = "\\{}"" to allow the input string to
contain LaTeX commands such as "this is \textbf{bold}
text".
- "use_textcomp"
- By default the "latex_encode" filter will encode
characters with the encodings provided by the "textcomp" LaTeX
package (for example the Pounds Sterling symbol is encoded as
"\textsterling{}"). Setting "use_textcomp = 0" turns
off these encodings.
"table()"¶
The "table()" function provides an interface to the
"LaTeX::Table" module.
The following example shows how a simple table can be set up.
[%- USE Latex;
data = [ [ 'London', 'United Kingdom' ],
[ 'Berlin', 'Germany' ],
[ 'Paris', 'France' ],
[ 'Washington', 'USA' ] ] );
text = Latex.table( caption = 'Capitol Cities',
label = 'table:capitols',
headings = [ [ 'City', 'Country' ] ],
data = data );
-%]
The variable "text" will hold the LaTeX commands to typeset the table
and can be further interpolated into a LaTeX document template.
DIAGNOSTICS¶
Most failures result from invalid LaTeX input and are propogated up from
LaTeX::Driver, LaTeX::Encode or LaTeX::Table.
Failures detected in this module include:
- "OUTPUT_PATH is not set"
- an output filename was specified but the
"OUTPUT_PATH" configuration option has not been set.
DEPENDENCIES¶
- Template
- The Template Toolkit.
- LaTeX::Driver
- Provides the logic for driving the LaTeX programs.
- LaTeX::Encode
- Underpins the "latex_encode" filter.
- LaTeX::Table
- Underpins the "table" function.
INCOMPATIBILITIES¶
The "latex" filter was distributed as part of the core Template
Toolkit distribution until version 2.15 (released in May 2006), when it was
moved into the separate Template-Latex distribution. The "Latex"
plugin must now be explicity to enable the "latex" filter.
BUGS AND LIMITATIONS¶
The paths to the
latex,
pdflatex and
dvips should be
pre-defined as part of the installation process of LaTeX::Driver (i.e. when
you run "perl Makefile.PL" for that package). Alternative values can
be specified from Perl code using the "program_path" class method
from that package, but there are deliberately no options to specify these
paths from TT code.
AUTHOR¶
Andrew Ford <a.ford@ford-mason.co.uk> (current maintainer)
Andy Wardley <abw@wardley.org> <
http://wardley.org/>
The original Latex plugin on which this is based was written by Craig Barratt
with additions for Win32 by Richard Tietjen. The code has subsequently been
radically refactored by Andrew Ford.
LICENSE AND COPYRIGHT¶
Copyright (C) 2006-2009 Andrew Ford. All Rights Reserved.
Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
This software is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE.
SEE ALSO¶
Template, LaTeX::Driver, LaTeX::Table, LaTeX::Encode
latex2dvi(1),
latex2pdf(1) and
latex2ps(1) (part of the
"LaTeX::Driver" distribution)