NAME
   LaTeX::Driver - Latex driver

VERSION
   This document describes version 0.200.4 of "LaTeX::Driver".

SYNOPSIS
       use LaTeX::Driver;

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

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 can be removed with the "cleanup" method.

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.

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

   "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").

   "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
DEPENDENCIES
   "LaTeX::Driver" depends on latex and friends being installed.

INCOMPATIBILITIES
   None known.

BUGS AND LIMITATIONS
   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 <[email protected]>.

   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
   Andrew Ford <[email protected]>

LICENSE AND COPYRIGHT
   Copyright (C) 2009-2011 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.

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.