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

Template-Plugin-Latex documentation Contained in the Template-Plugin-Latex distribution.

Index

Code Index:

NAME

Top

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

VERSION

Top

This documentation refers to Template::Plugin::Latex version 3.02.

SYNOPSIS

Top

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

Top

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 explicity 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

Top

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

Top

Most failures result from invalid LaTeX input and are propogated 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

Top

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

Top

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

BUGS AND LIMITATIONS

Top

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

Top

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

Top

Copyright (C) 2006-2009 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

Top

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

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

Template-Plugin-Latex documentation Contained in the Template-Plugin-Latex distribution. 
#============================================================= -*-perl-*-
#
# Template::Plugin::Latex
#
# $Id:$
#
# DESCRIPTION
#   Template Toolkit plugin for Latex
#
# AUTHOR
#   Andrew Ford    <a.ford@ford-mason.co.uk>  (current maintainer)
#   Andy Wardley   <abw@wardley.org>          (original author)
#
# 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.
#
# HISTORY
#   * Originally written by Craig Barratt, Apr 28 2001.
#   * Win32 additions by Richard Tietjen.
#   * Extracted into a separate Template::Plugin::Latex module by 
#     Andy Wardley, 27 May 2006
#   * Removed the program pathname options on the FILTER call
#     Andrew Ford, 05 June 2006
#   * Totally rewritten by Andrew Ford September 2007
#   * Version 3.00 released March 2009
#
#========================================================================

package Template::Plugin::Latex;

use strict;
use warnings;
use base 'Template::Plugin';

use File::Spec;
use LaTeX::Driver 0.07;
use LaTeX::Encode;
use LaTeX::Table;


our $VERSION = 3.02;           # Update "=head1 VERSION" below!!!!
our $DEBUG; $DEBUG = 0 unless defined $DEBUG;
our $ERROR   = '';
our $FILTER  = 'latex';
our $THROW   = 'latex';        # exception type

#------------------------------------------------------------------------
# constructor
#
#------------------------------------------------------------------------

sub new {
    my ($class, $context, $options) = @_;

    # make sure that $options is a hash ref
    $options ||= {};

    # create a closure to generate filters with additional options
    my $filter_factory = sub {
        my $factory_context = shift;
        my $filter_opts = ref $_[-1] eq 'HASH' ? pop : { };
        my $filter_args = [ @_ ];
        @$filter_opts{ keys %$options } = values %$options;
        return sub {
            # Template::Plugin::Latex::_filter->run($context, $filter_opts, $filter_args, @_);
            _tt_latex_filter($class, $factory_context, $filter_opts, $filter_args, @_);
        };
    };

    # create a closure to generate filters with additional options
    my $encode_filter_factory = sub {
        my $factory_context = shift;
        my $filter_opts = ref $_[-1] eq 'HASH' ? pop : { };
        my $filter_args = [ @_ ];
        @$filter_opts{ keys %$options } = values %$options;
        return sub {
            # Template::Plugin::Latex::_filter->run($context, $filter_opts, $filter_args, @_);
            _tt_latex_encode_filter($class, $factory_context, $filter_opts, $filter_args, @_);
        };
    };

    # and a closure to represent the plugin
    my $plugin = sub {
        my $plugopt = ref $_[-1] eq 'HASH' ? pop : { };
        @$plugopt{ keys %$options } = values %$options;
        # Template::Plugin::Latex::_filter->run($context, $plugopt, @_ );
        _tt_latex_filter($class, $context, $plugopt, {}, @_ );
    };


    # now define the filter and return the plugin
    $context->define_filter('latex_encode', [ $encode_filter_factory => 1 ]);
    $context->define_filter($options->{filter} || $FILTER, [ $filter_factory => 1 ]);

    return bless $plugin, $class;
}


#------------------------------------------------------------------------
# _tt_latex_encode_filter
#
#
#------------------------------------------------------------------------

sub _tt_latex_encode_filter {
    my ($class, $context, $options, $filter_args, @text) = @_;
    my $text = join('', @text);
    return latex_encode($text, %{$options});
}


#------------------------------------------------------------------------
# _tt_latex_filter
#
#
#------------------------------------------------------------------------

sub _tt_latex_filter {
    my ($class, $context, $options, $filter_args, @text) = @_;
    my $text = join('', @text);

    # Get the output and format options

#    my $output = $options->{output};
    my $output = delete $options->{ output } || shift(@$filter_args) || '';
    my $format = $options->{format};

    # If the output is just a format specifier then set the format to
    # that and undef the output

    if ($output =~ /^ (?: dvi | ps | pdf(?:\(\w+\))? ) $/x) {
        ($format, $output) = ($output, undef);
    }

    # If the output is a filename then convert to a full pathname in
    # the OUTPUT_PATH directory, outherwise set the output to a
    # reference to a temporary variable.

    if ($output) {
        my $path = $context->config->{ OUTPUT_PATH }
            or $class->_throw('OUTPUT_PATH is not set');
        $output = File::Spec->catfile($path, $output);
    }
    else {
        my $temp;
        $output = \$temp;
    }

    # Run the formatter

    eval {
        my $drv = LaTeX::Driver->new( source    => \$text,
                                      output    => $output,
                                      format    => $format,
                                      maxruns   => $options->{maxruns},
                                      extraruns => $options->{extraruns},
                                      texinputs => _setup_texinput_paths($context),
                                    );
        $drv->run;
    };
    if (my $e = LaTeX::Driver::Exception->caught()) {
        $class->_throw("$e");
    }

    # Return the text if it was output to a scalar variable, otherwise
    # return nothing.

    return ref $output ? $$output : '';
}


#------------------------------------------------------------------------
# $self->setup_texinput_paths
#
# setup the TEXINPUT path environment variables
#------------------------------------------------------------------------

sub _setup_texinput_paths {
    my ($context) = @_;
    my $template_name = $context->stash->get('template.name');
    my $include_path  = $context->config->{INCLUDE_PATH} || [];
    $include_path = [ $include_path ] unless ref $include_path;

    my @texinput_paths = ("");
    foreach my $path (@$include_path) {
        my $template_path = File::Spec->catfile($path, $template_name);
        if (-f $template_path) {
            my($volume, $dir) = File::Spec->splitpath($template_path);
            $dir = File::Spec->catfile($volume, $dir);
            unshift @texinput_paths, $dir;
            next if $dir eq $path;
        }
        push @texinput_paths, $path;
    }
    return  \@texinput_paths;
}


sub _throw {
    my $self = shift;
    die Template::Exception->new( $THROW => join('', @_) );
}


sub table {
    my $args  = ref($_[-1]) eq 'HASH' ? pop(@_) : { };
    my ($table, $text);
    eval {
        $table = LaTeX::Table->new($args);
        $text  = $table->generate_string;
    };
    if ($@) {
        die Template::Exception->new( $THROW => $@ );
    }
    return $text;
}


1;

__END__



# Local Variables:
# mode: perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4: