Templa...::Latex(3pm)

Template::Plugin::Latex 💅✨

okay bestie so this is the Template::Plugin::Latex page — it's the Template Toolkit plugin for LaTeX, and yes it's filed under "User Contributed Perl Documentation" which is giving very "made by the community, for the community" 💖. It's a perl module manpage, section 3pm, and honestly? iconic.

---

✨ VERSION ✨

This documentation refers to Template::Plugin::Latex version 3.12 🎀

---

🌸 SYNOPSIS 🌸

Sample Template Toolkit code, no cap:

    [%- 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 hands you a latex filter, and that filter is the whole point: it lets you use LaTeX to generate PDF, PostScript and DVI output files straight out of the Template Toolkit. Under the hood it's LaTeX::Driver doing the actual running of all the various LaTeX programs. bestie is delegating. we love a delegation moment 🫶

Processing of the LaTeX document happens in a temporary directory, and that directory gets yeeted once processing is done. 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 until it becomes apparent that they are never going to stabilize 😭 (we've all been there). The format converters dvips, dvipdf, ps2pdf and pdf2ps get run as needed to convert the output document to whatever format you asked for. And the TEXINPUTS environment variable is set up to include the template directory plus the INCLUDES directories, so that LaTeX file inclusion commands actually find the files they're supposed to find. slay 🔥

⚠️ The output of the filter is binary data (although honestly PDF and PostScript are not stictly binary — that's the original's spelling, not mine, iykyk). Be careful: do not prepend or append any extraneous characters — not even space characters — or text outside the FILTER block, because that text will be included in the file output. Not a vibe. 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. fr fr.

    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 into a template variable instead, you can do it 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 explicitly specify an output format then the filename extension (e.g. 'pdf' in the above example) will be used to determine the correct format. she's intuitive like that 💅

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 files respectively. These programs have a -tt2 option to run their input through the Template Toolkit before processing it as LaTeX source. The programs do not use the Latex plugin unless the template asks for it, but they may give you an alternative way of processing Template Toolkit templates to generate typeset output. options options options ✨

---

🦋 SUBROUTINES/METHODS 🦋

USE Latex(options)

This statement loads the plugin. heads up: prior to version 2.15 the filter was built in to Template Toolkit, so this statement was unnecessary — but now it is required. so don't skip it, bestie 🙈

The latex Filter

The latex filter accepts a number of options, and you can specify them either on the USE statement or on the filter invocation. dealer's choice 🎀

• 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. math is mathing 📐

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. she's got connections 💅

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 it can be further interpolated into a LaTeX document template. cute, right? 🎀

---

👑 DIAGNOSTICS 👑

Most failures result from invalid LaTeX input and are propagated 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. girl, where's your output path 😭

---

🧚 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 explicitly to enable the latex filter.

(yes, "must now be explicitly" — that's the original, I'm not fixing her, she's doing her best 🫶)

---

💀 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. on purpose. on purpose. don't ask 🙈

---

🌈 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.

radically refactored. ate and left no crumbs 💅

---

💖 LICENSE AND 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.

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. 😭 (legally required yelling, bestie, not a vibe check)

---

🔥 SEE ALSO 🔥

Template, LaTeX::Driver, LaTeX::Table, LaTeX::Encode

latex2dvi(1), latex2pdf(1) and latex2ps(1) (part of the LaTeX::Driver distribution)

---

and that's the whole page, bestie 💜 this one came from perl v5.36.0, dated 2022-11-19, and it's the Template::Plugin::Latex (3pm) page — go make some PDFs, you've got this ✨🎀