Template::Latex(3pm)

💖 NAME 💖

Template::Latex — Latex support for the Template Toolkit, bestie ✨

---

🌸 SYNOPSIS 🌸

okay so this is the whole vibe, look:

use Template::Latex;

my $tt = Template::Latex->new({
    INCLUDE_PATH  => '/path/to/templates',
    OUTPUT_PATH   => '/path/to/pdf/output',
    LATEX_FORMAT  => 'pdf',
});
my $vars = {
    title => 'Hello World',
}
$tt->process('example.tt2', $vars, 'example.pdf', binmode => 1)
    || die $tt->error();

---

🦋 DESCRIPTION 🦋

Template::Latex is literally just a wrapper of convenience around the Template module — she's holding your hand while you generate PDF, PostScript and DVI documents from LaTeX templates. slay 💅

You use her exactly how you'd use Template:

my $tt = Template::Latex->new(\%config);
$tt->process($input, \%vars, $output)
    || die $t->error();

She supports the LATEX_FORMAT option to set the default output format, no cap. It can be pdf, ps or dvi:

my $tt = Template::Latex->new({
    LATEX_FORMAT  => 'pdf',
});

🙈 okay so tea time: previous versions of this module supported the LATEX_PATH, PDFLATEX_PATH, DVIPS_PATH, PS2PDF_PATH, BIBTEX_PATH and MAKEINDEX_PATH options. Those are deprecated now and using them gives you a deprecation warning — because using them would mean modifying global state, which disallows different values for different simultaneous instances. so yeah, she had to let them go 🥲

If you wanna change the paths of the various programs being called by the LaTeX::Driver module (which this module wraps), go read that module's API, bestie. This module provides a bunch of (wrapper) class methods around the LaTeX::Driver routine — like latex_path() and friends. 🫶

Also the latex filter is automatically defined when you use Template::Latex. No need to load the Latex plugin in this case — though you can if you want (e.g. to set some configuration defaults ✨). If you're using the regular Template module though, you should first load the Latex plugin to define the latex filter:

[% USE Latex %]
[% FILTER latex('example.pdf') %]
...LaTeX doc...
[% END %]

---

👑 PUBLIC METHODS 👑

Template::Latex is a subclass of the Template module and inherits all her methods. Please go consult the docs for the Template module for more info on using it for template processing. Wherever you see Template, just substitute Template::Latex and you're golden 💖

In addition to those inherited from the Template module, these methods are also defined:

⭐ latex_paths()

Method to get or set the paths to the latex, pdflatex and dvips programs. These values live in the Template::Latex $LATEX, $PDFLATEX and $DVIPS package variables, respectively. Call it as either a class or object method, whichever fits your vibe.

Template::Latex->latex_paths({
    latex    => '/usr/bin/latex',
    pdflatex => '/usr/bin/pdflatex',
    dvips    => '/usr/bin/dvips',
});

my $paths = Template::Latex->latex_paths();
print $paths->{ latex };    # /usr/bin/latex

🌈 latex_path()

Method to get or set the $Template::Latex::LATEX package variable, which defines where the latex program lives on your system. Class method or object method, both work 💜

Template::Latex->latex_path('/usr/bin/latex');
print Template::Latex->latex_path();   # '/usr/bin/latex'

💫 pdflatex_path()

Method to get or set the $Template::Latex::PDFLATEX package variable, which defines where the pdflatex program lives on your system. Class or object method, your choice 🎀

Template::Latex->pdflatex_path('/usr/bin/pdflatex');
print Template::Latex->pdflatex_path();   # '/usr/bin/pdflatex'

🧚 dvips_path()

Method to get or set the $Template::Latex::DVIPS package variable, which defines where the dvips program lives on your system. Class or object method, obviously ✨

Template::Latex->dvips_path('/usr/bin/dvips');
print Template::Latex->dvips_path();   # '/usr/bin/dvips'

🍓 bibtex_path()

Method to get or set the $Template::Latex::BIBTEX package variable, which defines where the bibtex program lives on your system. Class or object method, we love consistency 💅

Template::Latex->bibtex_path('/usr/bin/bibtex');
print Template::Latex->bibtex_path();   # '/usr/bin/bibtex'

🦄 makeindex_path()

Method to get or set the $Template::Latex::MAKEINDEX package variable, which defines where the makeindex program lives on your system. Class or object method, iconic behavior fr fr 💖

Template::Latex->makeindex_path('/usr/bin/makeindex');
print Template::Latex->makeindex_path();   # '/usr/bin/makeindex'

---

🔥 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 interested in understanding how it works. You genuinely don't need to know anything about them to use the module, and you can safely skip this whole section. no thoughts, just vibes 🌸

💀 define_filter($context,%config)

This class method installs the latex 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 USE directive).

Template::Latex->define_filter($context, { format => 'pdf' });

The filter is installed as a dynamic filter factory. That's just a fancy way of saying the filter generates a new filter subroutine every time it's used, so it can account for different invocation parameters. The filter subroutine it creates is effectively a wrapper — a "closure" in technical terms — around the filter() subroutine (see below), which is the one doing 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 filter() subroutine (see below).

See the Template::Filters module for further info on how filters work 🫶

⚡ filter($text,%config)

This is the main LaTeX filter subroutine, 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 — usually provided by the filter subroutine that's generated by the filter factory.

Template::Latex::filter($latex, {
    latex    => '/usr/bin/latex',
    pdflatex => '/usr/bin/pdflatex',
    dvips    => '/usr/bin/dvips',
    output   => 'example.pdf',
});

😭 throw($message)

Subroutine that throws a Template::Exception error using die. The exception type is set to latex.

Template::Latex::throw("I'm sorry Dave, I can't do that");

🐛 debug($message)

Debugging subroutine that prints all arguments to STDERR. Set the $DEBUG package variable to enable debugging messages.

$Template::Latex::DEBUG = 1;

---

💜 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. shoutout to the OGs 🫶

---

🎀 COPYRIGHT 🎀

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.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. periodt 💅

---

🌟 SEE ALSO 🌟

• Template::Plugin::Latex

---

and that's a wrap, bestie 🎀 this was perl v5.36.0, dated 2022-11-19, from the Template::Latex(3pm) page — go make something beautiful, ily 🦋💖