Returns the std_error_file used by this run. Note that this is UNIX only and will only exists in case you've set the option capture_stderr to 1.
Usage:
my $error_file = $this->std_error_file();
LaTeX::CatSuit - Latex driver - Forked from LaTeX::Driver by A. Ford-Mason with extra features.
This document describes version 1.00 of LaTeX::CatSuit.
LaTeX::CatSuit
use LaTeX::CatSuit; $drv = LaTeX::CatSuit->new( source => \$doc_text, output => $filename, format => 'pdf', %other_params ); $ok = $drv->run; $stats = $drv->stats; $drv->cleanup($what);
The LaTeX::CatSuit 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 cleanup method.
dirname
basename
cleanup
Source code can be found at https://github.com/jeteve/LaTeX-CatSuit
Feel free to fork and add your stuff!
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.
run
source
output
The full list of arguments is as follows:
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.
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.
"dvi"
"ps"
"pdf"
"pdf(ps)"
dvips
ps2pdf
"pdf(dvi)"
dvipdfm
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.
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.
none
logfiles
tempfiles
timeout
Specifies a timeout in second under which any underlying LaTeX command should finish. The run method will die in case it takes too long.
indexstyle
The name of a makeindex index style file that should be passed to makeindex.
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.
-c
-l
-r
texinputs
Specifies one or more directories to be searched for LaTeX files.
capture_stderr
Capture the STDERR of your run into a file so you can examine it later.
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.
stats()
Returns a reference to a hash containing stats about the processing tht 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.
cleanup($what)
Removes temporary intermediate files from the document directory and resets the stats.
Not yet implemented
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).
latex
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.
.dvi
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.
$DEBUG
The following errors may be detected by the constructor method.
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).
The source paramater 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 a reference, but not a reference to a scalar variable
The source file specified 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.
An output format was specified, either explicitly or implicitly as the extension of the output file, but the output format specified is not supported.
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.
The module has determined that it needs to create a temporary file containing the source document but it cannot.
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:
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.
The named program (latex or pdflatex) exited with the errors listed. You may have errors in your source file.
The bibtex program exited with errors. These are not fully parsed yet.
bibtex
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.
The makeindex program exited with errors. These are not fully parsed yet.
The dvips program exited with errors. These are not fully parsed yet.
The ps2pdf program exited with errors. These are not fully parsed yet.
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.
The driver failed to copy the formatted file to the specified output location.
LaTeX::CatSuit 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 <jeteve@cpan.org<gt>.
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 (TEXINPUTS, TEXINPUTS_latex, TEXINPUTS_pdflatex, BIBINPUTS, etc), and how these should interact with the system paths.
TEXINPUTS
TEXINPUTS_latex
TEXINPUTS_pdflatex
BIBINPUTS
Investigate pre- and post-processors and other auxilliary programs.
This is a fork of the original LaTeX::Driver module by Andrew Mason.
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).
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 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
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.
.idx
.ind
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.
.ist
INDEXSTYLE
An alternative to makeindex is xindy, but that program is not widespread yet.
xindy
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.
.aux
.bbl
.bst
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.
BSTINPUTS
The dvips program takes a DVI file produced by TeX and converts it to PostScript.
The ps2pdf program invokes Ghostscript to converts a PostScript file to PDF.
Commands are executed with cmd.exe. The syntax is:
cmd.exe
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.
kpsewhich
Andrew Ford <a.ford@ford-mason.co.uk>
Copyright (C) 2012 Jerome Eteve. All Rights Reserved.
Copyright (C) 2009 Ford & Mason Ltd. All Rights Reserved.
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.
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
To install LaTeX::CatSuit, copy and paste the appropriate command in to your terminal.
cpanm
cpanm LaTeX::CatSuit
CPAN shell
perl -MCPAN -e shell install LaTeX::CatSuit
For more information on module installation, please visit the detailed CPAN module installation guide.