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