.\" 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::Latex 3pm"
.TH Template::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::Latex \- Latex support for the Template Toolkit
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Template::Latex;
\&    
\&    my $tt = Template::Latex\->new({
\&        INCLUDE_PATH  => \*(Aq/path/to/templates\*(Aq,
\&        OUTPUT_PATH   => \*(Aq/path/to/pdf/output\*(Aq,
\&        LATEX_FORMAT  => \*(Aqpdf\*(Aq,
\&    });
\&    my $vars = {
\&        title => \*(AqHello World\*(Aq,
\&    }
\&    $tt\->process(\*(Aqexample.tt2\*(Aq, $vars, \*(Aqexample.pdf\*(Aq, binmode => 1)
\&        || die $tt\->error();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Template::Latex module is a wrapper of convenience around the
Template module, providing additional support for generating \s-1PDF,\s0
PostScript and \s-1DVI\s0 documents from LaTeX templates.
.PP
You use the Template::Latex module exactly as you would the Template
module.
.PP
.Vb 3
\&    my $tt = Template::Latex\->new(\e%config);
\&    $tt\->process($input, \e%vars, $output)
\&        || die $t\->error();
.Ve
.PP
It supports the \f(CW\*(C`LATEX_FORMAT\*(C'\fR option to specify the default
output format.  This can be set to \f(CW\*(C`pdf\*(C'\fR, \f(CW\*(C`ps\*(C'\fR or \f(CW\*(C`dvi\*(C'\fR.
.PP
.Vb 3
\&    my $tt = Template::Latex\->new({
\&        LATEX_FORMAT  => \*(Aqpdf\*(Aq,
\&    });
.Ve
.PP
Previous versions of the module supported the \f(CW\*(C`LATEX_PATH\*(C'\fR,
\&\f(CW\*(C`PDFLATEX_PATH\*(C'\fR, \f(CW\*(C`DVIPS_PATH\*(C'\fR, \f(CW\*(C`PS2PDF_PATH\*(C'\fR, \f(CW\*(C`BIBTEX_PATH\*(C'\fR
and \f(CW\*(C`MAKEINDEX_PATH\*(C'\fR options. These are now deprecated
and their use will result in a deprecation warning, as their use
would result in modifying global state, disallowing different values
for different simultaneous instances.
.PP
To change the paths of the various programs being called by the
LaTeX::Driver module which this module wraps, the user is referred
to the \s-1API\s0 of that module.  This module provides a number of (wrapper)
class methods around the LaTeX::Driver routine (\fBlatex_path()\fR and
friends).
.PP
The \f(CW\*(C`latex\*(C'\fR filter is automatically defined when you use the
Template::Latex module.  There's no need to load the Latex plugin in
this case, although you can if you want (e.g. to set some
configuration defaults).  If you're using the regular Template module
then you should first load the Latex plugin to define the \f(CW\*(C`latex\*(C'\fR
filter.
.PP
.Vb 4
\&    [% USE Latex %]
\&    [% FILTER latex(\*(Aqexample.pdf\*(Aq) %]
\&    ...LaTeX doc...
\&    [% END %]
.Ve
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
The Template::Latex module is a subclass of the Template module and
inherits all its methods.  Please consult the documentation for the
Template module for further information on using it for template
processing.  Wherever you see \f(CW\*(C`Template\*(C'\fR substitute it for
\&\f(CW\*(C`Template::Latex\*(C'\fR.
.PP
In addition to those inherted from the Template module, the following
methods are also defined.
.SS "\fBlatex_paths()\fP"
.IX Subsection "latex_paths()"
Method to get or set the paths to the \fIlatex\fR, \fIpdflatex\fR and
\&\fIdvips\fR programs.  These values are stored in the Template::Latex
\&\f(CW$LATEX\fR, \f(CW$PDFLATEX\fR and \f(CW$DVIPS\fR package variables, respectively.
It can be called as either a class or object method.
.PP
.Vb 5
\&    Template::Latex\->latex_paths({
\&        latex    => \*(Aq/usr/bin/latex\*(Aq,
\&        pdflatex => \*(Aq/usr/bin/pdflatex\*(Aq,
\&        dvips    => \*(Aq/usr/bin/dvips\*(Aq,
\&    });
\&
\&    my $paths = Template::Latex\->latex_paths();
\&    print $paths\->{ latex };    # /usr/bin/latex
.Ve
.SS "\fBlatex_path()\fP"
.IX Subsection "latex_path()"
Method to get or set the \f(CW$Template::Latex::LATEX\fR package
variable which defines the location of the \fIlatex\fR program on your
system.  It can be called as a class or object method.
.PP
.Vb 2
\&    Template::Latex\->latex_path(\*(Aq/usr/bin/latex\*(Aq);
\&    print Template::Latex\->latex_path();   # \*(Aq/usr/bin/latex\*(Aq
.Ve
.SS "\fBpdflatex_path()\fP"
.IX Subsection "pdflatex_path()"
Method to get or set the \f(CW$Template::Latex::PDFLATEX\fR package
variable which defines the location of the \fIpdflatex\fR program on your
system.  It can be called as a class or object method.
.PP
.Vb 2
\&    Template::Latex\->pdflatex_path(\*(Aq/usr/bin/pdflatex\*(Aq);
\&    print Template::Latex\->pdflatex_path();   # \*(Aq/usr/bin/pdflatex\*(Aq
.Ve
.SS "\fBdvips_path()\fP"
.IX Subsection "dvips_path()"
Method to get or set the \f(CW$Template::Latex::DVIPS\fR package
variable which defines the location of the \fIdvips\fR program on your
system.  It can be called as a class or object method.
.PP
.Vb 2
\&    Template::Latex\->dvips_path(\*(Aq/usr/bin/dvips\*(Aq);
\&    print Template::Latex\->dvips_path();   # \*(Aq/usr/bin/dvips\*(Aq
.Ve
.SS "\fBbibtex_path()\fP"
.IX Subsection "bibtex_path()"
Method to get or set the \f(CW$Template::Latex::BIBTEX\fR package
variable which defines the location of the \fIbibtex\fR program on your
system.  It can be called as a class or object method.
.PP
.Vb 2
\&    Template::Latex\->bibtex_path(\*(Aq/usr/bin/bibtex\*(Aq);
\&    print Template::Latex\->bibtex_path();   # \*(Aq/usr/bin/bibtex\*(Aq
.Ve
.SS "\fBmakeindex_path()\fP"
.IX Subsection "makeindex_path()"
Method to get or set the \f(CW$Template::Latex::MAKEINDEX\fR package
variable which defines the location of the \fImakeindex\fR program on your
system.  It can be called as a class or object method.
.PP
.Vb 2
\&    Template::Latex\->makeindex_path(\*(Aq/usr/bin/makeindex\*(Aq);
\&    print Template::Latex\->makeindex_path();   # \*(Aq/usr/bin/makeindex\*(Aq
.Ve
.SH "INTERNALS"
.IX Header "INTERNALS"
This section is aimed at a technical audience.  It documents the
internal methods and subroutines as a reference for the module's
developers, maintainers and anyone interesting in understanding how it
works.  You don't need to know anything about them to use the module
and can safely skip this section.
.SS "define_filter($context,\e%config)"
.IX Subsection "define_filter($context,%config)"
This class method installs the \f(CW\*(C`latex\*(C'\fR filter in the context passed
as the first argument.  The second argument is a hash reference
containing any default filter parameters (e.g. those specified when
the Template::Plugin::Latex plugin is loaded via a \f(CW\*(C`USE\*(C'\fR directive).
.PP
.Vb 1
\&    Template::Latex\->define_filter($context, { format => \*(Aqpdf\*(Aq });
.Ve
.PP
The filter is installed as a \fIdynamic filter factory\fR.  This is just
a fancy way of saying that the filter generates a new filter
subroutine each time it is used to account for different invocation
parameters.  The filter subroutine it creates is effectively a wrapper
(a \*(L"closure\*(R" in technical terms) around the \f(CW\*(C`filter()\*(C'\fR subroutine
(see below) which does the real work.  The closure keeps track of any
configuration parameters specified when the filter is first defined
and/or when the filter is invoked.  It passes the merged configuration
as the second argument to the \f(CW\*(C`filter()\*(C'\fR subroutine (see below).
.PP
See the Template::Filters module for further information on how
filters work.
.SS "filter($text,\e%config)"
.IX Subsection "filter($text,%config)"
This is the main LaTeX filter subroutine which is called by the
Template Toolkit to generate a LaTeX document from the text passed as
the first argument.  The second argument is a reference to a hash
array of configuration parameters.  These are usually provided by the
filter subroutine that is generated by the filter factory.
.PP
.Vb 6
\&    Template::Latex::filter($latex, { 
\&        latex    => \*(Aq/usr/bin/latex\*(Aq,
\&        pdflatex => \*(Aq/usr/bin/pdflatex\*(Aq,
\&        dvips    => \*(Aq/usr/bin/dvips\*(Aq,
\&        output   => \*(Aqexample.pdf\*(Aq,
\&    });
.Ve
.SS "throw($message)"
.IX Subsection "throw($message)"
Subroutine which throws a Template::Exception error using \f(CW\*(C`die\*(C'\fR.
The exception type is set to \f(CW\*(C`latex\*(C'\fR.
.PP
.Vb 1
\&    Template::Latex::throw("I\*(Aqm sorry Dave, I can\*(Aqt do that");
.Ve
.SS "debug($message)"
.IX Subsection "debug($message)"
Debugging subroutine which print all argument to \s-1STDERR.\s0  Set the 
\&\f(CW$DEBUG\fR package variable to enable debugging messages.
.PP
.Vb 1
\&    $Template::Latex::DEBUG = 1;
.Ve
.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.
.SH "COPYRIGHT"
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template::Plugin::Latex