NAME

VERSION

SYNOPSIS

    use LaTeX::Driver;

    $drv = LaTeX::Driver->new( source  => \$doc_text,
                               output  => $filename,
                               format  => 'pdf',
                               %other_params );
    $ok    = $drv->run;
    $stats = $drv->stats;

DESCRIPTION

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

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:

"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:

"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

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

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

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

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

   cmd /c "cd $dir && $program $args"

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

There are a number of books and other documents that cover LaTeX:

• The LaTeX Companion
• Web2c manual