1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
|
NAME
LaTeX::Driver - Latex driver
VERSION
1.2.0
SYNOPSIS
use LaTeX::Driver;
$drv = LaTeX::Driver->new( source => \$doc_text,
output => $filename,
format => 'pdf',
%other_params );
$ok = $drv->run;
$stats = $drv->stats;
DESCRIPTION
The LaTeX::Driver module encapsulates the details of invoking the Latex
programs to format a LaTeX document. Formatting with LaTeX is
complicated; there are potentially many programs to run and the output
of those programs must be monitored to determine whether further
processing is required.
This module runs the required commands in the directory specified,
either explicitly with the "dirname" option or implicitly by the
directory part of "basename", or in the current directory. As a result
of the processing up to a dozen or more intermediate files are created.
These will be removed upon object destruction, given the "cleanup"
argument to "new".
SOURCE
Source code can be found at <https://github.com/fordmason/LaTeX-Driver>
Feel free to fork and add your stuff!
SUBROUTINES/METHODS
"new(%params)"
This is the constructor method. It creates a driver object on which
the "run" method is used to format the document specified. The main
arguments are "source" and "output"; the "source" argument is
required to specify the input document; "output" is only mandatory
if "source" is a scalar reference.
The full list of arguments is as follows:
"source"
This parameter is mandatory; it can either specify the name of
the document to be formatted or be a reference to a scalar
containing the document source.
"output"
specifies the output for the formatted document; this may either
be a file name or be a scalar reference. In the latter case the
contents of the formatted document file is copied into the
scalar variable referenced.
"format"
the format of output required: 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").
If not specified then the format is determined from the name of
the output document if specified, or defaults to PDF.
The following list of formats is supported
* dvi
* ps
* postscript
* pdf
* pdf(pdflatex)
* pdf(xelatex)
* pdf(lualatex)
* pdf(dvi)
* pdf(ps)
* ps(pdf)
* ps(pdflatex)
* ps(xelatex)
* ps(lualatex)
"tmpdir"
Specifies whether the formatting should be done in a temporary
directory in which case the source document is copied into the
directory before formatting. This option can either take the
value 1, in which case a temporary directory is automatically
generated, or it is taken as the name of a subdirectory of the
system temporary directory. A temporary directory is always
created if the source document is specified as a scalar
reference.
"paths"
Specifies a mapping of program names to full pathname as a hash
reference. These paths override the paths determined at
installation time.
"maxruns"
The maximum number of runs of the formatter program (defaults to
10).
"extraruns"
The number of additional runs of the formatter program after the
document has stabilized.
"timeout"
Specifies a timeout in seconds within which any commands spawned
should finish.
"cleanup"
Specifies whether temporary files and directories should be
automatically removed when the object destructor is called.
Accepted values are "none" (do no cleanup), "logfiles" (remove
log files) and "tempfiles" (remove log and temporary files). By
default the destructor will remove the entire contents of any
automatically generated temporary directory, but will leave all
other files intact.
"indexstyle"
The name of a "makeindex" index style file that should be passed
to "makeindex".
"indexoptions"
Specifies additional options that should be passed to
"makeindex". Useful options are: "-c" to compress intermediate
blanks in index keys, "-l" to specify letter ordering rather
than word ordering, "-r" to disable implicit range formation.
Refer to makeindex(1) for full details.
"texinputs"
Specifies one or more directories to be searched for LaTeX
files.
"DEBUG"
Enables debug statements if set to a non-zero value.
"DEBUGPREFIX"
Sets the debug prefix, which is prepended to debug output if
debug statements. By default there is no prefix.
The constructor performs sanity checking on the options and will die
if the following conditions are detected:
* no source is specified
* an invalid format is specified
The constructor method returns a driver object.
"run()"
Format the document.
"stderr"
Holds the error output from subcommands, if the "-capture_stderr"
option was passed to "new()".
"stats()"
Returns a reference to a hash containing stats about the processing
that was performed, containing the following items:
"pages"
number of pages in the formatted document
"bytes"
number of bytes in the formatted document
"runs"
hash of the number of times each of the programs was run
Note: the return value will probably become an object in a future
version of the module.
"program_path($program_name, $opt_value)"
Get or set the path to the named program. Can be used as a class
method to set the default path or as an object method to set the
path for that instance of the driver object.
There are a number of other methods that are used internally by the
driver. Calling these methods directly may lead to unpredictable
results.
"run_latex"
Runs the formatter ("latex" or "pdflatex").
"need_to_run_latex"
Determines whether the formatter needs to be run.
"reset_latex_required"
Reset the flags that indicate whether latex needs to be re-run
(invoked prior to each iteration of running any necessary commands).
"run_bibtex"
Runs bibtex to generate the bibliography.
"need_to_run_bibtex"
Determines whether bibtex needs to be run.
"run_makeindex"
Runs makeindex to generate the index.
"need_to_run_makeindex"
Determines whether makeindex needs to be run.
"run_dvips"
Runs dvips to generate postscript output from an intermediate ".dvi"
file.
"run_ps2pdf"
Runs ps2pdf to generate PDF output from an intermediate PostScript
file.
"run_pdf2ps"
Runs pdf2ps to generate PostScript output from an intermediate PDF
file.
"run_command"
Run a command in a controlled environment, allowing for operating
system differences.
"copy_to_output"
Copy the output to its final destination.
"throw"
Throw an exception.
"debug"
Print a debug message - the caller should test $DEBUG to determine
whether to invoke this function.
DIAGNOSTICS
The following errors may be detected by the constructor method.
not available on XXX
The module is not supported on MacOS, OS/2 or VMS (or on a host of
other operating systems but these are the only ones that are
explicitly tested for).
no source specified
The "source" parameter should be specified as the name of a LaTeX
source file or it should be a reference to a scalar variable holding
the LaTeX source document.
source is an invalid reference
"source" is a reference, but not a reference to a scalar variable
source file XXX.tex does not exist
The source file specified does not exist
output directory DIR does not exist
An "output" parameter was specified as a scalar value, which was
taken as the name of the output file, but the directory part of the
path does not exist.
invalid output format XXX
An output format was specified, either explicitly or implicitly as
the extension of the output file, but the output format specified is
not supported.
cannot create temporary directory
The module could not create the temporary directory, which is used
if the source is not specified as a filename, and the output is not
to be left in the same directory as the source, or if a temporary
directory name is specified explicitly.
cannot create temporary latex file
The module has determined that it needs to create a temporary file
containing the source document but it cannot.
cannot copy XXX.ext to temporary directory
The module was trying to copy the specified source file to the
temporary directory but couldn't. Perhaps you specified the
temporary directory name explicitly but the directory does not exist
or is not writeable.
The following errors may be detected when the driver's "run()" method is
called:
file XXX.tex does not exist
The source file does not exist; it may have been removed between the
time the constructor was called and the time that the driver was
run.
PROGRAM exited with errors: ERRORS
The named program ("latex" or "pdflatex") exited with the errors
listed. You may have errors in your source file.
bibtex FILE failed (EXITCODE)
The "bibtex" program exited with errors. These are not fully parsed
yet.
failed to open BASEPATH.cit
The driver generates its own temporary file listing the citations
for a document, so that it can determine whether the citations have
changed. This error indicates that it was unable to create the file.
makeindex FILE failed (EXITCODE)
The "makeindex" program exited with errors. These are not fully
parsed yet.
dvips FILE failed (EXITCODE)
The "dvips" program exited with errors. These are not fully parsed
yet.
ps2pdf FILE failed (EXITCODE)
The "ps2pdf" program exited with errors. These are not fully parsed
yet.
PROGNAME cannot be found, please specify its location
The pathname for the specified program was not found in the modules
configuration. The program may not have been found and the pathname
not been explicitly specified when the module was installed.
failed to copy FILE to OUTPUT
The driver failed to copy the formatted file to the specified output
location.
CONFIGURATION AND ENVIRONMENT
When the using application configures Log::Any, this module will use it
to log "debug" and "trace" level messages to the "LaTeX::Driver"
category. Please note that the $DEBUG variable does not need to be set
to enable this type of logging. When this type of logging is enabled,
the value of $DEBUG is ignored.
DEPENDENCIES
"LaTeX::Driver" depends on latex and friends being installed.
INCOMPATIBILITIES
None known.
BUGS AND LIMITATIONS
If you have any comments about this software I would be very grateful to
hear them; please file your comments as issues at
<https://github.com/Template-Toolkit-Latex/LaTeX-Driver/issues>.
Among the things I am aware of are:
* I haven't worked out how I am going to deal with tex-related
environment variables.
FUTURE DIRECTIONS
* Look at how path variables could be specified to the filter
("TEXINPUTS", "TEXINPUTS_latex", "TEXINPUTS_pdflatex", "BIBINPUTS",
etc), and how these should interact with the system paths.
* Investigate pre- and post-processors and other auxiliary programs.
BACKGROUND
This module has its origins in the original "latex" filter that was part
of Template Toolkit prior to version 2.16. That code was fairly
simplistic; it created a temporary directory, copied the source text to
a file in that directory, and ran either "latex" or "pdflatex" on the
file once; if postscript output was requested then it would run "dvips"
after running "latex". This did not cope with documents that contained
forward references, a table of contents, lists of figures or tables,
bibliographies, or indexes.
The current module does not create a temporary directory for formatting
the document; it is given the name and location of an existing LaTeX
document and runs the latex programs in the directory specified (the
Template Toolkit plugin will be modified to set up a temporary
directory, copy the source text in, then run this module, extract the
output and remove the temporary directory).
INTERNALS
This section is aimed at a technical audience. It documents the internal
methods and subroutines as a reference for the module's developers,
maintainers and anyone interesting in understanding how it works. You
don't need to know anything about them to use the module and can safely
skip this section.
Formatting with LaTeX or PDFLaTeX
LaTeX documents can be formatted with "latex" or "pdflatex"; the former
generates a ".dvi" file (device independent - TeX's native output
format), which can be converted to PostScript or PDF; the latter program
generates PDF directly.
finds inputs in "TEXINPUTS", "TEXINPUTS_latex", "TEXINPUTS_pdflatex",
etc
Generating indexes
The standard program for generating indexes is "makeindex", is a general
purpose hierarchical index generator. "makeindex" accepts one or more
input files (".idx"), sorts the entries, and produces an output (".ind")
file which can be formatted.
The style of the generated index is specified by a style file (".ist"),
which is found in the path specified by the "INDEXSTYLE" environment
variable.
An alternative to "makeindex" is "xindy", but that program is not
widespread yet.
Generating bibliographies with BiBTeX
BiBTeX generates a bibliography for a LaTeX document. It reads the
top-level auxiliary file (".aux") output during the running of latex and
creates a bibliography file (".bbl") that will be incorporated into the
document on subsequent runs of latex. It looks up the entries specified
by \cite and \nocite commands in the bibliographic database files (.bib)
specified by the \bibliography commands. The entries are formatted
according to instructions in a bibliography style file (".bst"),
specified by the \bibliographystyle command.
Bibliography style files are searched for in the path specified by the
"BSTINPUTS" environment variable; for bibliography files it uses the
"BIBINPUTS" environment variable. System defaults are used if these
environment variables are not set.
Running Dvips
The "dvips" program takes a DVI file produced by TeX and converts it to
PostScript.
Running ps2pdf
The "ps2pdf" program invokes Ghostscript to converts a PostScript file
to PDF.
Running on Windows
Commands are executed with "cmd.exe". The syntax is:
cmd /c "cd $dir && $program $args"
This changes to the specified directory and executes the program there,
without affecting the working directory of the the Perl process.
Need more information on how to set environment variables for the
invoked programs.
Miscellaneous Information
This is a placeholder for information not yet incorporated into the rest
of the document.
May want to mention the kpathsea library, the "kpsewhich" program, the
web2c TeX distribution, TeX live, tetex, TeX on Windows, etc.
AUTHOR
Erik Huelsmann <erik@efficito.com> (current maintainer)
LICENSE AND COPYRIGHT
Copyright (C) 2020 Erik Huelsmann.
Copyright (C) 2014 Chris Travers.
Copyright (C) 2009-2013 Ford & Mason Ltd.
Copyright (C) 2006-2007 Andrew Ford.
Portions Copyright (C) 1996-2006 Andy Wardley.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
Template::Plugin::Latex, latex(1), makeindex(1), bibtex(1), dvips(1),
The dvips manual
There are a number of books and other documents that cover LaTeX:
* The LaTeX Companion
* Web2c manual
|