The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Template-Plugin-Latex-3.00_04
River stage one • 1 direct dependent • 1 total dependent
/ Template::Plugin::Latex

NAME

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

VERSION

This documentation refers to Template::Plugin::Latex version 3.00_03

SYNOPSIS

[%  # sample Template Toolkit code

    USE Latex;

    mystr = "a, b & c" FILTER latex_encode;

    mydoc = BLOCK %]

\documentclass{article}
\begin{document}
  This is a PDF document generated by 
  LaTeX and the Template Toolkit, with some 
  interpolated data: [% mystr %]
\end{document}

[%  END;

    mydoc FILTER latex("pdf");

    # eat all whitespace 

 -%]

DESCRIPTION

This plugin allows you to use LaTeX to generate PDF, PostScript and DVI output files from the Template Toolkit.

The latex filter was distributed as part of the core Template Toolkit until version 2.15 released in May 2006 when it was moved into the separate Template-Latex distribution. It should now be loaded as a plugin to enable the latex filter:

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.

TO BE EXPANDED.

OLD DOCUMENTATION

[% USE Latex -%]
[% FILTER latex %]
...LaTeX document...
[% END %]

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') %]

With the plugin loaded and a default format defined, you can now use the latex filter.

[% FILTER latex -%]
\documentclass{article}
\begin{document}
This is a PDF document generated by 
Latex and the Template Toolkit.
\end{document}
[% END %]

You can pass additional arguments when you invoke the filter to specify the output format.

[% FILTER latex(format='pdf') -%]
   ...LaTeX document...
[% END %]

The template content between the FILTER and END directives will be piped to the appropriate program(s) to generate the document output. This is fine if you're generating a document directly from a template. For example:

example.pdf:

[% USE Latex(format='pdf') -%]
[% FILTER latex %]
...LaTeX document...
[% END -%]

The output will be a binary format PDF, PostScript or DVI file. You should be careful not to prepend or append any extraneous characters or text outside the FILTER block as this text will be included in the file output. Notice in the above example how we use the post-chomp flags ('-') at the end of the USE and END directives to remove the trailing newline characters.

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 %]

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 explicity specify an output format then the filename extension (e.g. 'pdf' in the above example) will be used to determine the correct format.

DEPENDENCIES

BUGS AND LIMITATIONS

The paths to the latex, pdflatex and dvips should be pre-defined as part of the installation process (i.e. when you run perl Makefile.PL). You can specify alternate values as configuration options to the Template constructor in the Perl inteface, but there are no option to specify these paths in template code as this

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.

LICENSE AND COPYRIGHT

Copyright (C) 2006-2007 Andrew Ford. All Rights Reserved.

Copyright (C) 1996-2006 Andy Wardley. 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, LaTeX::Driver, LaTeX::Table