line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
#============================================================= -*-perl-*- |
2
|
|
|
|
|
|
|
# |
3
|
|
|
|
|
|
|
# Template::Plugin::Latex |
4
|
|
|
|
|
|
|
# |
5
|
|
|
|
|
|
|
# $Id:$ |
6
|
|
|
|
|
|
|
# |
7
|
|
|
|
|
|
|
# DESCRIPTION |
8
|
|
|
|
|
|
|
# Template Toolkit plugin for Latex |
9
|
|
|
|
|
|
|
# |
10
|
|
|
|
|
|
|
# AUTHOR |
11
|
|
|
|
|
|
|
# Chris Travers <chris.travers@gmail.com> (Current Maintainer) |
12
|
|
|
|
|
|
|
# Andrew Ford <a.ford@ford-mason.co.uk> |
13
|
|
|
|
|
|
|
# Andy Wardley <abw@wardley.org> |
14
|
|
|
|
|
|
|
# |
15
|
|
|
|
|
|
|
# COPYRIGHT |
16
|
|
|
|
|
|
|
# Copyright (C) 2014-2016 Chris Travers. All Rights Reserved. |
17
|
|
|
|
|
|
|
# Copyright (C) 2006-2014 Andrew Ford. All Rights Reserved. |
18
|
|
|
|
|
|
|
# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved. |
19
|
|
|
|
|
|
|
# |
20
|
|
|
|
|
|
|
# This module is free software; you can redistribute it and/or |
21
|
|
|
|
|
|
|
# modify it under the same terms as Perl itself. |
22
|
|
|
|
|
|
|
# |
23
|
|
|
|
|
|
|
# HISTORY |
24
|
|
|
|
|
|
|
# * Originally written by Craig Barratt, Apr 28 2001. |
25
|
|
|
|
|
|
|
# * Win32 additions by Richard Tietjen. |
26
|
|
|
|
|
|
|
# * Extracted into a separate Template::Plugin::Latex module by |
27
|
|
|
|
|
|
|
# Andy Wardley, 27 May 2006 |
28
|
|
|
|
|
|
|
# * Removed the program pathname options on the FILTER call |
29
|
|
|
|
|
|
|
# Andrew Ford, 05 June 2006 |
30
|
|
|
|
|
|
|
# * Totally rewritten by Andrew Ford September 2007 |
31
|
|
|
|
|
|
|
# * Version 3.00 released March 2009 |
32
|
|
|
|
|
|
|
# |
33
|
|
|
|
|
|
|
#======================================================================== |
34
|
|
|
|
|
|
|
|
35
|
|
|
|
|
|
|
package Template::Plugin::Latex; |
36
|
|
|
|
|
|
|
|
37
|
4
|
|
|
4
|
|
58769
|
use strict; |
|
4
|
|
|
|
|
5
|
|
|
4
|
|
|
|
|
100
|
|
38
|
4
|
|
|
4
|
|
12
|
use warnings; |
|
4
|
|
|
|
|
6
|
|
|
4
|
|
|
|
|
86
|
|
39
|
4
|
|
|
4
|
|
12
|
use base 'Template::Plugin'; |
|
4
|
|
|
|
|
4
|
|
|
4
|
|
|
|
|
1655
|
|
40
|
|
|
|
|
|
|
|
41
|
4
|
|
|
4
|
|
1866
|
use File::Spec; |
|
4
|
|
|
|
|
4
|
|
|
4
|
|
|
|
|
84
|
|
42
|
4
|
|
|
4
|
|
2228
|
use LaTeX::Driver 0.07; |
|
0
|
|
|
|
|
|
|
|
0
|
|
|
|
|
|
|
43
|
|
|
|
|
|
|
use LaTeX::Encode; |
44
|
|
|
|
|
|
|
use LaTeX::Table; |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
|
47
|
|
|
|
|
|
|
our $VERSION = '3.11'; # Update "=head1 VERSION" below!!!! |
48
|
|
|
|
|
|
|
our $DEBUG; $DEBUG = 0 unless defined $DEBUG; |
49
|
|
|
|
|
|
|
our $ERROR = ''; |
50
|
|
|
|
|
|
|
our $FILTER = 'latex'; |
51
|
|
|
|
|
|
|
our $THROW = 'latex'; # exception type |
52
|
|
|
|
|
|
|
|
53
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
54
|
|
|
|
|
|
|
# constructor |
55
|
|
|
|
|
|
|
# |
56
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
57
|
|
|
|
|
|
|
|
58
|
|
|
|
|
|
|
sub new { |
59
|
|
|
|
|
|
|
my ($class, $context, $options) = @_; |
60
|
|
|
|
|
|
|
|
61
|
|
|
|
|
|
|
# make sure that $options is a hash ref |
62
|
|
|
|
|
|
|
$options ||= {}; |
63
|
|
|
|
|
|
|
|
64
|
|
|
|
|
|
|
# create a closure to generate filters with additional options |
65
|
|
|
|
|
|
|
my $filter_factory = sub { |
66
|
|
|
|
|
|
|
my $factory_context = shift; |
67
|
|
|
|
|
|
|
my $filter_opts = ref $_[-1] eq 'HASH' ? pop : { }; |
68
|
|
|
|
|
|
|
my $filter_args = [ @_ ]; |
69
|
|
|
|
|
|
|
$filter_opts->{$_} //= $options->{$_} for keys %$options; |
70
|
|
|
|
|
|
|
return sub { |
71
|
|
|
|
|
|
|
# Template::Plugin::Latex::_filter->run($context, $filter_opts, $filter_args, @_); |
72
|
|
|
|
|
|
|
_tt_latex_filter($class, $factory_context, $filter_opts, $filter_args, @_); |
73
|
|
|
|
|
|
|
}; |
74
|
|
|
|
|
|
|
}; |
75
|
|
|
|
|
|
|
|
76
|
|
|
|
|
|
|
# create a closure to generate filters with additional options |
77
|
|
|
|
|
|
|
my $encode_filter_factory = sub { |
78
|
|
|
|
|
|
|
my $factory_context = shift; |
79
|
|
|
|
|
|
|
my $filter_opts = ref $_[-1] eq 'HASH' ? pop : { }; |
80
|
|
|
|
|
|
|
my $filter_args = [ @_ ]; |
81
|
|
|
|
|
|
|
$filter_opts->{$_} //= $options->{$_} for keys %$options; |
82
|
|
|
|
|
|
|
return sub { |
83
|
|
|
|
|
|
|
# Template::Plugin::Latex::_filter->run($context, $filter_opts, $filter_args, @_); |
84
|
|
|
|
|
|
|
_tt_latex_encode_filter($class, $factory_context, $filter_opts, $filter_args, @_); |
85
|
|
|
|
|
|
|
}; |
86
|
|
|
|
|
|
|
}; |
87
|
|
|
|
|
|
|
|
88
|
|
|
|
|
|
|
# and a closure to represent the plugin |
89
|
|
|
|
|
|
|
my $plugin = sub { |
90
|
|
|
|
|
|
|
my $plugopt = ref $_[-1] eq 'HASH' ? pop : { }; |
91
|
|
|
|
|
|
|
$plugopt->{$_} //= $options->{$_} for keys %$options; |
92
|
|
|
|
|
|
|
# Template::Plugin::Latex::_filter->run($context, $plugopt, @_ ); |
93
|
|
|
|
|
|
|
_tt_latex_filter($class, $context, $plugopt, {}, @_ ); |
94
|
|
|
|
|
|
|
}; |
95
|
|
|
|
|
|
|
|
96
|
|
|
|
|
|
|
|
97
|
|
|
|
|
|
|
# now define the filter and return the plugin |
98
|
|
|
|
|
|
|
$context->define_filter('latex_encode', [ $encode_filter_factory => 1 ]); |
99
|
|
|
|
|
|
|
$context->define_filter($options->{filter} || $FILTER, [ $filter_factory => 1 ]); |
100
|
|
|
|
|
|
|
|
101
|
|
|
|
|
|
|
return bless $plugin, $class; |
102
|
|
|
|
|
|
|
} |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
|
105
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
106
|
|
|
|
|
|
|
# _tt_latex_encode_filter |
107
|
|
|
|
|
|
|
# |
108
|
|
|
|
|
|
|
# |
109
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
110
|
|
|
|
|
|
|
|
111
|
|
|
|
|
|
|
sub _tt_latex_encode_filter { |
112
|
|
|
|
|
|
|
my ($class, $context, $options, $filter_args, @text) = @_; |
113
|
|
|
|
|
|
|
my $text = join('', @text); |
114
|
|
|
|
|
|
|
return latex_encode($text, %{$options}); |
115
|
|
|
|
|
|
|
} |
116
|
|
|
|
|
|
|
|
117
|
|
|
|
|
|
|
|
118
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
119
|
|
|
|
|
|
|
# _tt_latex_filter |
120
|
|
|
|
|
|
|
# |
121
|
|
|
|
|
|
|
# |
122
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
123
|
|
|
|
|
|
|
|
124
|
|
|
|
|
|
|
sub _tt_latex_filter { |
125
|
|
|
|
|
|
|
my ($class, $context, $options, $filter_args, @text) = @_; |
126
|
|
|
|
|
|
|
my $text = join('', @text); |
127
|
|
|
|
|
|
|
|
128
|
|
|
|
|
|
|
# Get the output and format options |
129
|
|
|
|
|
|
|
|
130
|
|
|
|
|
|
|
# my $output = $options->{output}; |
131
|
|
|
|
|
|
|
my $output = delete $options->{ output } || shift(@$filter_args) || ''; |
132
|
|
|
|
|
|
|
my $format = $options->{format}; |
133
|
|
|
|
|
|
|
|
134
|
|
|
|
|
|
|
# If the output is just a format specifier then set the format to |
135
|
|
|
|
|
|
|
# that and undef the output |
136
|
|
|
|
|
|
|
|
137
|
|
|
|
|
|
|
if ($output =~ /^ (?: dvi | ps | pdf(?:\(\w+\))? ) $/x) { |
138
|
|
|
|
|
|
|
($format, $output) = ($output, undef); |
139
|
|
|
|
|
|
|
} |
140
|
|
|
|
|
|
|
|
141
|
|
|
|
|
|
|
# If the output is a filename then convert to a full pathname in |
142
|
|
|
|
|
|
|
# the OUTPUT_PATH directory, outherwise set the output to a |
143
|
|
|
|
|
|
|
# reference to a temporary variable. |
144
|
|
|
|
|
|
|
|
145
|
|
|
|
|
|
|
if ($output) { |
146
|
|
|
|
|
|
|
my $path = $context->config->{ OUTPUT_PATH } |
147
|
|
|
|
|
|
|
or $class->_throw('OUTPUT_PATH is not set'); |
148
|
|
|
|
|
|
|
$output = File::Spec->catfile($path, $output); |
149
|
|
|
|
|
|
|
} |
150
|
|
|
|
|
|
|
else { |
151
|
|
|
|
|
|
|
my $temp; |
152
|
|
|
|
|
|
|
$output = \$temp; |
153
|
|
|
|
|
|
|
} |
154
|
|
|
|
|
|
|
|
155
|
|
|
|
|
|
|
# Run the formatter |
156
|
|
|
|
|
|
|
|
157
|
|
|
|
|
|
|
eval { |
158
|
|
|
|
|
|
|
my $drv = LaTeX::Driver->new( source => \$text, |
159
|
|
|
|
|
|
|
output => $output, |
160
|
|
|
|
|
|
|
format => $format, |
161
|
|
|
|
|
|
|
maxruns => $options->{maxruns}, |
162
|
|
|
|
|
|
|
extraruns => $options->{extraruns}, |
163
|
|
|
|
|
|
|
texinputs => _setup_texinput_paths($context), |
164
|
|
|
|
|
|
|
); |
165
|
|
|
|
|
|
|
$drv->run; |
166
|
|
|
|
|
|
|
}; |
167
|
|
|
|
|
|
|
if (my $e = LaTeX::Driver::Exception->caught()) { |
168
|
|
|
|
|
|
|
$class->_throw("$e"); |
169
|
|
|
|
|
|
|
} |
170
|
|
|
|
|
|
|
|
171
|
|
|
|
|
|
|
# Return the text if it was output to a scalar variable, otherwise |
172
|
|
|
|
|
|
|
# return nothing. |
173
|
|
|
|
|
|
|
|
174
|
|
|
|
|
|
|
return ref $output ? $$output : ''; |
175
|
|
|
|
|
|
|
} |
176
|
|
|
|
|
|
|
|
177
|
|
|
|
|
|
|
|
178
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
179
|
|
|
|
|
|
|
# $self->setup_texinput_paths |
180
|
|
|
|
|
|
|
# |
181
|
|
|
|
|
|
|
# setup the TEXINPUT path environment variables |
182
|
|
|
|
|
|
|
#------------------------------------------------------------------------ |
183
|
|
|
|
|
|
|
|
184
|
|
|
|
|
|
|
sub _setup_texinput_paths { |
185
|
|
|
|
|
|
|
my ($context) = @_; |
186
|
|
|
|
|
|
|
my $template_name = $context->stash->get('template.name'); |
187
|
|
|
|
|
|
|
my $include_path = []; |
188
|
|
|
|
|
|
|
|
189
|
|
|
|
|
|
|
# Ask each Template::Provider object for a list of paths. This properly |
190
|
|
|
|
|
|
|
# handles coderefs and objects in INCLUDE_PATH. |
191
|
|
|
|
|
|
|
for my $provider (@{ $context->{LOAD_TEMPLATES} }) { |
192
|
|
|
|
|
|
|
push @$include_path, @{ $provider->paths || [] }; |
193
|
|
|
|
|
|
|
} |
194
|
|
|
|
|
|
|
|
195
|
|
|
|
|
|
|
my @texinput_paths = (""); |
196
|
|
|
|
|
|
|
foreach my $path (@$include_path) { |
197
|
|
|
|
|
|
|
my $template_path = File::Spec->catfile($path, $template_name); |
198
|
|
|
|
|
|
|
if (-f $template_path) { |
199
|
|
|
|
|
|
|
my($volume, $dir) = File::Spec->splitpath($template_path); |
200
|
|
|
|
|
|
|
$dir = File::Spec->catfile($volume, $dir); |
201
|
|
|
|
|
|
|
unshift @texinput_paths, $dir; |
202
|
|
|
|
|
|
|
next if $dir eq $path; |
203
|
|
|
|
|
|
|
} |
204
|
|
|
|
|
|
|
push @texinput_paths, $path; |
205
|
|
|
|
|
|
|
} |
206
|
|
|
|
|
|
|
return \@texinput_paths; |
207
|
|
|
|
|
|
|
} |
208
|
|
|
|
|
|
|
|
209
|
|
|
|
|
|
|
|
210
|
|
|
|
|
|
|
sub _throw { |
211
|
|
|
|
|
|
|
my $self = shift; |
212
|
|
|
|
|
|
|
die Template::Exception->new( $THROW => join('', @_) ); |
213
|
|
|
|
|
|
|
} |
214
|
|
|
|
|
|
|
|
215
|
|
|
|
|
|
|
|
216
|
|
|
|
|
|
|
sub table { |
217
|
|
|
|
|
|
|
my $args = ref($_[-1]) eq 'HASH' ? pop(@_) : { }; |
218
|
|
|
|
|
|
|
my ($table, $text); |
219
|
|
|
|
|
|
|
eval { |
220
|
|
|
|
|
|
|
$table = LaTeX::Table->new($args); |
221
|
|
|
|
|
|
|
$text = $table->generate_string; |
222
|
|
|
|
|
|
|
}; |
223
|
|
|
|
|
|
|
if ($@) { |
224
|
|
|
|
|
|
|
die Template::Exception->new( $THROW => $@ ); |
225
|
|
|
|
|
|
|
} |
226
|
|
|
|
|
|
|
return $text; |
227
|
|
|
|
|
|
|
} |
228
|
|
|
|
|
|
|
|
229
|
|
|
|
|
|
|
|
230
|
|
|
|
|
|
|
1; |
231
|
|
|
|
|
|
|
|
232
|
|
|
|
|
|
|
__END__ |
233
|
|
|
|
|
|
|
|
234
|
|
|
|
|
|
|
=head1 NAME |
235
|
|
|
|
|
|
|
|
236
|
|
|
|
|
|
|
Template::Plugin::Latex - Template Toolkit plugin for Latex |
237
|
|
|
|
|
|
|
|
238
|
|
|
|
|
|
|
=head1 VERSION |
239
|
|
|
|
|
|
|
|
240
|
|
|
|
|
|
|
This documentation refers to C<Template::Plugin::Latex> version 3.11 |
241
|
|
|
|
|
|
|
|
242
|
|
|
|
|
|
|
=head1 SYNOPSIS |
243
|
|
|
|
|
|
|
|
244
|
|
|
|
|
|
|
Sample Template Toolkit code: |
245
|
|
|
|
|
|
|
|
246
|
|
|
|
|
|
|
[%- USE Latex; |
247
|
|
|
|
|
|
|
|
248
|
|
|
|
|
|
|
mystr = "a, b & c" | latex_encode; |
249
|
|
|
|
|
|
|
|
250
|
|
|
|
|
|
|
FILTER latex("pdf"); -%] |
251
|
|
|
|
|
|
|
|
252
|
|
|
|
|
|
|
\documentclass{article} |
253
|
|
|
|
|
|
|
\begin{document} |
254
|
|
|
|
|
|
|
This is a PDF document generated by |
255
|
|
|
|
|
|
|
LaTeX and the Template Toolkit, with some |
256
|
|
|
|
|
|
|
interpolated data: [% mystr %] |
257
|
|
|
|
|
|
|
\end{document} |
258
|
|
|
|
|
|
|
|
259
|
|
|
|
|
|
|
[% END; -%] |
260
|
|
|
|
|
|
|
|
261
|
|
|
|
|
|
|
|
262
|
|
|
|
|
|
|
=head1 DESCRIPTION |
263
|
|
|
|
|
|
|
|
264
|
|
|
|
|
|
|
The C<Latex> Template Toolkit plugin provides a C<latex> filter that |
265
|
|
|
|
|
|
|
allows the use of LaTeX to generate PDF, PostScript and DVI output files |
266
|
|
|
|
|
|
|
from the Template Toolkit. The plugin uses L<LaTeX::Driver> to run the |
267
|
|
|
|
|
|
|
various LaTeX programs. |
268
|
|
|
|
|
|
|
|
269
|
|
|
|
|
|
|
Processing of the LaTeX document takes place in a temporary directory |
270
|
|
|
|
|
|
|
that is deleted once processing is complete. The standard LaTeX |
271
|
|
|
|
|
|
|
programs (C<latex> or C<pdflatex>, C<bibtex> and C<makeindex>) are run |
272
|
|
|
|
|
|
|
and re-run as necessary until all references, indexes, bibliographies, |
273
|
|
|
|
|
|
|
table of contents, and lists of figures and tables are stable or it is |
274
|
|
|
|
|
|
|
apparent that they will not stabilize. The format converters C<dvips>, |
275
|
|
|
|
|
|
|
C<dvipdf>, C<ps2pdf> and C<pdf2ps> are run as necessary to convert the |
276
|
|
|
|
|
|
|
output document to the requested format. The C<TEXINPUTS> environment |
277
|
|
|
|
|
|
|
variable is set up to include the template directory and the C<INCLUDES> |
278
|
|
|
|
|
|
|
directories, so that LaTeX file inclusion commands should find the |
279
|
|
|
|
|
|
|
intended files. |
280
|
|
|
|
|
|
|
|
281
|
|
|
|
|
|
|
The output of the filter is binary data (although PDF and PostScript are |
282
|
|
|
|
|
|
|
not stictly binary). You should be careful not to prepend or append any |
283
|
|
|
|
|
|
|
extraneous characters (even space characters) or text outside the FILTER |
284
|
|
|
|
|
|
|
block as this text will be included in the file output. Notice in the |
285
|
|
|
|
|
|
|
example below how we use the post-chomp flags ('-') at the end of the |
286
|
|
|
|
|
|
|
C<USE> and C<END> directives to remove the trailing newline characters: |
287
|
|
|
|
|
|
|
|
288
|
|
|
|
|
|
|
[% USE Latex(format='pdf') -%] |
289
|
|
|
|
|
|
|
[% FILTER latex %] |
290
|
|
|
|
|
|
|
...LaTeX document... |
291
|
|
|
|
|
|
|
[% END -%] |
292
|
|
|
|
|
|
|
|
293
|
|
|
|
|
|
|
If you're redirecting the output to a file via the third argument of |
294
|
|
|
|
|
|
|
the Template module's C<process()> method then you should also pass |
295
|
|
|
|
|
|
|
the C<binmode> parameter, set to a true value to indicate that it is a |
296
|
|
|
|
|
|
|
binary file. |
297
|
|
|
|
|
|
|
|
298
|
|
|
|
|
|
|
use Template; |
299
|
|
|
|
|
|
|
|
300
|
|
|
|
|
|
|
my $tt = Template->new({ |
301
|
|
|
|
|
|
|
INCLUDE_PATH => '/path/to/templates', |
302
|
|
|
|
|
|
|
OUTPUT_PATH => '/path/to/pdf/output', |
303
|
|
|
|
|
|
|
}); |
304
|
|
|
|
|
|
|
my $vars = { |
305
|
|
|
|
|
|
|
title => 'Hello World', |
306
|
|
|
|
|
|
|
} |
307
|
|
|
|
|
|
|
$tt->process('example.tt2', $vars, 'example.pdf', binmode => 1) |
308
|
|
|
|
|
|
|
|| die $tt->error(); |
309
|
|
|
|
|
|
|
|
310
|
|
|
|
|
|
|
If you want to capture the output to a template variable, you can do |
311
|
|
|
|
|
|
|
so like this: |
312
|
|
|
|
|
|
|
|
313
|
|
|
|
|
|
|
[% output = FILTER latex %] |
314
|
|
|
|
|
|
|
...LaTeX document... |
315
|
|
|
|
|
|
|
[% END %] |
316
|
|
|
|
|
|
|
|
317
|
|
|
|
|
|
|
You can pass additional arguments when you invoke the filter, for |
318
|
|
|
|
|
|
|
example to specify the output format. |
319
|
|
|
|
|
|
|
|
320
|
|
|
|
|
|
|
[% FILTER latex(format='pdf') -%] |
321
|
|
|
|
|
|
|
...LaTeX document... |
322
|
|
|
|
|
|
|
[% END %] |
323
|
|
|
|
|
|
|
|
324
|
|
|
|
|
|
|
If you want to write the output to a file then you can specify an |
325
|
|
|
|
|
|
|
C<output> parameter. |
326
|
|
|
|
|
|
|
|
327
|
|
|
|
|
|
|
[% FILTER latex(output='example.pdf') %] |
328
|
|
|
|
|
|
|
...LaTeX document... |
329
|
|
|
|
|
|
|
[% END %] |
330
|
|
|
|
|
|
|
|
331
|
|
|
|
|
|
|
If you don't explicitly specify an output format then the filename |
332
|
|
|
|
|
|
|
extension (e.g. 'pdf' in the above example) will be used to determine |
333
|
|
|
|
|
|
|
the correct format. |
334
|
|
|
|
|
|
|
|
335
|
|
|
|
|
|
|
You can specify a different filter name using the C<filter> parameter. |
336
|
|
|
|
|
|
|
|
337
|
|
|
|
|
|
|
[% USE Latex(filter='pdf') -%] |
338
|
|
|
|
|
|
|
[% FILTER pdf %] |
339
|
|
|
|
|
|
|
...LaTeX document... |
340
|
|
|
|
|
|
|
[% END %] |
341
|
|
|
|
|
|
|
|
342
|
|
|
|
|
|
|
You can also specify the default output format. This value can be |
343
|
|
|
|
|
|
|
C<latex>, C<pdf> or C<dvi>. |
344
|
|
|
|
|
|
|
|
345
|
|
|
|
|
|
|
[% USE Latex(format='pdf') %] |
346
|
|
|
|
|
|
|
|
347
|
|
|
|
|
|
|
|
348
|
|
|
|
|
|
|
Note: the C<LaTeX::Driver> distribution includes three filter programs |
349
|
|
|
|
|
|
|
(C<latex2dvi>, C<latex2pdf> and C<latex2ps>) that use the |
350
|
|
|
|
|
|
|
C<LaTeX::Driver> package to process LaTeX source data into DVI, PDF or |
351
|
|
|
|
|
|
|
PostScript file respectively. These programs have a C<-tt2> option to |
352
|
|
|
|
|
|
|
run their input through the Template Toolkit before processing as LaTeX |
353
|
|
|
|
|
|
|
source. The programs do not use the C<Latex> plugin unless the template |
354
|
|
|
|
|
|
|
requests it, but they may provide an alternative way of processing |
355
|
|
|
|
|
|
|
Template Toolkit templates to generate typeset output. |
356
|
|
|
|
|
|
|
|
357
|
|
|
|
|
|
|
|
358
|
|
|
|
|
|
|
=head1 SUBROUTINES/METHODS |
359
|
|
|
|
|
|
|
|
360
|
|
|
|
|
|
|
=head2 C<USE Latex(options)> |
361
|
|
|
|
|
|
|
|
362
|
|
|
|
|
|
|
This statement loads the plugin (note that prior to version 2.15 the |
363
|
|
|
|
|
|
|
filter was built in to Template Toolkit so this statement was |
364
|
|
|
|
|
|
|
unnecessary; it is now required). |
365
|
|
|
|
|
|
|
|
366
|
|
|
|
|
|
|
|
367
|
|
|
|
|
|
|
=head2 The C<latex> Filter |
368
|
|
|
|
|
|
|
|
369
|
|
|
|
|
|
|
The C<latex> filter accepts a number of options, which may be |
370
|
|
|
|
|
|
|
specified on the USE statement or on the filter invocation. |
371
|
|
|
|
|
|
|
|
372
|
|
|
|
|
|
|
=over 4 |
373
|
|
|
|
|
|
|
|
374
|
|
|
|
|
|
|
=item C<format> |
375
|
|
|
|
|
|
|
|
376
|
|
|
|
|
|
|
specifies the format of the output; one of C<dvi> (TeX device |
377
|
|
|
|
|
|
|
independent format), C<ps> (PostScript) or C<pdf> (Adobe Portable |
378
|
|
|
|
|
|
|
Document Format). The follow special values are also accepted: |
379
|
|
|
|
|
|
|
C<pdf(ps)> (generates PDF via PostScript, using C<dvips> and |
380
|
|
|
|
|
|
|
C<ps2pdf>), C<pdf(dvi)> (generates PDF via dvi, using C<dvipdfm>) |
381
|
|
|
|
|
|
|
|
382
|
|
|
|
|
|
|
=item C<output> |
383
|
|
|
|
|
|
|
|
384
|
|
|
|
|
|
|
the name of the output file, or just the output format |
385
|
|
|
|
|
|
|
|
386
|
|
|
|
|
|
|
=item C<indexstyle> |
387
|
|
|
|
|
|
|
|
388
|
|
|
|
|
|
|
the name of the C<makeindex> style file to use (this is passed with |
389
|
|
|
|
|
|
|
the C<-s> option to C<makeindex>) |
390
|
|
|
|
|
|
|
|
391
|
|
|
|
|
|
|
=item C<indexoptions> |
392
|
|
|
|
|
|
|
|
393
|
|
|
|
|
|
|
options to be passed to C<makeindex>. Useful options are C<-l> for |
394
|
|
|
|
|
|
|
letter ordering of index terms (rather than the default word |
395
|
|
|
|
|
|
|
ordering), C<-r> to disable implicit page range formation, and C<-c> |
396
|
|
|
|
|
|
|
to compress intermediate blanks in index keys. Refer to L<makeindex(1)> |
397
|
|
|
|
|
|
|
for full details. |
398
|
|
|
|
|
|
|
|
399
|
|
|
|
|
|
|
=item C<maxruns> |
400
|
|
|
|
|
|
|
|
401
|
|
|
|
|
|
|
The maximum number of runs of the formatter program (defaults to 10). |
402
|
|
|
|
|
|
|
|
403
|
|
|
|
|
|
|
=item C<extraruns> |
404
|
|
|
|
|
|
|
|
405
|
|
|
|
|
|
|
The number of additional runs of the formatter program after it seems |
406
|
|
|
|
|
|
|
that the formatting of the document has stabilized (default 0). Note |
407
|
|
|
|
|
|
|
that the setting of C<maxruns> takes precedence, so if C<maxruns> is |
408
|
|
|
|
|
|
|
set to 10 and C<extraruns> is set to 3, and formatting stabilizes |
409
|
|
|
|
|
|
|
after 8 runs then only 2 extra runs will be performed. |
410
|
|
|
|
|
|
|
|
411
|
|
|
|
|
|
|
=back |
412
|
|
|
|
|
|
|
|
413
|
|
|
|
|
|
|
|
414
|
|
|
|
|
|
|
=head2 The C<latex_encode> filter |
415
|
|
|
|
|
|
|
|
416
|
|
|
|
|
|
|
The C<latex_encode> filter encodes LaTeX special characters in its |
417
|
|
|
|
|
|
|
input into their LaTeX encoded representations. It also encodes other characters that have |
418
|
|
|
|
|
|
|
|
419
|
|
|
|
|
|
|
The special characters are: C<\> (command character), C<{> (open |
420
|
|
|
|
|
|
|
group), C<}> (end group), C<&> (table column separator), C<#> |
421
|
|
|
|
|
|
|
(parameter specifier), C<%> (comment character), C<_> (subscript), |
422
|
|
|
|
|
|
|
C<^> (superscript), C<~> (non-breakable space), C<$> (mathematics mode). |
423
|
|
|
|
|
|
|
|
424
|
|
|
|
|
|
|
|
425
|
|
|
|
|
|
|
=over 4 |
426
|
|
|
|
|
|
|
|
427
|
|
|
|
|
|
|
=item C<except> |
428
|
|
|
|
|
|
|
|
429
|
|
|
|
|
|
|
Lists the characters that should be excluded from encoding. By |
430
|
|
|
|
|
|
|
default no special characters are excluded, but it may be useful to |
431
|
|
|
|
|
|
|
specify C<except = "\\{}"> to allow the input string to contain LaTeX |
432
|
|
|
|
|
|
|
commands such as C<"this is \textbf{bold} text">. |
433
|
|
|
|
|
|
|
|
434
|
|
|
|
|
|
|
=item C<use_textcomp> |
435
|
|
|
|
|
|
|
|
436
|
|
|
|
|
|
|
By default the C<latex_encode> filter will encode characters with the |
437
|
|
|
|
|
|
|
encodings provided by the C<textcomp> LaTeX package (for example the |
438
|
|
|
|
|
|
|
Pounds Sterling symbol is encoded as C<\textsterling{}>). Setting |
439
|
|
|
|
|
|
|
C<use_textcomp = 0> turns off these encodings. |
440
|
|
|
|
|
|
|
|
441
|
|
|
|
|
|
|
=back |
442
|
|
|
|
|
|
|
|
443
|
|
|
|
|
|
|
=head2 C<table()> |
444
|
|
|
|
|
|
|
|
445
|
|
|
|
|
|
|
The C<table()> function provides an interface to the C<LaTeX::Table> module. |
446
|
|
|
|
|
|
|
|
447
|
|
|
|
|
|
|
The following example shows how a simple table can be set up. |
448
|
|
|
|
|
|
|
|
449
|
|
|
|
|
|
|
[%- USE Latex; |
450
|
|
|
|
|
|
|
|
451
|
|
|
|
|
|
|
data = [ [ 'London', 'United Kingdom' ], |
452
|
|
|
|
|
|
|
[ 'Berlin', 'Germany' ], |
453
|
|
|
|
|
|
|
[ 'Paris', 'France' ], |
454
|
|
|
|
|
|
|
[ 'Washington', 'USA' ] ] ); |
455
|
|
|
|
|
|
|
|
456
|
|
|
|
|
|
|
text = Latex.table( caption = 'Capitol Cities', |
457
|
|
|
|
|
|
|
label = 'table:capitols', |
458
|
|
|
|
|
|
|
headings = [ [ 'City', 'Country' ] ], |
459
|
|
|
|
|
|
|
data = data ); |
460
|
|
|
|
|
|
|
-%] |
461
|
|
|
|
|
|
|
|
462
|
|
|
|
|
|
|
The variable C<text> will hold the LaTeX commands to typeset the table |
463
|
|
|
|
|
|
|
and can be further interpolated into a LaTeX document template. |
464
|
|
|
|
|
|
|
|
465
|
|
|
|
|
|
|
=head1 DIAGNOSTICS |
466
|
|
|
|
|
|
|
|
467
|
|
|
|
|
|
|
Most failures result from invalid LaTeX input and are propagated up from |
468
|
|
|
|
|
|
|
L<LaTeX::Driver>, L<LaTeX::Encode> or L<LaTeX::Table>. |
469
|
|
|
|
|
|
|
|
470
|
|
|
|
|
|
|
Failures detected in this module include: |
471
|
|
|
|
|
|
|
|
472
|
|
|
|
|
|
|
=over 4 |
473
|
|
|
|
|
|
|
|
474
|
|
|
|
|
|
|
=item C<OUTPUT_PATH is not set> |
475
|
|
|
|
|
|
|
|
476
|
|
|
|
|
|
|
an output filename was specified but the C<OUTPUT_PATH> configuration |
477
|
|
|
|
|
|
|
option has not been set. |
478
|
|
|
|
|
|
|
|
479
|
|
|
|
|
|
|
=back |
480
|
|
|
|
|
|
|
|
481
|
|
|
|
|
|
|
|
482
|
|
|
|
|
|
|
=head1 DEPENDENCIES |
483
|
|
|
|
|
|
|
|
484
|
|
|
|
|
|
|
=over 4 |
485
|
|
|
|
|
|
|
|
486
|
|
|
|
|
|
|
=item L<Template> |
487
|
|
|
|
|
|
|
|
488
|
|
|
|
|
|
|
The Template Toolkit. |
489
|
|
|
|
|
|
|
|
490
|
|
|
|
|
|
|
=item L<LaTeX::Driver> |
491
|
|
|
|
|
|
|
|
492
|
|
|
|
|
|
|
Provides the logic for driving the LaTeX programs. |
493
|
|
|
|
|
|
|
|
494
|
|
|
|
|
|
|
=item L<LaTeX::Encode> |
495
|
|
|
|
|
|
|
|
496
|
|
|
|
|
|
|
Underpins the C<latex_encode> filter. |
497
|
|
|
|
|
|
|
|
498
|
|
|
|
|
|
|
=item L<LaTeX::Table> |
499
|
|
|
|
|
|
|
|
500
|
|
|
|
|
|
|
Underpins the C<table> function. |
501
|
|
|
|
|
|
|
|
502
|
|
|
|
|
|
|
=back |
503
|
|
|
|
|
|
|
|
504
|
|
|
|
|
|
|
|
505
|
|
|
|
|
|
|
=head1 INCOMPATIBILITIES |
506
|
|
|
|
|
|
|
|
507
|
|
|
|
|
|
|
The C<latex> filter was distributed as part of the core |
508
|
|
|
|
|
|
|
Template Toolkit distribution until version 2.15 (released in May 2006), |
509
|
|
|
|
|
|
|
when it was moved into the separate Template-Latex distribution. The |
510
|
|
|
|
|
|
|
C<Latex> plugin must now be explicitly to enable the C<latex> filter. |
511
|
|
|
|
|
|
|
|
512
|
|
|
|
|
|
|
|
513
|
|
|
|
|
|
|
=head1 BUGS AND LIMITATIONS |
514
|
|
|
|
|
|
|
|
515
|
|
|
|
|
|
|
The paths to the F<latex>, F<pdflatex> and F<dvips> should be |
516
|
|
|
|
|
|
|
pre-defined as part of the installation process of L<LaTeX::Driver> |
517
|
|
|
|
|
|
|
(i.e. when you run C<perl Makefile.PL> for that package). Alternative |
518
|
|
|
|
|
|
|
values can be specified from Perl code using the C<program_path> class |
519
|
|
|
|
|
|
|
method from that package, but there are deliberately no options to |
520
|
|
|
|
|
|
|
specify these paths from TT code. |
521
|
|
|
|
|
|
|
|
522
|
|
|
|
|
|
|
|
523
|
|
|
|
|
|
|
=head1 AUTHOR |
524
|
|
|
|
|
|
|
|
525
|
|
|
|
|
|
|
Andrew Ford E<lt>a.ford@ford-mason.co.ukE<gt> (current maintainer) |
526
|
|
|
|
|
|
|
|
527
|
|
|
|
|
|
|
Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> |
528
|
|
|
|
|
|
|
|
529
|
|
|
|
|
|
|
The original Latex plugin on which this is based was written by Craig |
530
|
|
|
|
|
|
|
Barratt with additions for Win32 by Richard Tietjen. The code has |
531
|
|
|
|
|
|
|
subsequently been radically refactored by Andrew Ford. |
532
|
|
|
|
|
|
|
|
533
|
|
|
|
|
|
|
=head1 LICENSE AND COPYRIGHT |
534
|
|
|
|
|
|
|
|
535
|
|
|
|
|
|
|
Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved. |
536
|
|
|
|
|
|
|
Copyright (C) 2006-2014 Andrew Ford. All Rights Reserved. |
537
|
|
|
|
|
|
|
Copyright (C) 2014-2016 Chris Travers. All Rights Reserved. |
538
|
|
|
|
|
|
|
|
539
|
|
|
|
|
|
|
This module is free software; you can redistribute it and/or |
540
|
|
|
|
|
|
|
modify it under the same terms as Perl itself. |
541
|
|
|
|
|
|
|
|
542
|
|
|
|
|
|
|
This software is distributed in the hope that it will be useful, but |
543
|
|
|
|
|
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of |
544
|
|
|
|
|
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
545
|
|
|
|
|
|
|
|
546
|
|
|
|
|
|
|
=head1 SEE ALSO |
547
|
|
|
|
|
|
|
|
548
|
|
|
|
|
|
|
L<Template>, L<LaTeX::Driver>, L<LaTeX::Table>, L<LaTeX::Encode> |
549
|
|
|
|
|
|
|
|
550
|
|
|
|
|
|
|
|
551
|
|
|
|
|
|
|
L<latex2dvi(1)>, L<latex2pdf(1)> and L<latex2ps(1)> (part of the |
552
|
|
|
|
|
|
|
C<LaTeX::Driver> distribution) |
553
|
|
|
|
|
|
|
|
554
|
|
|
|
|
|
|
=cut |
555
|
|
|
|
|
|
|
|
556
|
|
|
|
|
|
|
|
557
|
|
|
|
|
|
|
# Local Variables: |
558
|
|
|
|
|
|
|
# mode: perl |
559
|
|
|
|
|
|
|
# perl-indent-level: 4 |
560
|
|
|
|
|
|
|
# indent-tabs-mode: nil |
561
|
|
|
|
|
|
|
# End: |
562
|
|
|
|
|
|
|
# |
563
|
|
|
|
|
|
|
# vim: expandtab shiftwidth=4: |