Provided by: liblatex-driver-perl_1.2.0-2_all bug

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