- BUGS AND LIMITATIONS
- FUTURE DIRECTIONS
- LICENSE AND COPYRIGHT
- SEE ALSO
LaTeX::Driver - Latex driver
This document describes version 0.03 of
use LaTeX::Driver; $drv = LaTeX::Driver->new( basename => $basename, formatter => 'pdflatex', %other_options ); $ok = $drv->run; $stats = $drv->stats; $drv->cleanup($what);
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 can be removed with the
This is the constructor method. It takes the following options:
The base name of the document to be formatted. This is mandatory. The name may include the directory, in which case that is taken as the base directory (overriding any value of
basedir). If the basename includes a
.texsuffix that is stripped off.
The base directory of the document to be formatted. If
basenamecontains a directory part then that is used, if not and
basediris not specified then the current directory is used.
The name of the formatter to be used (either
Specifies a mapping of program names to full pathname as a hash reference. These paths override the paths determined at installation time.
The type of output required (
The maximum number of runs of the formatter program (defaults to 10).
The number of additional runs of the formatter program after the document has stabilized.
The name of a
makeindexindex style file that should be passed to
Specifies additional options that should be passed to
makeindex. Useful options are:
-cto compress intermdiate blanks in index keys,
-lto specify letter ordering rather than word ordering,
-rto disable implicit range formation. Refer to makeindex(1) for full details.
The constructor performs sanity checking on the options and will die if the following conditions are detected:
no base name is specified
an invalid outputtype is specified
an invalid formatter is specified
a formatter and an outputtype are specified but the formatter is not able to generate the specified output type (even with known postprocessors).
The constructor method returns a driver object.
Format the document.
Returns a reference to a hash containing stats about the processing tht was performed, containing the following items:
number of times
number of times
number of times
Removes temporary intermediate files from the document directory and resets the stats.
Not yet implemented
There are a number of other methods that are used internally by the driver. Calling these methods directly may lead to unpredictable results.
Runs the formatter (
LaTeX::Driver depends on latex and friends being installed.
This is beta software - there are bound to be bugs and misfeatures. If you have any comments about this software I would be very grateful to hear them; email me at <firstname.lastname@example.org>.
Among the things I am aware of are:
I haven't worked out how I am going to deal with tex-related environment variables.
Look at how path variables could be specified to the filter (
BIBINPUTS, etc), and how these should interact with the system paths.
Investigate pre- and post-processors and other auxilliary programs.
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
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).
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.
LaTeX documents can be formatted with
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
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
xindy, but that program is not widespread yet.
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 bibliograpy 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.
dvips program takes a DVI file produced by TeX and converts it to PostScript.
ps2pdf program invokes Ghostscript to converts a PostScript file to PDF.
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.
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.
Andrew Ford <email@example.com>
Copyright (C) 2007 Andrew Ford. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
There are a number of books and other documents that cover LaTeX:
The LaTeX Companion