NAME

       Template::Plugin::Latex - Template Toolkit plugin for Latex

VERSION

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

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

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.

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

SEE ALSO

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

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