.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Plugin::Latex 3pm"
.TH Template::Plugin::Latex 3pm "2022-11-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Plugin::Latex \- Template Toolkit plugin for Latex
.SH "VERSION"
.IX Header "VERSION"
This documentation refers to \f(CW\*(C`Template::Plugin::Latex\*(C'\fR version 3.12
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Sample Template Toolkit code:
.PP
.Vb 1
\&    [%\- USE Latex;
\&
\&        mystr = "a, b & c" | latex_encode;
\&
\&        FILTER latex("pdf");  \-%]
\&
\&    \edocumentclass{article}
\&    \ebegin{document}
\&      This is a PDF document generated by
\&      LaTeX and the Template Toolkit, with some
\&      interpolated data: [% mystr %]
\&    \eend{document}
\&
\&    [%  END; \-%]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Latex\*(C'\fR Template Toolkit plugin provides a \f(CW\*(C`latex\*(C'\fR filter that
allows the use of LaTeX to generate \s-1PDF,\s0 PostScript and \s-1DVI\s0 output files
from the Template Toolkit.  The plugin uses LaTeX::Driver to run the
various LaTeX programs.
.PP
Processing of the LaTeX document takes place in a temporary directory
that is deleted once processing is complete.  The standard LaTeX
programs (\f(CW\*(C`latex\*(C'\fR or \f(CW\*(C`pdflatex\*(C'\fR, \f(CW\*(C`bibtex\*(C'\fR and \f(CW\*(C`makeindex\*(C'\fR) 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 \f(CW\*(C`dvips\*(C'\fR,
\&\f(CW\*(C`dvipdf\*(C'\fR, \f(CW\*(C`ps2pdf\*(C'\fR and \f(CW\*(C`pdf2ps\*(C'\fR are run as necessary to convert the
output document to the requested format.  The \f(CW\*(C`TEXINPUTS\*(C'\fR environment
variable is set up to include the template directory and the \f(CW\*(C`INCLUDES\*(C'\fR
directories, so that LaTeX file inclusion commands should find the
intended files.
.PP
The output of the filter is binary data (although \s-1PDF\s0 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 \s-1FILTER\s0
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
\&\f(CW\*(C`USE\*(C'\fR and \f(CW\*(C`END\*(C'\fR directives to remove the trailing newline characters:
.PP
.Vb 4
\&    [% USE Latex(format=\*(Aqpdf\*(Aq) \-%]
\&    [% FILTER latex %]
\&    ...LaTeX document...
\&    [% END \-%]
.Ve
.PP
If you're redirecting the output to a file via the third argument of
the Template module's \f(CW\*(C`process()\*(C'\fR method then you should also pass
the \f(CW\*(C`binmode\*(C'\fR parameter, set to a true value to indicate that it is a
binary file.
.PP
.Vb 1
\&    use Template;
\&
\&    my $tt = Template\->new({
\&        INCLUDE_PATH => \*(Aq/path/to/templates\*(Aq,
\&        OUTPUT_PATH  => \*(Aq/path/to/pdf/output\*(Aq,
\&    });
\&    my $vars = {
\&        title => \*(AqHello World\*(Aq,
\&    }
\&    $tt\->process(\*(Aqexample.tt2\*(Aq, $vars, \*(Aqexample.pdf\*(Aq, binmode => 1)
\&        || die $tt\->error();
.Ve
.PP
If you want to capture the output to a template variable, you can do
so like this:
.PP
.Vb 3
\&    [% output = FILTER latex %]
\&    ...LaTeX document...
\&    [% END %]
.Ve
.PP
You can pass additional arguments when you invoke the filter, for
example to specify the output format.
.PP
.Vb 3
\&    [% FILTER latex(format=\*(Aqpdf\*(Aq) \-%]
\&       ...LaTeX document...
\&    [% END %]
.Ve
.PP
If you want to write the output to a file then you can specify an
\&\f(CW\*(C`output\*(C'\fR parameter.
.PP
.Vb 3
\&    [% FILTER latex(output=\*(Aqexample.pdf\*(Aq) %]
\&    ...LaTeX document...
\&    [% END %]
.Ve
.PP
If you don't explicitly specify an output format then the filename
extension (e.g. 'pdf' in the above example) will be used to determine
the correct format.
.PP
You can specify a different filter name using the \f(CW\*(C`filter\*(C'\fR parameter.
.PP
.Vb 4
\&    [% USE Latex(filter=\*(Aqpdf\*(Aq) \-%]
\&    [% FILTER pdf %]
\&    ...LaTeX document...
\&    [% END %]
.Ve
.PP
You can also specify the default output format.  This value can be
\&\f(CW\*(C`latex\*(C'\fR, \f(CW\*(C`pdf\*(C'\fR or \f(CW\*(C`dvi\*(C'\fR.
.PP
.Vb 1
\&    [% USE Latex(format=\*(Aqpdf\*(Aq) %]
.Ve
.PP
Note: the \f(CW\*(C`LaTeX::Driver\*(C'\fR distribution includes three filter programs
(\f(CW\*(C`latex2dvi\*(C'\fR, \f(CW\*(C`latex2pdf\*(C'\fR and \f(CW\*(C`latex2ps\*(C'\fR) that use the
\&\f(CW\*(C`LaTeX::Driver\*(C'\fR package to process LaTeX source data into \s-1DVI, PDF\s0 or
PostScript file respectively.  These programs have a \f(CW\*(C`\-tt2\*(C'\fR option to
run their input through the Template Toolkit before processing as LaTeX
source.  The programs do not use the \f(CW\*(C`Latex\*(C'\fR plugin unless the template
requests it, but they may provide an alternative way of processing
Template Toolkit templates to generate typeset output.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.ie n .SS """USE Latex(options)"""
.el .SS "\f(CWUSE Latex(options)\fP"
.IX Subsection "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).
.ie n .SS "The ""latex"" Filter"
.el .SS "The \f(CWlatex\fP Filter"
.IX Subsection "The latex Filter"
The \f(CW\*(C`latex\*(C'\fR filter accepts a number of options, which may be
specified on the \s-1USE\s0 statement or on the filter invocation.
.ie n .IP """format""" 4
.el .IP "\f(CWformat\fR" 4
.IX Item "format"
specifies the format of the output; one of \f(CW\*(C`dvi\*(C'\fR (TeX device
independent format), \f(CW\*(C`ps\*(C'\fR (PostScript) or \f(CW\*(C`pdf\*(C'\fR (Adobe Portable
Document Format).  The follow special values are also accepted:
\&\f(CW\*(C`pdf(ps)\*(C'\fR (generates \s-1PDF\s0 via PostScript, using \f(CW\*(C`dvips\*(C'\fR and
\&\f(CW\*(C`ps2pdf\*(C'\fR), \f(CW\*(C`pdf(dvi)\*(C'\fR (generates \s-1PDF\s0 via dvi, using \f(CW\*(C`dvipdfm\*(C'\fR)
.ie n .IP """output""" 4
.el .IP "\f(CWoutput\fR" 4
.IX Item "output"
the name of the output file, or just the output format
.ie n .IP """indexstyle""" 4
.el .IP "\f(CWindexstyle\fR" 4
.IX Item "indexstyle"
the name of the \f(CW\*(C`makeindex\*(C'\fR style file to use (this is passed with
the \f(CW\*(C`\-s\*(C'\fR option to \f(CW\*(C`makeindex\*(C'\fR)
.ie n .IP """indexoptions""" 4
.el .IP "\f(CWindexoptions\fR" 4
.IX Item "indexoptions"
options to be passed to \f(CW\*(C`makeindex\*(C'\fR.  Useful options are \f(CW\*(C`\-l\*(C'\fR for
letter ordering of index terms (rather than the default word
ordering), \f(CW\*(C`\-r\*(C'\fR to disable implicit page range formation, and \f(CW\*(C`\-c\*(C'\fR
to compress intermediate blanks in index keys. Refer to \fBmakeindex\fR\|(1)
for full details.
.ie n .IP """maxruns""" 4
.el .IP "\f(CWmaxruns\fR" 4
.IX Item "maxruns"
The maximum number of runs of the formatter program (defaults to 10).
.ie n .IP """extraruns""" 4
.el .IP "\f(CWextraruns\fR" 4
.IX Item "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 \f(CW\*(C`maxruns\*(C'\fR takes precedence, so if \f(CW\*(C`maxruns\*(C'\fR is
set to 10 and \f(CW\*(C`extraruns\*(C'\fR is set to 3, and formatting stabilizes
after 8 runs then only 2 extra runs will be performed.
.ie n .SS "The ""latex_encode"" filter"
.el .SS "The \f(CWlatex_encode\fP filter"
.IX Subsection "The latex_encode filter"
The \f(CW\*(C`latex_encode\*(C'\fR filter encodes LaTeX special characters in its
input into their LaTeX encoded representations.  It also encodes other characters that have
.PP
The special characters are: \f(CW\*(C`\e\*(C'\fR (command character), \f(CW\*(C`{\*(C'\fR (open
group), \f(CW\*(C`}\*(C'\fR (end group), \f(CW\*(C`&\*(C'\fR (table column separator), \f(CW\*(C`#\*(C'\fR
(parameter specifier), \f(CW\*(C`%\*(C'\fR (comment character), \f(CW\*(C`_\*(C'\fR (subscript),
\&\f(CW\*(C`^\*(C'\fR (superscript), \f(CW\*(C`~\*(C'\fR (non-breakable space), \f(CW\*(C`$\*(C'\fR (mathematics mode).
.ie n .IP """except""" 4
.el .IP "\f(CWexcept\fR" 4
.IX Item "except"
Lists the characters that should be excluded from encoding.  By
default no special characters are excluded, but it may be useful to
specify \f(CW\*(C`except = "\e\e{}"\*(C'\fR to allow the input string to contain LaTeX
commands such as \f(CW"this is \etextbf{bold} text"\fR.
.ie n .IP """use_textcomp""" 4
.el .IP "\f(CWuse_textcomp\fR" 4
.IX Item "use_textcomp"
By default the \f(CW\*(C`latex_encode\*(C'\fR filter will encode characters with the
encodings provided by the \f(CW\*(C`textcomp\*(C'\fR LaTeX package (for example the
Pounds Sterling symbol is encoded as \f(CW\*(C`\etextsterling{}\*(C'\fR).  Setting
\&\f(CW\*(C`use_textcomp = 0\*(C'\fR turns off these encodings.
.ie n .SS """table()"""
.el .SS "\f(CWtable()\fP"
.IX Subsection "table()"
The \f(CW\*(C`table()\*(C'\fR function provides an interface to the \f(CW\*(C`LaTeX::Table\*(C'\fR module.
.PP
The following example shows how a simple table can be set up.
.PP
.Vb 1
\&    [%\- USE Latex;
\&
\&        data = [ [ \*(AqLondon\*(Aq, \*(AqUnited Kingdom\*(Aq ],
\&                 [ \*(AqBerlin\*(Aq, \*(AqGermany\*(Aq        ],
\&                 [ \*(AqParis\*(Aq,  \*(AqFrance\*(Aq         ],
\&                 [ \*(AqWashington\*(Aq, \*(AqUSA\*(Aq        ] ] );
\&
\&        text = Latex.table( caption  = \*(AqCapitol Cities\*(Aq,
\&                            label    = \*(Aqtable:capitols\*(Aq,
\&                            headings = [ [ \*(AqCity\*(Aq, \*(AqCountry\*(Aq ] ],
\&                            data     = data );
\&     \-%]
.Ve
.PP
The variable \f(CW\*(C`text\*(C'\fR will hold the LaTeX commands to typeset the table
and can be further interpolated into a LaTeX document template.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Most failures result from invalid LaTeX input and are propagated up from
LaTeX::Driver, LaTeX::Encode or LaTeX::Table.
.PP
Failures detected in this module include:
.ie n .IP """OUTPUT_PATH is not set""" 4
.el .IP "\f(CWOUTPUT_PATH is not set\fR" 4
.IX Item "OUTPUT_PATH is not set"
an output filename was specified but the \f(CW\*(C`OUTPUT_PATH\*(C'\fR configuration
option has not been set.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "Template" 4
.IX Item "Template"
The Template Toolkit.
.IP "LaTeX::Driver" 4
.IX Item "LaTeX::Driver"
Provides the logic for driving the LaTeX programs.
.IP "LaTeX::Encode" 4
.IX Item "LaTeX::Encode"
Underpins the \f(CW\*(C`latex_encode\*(C'\fR filter.
.IP "LaTeX::Table" 4
.IX Item "LaTeX::Table"
Underpins the \f(CW\*(C`table\*(C'\fR function.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
The \f(CW\*(C`latex\*(C'\fR 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
\&\f(CW\*(C`Latex\*(C'\fR plugin must now be explicitly to enable the \f(CW\*(C`latex\*(C'\fR filter.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
The paths to the \fIlatex\fR, \fIpdflatex\fR and \fIdvips\fR should be
pre-defined as part of the installation process of LaTeX::Driver
(i.e. when you run \f(CW\*(C`perl Makefile.PL\*(C'\fR for that package).  Alternative
values can be specified from Perl code using the \f(CW\*(C`program_path\*(C'\fR class
method from that package, but there are deliberately no options to
specify these paths from \s-1TT\s0 code.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Ford <a.ford@ford\-mason.co.uk> (current maintainer)
.PP
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.PP
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.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
.Vb 3
\&  Copyright (C) 1996\-2006 Andy Wardley.  All Rights Reserved.
\&  Copyright (C) 2006\-2014 Andrew Ford.  All Rights Reserved.
\&  Copyright (C) 2014\-2016 Chris Travers. All Rights Reserved.
.Ve
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
This software is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template, LaTeX::Driver, LaTeX::Table, LaTeX::Encode
.PP
\&\fBlatex2dvi\fR\|(1), \fBlatex2pdf\fR\|(1) and \fBlatex2ps\fR\|(1) (part of the
\&\f(CW\*(C`LaTeX::Driver\*(C'\fR distribution)